Bootstrapping Rules to Existing Folders in Alfresco

Overview

There are times when we need to bootstrap one or more rules to a site that already exists.  Perhaps you need to add a rule to sites folder to handle applying a site template to a site, need to add new rules to the Unfiled folder in a Records Management site, or you simply need to add a new rule to an existing site.

In this case you can't simply upload an ACP file as the folder already exists.  Rather we just need to bootstrap the rules to the folder in question.  In the example I am going through I am assuming the folder in question already has one or more rules attached to it.  If in your example it doesn't then you will need to create the rule folder (I'll highlight below how you would do that).

My example in this case is going to be to add a new rule to the Unfiled folder of the Records Management site.  For those who haven't worked with Records Management (RM) in Alfresco you are only allowed one RM site per Alfresco cluster.  This RM site would need to support all RM clients within the system.  It is quite common for a new client to come in that will need to have its records filed based on rules so hence the need to add new rules to an existing folder.

Test Environment

The following is the environment in which I performed this test, it should work in other versions of Alfresco as well:

• Alfresco One Enterprise 5.0.2
• Alfresco Records Manager 2.3
• Alfresco SDK 2.1.1
• I am deploying the Alfresco and Share web apps to an existing Alfresco installation rather than using the Maven runner.  I found that the Share Import/Export extension didn't work when I tried running it through Maven.
• Import/Export ACP, ZIP Share Addon by Atol Conseils et Développements
• Click the download button on https://addons.alfresco.com/addons/importexport-acpzip-share
• I downloaded the JAR and included it as a project local Maven repository.  It needs to be a dependency of both Share and Alfresco projects.
• I used the version for 4.0 and this appears to work.
• This is really only needed on the development machine as we won't be using it for import, just to help us create the bootstrap file.

Bootstrapping Process

At a high level the steps to bootstrap a rule to an existing folder are:

1. Create the rule on a folder in a development environment.
2. Export the folder as an ACP file.
3. Using the ACP file create a bootstrap view.
4. Create the bootstrap bean.
5. Test the bootstrap.

Create a Rule

Before we can begin we need to have a rule defined in a development environment.  For my example I am going to create a very simple rule:

When items are created or enter the folder and if the name contains the letter '3' then they will be filed to the record path '/EATest/Test' without creating the record path.

If you aren't familiar with records management filing a record is the same concept as moving the record to a specific folder.  Filing insinuates more than just moving the record but that isn't important in our example.  In addition a record can be thought of as a document for the purposes of this discussion; documents and records are different but this difference isn't relevant to this discussion.

The rule is created in share as follows:

Export Folder

If you are using Alfresco 5.x then you must have the Share Import/Export addon installed correctly.  For Alfresco 4.x you can use the export in Alfresco Explorer to perform the same action (refer to http://docs.alfresco.com/4.2/concepts/cuh-content-exportimport.html for more information on using Alfresco Explorer to export an ACP).

To export the ACP in Alfresco 5.x perform the following steps:

1. Click on Admin Tools in the menu bar.
   
2. Click on Export in the left navigation bar.
   
   
3. On the export metadata and content of a space screen enter the following:
   • Package name
   • This is the name of the package and can be any valid name.
   • Space to export
   • This is the space that you wish to export.  In this case it is the unfiled folder which is '/Sites/rm/documentLibrary/Unfiled Records'.
   • Destination Space
   • When you export a space the ACP file is actually created in Alfresco rather than downloaded to your machine.  Select anywhere you want to save the file, such as your user home.
   • Include Child Spaces
   • This should be checked to ensure that the rule folder is included.
   • Include Selected Space
   • This must be checked.
   • Run export in background
   • Check this if you wish to run the export in the background.  If there are a lot of documents in the unfiled folder this may take a little bit to complete.
   
4. Navigate to the destination space and download the file you exported.  If you selected run export in the background then you may have to wait a few minutes before the file is created.

Create Bootstrap View

Now that we have an ACP file we can use that to create a bootstrap view that will define the rule that will be created.  The ACP file is just a ZIP file with a specific format.  In this case we only care about one file in the ACP (if you don't have any documents in the folder it will be the only file).  This file will be at the root of the ACP file and will have the same name as the ACP file itself but with an XML extension.  So for example if the ACP file is named Unfiled_With_Name_Contains_3_Rule.acp then it will contain a file named Unfiled_With_Name_Contains_3_Rule.xml.  We will refer to this as the original view file.

The following instructions assume you are using an AMP project created by the Alfresco SDK:

1. Create an XML file for the bootstrap view.  It should be post-fixed with -rule.xml to indicate it is defining a rule.  The recommended location to place the file is <amp-project>/src/main/amp/config/alfresco/module/<module name>/bootstrap.  In my case I have named the file: unfiled-name-contains-3-rule.xml
2. Populate the XML file with the following:

   1 2 3 4 5 6 7 8

   <?xml version="1.0" encoding="UTF-8"?> <view:view xmlns:view="http://www.alfresco.org/view/repository/1.0"> <view:reference xmlns:rule="http://www.alfresco.org/model/rule/1.0" xmlns:cm="http://www.alfresco.org/model/content/1.0" xmlns:act="http://www.alfresco.org/model/action/1.0" xmlns:sys="http://www.alfresco.org/model/system/1.0" view:pathref="/app:company_home/st:sites/cm:rm/cm:documentLibrary/rma:Unfiled_x0020_Records/rule:ruleFolder"> </view:view>

• You may need to add additional namespaces under the view:reference tag depending on the content of your rules.  Note that you will not need all of the namespaces defined in the XML from the ACP file, you can add them all if you want but it does make the file a bit messy.
• This XML defines a view which will populate the rule folder under the Unfiled folder.  If the rule folder doesn't exist then you will also need another XML file named something like unfiled-creates-rule-folder.xml with the following contents:

  1 2 3 4 5 6 7 8 9

  <?xml version="1.0" encoding="UTF-8"?> <view:view xmlns:view="http://www.alfresco.org/view/repository/1.0"> <view:reference xmlns:rule="http://www.alfresco.org/model/rule/1.0" view:pathref="/app:company_home/st:sites/cm:rm/cm:documentLibrary/rma:Unfiled_x0020_Records"> <view:aspects> <rule:rules /> </view:aspects> </view:reference> </view:view>

  • By adding the rule aspect to the parent folder the rule folder automatically gets created.
  • When we get to the step of creating the bootstrapping bean we need to make sure this file is loaded before the file to create the view.
3. Open the XML file found in the ACP file in any text editor.  There should be a cm:systemfolder tag immediately after the closing if the view:metadata.  Within this cm:systemfolder tag find the view:associations tag.  Copy this tag and its contents.
• It should contain a cm:contains tag that only contains the rule or rules you are trying to bootstrap.  If there are extra rules then you want to look for the rules with the appropriate value for the view:properties/cm:title/view:mlvalue tag and remove all rules that do not have the appropriate value.
4. This copied value should be placed into the XML file you created above so it should look something like the following:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

   <?xml version="1.0" encoding="UTF-8"?> <view:view xmlns:view="http://www.alfresco.org/view/repository/1.0"> <view:reference xmlns:rule="http://www.alfresco.org/model/rule/1.0" xmlns:cm="http://www.alfresco.org/model/content/1.0" xmlns:act="http://www.alfresco.org/model/action/1.0" xmlns:sys="http://www.alfresco.org/model/system/1.0" view:pathref="/app:company_home/st:sites/cm:rm/cm:documentLibrary/rma:Unfiled_x0020_Records/rule:ruleFolder"> <view:associations> <cm:contains> <rule:rule view:childName="rule:rulesce788b56-1d9d-4d8f-86fd-874be2d8048f"> <content-of-rule-removed /> </rule:rule> </cm:contains> </view:associations> </view:reference> </view:view>

   • The tag content-of-rule-removed is just a placeholder for the rule itself rather then pasting all 200+ lines of XML in this blog :).

Create Bootstrap Bean

In order to create the bootstrap bean you should already have a bootstrap-context.xml file in <amp-project>/src/main/amp/config/alfresco/module/<module name>/context.  If you don't you will need to create one and make sure you import that file in <amp-project>/src/main/amp/config/alfresco/module/<module name>/module-context.xml.  The remainder of this section assumes this file exists and the bean just need to be added to it.

Within the beans tag add the following bean:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

<bean id="com.microstrat.rbc.demo.rmUnfiledNameContains3CreatingFolderRuleBootstrap" class="org.alfresco.repo.module.ImporterModuleComponent" parent="module.baseComponent"> <!-- Module Details --> <property name="moduleId" value="my-module-name"/> <property name="name" value="rmUnfiledNameContains3Bootstrap"/> <property name="description" value="Add Rule to unfiled folder for names with letter 3"/> <property name="sinceVersion" value="0.0.1"/> <property name="appliesFromVersion" value="0.0.1"/> <property name="executeOnceOnly" value="true"/> <property name="importer" ref="spacesBootstrap" /> <property name="bootstrapViews"> <list> <props> <prop key="path">/app:company_home/st:sites/cm:rm/cm:documentLibrary/rma:Unfiled_x0020_Records/rule:ruleFolder</prop> <prop key="location">alfresco/module/my-module-name/bootstrap/unfiled-name-contains-3-rule.xml</prop> <prop key="uuidBinding">UPDATE_EXISTING</prop> </props> </list> </property> </bean>

You need to change the values that are in bold italics as follows:

• moduleId
• This is the module ID of your module as found in module.properties folder (it is also the name of the folder under src/main/amp/config/alfresco/module.
• name
• The name of the bootstrap.  The should be unique and descriptive.
• description
• The description of the bootstrap.  This is documentation that will be used to identify the bootstrap rule later.
• sinceVersion
• The version of the module in which the bootstrap was added.  This is generally the current version of the module.
• appliesFromVersion
• The version of the module in which this bootstrap applies from.  This is generally the current version of the module.
• location property key
• The location of the XML bootstrap file created above starting under the <amp-project>/src/main/amp/config folder.

If you need to also create the rule folder you will need to add the following props tag before the current props tag within the bootstrapViews property list tag:

1 2 3 4 5

<props> <prop key="path">/app:company_home/st:sites/cm:rm/cm:documentLibrary/rma:Unfiled_x0020_Records</prop> <prop key="location">alfresco/module/repo-amp/bootstrap/unfiled-creates-rule-folder.xml</prop> <prop key="uuidBinding">UPDATE_EXISTING</prop> </props>

Testing the Bootstrap

When it comes to testing the bootstrap there are a couple of ways you can do this:

• Try the bootstrap in a share development or QA environment.
• Create another installation of Alfresco on your machine and prep that for the bootstrap (like create the RM site).
• If you have your Alfresco instance setup to connect to an external database you can simply point it to a new database or schema (depending on the database type) and prep it for the bootstrap the same as above.

Testing it is relatively straight forward once you have an environment to test with.  If the bootstrap files are not correct it will fail to start up Alfresco and generally give you a somewhat helpful error indicating where the problem is.  Once the server starts up you can verify the rule was added.

I hope this blog was helpful and happy coding!