Understanding Aras Innovator Data Synchronization Service (DSS)

In a world where companies often operate multiple Aras Innovator instances, keeping data consistent across them can be a challenge. The Data Synchronization Service (DSS) is designed to make this easier by enabling one-way synchronization from a Source system to a Destination system. I have seen some implementations that support two-way synchronization, but let’s keep it simple for the sake of clarity.

What is DSS?

DSS is a set of APIs and events that allow you to:

• Add items from the source to the destination.
• Update already synchronized items.
• Purge (delete) items that are no longer needed.

It’s particularly useful for:

• Multi-site PLM environments.
• Master data replication.
• Keeping sandbox/test environments up-to-date.

Key Concepts

Terminology

• Source System – Where the data originates.
• Destination System – Where the data is synchronized to.
• Synchronization Scope – Which items and item types are included.
• dss_SyncReceiver Identity – Special permission group that can execute sync operations.

Why Not Use Standard Add/Update/Delete?

Standard Aras item actions:

• Perform extra logic like workflows, lifecycle state changes, and validations.
• Calculate values like id, generation, and config_id automatically.

DSS actions:

• Bypass unnecessary logic for sync operations.
• Allow direct database writes with controlled server events.
• Support overwriting system fields when needed.

Main DSS Actions

1. dss_syncAdd
   • Adds a new item exactly as it exists on the source.
   • Requires id, config_id, generation.
   • Skips standard add events, uses onBeforeSyncAdd / onAfterSyncAdd.
2. dss_syncUpdate
   • Updates existing items without versioning.
   • Uses onBeforeSyncUpdate / onAfterSyncUpdate.
3. dss_syncPurge
   • Removes an item from the destination if it’s deleted in the source.

Security

Only users or identities in dss_SyncReceiver can run DSS actions.
Permissions are configured separately on each system, ensuring only intended data is synced.

Mermaid Diagram – DSS Workflow

sequenceDiagram
    participant Source as Source System
    participant API as DSS API
    participant Dest as Destination System

    Source->>API: Send Sync Request (Add/Update/Purge)
    API->>Dest: Authenticate as dss_SyncReceiver
    Dest->>Dest: Run Sync Action (dss_syncAdd/Update/Purge)
    Dest-->>API: Return Success/Failure
    API-->>Source: Confirmation

Practical Tips

• Always define Synchronization Scope to avoid unwanted data changes.
• Use Global Version property to track updates.
• Keep Source and Destination metadata aligned to prevent errors.
• Test with a staging environment before production rollout.

Examples

1. Adding an Item with dss_syncAdd

This example adds a Part item from the source system to the destination system exactly as it exists, including id, config_id, and generation.

<Item type="Part" id="7073098207234317BBC2CA865413CAD5" action="dss_syncAdd">
  <config_id>7073098207234317BBC2CA865413CAD5</config_id>
  <generation>1</generation>
  <major_rev>A</major_rev>
  
  <item_number>PA-1586-0</item_number>
  <name>Engine Assembly</name>
  <description>Main propulsion unit</description>
  <classification>Mechanical/Assembly</classification>
  <created_on>2025-08-10T14:35:00</created_on>
  <created_by_id>5C8B108AF37C45B1B9A31B5B1D234F20</created_by_id>
</Item>

Key Points

• id, config_id, and generation must be present.
• This bypasses normal add events and uses onBeforeSyncAdd / onAfterSyncAdd.
• Fields like created_on and created_by_id can be set directly.

2. Updating an Item with dss_syncUpdate

This example updates the name and description of an already synchronized Part.

<Item type="Part" id="7073098207234317BBC2CA865413CAD5" action="dss_syncUpdate">
  <name>Main Engine Module</name>
  <description>Updated description from Source System</description>
  <modified_on>2025-08-12T10:20:00</modified_on>
  <modified_by_id>3D5B209AA94C4B9E94A3CFA9E91CBA76</modified_by_id>
</Item>

Key Points

• Works only if the item already exists in the destination.
• Skips normal update events; uses onBeforeSyncUpdate / onAfterSyncUpdate.
• Does not create a new version for versionable items.

3. Purging an Item with dss_syncPurge

If the item was deleted in the source, you can remove it from the destination:

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

Key Points

• Deletes the record directly.
• Uses onBeforeSyncPurge / onAfterSyncPurge if defined.
• Make sure your synchronization logic handles dependencies.

4. Example: Synchronizing from Two Source Systems

When you have two sources pushing different item types to the same destination:

Source A: Sends Parts and Documents
Source B: Sends Change Orders
Destination: Accepts both, but keeps them in separate scopes

Configuration Tip

• Assign different users for each source.
• Ensure each user/identity in the destination has permission only for its scope.

Mermaid Example – Two Source Systems

flowchart LR
    A[Source System A] -- Parts & Docs --> D[Destination System]
    B[Source System B] -- Change Orders --> D
    D --> DB[(Destination Database)]