State Machine

introduction to state machine service 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 docid\ onamjh1ianfuwvykha69n (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 machine docid\ onamjh1ianfuwvykha69n , state machine docid\ onamjh1ianfuwvykha69n event , and state machine docid\ onamjh1ianfuwvykha69n state the state defines the current status/behavior of an state machine docid\ onamjh1ianfuwvykha69n object an object entity undergoes various state machine docid\ onamjh1ianfuwvykha69n 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 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 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 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 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 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 state machine docid\ onamjh1ianfuwvykha69n 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 create reason code request body { "description" "reasoncode", "isenabled" true } state machine configuration 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 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 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 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 )