Concurrency handling
Concurrency handling is a method designed to prevent data loss when multiple updates occur on the same record simultaneously or within a short time frame.
For instance, if two AppConnect recipes attempt to update the same record simultaneously, changes made by Recipe 1 might unintentionally overwrite those from Recipe 2. To address this, Insightly is introducing concurrency handling—a safeguard that checks whether an update is based on the latest version of a record. This ensures that only valid, up-to-date changes are applied, helping maintain data accuracy and integrity.
How It Works
To handle concurrency when updating records, Insightly now includes a special “version tag” for each record. This is called an ETag. This helps the system determine whether an update is happening on the latest version of the record or an old version.
ETag = the record’s version number (automatically assigned by Insightly). Each time the record changes, an updated ETag is returned. This field can be located in the payload received from Insightly.
If-Match = a way of saying “only update this record if it’s still the version I last saw”. This tells Insightly which version your update is based on.
- Successful update - If the If-Match header value matches the current ETag value of the record stored, the update is applied. This means the change was made to the most up-to-date record.
- Unsuccessful update - If the If-Match header value does not match the current ETag value of the record stored, the update is rejected with a 412 Precondition Failed error. This means the update was based on an older version of the record and could not be applied. When this happens, the recipe will need to decide what to do. It could decide to fail the transaction or retry it.
Concurrency handling setup
AppConnect recipes use Insightly API to create, read, update, or delete records (CRUD operations). Concurrency handling can only be applied to “Update existing entity” actions.
To enable it, the following setup is required:
If-Match header:
In the "Update existing entity" action, users will find an optional "Headers" field.
This field takes Key-Value pair as input.
Key : "If-Match"
Value : The "ETag" field from the previous step added as a data pill.
Having this setup on the Update action indicates that concurrency handling should be enforced.
If the Headers or If-Match key-value are missing, concurrency handling will not be applied to the Update action.
Recipe Setup
In the sample recipe below, the recipe handles concurrency errors by reloading the latest version of the record and retrying the update up to three times if needed.
Sample recipe setup:
Break down of how to set up the recipe for using Concurrency handling:
Create a new recipe in AppConnect.
Create a new trigger > Select an object.
Create a "Monitor" step by selecting "Handle errors" actions.
Create an "Update existing entity" action within the Monitor block.
Set up an "Error Found?" block - This block allows us to detect a 412 Precondition Failed error, which occurs when the stored record has changed and the ETag no longer matches the one provided in through the recipe.
Set "Retry actions in Monitor block?" to "Do not retry".
Create an "IF condition" action > Select "Error message" under "Data field" > Set "Condition" as "contains" > Set "Value" as "412".
This step is optional. To perform a wait action before retrying the update again, utilize "Scheduler by Workato" action > Select "Wait for time duration" > Set "Interval" to "Enter custom value" for adding wait time in seconds > Set the number of seconds you want to wait before retrying the actions again.
For the "Yes" block of the "IF" condition action, create a new "Monitor" step by selecting the "Handle errors" actions.
Create a "Get single entity by object name and ID" action > Select the object name > Set the "Entity Id" field to "Record Id" from the previous step, which contains the value of the record that needs to be updated.
Copy the "Update existing entity" action for which concurrency handling headers are set > Paste it after the "Get" action mentioned above > Inside this newly pasted action, remap the "ETag" field in the Headers "Value" field to the one from the "Get" action > Remap all other data fields if necessary.
Setup the Error found block:
Select the number of times you want to retry.
Select the duration you want to wait before retrying.
Set "Data" as "Error message" > Set "Condition" as "contains" > Set "Value" as "412".
If the 412 Error persists or if actions run into new errors, you can either choose to continue with the recipe or stop the current job.
OR