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:

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:

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:

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:

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:

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:

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:

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:

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.

In the above example payload,

The two types of callback URLs can be defined:

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.

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:

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:

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: