Sync actions

Sync actions focused on synchronization processes, such as starting sync operations, managing sync scopes, or deleting sync-related data. These actions ensure data consistency across different parts of the system.

Types of Syncs

Action name	Action	Description
Delete sync scope	action.delete-sync-scope	Deletes a specific sync scope from the database table using its sync-scope ID.
Delete sync status	action.delete-sync-status	Deletes a specific sync status from the database table using its sync-status ID.
Start sync scope	action.start-sync-scope	Starts or restarts a specific sync scope. The scope completes once all defined sync-entity actions/datasources have finished.
Sync entities	action-sync-entities	Syncs the local database with the live database on the server.

Key Components

1. The _syncStatus Table

This table tracks the status of individual sync operations with the following properties:

Column	Description
id	Unique identifier for the sync operation.
provider	The data provider being used.
entity	The entity being synchronized.
functionId	The function handling the sync.
state	Current sync state, which is either: syncing synced failed
timestamp	When the last status change occurred.
error	Contains any errors that occurred during sync.

2. The _syncScope Table

This table tracks declared sync scopes and monitors their overall progress. The table allows a sync scope to be started and use a datasource to track the progress of the sync scope.

Column	description
id	Comes from the instanceId of the action.start-sync-scope
state	Overall scope state, which is either: syncing: Not all instances completed (i.e. failed or succeeded), some may not have started yet. failed: All instances completed, at least one failed synced: All instances completed successfully interrupted: App was closed, crashed, or put in the background
notStarted	Count of instances not yet started.
syncing	Count of instances currently syncing, and have not completed or been interrupted.
failed	Count of instances that completed with errors.
synced	Count of instances that completed successfully.
lastStartedAt	Timestamp when scope last started (epoch milliseconds).
lastFailedAt	Timestamp when scope last failed (epoch milliseconds).
lastSyncedAt	Timestamp when scope last succeeded (epoch milliseconds).
details	JSON structure with per-instance details and failure information.

How to use sync scopes

Step 1: Define the action-start-sync-scope

Use action.start-sync-scope to initialize a sync scope with a unique instanceId:

- type: action.start-sync-scope
  instanceId: "sync-scope-lookup-data"
  options:
    instanceIds:
      - sync-tasks-and-categories-via-dd
      - sync-local-books-via-rest
      - sync-acuerp-customers-via-rest
      - sync-acuerp-stock-items-via-rest

Step 2: Define individual sync actions

Each sync operation needs its own action.sync-entities with a matching instanceId:

- type: action.sync-entities
  instanceId: sync-tasks-and-categories-via-dd
  options:
    provider: DATA_PROVIDER_DYNAMIC
    entities:
      - default/tasks
      - default/task-categories

- type: action.sync-entities
  instanceId: sync-local-books-via-rest
  options:
    provider: DATA_PROVIDER_REST
    entities:
      - entity: local/books
        function: list-books-local-rest

Step 3: Conditionally trigger sync

Prevent multiple simultaneous syncs using a condition:

- type: action.action-list
  when: "=@ctx.datasources.sync-scopes[id = 'sync-scope-lookup-data'].state = 'syncing' ? false : true"
  options:
    title: Sync data
    actions:
      # Your sync scope and sync actions go here

Monitoring Sync Progress

Query _syncStatus for individual operations

datasources:
  sync-status:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_LOCAL
      entities:
        - _syncStatus
      query: |
        SELECT
          id, 
          provider, 
          entity, 
          functionId, 
          timestamp, 
          state, 
          error
        FROM [_syncStatus]
        ORDER BY provider

Query _syncScope for overall progress

datasources:
  sync-scopes:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_LOCAL
      entities:
        - _syncScope
      query: |
        SELECT 
          id, 
          state, 
          timestamp, 
          lastSyncedAt, 
          lastStartedAt, 
          lastFailedAt, 
          notStarted, 
          syncing, 
          synced, 
          failed, 
          details 
        FROM [_syncScope]

Benefits

1. Coordinated syncing: Manage multiple entity syncs as a single operation.

2. Progress tracking: Monitor counts of syncing, synced, failed, and pending operations.

3. Error Handling: Track failures with detailed error information.

4. State Management: Prevent duplicate syncs and handle interruptions.

5. Historical Data: Access timestamps for sync events and detailed operation history.

Best practices

• Always assign unique instanceId values to each sync operation.

• Use conditional logic to prevent overlapping sync operations.

• Monitor the _syncScope state to provide user feedback.

• Handle the interrupted state for better user experience when apps are put in the background.

• Check the details column for granular failure information.