🚀 NEW! Build mobile ready forms in minutes with JigxForms. The JigxForms Beta is now open!
Sign up today!
Ctrlk
System StatusSamples on GitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Offline remote data handling

Dealing with offline remote data is fundamental to ensuring data synchronization and consistency between the mobile app and the remote data source, allowing users to continue using the app and performing actions without interruption. Queue operations provide the functionality needed when the device regains network connectivity and manages a sequence of elements in a specific order. The commands in the queue can be manipulated to reduce the number of calls to the remote data store or Dynamic Data.

What happens to data when you are offline?

  1. Data Capture Offline:

    • When the mobile app is offline, any actions that require remote data interaction, such as submitting a form, uploading a file, or syncing data, are queued.

    • Each action is captured and stored in a queue in the local data provider on the device.

  2. Network Monitoring:

    • The app monitors the network status. It triggers the dequeuing process when it detects that the device has regained connectivity.

  3. Dequeue and Sync:

    • The app starts processing the commands in the queue. It dequeues each command and attempts to send it to the remote server.

    • If the operation is successful, the app removes the command from the queue.

How to configure the queue

In the execute-entity, execute-entities , and submit-form actions, the queueOperation property is configured to determine how the record must be handled in the queue when the device is offline. There are two configuration options:

Property
description

replace

All queued commands for the specified record and method type are replaced with the current action. For example, a record is created and then updated a few times. Using replace for the update method results in only two commands in the queue for the record: create and update. If replace is not used, there will be a command for every action: create, update, update, update. Replace is recommended for backend systems with rate limits. The queueOperation: replace requires an id (must be in lowercase). This is configured in the:

  • Parameter of the execute-entity action with an id configured in the parameters of the function file.

  • data property in the execute-entity action.

add

All commands are added to the queue. When the queueOperation property is omitted, the default is add.

actions:
  - children:
      - type: action.execute-entity
        options:
          title: Update Customer
          provider: DATA_PROVIDER_REST
          entity: customers
          method: update
          # Use replace to ensure you only have one update on the queue related
          # to a record. Not adding the replace will not break the solution but
          # will help to avoid chattiness and scenarios where backends have 
          # rate limits.
          queueOperation: replace
          function: rest-update-customer
          # Parameters to update in the remote server.
          parameters:
            # id is a required property for the replace queue
            id: =@ctx.jig.inputs.customer.id
            firstName: =@ctx.components.firstName.state.value
            lastName: =@ctx.components.lastName.state.value
            companyName: =@ctx.components.companyName.state.value
            address: =@ctx.components.address.state.value
            city: =@ctx.components.city.state.value
            email: =$lowercase(@ctx.components.email.state.value)
          # Data records to update in the local SQLite table. 
          data: 
            id: =@ctx.jig.inputs.customer.id
            firstName: =@ctx.components.firstName.state.value
            lastName: =@ctx.components.lastName.state.value
            companyName: =@ctx.components.companyName.state.value
            address: =@ctx.components.address.state.value
            city: =@ctx.components.city.state.value
            email: =$lowercase(@ctx.components.email.state.value)

Examples of configuring the required id property when using queueOperation: replace.

How to clear the queue

For scenarios where operations on a record must be treated as draft and all queued commands must be removed without impacting the local record, use the clear-queue action, and specify the id of the record and a title for the action. See clear all commands in the queue example.

Queue handling for delete methods

When using the replace property with a delete method, all commands on the queue for the specified record are removed. The delete method will still delete the local entity record as expected, for example while offline a record is created with a tempId, then updated, and then deleted with a queueOperations: replace, the commands for that record are removed from the queue and local entity will also be deleted. This avoids the need for the full cycle of calls to be sent to the backend (create, update, delete) if the end result is that the record is deleted.

If the record to be deleted has a valid Id then the queueOperations: add is used to add the record to the queue, when the device is back online the queue is processed and the record is deleted using the function.

If you want to cater for both tempId and a valid Id records when offline in one queueOperation configuration use the following expression =$isTempId(@ctx.current.item.id) ? replace:add

Note that queueOperation: replace with the delete method does not behave the same for Dynamic Data as it does for REST. Dynamic Data does not generate a tempId, so the $isTempId() check is not applicable. When working with Dynamic Data, you must use queueOperation: add for delete operations, as replace clears the queue without executing the delete method.

Handling TempIds

All tempIds for a record are replaced in all other queued commands if a valid id is returned. If you use a record's id in another record while offline and a valid id is returned back when the device is back online, Jigx updates the tempId used in all the other records that used it with the valid id. This makes for smoother integration with backend systems as the ids will match up. This is applicable to remote stores, but not to Dynamic Data which does not generate tempIds. See working with REST ids for more information on returning the id.

Dynamic Data change tracking & queuing

What you need to know about how Dynamic Data table changes are tracked and queued:

  • Applies to Dynamic Data tables defined as default/table name

  • All changes made to the tables are automatically queued

  • Purpose is to facilitate offline sync / cloud sync support

  • Supported operations are:

    • CRUD operations

    • SQL execution

    • Find & replace

  • Behavior is automatic and consistent

  • Use queueOperations with add or replace

Behavior overview

The change tracking and queuing is executed in the following way:

Update Dynamic Data table → Temp table created → Changes detected → Batch queued → Temp cleaned up

Examples and code snippets

See the Dynamic data examples for examples demonstrating how to use queueOperation with the execute-entity action when working with a Dynamic Data database.

Execute-entity with queueOperation (replace)

In this example, when the device is offline and a customer record is created and then updated multiple times, only one create and one update command is queued. When the device is back online the queue is cleared. The remote data store returns an id that we can use to map back to the record locally in the outputTransform of the function (rest-create-customer). queueOperation is not required for the create of the customer because once the device comes online, the record will be created, and the id from the remote data store will be returned and any records with the same tempId will be updated with the returning id and will update the correct record. The queueOperation: replace is rather used in the update-customer jig.

Execute-entity with queueOperation (add)

In this example, when the device is offline and a customer record is updated multiple times , all the update commands are queued. When the device is back online the queue is cleared.

Execute-entity (delete) with queueOperation (replace)

In this example, when the device is offline and a customer record is updated multiple times and then deleted, all the the commands for the record are removed from the queue and local entity is deleted. When the device is back online the queue is cleared.

Execute-entity with queueOperations when no id is returned

In this example, the remote data store does not return an id, and we need to sync the data before we get the correct backend id for the record. We need to be careful not to create and update the same record on the queue because the backend cannot associate the records after the sync. To accommodate for this in the update-customer jig we configure two execute-entity actions.

  • The first action checks to see if a record has a tempId by using the following expression when: =$isTempId(@ctx.jig.inputs.customer.id). If the record on the queue has a tempId, we replace it using the create method with a new item that will be placed on the queue.

  • The second action checks to see if the record has a valid Id rather than a tempId by using the following expression when: =$not($isTempId(@ctx.jig.inputs.customer.id)). If the record on the queue has a valid id, we replace it using the update method with an item that will be placed on the queue.

Clear commands in the queue for a record

In this example, a secondary button is added to clear the queue for commands for a specific record using the action.clear-queue.

Testing and debugging queues

As you add the queueOperation property to actions, it is helpful to test or debug that the commands are being executed as configured. Here is a jig that can help you see the commands being queued when the device is offline, and then see the queue clear when the device is back online.

PreviousOffline SolutionsNextFile handling

Last updated

Was this helpful?