State Machine
The State Machine Service is responsible for the lifecycle management of resources of types such as a Participant, Container, etc created on the Platform. The State Machine is generic and configurable which can be used by any service for lifecycle management.
State Machine Service provides an API for creating State Machine Configuration (states, sub-states, and state transition rules) of an Entity type. While creating a new State Machine Config, you need to define Event & Reason Codes along with other parameters. So, before moving on to the State Machine Configuration, let's understand State, Entity, Event, and Reason Code
The state defines the current status/behavior of an entity object. An object entity undergoes various transitions of states as events are raised on them. States are devoid of any data/information related to the events that were raised on the entity object. At any given point in time, an entity object can be in only one state.
Substate: A state within the main state is called a Substate.
The Event/Reason Code (ERC) Service has the following functionalities associated with them:
- Entity, Event Code & Reason Code Registry
- Event Code & Reason Codes Mapping & Rules
- Event Code/Reason Code Validation & Listing
An entity is an object or a concept about which data is being stored and operations performed. It can be of different types like users, bags, boxes, vehicles, etc.
The Event/Reason Code (ERC) Service provides APIs for the registration of new entities within CoreOS services (eg. container type bag, pallet, carton, etc. defined in Container Service) and is done automatically when these entities are defined in the respective services.
Entities in the Entity Registry have the following attributes:
Attribute | Description |
tenantId | Tenant Identifier |
entityName | Alphanumeric string (max length - 16 characters) starting with an alphabet only. |
entityCode (Optional) | A numeric string of four digits (starting from 0001) is automatically generated by the service. CoreOS entities should range from 0001 to 0999. Non-CoreOS entities should range from 1000 to 9999. |
description (Optional) | Short description of the entity type. Max length 64 characters. |
isCoreOsEntity (Optional) | Boolean value indicating whether the Entity belongs to CoreOS (cannot be edited). By default, it is false. |
isEnabled (Optional) | Boolean value: True - Entity is enabled (Event Codes & Reason Codes are valid & usable). False - Entity is disabled (Event Codes & Reason Codes are not usable). By default, it is true. |
To create a state machine Entity, call the Create Entity endpoint.
Request bodies are specified in JSON format. The following example shows a request body for creating a state machine Entity:
Member | Description | Validation | Data type |
name | Name of the entity. |  | string |
description | Short description of the event. Max length 64 characters. | nullable: false minLength: 2 maxLength: 255 | string |
events | List of valid events that can be applied to this entity. | minItems: 1 maxItems: 999 pattern: ^(?!E-000)(E[-][0-9][0-9][0-9]) | string |
isEnabled | True - Entity Code is valid & usable. False - Entity Code is not usable. | default: true | boolean |
entityCode | Code of the entity. | pattern: ^(?!0000|^$)([0-9][0-9][0-9][0-9]) | string |
An event is an individual action performed on the Entity object either by a user, app, or system. It is an immutable record of a fact that happened during the lifecycle of the entity object. An event may or may not cause the system to change the state of the entity object. It can be applied to an instance of an entityType.
An event consists of:
- Name- Event name
- Data- Event data is the schema of the data that would be passed when this event is invoked/applied.
To create a state machine Event, call the Create Event endpoint.
Request bodies are specified in JSON format. The following example shows a request body for creating a state machine Event:
Member | Description | Validation | Data type | |
description | Short description of the event. Max length 64 characters. | nullable: false minLength: 2 maxLength: 255 | string | |
eventType | Specifies event is transitional or not. | default: TRANSITIONAL Valid values: TRANSITIONAL, NON_TRANSITIONAL | string | |
reasonCodes | List of valid reason codes that can raise this event code. | example: R-nnnn pattern: ^(?!R-0000|^$)(R[-][0-9][0-9][0-9][0-9])] | string |  |
entities | List of valid entities where this event can be applied. | minItems: 1 maxItems: 999 pattern: ^(?!0000)([0-9][0-9][0-9][0-9]) | string | |
eventCode | Code of the event. | pattern: ^(?!E-000|^$)(E[-][0-9][0-9][0-9]) | string |  |
Event Code: It is a unique alphanumeric code given to an event. Each event code represents a unique event. A particular Event Code can be associated with more than one type of entity.
The Event/Reason Code (ERC) Service provides APIs for the registration of new event codes. Event Codes Registry allows the definition of new Event Codes for an entity and it has the following attributes:
Attribute | Description |
tenantId | Tenant Identifier |
eventCode (optional) | Event Code of the format: E-xxxx-yyy E- Prefix indicating that this is an event code. xxxx- 4 digit entity code string for which this event code is applicable. yyy- 3 digit event code string ranging from 001 to 999 The code will be auto-generated by the service. |
description | Short description of the event. Max length 64 characters. |
reasonCodes (Optional) | List of valid reason codes that can raise this event code. The list can be empty. |
validCurrentStates (Optional) | List of valid current states of the entity when this event code can be applied. If the list is empty, the event code can be applied to any state. |
isEnabled (Optional) | Boolean value: True - Event Code is valid & usable. False - Event Code is not usable. The default value is true. |
Reason Code is a unique alphanumeric code given to a reason that triggers an event. There can be more than one reason which can trigger an event. It provides additional information/context about the event that has occurred.
The Event/Reason Code (ERC) Service provides APIs for the registration of new reason codes. Reason Codes Registry allows the definition of new Reason Codes valid across entities and has the following attributes:
Attribute | Description |
tenantId | Tenant Identifier |
reasonCode (Optional) | Reason Code of the format: R-nnnn R- Prefix indicating that this is a reason code nnnn- 4 digit reason code string ranging from 0001 to 9999 This code will be auto-generated by the service. |
description | Short description of the event. Max length 64 characters. |
isEnabled (Optional) | Boolean value: True- Reason Code is valid & usable. False- Reason Code is not usable The default value is true. |
To create a Reason Code, call the Create Reason endpoint.
Request bodies are specified in JSON format. The following example shows a request body for creating a Reason Code:
Member | Description | Validation | Data type | |
description | Short description of the reason. | nullable: false minLength: 2 maxLength: 255 | string | |
isEnabled | True - Event Code is valid & usable. False - Event Code is not usable. | default: true | boolean | |
reasonCode | Code of the reason. | pattern: ^(?!R-0000|^$)(R[-][0-9][0-9][0-9][0-9]) | string |  |
The State Machine Service provides an API for creating a new State Machine Configuration (states, sub-states, and state transition rules) of an entity type; e.g. users, bags, boxes, vehicles, etc. specified by entityType.
While creating State Machine Configuration, you can create States as well as Sub-states with Event and Reason Codes.
To create a state machine configuration, call the Create State Machine Configuration endpoint.
Request bodies are specified in JSON format. The following example shows a request body for creating a state machine configuration. In the example request bode, the state onboarding has a substate called verifying. Similarly, inactive has a substate dead.
Member | Description | Validation | Data type |
states | List of main states with its substates and transitions. | minItems: 1 |  |
states>name | Name of the state. | minLength: 3 maxLength: 32 pattern: Name can have alphabets and must be 3 to 16 characters long. | string |
defaultSubState | Represents default substate for this state. | minLength: 3 maxLength: 32 pattern: Name can have alphabets and must be 3 to 16 characters long. | string |
subStates |  | minItems: 1 |  |
subStates>name | Name of the sub-state. | minLength: 3 maxLength: 32 pattern: Name can have alphabets and must be 3 to 16 characters long. | string |
transitions | Represents an array of transition rules for this substate. Contains events and the destination state. |  |  |
eventCode | Represents the code of the event for state transition. |  | string |
reasonCode | Represents code of the reason for state transition. |  | string |
destination | Name of the main state and its substate. | minLength: 3 maxLength: 64 |  |
ttl | Time to live is associated with each state of an instance. |  |  |
time | Time to live. | Time string in days, hours, minutes and seconds. minLength: 2 Example- 30m, 1d 12h, 1d 12h 30m 45s etc. | string |
destination | Represents the destination state to which this instance should be transitioned to after ttl expiry. | minLength: 3 maxLength: 64 | string |
callback | Represents callback URL, which can be called to get any info about the state transition of an instance or its terminal ttl expiry or to notify the status of API request. | pattern: A valid URL. | string |
terminalStates | Represents terminal state list for this state. Only the last main state should have terminal states. | minLength: 3 maxLength: 32 pattern: Name can have alphabets and must be 3 to 16 characters long. |  |
terminalTTL | Represents the time to live of an instance in a transactional database after it has reached a terminal state. | Time string in days, hours, minutes, and seconds.minLength: 2 Example- 30m, 1d 12h, 1d 12h 30m 45s etc. | string |
In the above example payload,
- defaultSubState- This represents the default substate for this state.
- transitions- Represents an array of transition rules for this substate. Contains events and the destination state.
- terminalStates- Represents terminal state list for this state. Only the last main state should have terminal states.
- terminalTTL- Specifies the time to live for an instance of this entity type in the transaction database. Once this instance reaches any terminal state, the data for this instance would be deleted from the transaction database, after the specified time.
- callback- The URL endpoint to call once the state transition happens. The transition can be state transition due to ttl or transition due to some event. Also, if an instance of this entity type reaches a terminal state and is being removed from the transaction database, then also, this URL can be called.
The two types of callback URLs can be defined:
- Callback URL on Substate: If an instance of this entity type gets transitioned to this substate, then this URL endpoint can be called.
- Primary Callback URL: If no other callback URL is specified, then the primary callback URL, if specified, can be called.
State Machine Configuration cannot be partially updated. Once the state machine is created for a particular entity type, the main states cannot be modified. The tenant can only add/update substates. Addition/Updation of the rest of the configuration, except names of main states, is allowed.
An instance of an entity is created either by instantiating an entity or by instantiating an entity template.
The State Machine Service has an API to create an instance of a particular entity type with the default state machine configuration.
Member | Description | Validation | Data type |
instanceId | Unique Id of the instance that needs to be onboarded with the state machine configuration. | minLength: 1 maxLength: 64 | string |
state | The default state of the instance to which it should be onboarded to. If not provided, then the instance will be onboarded to the default state mentioned in the state machine config. | minLength: 3 maxLength: 64 | string |
callback | Represents callback url, which can be called to notify the status of API request. | pattern: https?://(www.)?[-a-zA-Z0-9@:%.+~#=]{2,256}.[a-z]{2,4}\b([-a-zA-Z0-9@:%+.~#?&//=]*) | string |
Here, instanceId- Unique Id of the instance that needs to be onboarded with the state machine configuration. state- The default state of the instance to which it should be onboarded. If not provided, then the instance will be onboarded to the default state mentioned in the state machine configuration. callback- Represents callback URL, which can be called to notify the status of the API request.
State transition can be triggered due to the following events:
- API requests: A request made via API triggers a state transition. Depending on the API request, the instance moves to a new state or sub-state.
- Time-based (TTL): TTL specifies the time to live for an instance in the transaction database. Once the instance reaches a terminal state defined by the state machine configuration it triggers a state transition.
🚧 NOTE
Transition can happen between Substates (across different states) and NOT between substates to states.
The following data points associated with an instance holding a particular state need to be captured:
1- Transitioned at (Timestamp when the state was set) 2- Transition requests require the following information:
- Instance ID (whose state is being transited)
- Event Name
- Source application ID
- User ID (User requesting the transition)
📘 NOTE
You can configure an attribute and its validations at the time of creating an event for an Entity/entities. Example: While updating the instance of an entitytype - package, statemachine can check whether an attribute item count was applied or not and it can also validate the data range if applied.
The Tenant has the option to define a list of Event names for transition as well as a list of States. For each State, the Tenant can define a set of sub-states (required) and the corresponding rules for state transition.
For each State, a substate (configurable by the Tenant) is kept as default. Transitions from a state/ substate to another state always happen to the default substate of the destination State.
The rules for substate transition comprise the following:
- Allowed Destination Substate- The Substate on which the instance would be transitioned when some event is provided.
- Transition Rules - List of Event Names on which the transition is allowed. Transition is defined with the combination of the (event + destination) or (destination + TTL).