Setting up a state machine
Setting up a state machine
This page shows how to define a state machine for a class, make it live, and move individuals through it by firing events. For background, see State machines and Actions.
Before you start, make sure you have the following:
- An ontology with an editable draft version, and a class with a collection mapping. For more information, see Mapping a class to a collection.
EDITpermission on the ontology.- To fire events,
INDIVIDUALS_EDITon every class bound to the machine. For more information, see Granting permissions.
Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp and draft version 2.
To set up a state machine, complete the following steps:
-
Create the state machine in the draft. Give each state, event, and transition an
_id, so transitions can refer to them. Mark exactly one state as initial.POST /aosvc/api/v1/ontologies/{ontologyId}/state-machines?nsfilter=myappX-Ontology-Draft: 2{"_name": "Approval","_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],"_states": [{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }],"_events": [{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }],"_transitions": [{"_name": "approve","_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed","_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7","_executionOrder": 0,"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],"_actions": [{"_name": "Start approval workflow","_actionType": "WORKFLOW","_executionOrder": 0,"_params": {"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"}}]}]}Note the machine
_idin the response. The service grants youCREATEon the machine's events, so you can fire them.For more information, see Create a state machine. For the settings of each action type, see Action types.
-
To use the machine for more classes, bind them.
POST /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/classes?nsfilter=myappX-Ontology-Draft: 2{"_classIds": ["9a3c5e7f-2b4d-4f6a-8c1e-3d5f7a9b1c2e"]}For more information, see Bind classes to a state machine.
-
Publish and promote the draft. For the steps, see steps 6 to 10 of Creating an ontology.
-
Create an individual of a bound class. Its
_aostatesfield holds the machine's initial state.POST /aosvc/api/v1/classes/{classId}/individuals?nsfilter=myapp{"_name": "Purchase order 1001"}For more information, see Create individuals.
-
Fire an event against the individuals, grouped by class. Send an
Idempotency-Keyheader so you can retry safely. Note the_eventTriggerIdin the response.POST /aosvc/api/v1/state-machines/{machineId}/events?nsfilter=myappIdempotency-Key: approve-po-1001{"_eventId": "11b700ba-c9bb-4776-a0f1-36202f24a6b3","_eventName": "Approve","_targets": [{"_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27","_individualIds": ["66f2a1c9e4b0a37d5c8e9f01"]}]}Note: A
201response means the event is queued. If you get503, retry with the sameIdempotency-Key.For more information, see Fire an event.
-
Get the transition history of the individual. Find the row with your
_eventTriggerId, and check that_successistrue. If there's no row yet, the event hasn't been processed, so try again later.GET /aosvc/api/v1/classes/{classId}/individuals/{individualId}/transition-history?nsfilter=myappFor more information, see Get the transition history of an individual.
-
Check that the transition's actions ran. Filter the machine's action executions on your
_eventTriggerId, and check the_statusof each entry in_actions.FAILEDmeans the action ran out of retries, and_lastErrorsays why.GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/action-executions?nsfilter=myapp&eventTriggerId=approve-po-1001For more information, see List action executions.