ConnectCloud Developers

The templates a new flow or immediate automation can start from (tenant:flows:read|write|admin)

GET /api/flows/v1/templates

Module: Flows · operationId: listFlowTemplates · Tag: Catalog · Auth: access token (Authorization: Bearer <accessToken>)

Ready-made automations in display order (category, then registry order). Without parameters the list holds the tenant-wide flows: pass a template's key as template (and the values of its params) to POST /api/flows/v1/flows. profile and scope pick another list – what the settings of a forge project or a desk space offer: scope is the kind of scope a template is made for (never one scope), profile=inline the immediate automations of the module that owns that kind. An inline template never becomes a flow: render it (POST /api/flows/v1/templates/{key}/render) and create the automation in its module. available is false while a module the template uses is not offered by the catalogue (for an inline template: while its module does not declare the template's actions as immediate); creating it would give a draft with validation errors.

Parameters

Name In Type Required Description
profile query string Where the templates run: durable (flows, the default) or inline (immediate automations of a module); anything else is 400 invalid, field profile (one of durable, inline; default "durable")
scope query string The kind of scope the templates are made for: desk:space or forge:project; without it the tenant-wide templates. Anything else – also one scope with its id – is 400 invalid, field scope (one of desk:space, forge:project)

Responses

  • 200 The templates (application/json)
  • 400 Invalid input (invalid); field names the first invalid field, details.fields every one. (application/json)
  • 401 Missing, invalid or expired token (no body).
  • 403 The token lacks the permission or has no active tenant (forbidden). Also: person_required (a service-account key on personal flows or the task inbox), live_test_forbidden, forbidden_grant, starter_excluded. (application/json)

Fields of the 200 answer:

  • items (array of FlowTemplate, required): The templates
    • available (boolean, required): False while a module the template uses is not offered by the catalogue
    • category (string, required): Category the template is listed under (one of support, sales, people, operations, development, general)
    • description (LocalizedText, required)
      • de (string, required): German text
      • en (string, required): English text
    • key (string, required): Template key; pass it as template to createFlow
    • modules (array of string, required): The modules whose actions and events the template uses
    • name (LocalizedText, required)
      • de (string, required): German text
      • en (string, required): English text
    • params (array of FlowTemplateParam, required): What the person fills in before creating it, in display order (empty: nothing)
      • key (string, required): Key of the value in params
      • label (LocalizedText, required)
      • required (boolean, required): The value must not be empty. Left out, a required parameter takes its default; one without a default must be sent. Every parameter is required or has a default.
      • type (string, required): The input and the JSON type of the value: text (string, at most 4000 characters), number, bool, enum (one options[].value), email (one address), people (always a list: person:<email>, employee:<id>, group:<id>, role:<id>, manager:<email or id> – the people references of a mail node with HR ids –, a plain address, or creator – the person creating it). The pickers hand over a key or name of the tenant's configuration as a string of at most 200 characters: desk_space (space key), desk_priority (priority key), desk_type (type key), desk_team (team key), desk_status (status key of a ticket workflow), desk_label (label name), forge_project (project key), forge_label (label name), forge_type (item type key), forge_status (status key). duration is a time span as a string: a whole number of hours or days, 4h or 2d (pattern ^[1-9][0-9]{0,3}[hd]$, at most 360 days; a day is 24 hours) – nothing else is accepted, and it is always required. (one of text, number, bool, enum, email, people, desk_space, desk_priority, desk_type, desk_team, desk_status, desk_label, forge_project, forge_label, forge_type, forge_status, duration)
      • default (any): The value used when none is sent, of the parameter's type (a list for multiple and people)
      • help (object): What to enter (absent when the label says it)
      • multiple (boolean): The value is a list of values of the type, at most 50 (enum and the pickers; people always is a list)
      • options (array of object): The choices of an enum
        • label (LocalizedText, required)
        • value (string, required): The value to send
    • profile (string, required): durable: a flow, created with POST /api/flows/v1/flows. inline: an immediate automation of the module in modules – rendered here, created there. (one of durable, inline)
    • triggers (array of string, required): The kinds of the template's triggers
    • hint (object): What to adjust after creating the flow that no parameter covers (absent: nothing)
    • scope (string): The kind of scope the template is made for (absent: tenant-wide) (one of desk:space, forge:project)
  • total (integer, required): Number of items

Example 200 answer:

{
  "items": [
    {
      "available": true,
      "category": "support",
      "description": {
        "de": "Bei jedem neuen Ticket mit einer der gewählten Prioritäten fasst die KI die Meldung zusammen und Sie bekommen eine Mail.",
        "en": "For every new ticket with one of the chosen priorities the AI summarises it and you get an email."
      },
      "key": "kritische-tickets-melden",
      "modules": [
        "desk"
      ],
      "name": {
        "de": "Kritische Tickets melden",
        "en": "Report critical tickets"
      },
      "params": [
        {
          "default": [
            "hoch",
            "kritisch"
          ],
          "key": "priorities",
          "label": {
            "de": "Prioritäten",
            "en": "Priorities"
          },
          "multiple": true,
          "required": false,
          "type": "desk_priority"
        },
        {
          "default": [
            "creator"
          ],
          "key": "recipients",
          "label": {
            "de": "Empfänger",
            "en": "Recipients"
          },
          "multiple": true,
          "required": true,
          "type": "people"
        }
      ],
      "profile": "durable",
      "triggers": [
        "event"
      ]
    }
  ],
  "total": 1
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/flows/v1/templates' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI