• Transitions List
  • Entity Transitions List /data/$module/$entity/transitions
  • Instance Transitions List /data/$module/$entity/$instance_id/transitions
• Executing Transitions
• Dereferencing /data/$module/$entity/$instance_id/transitions/$transition/deref
• Errors
  • errorType
    • COMPOUND
    • CUSTOM
    • REFERENTIAL
    • REGEXP
    • REQUIRED
    • UNIQUENESS
    • SYSTEM

Transitions are data manipulations, so the equivalent to CRUD operations but under the rules of ACL and workflows. They can be defined either on

• entity level (create type)
• instance level (read, edit and delete types)

Transitions List

Entity Transitions List /data/$module/$entity/transitions

[This is available in the universe, we might want to delete this endpoint.]

Returns a list of transitions on the entity which are available according to user's access control.

#!json
#/data/system/module/transitions
{
    "data": [
        {
            "modifying_client": 1,
            "entity": 63,
            "instance_entity": 6,
            "binding_entity": null,
            "description": "action that creates an instance",
            "modifying_action": 13,
            "successor": null,
            "action_type": 1,
            "label": "create",
            "id": 218,
            "notification": null,
            "name": "create",
            "modification_time": "2018-04-15 23:18:34.354119"
        }
    ]
}

Instance Transitions List /data/$module/$entity/$instance_id/transitions

Returns a list of transitions which are applicable according to user's access control and the actual state of the instance. Note: this is an expensive query, do not pre-fetch for lots of instances.

#/data/system/entity/1/transitions

{
  "data": [
    {
      "id": 6,
      "binding_entity": null,
      "modifying_client": 1,
      "instance_entity": 6,
      "notification": null,
      "action_type": 2,
      "description": "A transition that modifies an instance",
      "modification_time": "2018-12-10 14:27:42.434735",
      "modifying_action": 13,
      "entity": 3,
      "name": "edit",
      "label": "edit",
      "successor": null
    },
    {
      "successor": null,
      "label": "delete",
      "name": "delete",
      "modification_time": "2018-12-10 14:27:42.43474",
      "entity": 3,
      "modifying_action": 13,
      "action_type": 3,
      "description": "A transition that deletes an instance",
      "instance_entity": 6,
      "notification": null,
      "id": 8,
      "binding_entity": null,
      "modifying_client": 1
    }
  ]
}

Executing Transitions

To call a transition correctly, the correct verb ("invocationVerb") and attributes ("attributes") are available in the universe .

The example is an add (which is of type create), then an edit and a purge (type delete). The reply for all but delete types will includes the details of the newly created / just edited instance. The "meta" information will only be present in debug mode.

#POST /data/extensions/query/transitions/add
#{"name":"abc","entity":3, "is_default":false}

{
  "data": {
    "attrs": null,
    "is_valid": true,
    "id": 706,
    "modifying_client": 1,
    "successor": null,
    "modification_time": "2018-12-10T16:10:00.586207",
    "entity": 3,
    "modifying_action": 249,
    "name": "abc",
    "owning_client": 1,
    "is_default": false,
    "instance_entity": 62,
    "description": null,
    "error_log": null,
    "conds": null,
    "instance_state": 5
  },
  "meta": {
    "generated_query": [
      "SELECT * FROM extensions_query_add_json(?::JSON) as result",
      "{\"is_default\":false,\"is_valid\":true,\"name\":\"abc\",\"entity\":3}"
    ]
  }
}

#POST /data/extensions/query/706/transitions/edit
#{"name":"def"}

{
  "data": {
    "successor": null,
    "name": "def",
    "owning_client": 1,
    "modification_time": "2018-12-10T16:12:31.724033",
    "modifying_action": 215,
    "entity": 3,
    "description": null,
    "instance_entity": 62,
    "is_default": false,
    "error_log": null,
    "conds": null,
    "instance_state": 5,
    "is_valid": true,
    "attrs": null,
    "id": 706,
    "modifying_client": 1
  },
  "meta": {
    "generated_query": [
      "SELECT * FROM extensions_query_edit_json(?::JSON) as result",
      "{\"id\":\"706\",\"is_valid\":true,\"name\":\"def\"}"
    ]
  }
}

#DELETE /data/extensions/query/706/transitions/purge
{
  "data": null,
  "meta": {
    "generated_query": [
      "SELECT * FROM extensions_query_purge_json(?::JSON) as result",
      "{\"id\":\"706\"}"
    ]
  }
}

Should the request fail, an error message including a "hint" as to how the request should look like will be returned:

#POST /data/extensions/query/transitions/add
#{"name":"abc","entity":3, "is_default":false}

{
  "error": {
    "uri": "http://localhost:3222/data/extensions/query/transitions/add",
    "http_code": 400,
    "message": "the database returned an error",
    "error": {
      "entity": "query",
      "module": "extensions",
      "involvedAttributes": [
        "entity",
        "name"
      ],
      "errorDescription": "must_be_unique",
      "errorID": "1234",
      "errorType": "UNIQUENESS"
    },
    "db_reply": {
      "errorCode": 1234
    },
    "hint": {
      "label": "add",
      "requestBody": {
        "is_default": "{{is_default}}",
        "conds": {},
        "owning_client": "{{owning_client}}",
        "name": "{{name}}",
        "entity": "{{entity}}",
        "attrs": {}
      },
      "category": "create",
      "attributes": {
        "name": {
          "name": "name",
          "required": true
        },
        "conds": {
          "name": "conds",
          "required": false
        },
        "owning_client": {
          "name": "owning_client",
          "required": true
        },
        "attrs": {
          "required": false,
          "name": "attrs"
        },
        "entity": {
          "name": "entity",
          "required": true
        },
        "is_default": {
          "name": "is_default",
          "required": true
        }
      },
      "invocationUrl": "/data/extensions/query/transitions/add",
      "preState": null,
      "name": "add",
      "invocationVerb": "POST",
      "postState": "unpublished",
      "description": "creates a new quey in the unpublished state",
      "requestBodyContentType": "application/json; charset=UTF-8",
      "postStateID": "5",
      "id": 249,
      "preStateID": null
    }
  }
}

Dereferencing /data/$module/$entity/$instance_id/transitions/$transition/deref

NOT YET DOCUMENTED

Errors

When a transition fails, an error message is returned, it looks like this:

{
  "error": {
    "error": {
      "involvedAttributes": [
        "parent"
      ],
      "entity": "unit",
      "errorType": "REQUIRED",
      "errorDescription": "required",
      "errorID": "1624",
      "module": "core"
    },
    "hint": {
      "requestBody": {
        "name": "{{name}}",
        "unit_type": "{{unit_type}}",
        "parent": "{{parent}}",
        "is_titular": "{{is_titular}}",
        "description": "{{description}}"
      },
      "description": "Neue Unit.",
      "invocationVerb": "POST",
      "id": 349,
      "preStateID": null,
      "name": "site_admin_create",
      "postStateID": null,
      "category": "create",
      "postState": null,
      "requestBodyContentType": "application/json; charset=UTF-8",
      "label": "neu",
      "attributes": {
        "is_titular": {
          "required": false,
          "name": "is_titular"
        },
        "description": {
          "required": false,
          "name": "description"
        },
        "parent": {
          "name": "parent",
          "required": true
        },
        "unit_type": {
          "required": false,
          "name": "unit_type"
        },
        "name": {
          "required": true,
          "name": "name"
        }
      },
      "invocationUrl": "/data/core/unit/transitions/site_admin_create",
      "preState": null
    },
    "db_reply": {
      "errorCode": 1624
    },
    "message": "the database returned an error",
    "path": "data/core/unit/3/transitions/site_admin_create",
    "http_code": 400
  }
}

The error->error entry has details of what type of error it is and additional information like which attributes are involved.

errorType

These are the possible error types:

COMPOUND

Attributes have to conform to a certain operator (e.g. equal).

CUSTOM

A custom error defined for a project.

REFERENTIAL

A reference is not found.

REGEXP

An attribute does not conform to a regex.

REQUIRED

One or more attributes are required.

UNIQUENESS

One or more attributes should be unique but already exist in the database.

SYSTEM

Various system errors, with 429 | unexpected_backend_error being equivalent to an internal server error.