Building blocks: people

In short: with human.request (Ask a person) the workflow asks a colleague a question with a few answers and waits for the answer. With task.create (Task) the workflow leaves a task and continues straight away. Both land in To do and, if the run is about a conversation, on the ticket.

Where to find this

Account > Workflows, open a workflow, Add step, group A person. Who: from the role Organisation admin. The colleague who gets the question or task handles it in To do or on the ticket.

An Ask a person step in the workflow editor with Title, Text, Answers, Button texts, Show, Fields to fill in (JSON schema), Starting values, For and Deadline (minutes), and for each answer the If choice.

human.request: Ask a person

Asks a colleague a question with a few answers (the exits of the step) and optionally fields to fill in or edit, and waits for the answer or for the deadline.

Input

A new step starts with {"exits": ["approve", "reject"]}.

Exits: every answer from exits, plus expired (expired) if nobody answered before the deadline.

Output fields

With expired, only actionId is filled.

Example: having a report approved before it goes to the dossier.

{
  "id": "controle",
  "label": "Have the adviser check the report",
  "block": "human.request",
  "inputs": {
    "title": "Check the report",
    "text": "Is this report of the conversation correct?",
    "exits": ["approve", "reject"],
    "exitLabels": { "approve": "Correct, send it", "reject": "Do not send" },
    "show": { "Report": "{{verslag.text}}" },
    "fields": { "type": "object", "properties": { "verslag": { "type": "string", "title": "Report" } } },
    "values": { "verslag": "{{verslag.text}}" },
    "assignee": "{{trigger.recordedByUserId}}",
    "deadlineMinutes": 2880
  },
  "exits": { "approve": "naar-dossier" }
}

Here the run ends at reject and expired, because those exits lead nowhere. You read the edited text later as {{controle.fields.verslag}}.

What the colleague sees: a card with the title, the text, what the workflow shows (show), the fields from the schema and the answers as buttons. Above it, if the run has them, are the customer, the recording and the documents the run made. The card is in To do and, if the run is about a conversation, on the ticket.

When to use it: for every decision a person has to make before the workflow continues, and as an approval before something goes to a customer or another system. When not to: if the workflow does not need to wait. Use task.create then.

task.create: Task

Leaves a task for a colleague, with an optional due date. The run does not wait: the task stays in the colleague’s To do.

Input

Exits: none; continues with next.

Output fields: actionId (Action), the id of the task.

When to use it: for work a person does later (“call the customer back on Friday”), and as a safety net for an error: give a step an onError to a task with {{<step>.error}} in the text. When not to: if what the workflow does next depends on the answer. Use human.request then.

Good to know

• A question or task is attached to the run’s ticket if it has one, and to the other objects of the run (the customer, the recording).
• A question or task that is still open on a closed or deleted ticket expires by itself; a waiting human.request then continues via expired. Work that has to happen after closing belongs in a workflow, not as an open item on the closed ticket.
• Waiting costs nothing: a run that waits for an answer stands still until the answer or the deadline comes.
• A fixed assignee who may not handle the organisation’s tickets makes the step fail. If a reference from the event ({{trigger.<...>UserId}}) is such a person, the work goes to everyone.
• Never put ids (ticketId, messageId, actionId) in show: the question is already linked to the ticket.

Related

• Building blocks of a workflow
• References, routing, repeating and choosing
• Following runs and catching errors
• To do