Update Entity with Conditional Updates

overview conditional updates enable developers to specify criteria that must be met for an update to occur this feature ensures that updates are executed only when certain preconditions are satisfied, allowing for greater control over data integrity and business logic it ensures that updates reflect valid business rules prevents unintended changes to data enhances data integrity by enforcing conditional logic the conditional updates feature also applies to batch operations you can specify conditional expressions for multiple entity updates in a single api call these conditional updates will be applied to entity instance updates and batch updates using jexl syntax with conditional expression a conditional update can be performed on any attribute in the update payload conditional expression developers can define conditions using a simple syntax based on the jexl (java expression language) allowed symbols the following symbols are allowed in the conditional expression symbol description ( opening parenthesis ) closing parenthesis == equal to != not equal to > greater than >= greater than or equal to < less than <= less than or equal to && logical and || logical or validation the system checks the syntax and the existence of attributes in the schema before processing the update before processing an update request syntax check the system validates the conditional expression for correctness boolean evaluation the expression must evaluate to a boolean value event handling success if the conditions evaluate to true, the update proceeds as planned failure if the conditions are not met, an updationfailedevent is emitted, detailing the reason for the failure use case in the tms (transportation management system) platform, a common use case for conditional updates might involve invoice management for instance, an invoice should only be marked as "closed" if the associated payments are fully processed and marked as "paid " using conditional updates, this requirement can be enforced programmatically using conditional updates conditional updates apply to both entity individual instance updates and bulk updates to use the conditional updates in the entity service apis for instance updates, it will include a core attribute called conditionexpression of type string, which contains the jexl syntax for evaluation conditions are defined within the conditionexpression attribute using jexl syntax they can include equality checks compare an attribute to a value inequality checks check for non equality comparison operators use greater than, less than, etc logical operators combine multiple conditions entity instance updates when updating a single entity instance, the request payload must include a conditionexpression alongside the attributes you wish to modify here’s how it works http request this api will be passed using the put method to update the conditional expression within the request body https put {{baseurl}}/\ entitytypepluralname/\ entityid request parameters parameters type description conditionalexpression string a jexl expression that evaluates to true for the update to proceed properties object the attributes of the entity you want to update payload example json http put {{baseurl}}/\ entitytype/\ entityid content type application/json { "properties" { "status" "closed" }, "conditionexpression" "properties paymentstatus == 'paid'" } understand this payload url replace {{baseurl}} , \ entitytype , and \ entityid with the appropriate endpoint details content type specifies that the request body is in json format properties \ this object contains the attributes you want to update here, you're changing the status of the invoice to "closed " only the attributes specified within this object will be modified conditionexpression the expression properties paymentstatus == 'paid' must evaluate to true for the update to proceed if the current paymentstatus of the invoice is not "paid," the update will be rejected batch updates info conditional updates can also be applied to batch updates, where multiple entity instances are updated in a single request each entry in the batch can have its own conditionexpression to learn about how to integrate batch updates, see the update entities in batch with conditional updates section json examples example 1 successful entity instance update sample request json https put {{baseurl}}/invoices/invoice123 content type application/json { "properties" { "status" "closed" }, "conditionexpression" "properties paymentstatus == 'paid'" } in this example , this request attempts to update the status of a specific invoice (identified by invoice123) to "closed " however, it includes a condition that must be met for the update to occur conditional logic the conditionexpression states that the update will only proceed if the paymentstatus of the invoice is currently set to "paid " this ensures that an invoice cannot be closed unless it has been fully paid expected outcome if the paymentstatus is "paid," the update will succeed, and the invoice status will change to "closed " the server will respond with a success message indicating the update was performed if the paymentstatus is anything other than "paid," the server will reject the update, returning an error message that explains the condition was not met sample response json { "message" "entity updated successfully ", "entityid" "invoice123" } example 2 failed entity instance update due to condition not met sample request https put {{baseurl}}/invoices/invoice123 content type application/json { "properties" { "status" "closed" }, "conditionexpression" "properties paymentstatus == 'paid'" } url ({{baseurl}}/invoices/invoice123) as before, this url targets the specific invoice instance for updating content type (application/json) this header indicates that the request body is formatted in json request body properties the status attribute is still being set to "closed " conditionexpression the same condition checks if paymentstatus is "paid " however, in this case, let’s assume the actual payment status is not "paid " expected outcome the request fails because the condition is not met the server returns an error code and a description indicating that the update could not proceed sample response json { "error" { "code" "101830023419", "description" "condition expression properties paymentstatus == 'paid' not met " } } example 3 failure event when provided with incorrect syntax { "error" { "code" "101830021054", "description" "conditional expression evaluation failed invalid conditional expression properties manufacturer !==! 'honda'", "additionalinfo" {} }, "request" { "uri" "/core/api/v2/entity/threevehicles/threevehicles 0bd46f15 d580 5509 85fc 98e499ca95f1", "method" "put", "querystring" "{}", "body" { "properties" { "manufacturer" "wonda" }, "callback" { "url" "https //webhook site/71b9fd76 2631 4710 835f 8e9aaa5a772a", "meta" { "sitcd" false } }, "conditionexpression" "properties manufacturer !==! 'honda'" } } } a few more valid conditional expressions example 1 payment amount greater than 100 and user status active json put {{baseurl}}/users/user123 content type application/json { "properties" { "paymentamount" 120, "userstatus" "active" }, "conditionexpression" "(properties paymentamount > 100) && (properties userstatus == 'active')" } this request updates a user's properties, ensuring that the update only occurs if paymentamount is greater than 100 and userstatus is active example 2 age below 18 or parental consent given https put {{baseurl}}/profiles/profile123 content type application/json { "properties" { "age" 16, "hasparentalconsent" true }, "conditionexpression" "(properties age < 18) || (properties hasparentalconsent == true)" } this condition allows the update if either the user's age is below 18 or they have parental consent example 3 user not suspended json http put {{baseurl}}/users/user123 content type application/json { "properties" { "issuspended" false }, "conditionexpression" "properties issuspendend == false" or "properties issuspendend != true" } the update is allowed only if the user is not suspended ( issuspended is false )