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.).

• The add/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 add and 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.)