State Machine

Introduction to State Machine Service

The State Machine Service is a responsible for 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.

State

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.

📘

State and Sub-state creation will be defined ahead in this document under State Machine Configuration.

Event/Reason Code (ERC) Service

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

Entity

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) 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:

{
   "name":"Entity1",
   "description":"This is a description for Entity1",
   "events":[
      "E-022",
      "E-023",
      "E-024"
   ],
   "isEnabled":true
}

Event & Event Code

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:

{
   "description":"new NON TRANSITIONAL event",
   "eventType":"NON_TRANSITIONAL",
   "entities":[
      "1000"
   ],
   "reasonCodes":[
      "R-0001",
      "R-0002"
   ],
   "isEnabled":true
}

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

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 Post reasons endpoint.

Request bodies are specified in JSON format. The following example shows a request body for creating a Reason Code:

{
   "description":"ReasonCode1",
   "isEnabled":true
}

State Machine Configuration

The State Machine Service provides an API is 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 Substates with Event and Reason Codes.

To create a state machine configuration, call the Create a new 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.

{
   "states":[
      {
         "name":"onboarding",
         "defaultSubState":"onboarding",
         "subStates":[
            {
               "name":"onboarding",
               "transitions":[
                  {
                     "eventCode":"E-022",
                     "destination":"onboarding:verifying",
                     "reasonCode":"R-0001"
                  }
               ]
            },
            {
               "name":"verifying",
               "transitions":[
                  {
                     "eventCode":"E-022",
                     "destination":"active:active"
                  }
               ]
            }
         ]
      },
      {
         "name":"active",
         "defaultSubState":"active",
         "subStates":[
            {
               "name":"active",
               "transitions":[
                  {
                     "eventCode":"E-023",
                     "destination":"inactive:inactive",
                     "reasonCode":"R-0001"
                  }
               ]
            }
         ]
      },
      {
         "name":"inactive",
         "defaultSubState":"inactive",
         "subStates":[
            {
               "name":"dead"
            },
            {
               "name":"inactive",
               "transitions":[
                  {
                     "eventCode":"E-024",
                     "destination":"inactive:dead",
                     "reasonCode":"R-0001"
                  }
               ]
            }
         ],
         "ttl":{
            "time":"1d",
            "destination":"inactive:inactive"
         },
         "terminalStates":[
            "dead"
         ]
      }
   ],
   "terminalTTL":"600s",
   "callback":"http://examplecallbackurl.com"
}

In the above example payload,

  • defaultSubState- 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 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.

{
   "states":[
      {
         "name":"onboarding",
         "defaultSubState":"onboarding",
         "subStates":[
            {
               "name":"onboarding",
               "transitions":[
                  {
                     "eventCode":"E-022",
                     "destination":"onboarding:verifying",
                     "reasonCode":"R-0001"
                  }
               ]
            },
            {
               "name":"verifying",
               "transitions":[
                  {
                     "eventCode":"E-022",
                     "destination":"active:active"
                  }
               ]
            }
         ]
      },
      {
         "name":"active",
         "defaultSubState":"active",
         "subStates":[
            {
               "name":"active",
               "transitions":[
                  {
                     "eventCode":"E-023",
                     "destination":"inactive:inactive",
                     "reasonCode":"R-0001"
                  }
               ]
            }
         ]
      },
      {
         "name":"inactive",
         "defaultSubState":"inactive",
         "subStates":[
            {
               "name":"dead"
            },
            {
               "name":"inactive",
               "transitions":[
                  {
                     "eventCode":"E-024",
                     "destination":"inactive:dead",
                     "reasonCode":"R-0001"
                  }
               ]
            }
         ],
         "ttl":{
            "time":"1d",
            "destination":"inactive:inactive"
         },
         "terminalStates":[
            "dead"
         ]
      }
   ],
   "terminalTTL":"600s",
   "callback":"http://examplecallbackurl.com"
}

Instance Creation

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.

{
   "instanceId":"TestInstance",
   "state":"Onboarding",
   "callback":"http://examplecallbackurl.com"
}

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

State transition can be triggered due to the following events:

  • API requests: 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 substate to state.

State Transition Request parameters

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 requires the following information:

  • Instance ID (whose state is being transited)
  • Event Name
  • Source application ID
  • User ID (User requesting the transition)
  • Additional Information - With the standardization of key names for sending other participant IDs (and their instantaneous states) related to the state transition (TBD: Limit the size of the JSON)

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 to 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)

Did this page help you?