Adding a Replication Rule

To add a replication rule:

1. Click to edit the source Vault for the files (Administration>File Handling>Vaults).

   

   

   Figure 1.

2. On the new Replication Rule tab, click the Add Identities icon . The Identity search dialog box appears.

   

   

   Figure 2.

3. Click the Search icon and select the identity that executes the initiating event. Usually, this is set to World. If you would like to replicate files that are read or updated in the vault by only a particular group of users then specify that identity on the ‘Replication Rule’; otherwise set the identity to ‘World’.

4. Right click on the new entry, and click Replication Rule>Open. The Replication Rule form appears.

   

   

   Figure 3.

5. You may set the following properties:

   • Initiator Type defines the initiating event to run this rule. The options are:

     • onDemand, for cases where a user belonging in the rule’s related identity tries to get the physical file. In this case, target vault is the highest priority ”read’ vault of the user initiating this request, and related Target Vaults (see below) are ignored. If a file already exists in more than one vault, keep in mind that the rule may or may not create a replication transaction, depending on which vault the file is retrieved from. Therefore, you should usually have similar onDemand rules for each vault to get consistent behavior.
     • onChange, for cases where the physical file is added or changed by a user belonging in the rule’s related identity.

     • onEvent, for cases where a method explicitly requests replication checks be performed. The user must belong in the rule’s related identity, or must be granted special temporary credentials in the method through a GrantIdentity() call. onEvent replication rules are checked when AML of the form “<Item type='File’ action='replicate’ id=’…’ />” is sent to the Aras Innovator server for a specific file ID. Optionally, preferred vault(s) to replicate from may be specified by adding the Located relationship(s) in preference order to the AML. However, if none of the vaults specified have a copy, or no vaults are specified, Aras Innovator checks for the first vault with a copy.

       OnDemand and onChange events are automatically checked when a get or upload, respectively, occurs for a specific file on a vault. To replicate files for any situation other than these, use a method to pass File Item ID(s) with a replicate action, and create a matching onEvent rule.

   • Filter Method identifies a server method which is used to determine if a file having a replication transaction record should be replicated at the time the replication transaction is about to execute. It references a method with signature Item Method (Item file) that gets an IOM.Item of type File with the file ID set, and returns an IOM.Item with AML <Result>1</Result> in case the file must be replicated, or any other AML if the replication should not occur. The method is called immediately before executing a replication transaction created based on the rule and is not when the replication rule is checked, nor when the replication transaction is created. The reason for this is the necessity to check file properties (or properties of other items to which the file could be related) immediately prior to executing the transaction, as the properties could change since the replication transaction is created. If the filter method determines that the replication should not occur, it is recommended that the result be set to a text value indicating why, so this reason appears in the replication transaction log.

     Note

     In case the method returns “<Result>Do NOT replicate the file</Result>” the transaction is discarded (i.e. its status is set to Discarded) and the content of the returning <Result> tag is set on the ReplicationTxn.error_msg property.

   • Replication Mode specifies the timing for executing a replication transaction.

     • Immediate sets the execution time to the moment the transaction was created.
     • Delayed sets the execution time to the moment the transaction was created plus the defined Replication Time.
     • Scheduled sets the execution time to the UTC time specified in the Replication Time field defined below for today, or tomorrow if that UTC time has already passed for today.
     • Manual does not set an execution time, and the transactions are held until executed programmatically through a call to a special new method in the form - Aras.Server.Replication.Queue.Process(XmlDocument inDom, XmlDocument outDom). Note, a single call of Aras.Server.Replication.Queue.Process(...) only runs one iteration of the replication queue processing, so if there are more ‘Manual’ replication transactions than could be executed in a single replication queue processing iteration, some are not be completed, so you must take that into account in your code. See the Programming Notes section for more detail on Manual Replication.

   • Replication Type determines if the file is left in the source vault or not

     • Copy leaves the file in the source.
     • Move removes the file from the source vault after copying it to the target vault. Note that you should only have one target vault (or none chosen for onDemand Initiator types) when this option is chosen.
   • Is Active allows specific replication rules to be either in use or ignored for debugging and other administrative purposes. Those set to active are checked, and those not set are ignored.
   • Replication Time is relevant for Delayed and ScheduledReplication Modes only. For Delayed modes, it is the quantity of time in hours and minutes from when the rule creates a transaction record to the earliest that transaction should execute. For Scheduled modes, it is the hour and minute of the day in UTC Time (today if later than the present time, tomorrow if that time has already passed for today) representing the earliest the transaction should execute. Format for both modes is hhmm with 0000 representing immediately for Delayed, and midnight for Scheduled modes. The maximum allowed value for Scheduled modes is 2359, and any value not recognized is treated as 0000.
   • Timeout represents the maximum amount of time allowed from when a transaction execution request is sent to a vault server and accepted (and the transaction is set as Pending) until it completes either successfully (Completed) or not (Failed). Transactions not completed in the allotted time are automatically failed (Failed). A default value of 0100 (one hour) is set and assumed. Note that the vault server may be processing multiple requests. Format is hhmm.
   • Label is an arbitrary text field that is output on the replication transaction log. Labeling the rules may be helpful in searching and reading the logs.

Two relationships are made in the Replication Rule:

• File Types specifies and restricts which types of files are replicated using the rule. If no file types are specified, all file types are included.
• Target Vaults specifies the vault or vaults to copy the file to. This relationship is not appropriate, and is ignored, for rules where the Initiator Type is onDemand since the target is set to the initiating user’s highest ‘read’ priority vault. Only one vault should be specified where the Replication Type is Move. Having more than one target results in transaction errors since the file no longer exist in the source vault after the first completed ‘Move’ transaction.