ConnectCloud Developers

What desk's automations can use (desk access; a space the caller sees)

GET /api/desk/v1/automations/catalog

Module: Desk · operationId: getDeskAutomationCatalog · Tag: Automation · Auth: access token (Authorization: Bearer <accessToken>)

Scope tenant: everyone with desk access. Scope space:<id>: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 scope). The catalogue of the builder – the shape of flows' catalogue, cut down to what runs immediately – desk's events with their payload schemas, the actions with an immediate implementation, the node and trigger kinds of the inline profile (with the manual trigger), the expression namespaces and functions, the limits, and per action the parameters the builder prefills (defaults, ref ← the event's ticket).

Parameters

Name In Type Required Description
scope query string yes Whose automations: tenant (every space) or space:<space id>

Responses

  • 200 The catalogue (application/json)
  • 400 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • defaults (object, required): Per action key, the parameters the builder prefills when the action is added: the ones that address the item the event is about
  • functions (array of string, required): The functions of the expression language
  • kinds (array of object, required): The node kinds that run immediately, with their default ports and fields
    • fields (array of AutomationField, required): Settings of the node kind
      • path (string, required): Dotted below the node or trigger
      • type (string, required): Value type of the setting
      • options (array of string): Allowed values of the setting
      • when (object): The field applies only while the sibling field has one of the values
        • equals (array of string): Values of that setting for which this one applies
        • field (string): The setting this one depends on
    • name (string, required): Name of the node kind
    • ports (array of string, required): Output ports of the node kind
    • retry (boolean, required): Always false – an immediate automation is not retried
  • limits (object, required): Limits an automation must stay within
    • maxDepth (integer, required): How deep automations start each other
    • maxNodes (integer, required): The most nodes of an immediate automation
    • maxPerEvent (integer, required): The most automations one event starts
  • modules (array of object, required): forge's flows manifest, cut down to the actions with an immediate implementation: nodes (key, labels, parameter and output schemas) and events (type, labels, payload schema)
    • events (array of object): Events of the module an automation can start on
    • module (string): Module that offers the nodes and events
    • nodes (array of object): Action nodes of the module usable in an automation
    • revision (string): Revision of the module's flows manifest
    • version (integer): Version of the module's flows manifest
  • namespaces (array of string, required): The names expressions read
  • profile (string, required): Profile the catalog describes: inline (runs immediately in the transaction of the change) (one of inline)
  • retryFields (array of AutomationField, required): Always empty
    • path (string, required): Dotted below the node or trigger
    • type (string, required): Value type of the setting
    • options (array of string): Allowed values of the setting
    • when (object): The field applies only while the sibling field has one of the values
      • equals (array of string): Values of that setting for which this one applies
      • field (string): The setting this one depends on
  • triggers (array of object, required): The trigger kinds a definition may use here (forge - event only; nothing starts an automation by hand) with their fields
    • fields (array of AutomationField, required): Settings of the trigger kind
      • path (string, required): Dotted below the node or trigger
      • type (string, required): Value type of the setting
      • options (array of string): Allowed values of the setting
      • when (object): The field applies only while the sibling field has one of the values
        • equals (array of string): Values of that setting for which this one applies
        • field (string): The setting this one depends on
    • name (string, required): Name of the trigger kind

Example 200 answer:

{
  "defaults": {
    "desk.item.add_label": {
      "ref": "{{ trigger.data.itemId }}"
    },
    "desk.item.assign": {
      "ref": "{{ trigger.data.itemId }}"
    }
  },
  "functions": [
    "len",
    "any",
    "all",
    "contains",
    "hasPrefix",
    "lower",
    "now"
  ],
  "kinds": [
    {
      "fields": [
        {
          "path": "condition",
          "type": "condition"
        }
      ],
      "name": "if",
      "ports": [
        "true",
        "false",
        "error"
      ],
      "retry": false
    },
    {
      "fields": [
        {
          "path": "to",
          "type": "recipients"
        },
        {
          "path": "subject",
          "type": "template"
        },
        {
          "path": "text",
          "type": "template"
        }
      ],
      "name": "mail",
      "ports": [
        "main",
        "error"
      ],
      "retry": false
    }
  ],
  "limits": {
    "maxDepth": 4,
    "maxNodes": 25,
    "maxPerEvent": 20
  },
  "modules": [
    {
      "events": [
        {
          "label": {
            "de": "Ticket angelegt",
            "en": "Ticket created"
          },
          "type": "desk.item.created"
        },
        {
          "label": {
            "de": "SLA eskaliert",
            "en": "SLA escalated"
          },
          "type": "desk.sla.escalated"
        }
      ],
      "module": "desk",
      "nodes": [
        {
          "access": "write",
          "key": "desk.item.assign",
          "label": {
            "de": "Ticket zuweisen",
            "en": "Assign ticket"
          }
        },
        {
          "access": "write",
          "key": "desk.item.add_label",
          "label": {
            "de": "Label hinzufügen",
            "en": "Add label"
          }
        },
        {
          "access": "write",
          "key": "desk.entry.add",
          "label": {
            "de": "Kommentar hinzufügen",
            "en": "Add comment"
          }
        }
      ],
      "revision": "7b1e44c2",
      "version": 1
    }
  ],
  "namespaces": [
    "trigger",
    "nodes",
    "vars",
    "error",
    "run"
  ],
  "profile": "inline",
  "retryFields": [],
  "triggers": [
    {
      "fields": [
        {
          "path": "event",
          "type": "event"
        },
        {
          "path": "filter",
          "type": "condition"
        },
        {
          "path": "includeAutomated",
          "type": "boolean"
        }
      ],
      "name": "event"
    },
    {
      "fields": [
        {
          "path": "filter",
          "type": "condition"
        }
      ],
      "name": "manual"
    }
  ]
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/desk/v1/automations/catalog?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI