Scheduled workflows

In short: With the On a schedule trigger (schedule.due) a workflow starts according to a schedule, for example every working day at 8:30 or on the first of the month at 7:00, in the organisation’s time. Such a run does not belong to a conversation or customer: it fetches what it needs itself, for example from a connected system, and prepares work for colleagues.

Where to find this

Go to Account > Workflows, open a workflow and click the top box (When). At This happens, choose the event On a schedule. You need the Organisation admin role.

Setting up a schedule

1. At This happens, choose the event On a schedule. The schedule starts as every working day at 9:00.
2. At Every, choose how often.
3. Fill in the moment (see the table).
4. Leave Time zone empty for the organisation’s own time, or fill in a time zone such as Europe/Amsterdam.
5. Add the steps, try it out with Try as if it were now and publish.

The When panel with the choice On a schedule at This happens, and the fields Every (week, on), At, the day buttons Monday to Sunday and Time zone (menu Account > Workflows, open workflow, click the trigger).

A workflow On a schedule has no conditions (Only if) and no Never twice at once for: the schedule decides when it starts.

The schedule in the definition

In JSON the schedule is in the trigger, under schedule:

{
  "trigger": {
    "event": "schedule.due",
    "schedule": { "every": "week", "at": "09:00", "days": ["monday", "thursday"], "timeZone": "Europe/Amsterdam" }
  },
  "steps": [
    { "id": "task", "block": "task.create", "label": "Prepare the weekly check",
      "inputs": { "title": "Weekly check of outstanding returns", "dueMinutes": 480 } }
  ]
}

A schedule is only allowed with schedule.due. With another event, publishing gives the message Only “On a schedule” takes a schedule. If the schedule is missing, you see Say when the workflow starts. If a part is not right, you see The schedule is not complete: with what is missing.

When exactly the run starts

• aishaa checks every minute whether the moment of an active workflow has come. So the run may start a minute after the planned moment.
• Every moment starts exactly one run, however often aishaa checks.
• A moment that was missed because of a short outage still starts up to ten minutes later. Older moments are not caught up: a schedule never starts a backlog.
• A newly published version only responds to moments after the publication.
• A paused workflow starts nothing. Moments during the pause are not caught up.
• Only the workflow itself starts at its own moment. Other workflows with the On a schedule trigger start on their own schedule.
• When summer time starts, a time such as 2:30 does not exist that night: the run then starts an hour later. When winter time starts, a time occurs twice: the run starts once.

What a scheduled run knows and can do

The run only knows two fields:

A scheduled run does not belong to a conversation or customer. As a result:

Create a scheduled workflow for one organisation, not for the whole account. A run of a workflow for the whole account belongs to no organisation, and steps such as Task, Ask a person, Fetch from a connected system and Plugin action then fail. An Account admin who clicks New workflow creates a workflow for the whole account. So have a scheduled workflow created by an Organisation admin of the organisation, add it from the library, or let an AI assistant save it as a draft for the organisation through the connection.

Examples

The examples below are complete definitions that pass aishaa’s check. Replace ids and the names of reads with those of your own organisation.

Prepare a task every working day

A fixed check at the start of the day, for everyone in To do:

{
  "trigger": { "event": "schedule.due", "schedule": { "every": "weekday", "at": "08:30" } },
  "steps": [
    { "id": "task", "block": "task.create", "label": "Prepare the daily check",
      "inputs": { "title": "Daily check: go through waiting returns", "text": "Go through the returns that have been waiting for more than two days.", "dueMinutes": 240 } }
  ]
}

Without assignee the task is for everyone. With a colleague’s user id (for example "assignee": 42) it is for that colleague.

An overview from a connected system every Monday

aishaa fetches data from a connected system, lets the AI make a short overview of it and prepares that as a task. Replace PLUGIN/LEESACTIE and the parameter vanaf with a read and parameters that the connected system really offers (see Data from connected systems in a workflow).

{
  "trigger": { "event": "schedule.due", "schedule": { "every": "week", "at": "09:00", "days": ["monday"] } },
  "steps": [
    { "id": "vanaf", "block": "data.format", "label": "Calculate the date of a week ago",
      "inputs": { "operation": "add_time", "value": "{{trigger.scheduledFor}}", "amount": -7, "unit": "days" },
      "next": "datum" },
    { "id": "datum", "block": "data.format", "label": "Write the date for the system",
      "inputs": { "operation": "format_date", "value": "{{vanaf.result}}", "format": "iso_date" },
      "next": "ophalen" },
    { "id": "ophalen", "block": "plugin.read", "label": "Fetch the outstanding items",
      "inputs": { "read": "PLUGIN/LEESACTIE", "input": { "vanaf": "{{datum.result}}" } },
      "exits": { "found": "samenvatten", "none": "niets", "failed": "fout" } },
    { "id": "samenvatten", "block": "ai.transform", "label": "Make a short overview",
      "inputs": {
        "instruction": "Make an overview of at most ten lines of the outstanding items, the most important first.",
        "input": { "posten": "{{ophalen.data}}" },
        "output": { "type": "object", "properties": { "text": { "type": "string" } } }
      },
      "next": "taak" },
    { "id": "taak", "block": "task.create", "label": "Prepare the weekly overview",
      "inputs": { "title": "Weekly overview of outstanding items", "text": "{{samenvatten.text}}", "dueMinutes": 480 } },
    { "id": "niets", "block": "task.create", "label": "Report that nothing is outstanding",
      "inputs": { "title": "Weekly overview: nothing outstanding" } },
    { "id": "fout", "block": "task.create", "label": "Report that fetching failed",
      "inputs": { "title": "Weekly overview could not be fetched", "text": "{{ophalen.error}}" } }
  ]
}

Every hour, at a fixed minute

{ "event": "schedule.due", "schedule": { "every": "hour", "at": "00:15" } }

This is only the trigger: the workflow starts every hour at quarter past. Use this sparingly: every hour means 24 runs per day.

Good to know

• You try out a scheduled workflow with Try as if it were now, even before the first moment has ever come.
• Planned moment is stored in UTC. Calculate and format calculates and writes dates in the organisation’s time zone, so that 9:00 stays 9:00 even after the clocks change.
• A scheduled workflow only responds when it is Active.
• A monthly schedule only has a fixed day from 1 to 28. You cannot choose “the last day of the month” or “the first working day”.
• You see every run in View > Runs of the workflow, just like other runs.

Related

• Triggers and events
• Data from connected systems in a workflow
• Workflow recipes
• Create, test and publish a workflow
• Following runs and handling errors
• Opening hours