Skip to main content
Version: v5.3

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.
  • EDIT permission on the ontology.
  • To fire events, INDIVIDUALS_EDIT on 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:

  1. 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=myapp
    X-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 _id in the response. The service grants you CREATE on 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.

  2. To use the machine for more classes, bind them.

    POST /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/classes?nsfilter=myapp
    X-Ontology-Draft: 2

    {
    "_classIds": ["9a3c5e7f-2b4d-4f6a-8c1e-3d5f7a9b1c2e"]
    }

    For more information, see Bind classes to a state machine.

  3. Publish and promote the draft. For the steps, see steps 6 to 10 of Creating an ontology.

  4. Create an individual of a bound class. Its _aostates field 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.

  5. Fire an event against the individuals, grouped by class. Send an Idempotency-Key header so you can retry safely. Note the _eventTriggerId in the response.

    POST /aosvc/api/v1/state-machines/{machineId}/events?nsfilter=myapp
    Idempotency-Key: approve-po-1001

    {
    "_eventId": "11b700ba-c9bb-4776-a0f1-36202f24a6b3",
    "_eventName": "Approve",
    "_targets": [
    {
    "_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27",
    "_individualIds": ["66f2a1c9e4b0a37d5c8e9f01"]
    }
    ]
    }

    Note: A 201 response means the event is queued. If you get 503, retry with the same Idempotency-Key.

    For more information, see Fire an event.

  6. Get the transition history of the individual. Find the row with your _eventTriggerId, and check that _success is true. 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=myapp

    For more information, see Get the transition history of an individual.

  7. Check that the transition's actions ran. Filter the machine's action executions on your _eventTriggerId, and check the _status of each entry in _actions. FAILED means the action ran out of retries, and _lastError says why.

    GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/action-executions?nsfilter=myapp&eventTriggerId=approve-po-1001

    For more information, see List action executions.