Update Entity with Conditional Updates
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.
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.
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.
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:
This API will be passed using the PUT method to update the conditional expression within the request body.
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. |
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.
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.
Successful Entity Instance Update
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.
Failed Entity Instance Update Due to Condition Not Met
- 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.
Failure event when provided with incorrect syntax
Payment Amount Greater than 100 and User Status Active
This request updates a user's properties, ensuring that the update only occurs if paymentAmount is greater than 100 and userStatus is active.
Age Below 18 or Parental Consent Given
This condition allows the update if either the user's age is below 18 or they have parental consent.
User Not Suspended
The update is allowed only if the user is not suspended (isSuspended is false).