State Machine

introduction to state machine service the state machine service is responsible for the lifecycle management of resources of types such as a https //docs getos1 com/participant , https //docs getos1 com/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 https //app archbee com/public/preview fr9wrrvqdaz2i4jy49xez/preview onamjh1ianfuwvykha69n#xnpzy , and /#reason code state the state defines the current status/behavior of an /#entity object an object entity undergoes various /#state transition 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 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 https //docs getos1 com/container ) and is done automatically when these entities are defined in the respective services entities in the entity registry have the following attributes true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type to create a state machine entity, call the https //app archbee com/public/preview 9m3sxlb43kjczevknejvn/preview zpbs1q6co jdgxnoonkhv endpoint request bodies are specified in json format the following example shows a request body for creating a state machine entity true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type create entity request body { "name" "entity", "description" "this is a description for entity", "events" \[ "e 022", "e 023", "e 024" ], "isenabled" true, "entitycode" "101" } 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 https //docs getos1 com/reference/create event endpoint request bodies are specified in json format the following example shows a request body for creating a state machine event true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type create event request body { "description" "new non transitional event", "eventtype" "non transitional", "entities" \[ "1000" ], "reasoncodes" \[ "r 0001", "r 0002" ], "eventcode" "101" } 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type reason code reason code is a unique alphanumeric code given to a reason that triggers an /#eventreason code erc service 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type to create a reason code, call the https //docs getos1 com/reference/create reason endpoint request bodies are specified in json format the following example shows a request body for creating a reason code true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type create reason code request body { "description" "reasoncode", "isenabled" true } state machine configuration the state machine service provides an https //docs getos1 com/reference/register state machine config for entity type 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 https //docs getos1 com/reference/register state machine config for entity type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type sample payload for creating state machine configuration { "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 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 sample payload for updating a state machine configuration { "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 https //testdocs getos1 com/reference/create state machine config to create an instance of a particular entity type with the default state machine configuration true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type sample payload for instance creation { "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 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 note transition can happen between substates (across different states) and not between substates to states 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 require the following information instance id (whose state is being transited) event name source application id user id (user requesting the transition) 📘 note 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 )