search
System StatusSamples on GitHub

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.

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

hashtag
How to configure the queue

In the execute-entityarrow-up-right, execute-entitiesarrow-up-right , and submit-formarrow-up-right 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 can either be 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: [email protected]
            firstName: [email protected]
            lastName: [email protected]
            companyName: [email protected]
            address: [email protected]
            city: [email protected]
            email: =$lowercase(@ctx.components.email.state.value)
          # Data records to update in the local SQLite table. 
          data: 
            id: [email protected]
            firstName: [email protected]
            lastName: [email protected]
            companyName: [email protected]
            address: [email protected]
            city: [email protected]
            email: =$lowercase(@ctx.components.email.state.value)

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

hashtag
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 arrow-up-rightexample.

hashtag
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 delete 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

hashtag
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. See working with REST ids for more information on returning the id.

hashtag
Examples and code snippets

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

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

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

hashtag
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 accomodate 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.

hashtag
Clear all commands in the queue for record

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

hashtag
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?