API Guide

During synchronization, the Source system adds new Items from a Synchronization Scope and updates already synchronized Items on the Destination system.

Unfortunately, you cannot use the existing Item actions add and update for these operations for the following reasons:

• Synchronization may require overwriting some fields that are automatically calculated in add/update actions (for example: id, config_id, state, generation, etc.).
• Theadd/update/delete actions on ItemTypes may contain additional logic using Server Events that may not be necessary during synchronization. For example:
• Data validation in onBefore events – the data should be considered as already verified by the Source system.
• Field pre-calculation in onBefore events – the data should be considered as already calculated by the Source System. The result is passed to the Destination system for saving.
• Sequence field value calculation.
• The addand update actions also handle infrastructural processing (LifeCycle handling, workflows start, history tracking) which may be unnecessary or handled in a different way for synchronized Items.
• The standard add action treats received data as the initial generation of an Item which is not registered in the database. During synchronization the received data may correspond to a higher generation and should be written directly into the database.
• The Standard update action also performs additional generation handling for versionable Items, while for synchronization it is only necessary to update the record with the received data.

The following Item Actions were introduced in Aras Innovator 11.0 SP15 for synchronization purposes:

• dss_syncAdd
• dss_syncUpdate
• dss_syncPurge

Synchronization actions perform the required Server Events onBefore-/onAfter-Add/Update/Delete configured for the ItemType (i.e. with @is_required=1). In addition, each of the specialized synchronization actions come with a couple of corresponding onBeforeSync-/onAfterSync- Server Events (see New Server Events for Synchronization). Where possible, the new synchronization Server Events provide the means for more efficient processing of Item sets.

In addition, two new Data Types were introduced to enable tracking of item changes on the source system:

• Global Version
• Unsigned BigInt

Synchronization API actions have the following common restrictions:

• They can only be called by the dss_SyncReceiver Identity (which is also introduced in Aras Innovator 11.0 SP15)
• They are supported for Table ItemTypes, where custom OnAdd, OnUpdate, and OnDelete events are not defined.
• They return an error if the target Item is locked.
• They return an error in calls for Items associated with ItemTypes representing Aras Innovator metadata (ItemType, RelationshipType, Property, Method, SystemEvent, LifeCycle, Variable, Locale, Language, Permission, Workflow, WorkflowProcess, etc.)

There are two new Aras Innovator Data Types that were introduced in 11.0 SP15 that enable the tracking of changes to items on a Source system. These Data Types are very important in order to monitor and maintain synchronization between the Source and Destination systems.

The Global Version is a unique value across the entire database that should be attached to every ItemType that is intended to be synchronized. ItemTypes that will be synched should have the optional global_version property attached that will be incremented any time the item is updated. The value of a global_version property is handled by the system and cannot be modified by an administrator. In order to ensure that the value is unique, the Data Type supports values between 0 and 264-1.

The Global Version is a unique Data Type that is only used for the global_version property. In order to store and compare the current global_version value with a previously stored version, the Unsigned BigInt Data Type is introduced in order to be able to track the Global Version of an item. Since the value of a global_version property can range from 0 to 264-1, an Integer will not support values large enough to store and compare a global_version value, requiring the support for an Unsigned BigInt.

Data synchronization is a low-level, specialized process. Therefore, permissions to configure and run it should be granted carefully. The new dss_SyncReceiver Identity can receive synchronization requests and perform Item synchronization on the Destination system.

When applying synchronization requests, you must have create/update/delete permissions for Items associated with ItemTypes that come from a particular Source system. By default, dss_syncReceiver does not have these types of permissions. When preparing the Destination system for synchronization the Administrators of that system should give corresponding permissions either to the entire dss_SyncReceiver Identity or to a particular User Identity that will be used for synchronization requests from a particular Source system. Although this type of approach requires some time for manual configuration, it has the following advantages:

• It controls the amount of data that can be changed using the Synchronization API. It is only possible to modify Items associated with ItemTypes that have been specially configured for that.
• It is possible to receive synchronization requests from different Source systems on the same Destination System and ensure that they will modify different sets of Items.

Figure 3 shows a One-Source system where dss_SyncReceiver is an Alias Identity for sync request authentication User.

Figure 4 shows a One Source system where Sync request authentication User Identity is a member of dss_SyncReceiver.

Figure 5 shows two Source systems with different sets of synced Item types and two sync request authentication Users.

AML

<Item type='Part’ id='7073098207234317BBC2CA865413CAD5' action='dss_syncAdd'> <config_id>7073098207234317BBC2CA865413CAD5</config_id> <generation>1</generation> <major_rev>A</major_rev>

 <!-- Item properties with sync data--> <item_number>PA-1586-0</item_number> <name>Engine</name> <!-- … the rest of Item props to be synced --> </Item> 

Implementation Details

The main differences between the add action and dss_syncAdd are dss_syncAdd:

• Requires id, generation, and config_id values to be provided for the Item. dss_syncAdd does not generate an ID.
• Skips determination of the initial LifeCycle State.
• Allows the setting of system properties such as created_on, modified_on, etc.
• The default onBeforeAdd/onAfterAdd events are not called. Use the new server events onBeforeSyncAdd/onAfterSyncAdd instead.

Generally, dss_syncAdd directly saves the provided properties to the database.

Table 3 describes the processing of system properties in the dss_syncAdd action.

The dss_syncAdd action processing of system properties

* - Required properties should be provided with an Item, otherwise an error is returned.** - For compatibility with the format of the standard add action, the id property is expected to be provided for an Item as an attribute in the AML request. The <id/> property tag is ignored.

AML

<Item type="Part” id="7073098207234317BBC2CA865413CAD5" action="dss_syncUpdate"> <!-- Item properties with sync data--> <item_number>PA-1586-0</item_number> <name>Main Engine</name> <!-- … the rest of Item props to be synced --> </Item> 

Implementation Details

The main differences from update are that dss_syncUpdate:

• Allows the setting of system properties like modified_on, modified_by_id.
• Does not handle the float behavior of Relationships.
• The default onBeforeUpdate/onAfterUpdate events are not called. Instead, the new server events onBeforeSyncUpdate/onAfterSyncUpdate should be used.
• Does not handle versioning for Versionable Items.

Generally, dss_syncUpdate directly saves the provided properties to the database on the Item generation corresponding to the provided Item ID.

Table 4 describes the processing of system properties in the dss_syncUpdate action.

The dss_syncUpdate action processing of system properties

* - Required properties should be provided with an Item, otherwise an error is returned.

AML

 <Item type="Part” id="7073098207234317BBC2CA865413CAD5" action="dss_syncPurge” /> 

Implementation Details

In Aras Innovator 11.0 SP15 this item action is implemented as a wrapper for the purge action.

In future releases, it is planned to introduce custom onBeforeSyncDelete/onAfterSyncDelete events and switch off calls for onBeforeDelete/onAfterDelete which are not marked as required.

Overview

The onBeforeSyncAdd server event:

• Runs before an Item is added to the database during synchronization.
• Is called per Item.
• Can be used to populate some data with values that have not been passed from the Source System or to add local values, e.g., values for fields created_by_id andmanaged_by_id.
• Runs before required onBeforeAdd events (with @is_required=1).
• The dss_syncAdd request may be rejected completely by returning an error from this event handler.

Input/Output arguments

This event is called per Item. The request Item with the assigned ID is passed to the event handler as a Context Item (inDom). No additional event arguments are passed to the handler.

The context Item of onBeforeSyncAdd event handlers with all the changes applied to it inside the handlers is passed further as a Context Item to the onBeforeAdd event handlers.

The return results of onBeforeSyncAdd event handlers are ignored, unless there is an error. In this case the dss_syncAdd is stopped and the error is returned in the action response.

Overview

The onAfterSyncAdd server event:

• Runs after an item has been added to the database during synchronization
• Runs after required onAfterAdd events (with @is_required=1).
• Is called per Item.
• Can be used to propagate the synchronized Items to external systems if required, e.g., for Mixed Federated Items.

Input/Output arguments

Unlike the onAfterAdd Server Event, onAfterSyncAdd Server Event handlers don’t get the created Item as the Context Item. The event handler’s Context Item is empty. The details about the created Item are provided in event arguments of type OnAfterSyncAddEventArgs:

public class OnAfterSyncAddEventArgs 

{

 public string TypeId { get; }

 public string Id { get; }

}

If required, the event handlers can load the item from the DB themselves using the type and ID.

The return results of onAfterSyncAdd event handlers should be ignored, unless there is an error. In this case the dss_syncAdd should be stopped and the error should be returned in the action response.

Overview

The onBeforeSyncUpdate event:

• Runs before an Item is updated in the database during synchronization.
• Runs before the required onBeforeUpdate event (@is_required=1).
• Can be used to populate some data with values that have not been passed from the Source System or should be adjusted to local values, e.g., values for fields created_by_idand managed_by_id.
• Is called per Item.
• The request may be rejected by returning an error.

Input/Output arguments

If the request Item contains a where condition or idlist, the condition is resolved to a list of Item IDs and the event handlers are called per each Item ID.

The request Item with the condition replaced with the Item ID is passed to the event handler as a Context Item (inDom). Table 5 shows an example.

A request Item example

The context Item for onBeforeSyncUpdate event handlers with all the changes applied to it inside the handlers are passed further as a Context Item to the onBeforeUpdate event handlers.

In addition to the Context Items, the onBeforeSyncUpdate event handlers receive event arguments of type OnBeforeSyncUpdateEventArgs that contain a list of all the IDs in the entire as well as the ItemType ID:

public class OnBeforeSyncUpdateEventArgs 

{

 public string TypeId { get; }

 public IEnumerable<string> IdList { get; }

}

The return results for onBeforeSyncUpdate event handlers are ignored, unless there is an error. In this case that dss_syncUpdate is stopped and the error is returned in the action response.

Overview

The onAfterSyncUpdate event:

• Runs after an item has been updated in the database during synchronization.
• Runs after a required onAfterUpdate event (@is_required=1).
• Runs once for the whole Item set in the request.
• Can be used to propagate the synchronized Items to external systems if required, e.g., for Mixed Federated Items.

Input/Output arguments

The event handler’s Context Item is empty. The updated Items aren’t loaded. The details about the updated Items are provided in the event arguments of type OnAfterSyncUpdateEventArgs:

public class OnAfterSyncUpdateEventArgs 

{

 public string TypeId { get; }

 public IEnumerable<string> IdList { get; } }

If required, the event handlers can load the items from the database themselves using the type and ID list.

The return results of onAfterSyncUpdate event handlers are ignored, unless there is an error. In the case of an error, the dss_syncUpdate is stopped, the request transaction is rolled back, and the error is returned in the action response.