Update Attributes and State with a Single API
This Entity API enhancement enables developers to update both the state of an entity and its attributes in a single idempotent API call. This is useful when both actions need to be performed in the same flow to ensure that they are validated together and handled atomically.
Key Benefits:
- Idempotency: It ensures the same request can be made multiple times without causing unintended side effects.
- Atomic Operations: Both state transition and attribute updates are processed as a single transaction.
- Simplified Workflow: Reduces the number of API calls and validation steps for common use cases.
When integrating, you will need to include both properties (for attribute updates) and the stateTransition object (for state changes) in the request body. If only one of these is needed, you can omit the stateTransition or use the API as usual with just the properties field.
The system will validate both the state transition and attribute update together. This ensures consistency and accuracy when performing both operations at once.
To update entity attributes and perform state transitions in a single call, pass the stateTransition object along with the existing properties object in the API request body.
Step 1: Include a stateTransition object in the request body In addition to the existing properties, you can now include a stateTransition object in the request body:
- eventCode: Code representing the state transition event.
- reasonCode: Code representing the reason for the state transition.
The above request body explains the following:
- properties: The properties object contains the key-value pairs of attributes that need to be updated for the entity instance. This is the same behavior as the standard attribute update.
- stateTransition: The stateTransition object is new and allows you to specify details about the state transition. This is an optional field, but when included, both the state transition and the properties will be validated and updated together. stateTransition Object Fields:
- eventCode: Specifies the event associated with the state transition (e.g., "E-351").
- reasonCode: Provides the reason or justification for the state transition (e.g., "R-5334").
Step 2: When the API is invoked with a stateTransition object, the system will produce one of two events based on the outcome.
The two new events have been introduced to handle the result of this combined operation:
- EntityAttributeAndStateUpdationSuccessEvent: This event is triggered when both the attribute update and state transition are successful.
- EntityAttributeAndStateUpdationFailedEvent: This event is triggered if either the attribute update or the state transition fails.
Both success and failure events will include two new fields:
- smEventCode: Reflects the event code of the state transition.
- smReasonCode: Reflects the reason code for the state transition.