Entity Change

Entity Sync allows you to handle changes made to entities. There are two primary methods for fetching these changes.

Method 1: EntityChange Query

The first method is to use our EntityChange query. This query allows you to fetch all changes or specific changes that were made 7 days back based on an lastLocalId.

query GetEntityChanges
{
  entityChangesSync(lastLocalId: 123) {
    nodes {
      localId        # Incremental id that matches with LocalId
      entityId       # The entity´s id that were changed
      type           # The entity's type that were changed
      {
        id
      }
      statusCreated  # The time and date when the change occured
      pruned         # Is true if all rows before this row was pruned. This indicates that you have missed data.
    }
  }
}

Example of how you start using entity change.

• In addition to receiving a localId, you will also get an indication if you're lagging in updates and need to re-run a full sync.
• The latest localId is provided either when a pruned value is encountered or when you request lastLocalId with a value of null.

query startingPoint 
{
  entityChangesByEntityTypeIdSync(
    lastLocalId: null
    entityTypeId: "ledgerNote"
    first: 1
  ) {
    nodes {
      entityId
      statusCreated
      pruned
      type {
        displayName
        id
      }
      localId
    }
  }
}

Pruned

When changes that were made are older than 7 days, they are pruned. The first row after the pruned rows will have the value pruned=true.

If you encounter a row with pruned=true, it indicates that you may have missed some data.

Please note that rows can also be pruned outside the 7-day window, so it is important to be prepared to handle this scenario.

Method 2: Subscriptions

The second method is to subscribe to changes as they occure. This real-time functionality is implemented using GraphQL subscriptions. Clients can subscribe to specific events and receive the associated data as it becomes available.

Subscription Examples

Subscribe to Changes in Any Entity

This subscription will notify you of any change made to an entity:

subscription SubscribeOnEntityChange
{
  entityChange {
    localId
    entityId
    entityTypeId
  }
}

Subscribe to Changes in a Specific Entity or Entity Type

This subscription will notify you if a specific entity or entity type, identified by its Id, changes:

Specific Type

subscription testSubscribeOnEntityByTypeChange
{
  entityChangeByIdOrType(idOrType: "contract")
  {
    localId
    entityId
    entityTypeId
  }
}

Specific Id

subscription testSubscribeOnEntityByIdChange
{
  entityChangeByIdOrType(idOrType: "b40ae3a8dfac40ecba4c2624342f588d")
  {
    localId
    entityId
    entityTypeId
  }
}

Handling Missed Data

In the event of a disconnection, you can manage missed events by using queries that return EntityChange. For example, if you are running a subscription on an entity and you disconnect with the last row returned having:

Id: "AUniqueGuid" LocalId: 123

You can query for changes made after LocalId: 123, like this:

query GetEntityChanges
{
  entityChangesSync(lastLocalId: 123) {
    nodes {
      localId
      entityId
      pruned
    }
  }
}

After a successful change sync, you can resume subscribing to new changes.