Invoke a workflow at specific time intervals
Scheduled triggers are an automatic type of trigger. This means that once the trigger is created, they do not require any user input.
Use a scheduled trigger if you need a workflow to kick off after a delay or on an hourly, daily, weekly, or annual cadence.
Triggers can be added to workflows in two ways:
You can add triggers with the CLI. These static triggers are created only once. You create them with the Slack CLI, attach them to your app's workflow, and that's that. The trigger is defined within a trigger file.
You can add triggers at runtime. These dynamic triggers are created at any step of a workflow so they can incorporate data acquired from other workflow steps. The trigger is defined within a function file.
Slack CLI built-in documentation
Use slack trigger --help
to easily access information on the trigger
command's flags and subcommands.
The triggers you create when running locally (with the slack run
command) will not work when you deploy your app in production (with the slack deploy
command). You'll need to create
any triggers again with the CLI.
To create a scheduled trigger with the CLI, you'll need to create a trigger file. The trigger file contains the payload you used to define your trigger.
Create a TypeScript trigger file within your app's folder with the following form:
import { Trigger} from "deno-slack-api/types.ts";
const trigger : Trigger<typeof ExampleWorkflow.definition> = {
// your TypeScript payload
}
export default trigger;
Your TypeScript payload consists of the parameters needed for your own use case. Here is a TypeScript payload creating a scheduled trigger that will kick off a workflow at a specified start time:
name: "Example",
type: "scheduled",
workflow: "#/workflows/example",
inputs: {
example: { value: "example" },
},
schedule: {
start_time: "2022-03-01T14:00:00Z",
},
Here is a payload creating a scheduled trigger that has a start and end date, and a monthly frequency.
name: "Example",
type: "scheduled",
workflow: "#/workflows/example",
inputs: {
example: { value: "example" },
},
schedule: {
start_time: "2022-03-01T14:00:00Z",
end_time: "2022-06-01T14:00:00Z",
timezone: "UTC",
frequency: {
type: "monthly",
on_days: ["Monday"],
on_week_num: 3,
repeats_every: 2,
},
},
Once you have created a trigger file, use the following command to create the scheduled trigger:
slack trigger create --trigger-def "path/to/trigger.ts"
If you have not used slack triggers create
to create a trigger prior to running slack run
, you will receive a prompt in the CLI to do so.
Your app needs to have the triggers:write
scope to use a trigger at runtime. Include the scope within your app's manifest.
The logic of a runtime trigger lies within a function's TypeScript code. Within your functions
folder, you'll have the functions that are the steps making up your workflow. Within this folder is where you can create a trigger within the relevant <function>.ts
file.
When you create a runtime trigger, you can leverage inputs
acquired from functions within the workflow. Provide the workflow definition to get additional typing for the workflow and inputs fields.
Create a scheduled trigger at runtime using the client.workflows.triggers.create
method within the relevant function
file.
const triggerResponse = await client.workflows.triggers.create<typeof ExampleWorkflow.definition>({
// your TypeScript payload
});
Your TypeScript payload consists of the parameters needed for your own use case. Below is a function file with an example TypeScript payload for a scheduled trigger.
// functions/example_function.ts
import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";
import { SlackAPI } from "deno-slack-api/mod.ts";
export const ExampleFunctionDefinition = DefineFunction({
callback_id: "example_function_def",
title: "Example function",
source_file: "functions/example_function.ts",
});
export default SlackFunction(
ExampleFunctionDefinition,
({ inputs, client }) => {
const triggerResponse = await client.workflows.triggers.create<typeof ExampleWorkflow.definition>({
name: "Example",
type: "scheduled",
workflow: "#/workflows/example",
inputs: {
example: { value: "example" },
},
schedule: {
start_time: "2022-03-01T14:00:00Z", // yyyy-mm-dd
end_time: "2022-06-01T14:00:00Z",
timezone: "UTC",
frequency: {
type: "monthly",
on_days: ["Monday"],
on_week_num: 3,
repeats_every: 2,
},
},
});
// ...
Field | Description | Required |
---|---|---|
type |
The type of trigger: scheduled |
Required |
name |
The name of the trigger | Required |
workflow |
Path to workflow that the trigger initiates | Required |
description |
The description of the trigger | |
inputs |
The inputs provided to the workflow. See the inputs object below |
|
schedule |
When and how often the trigger will activate. See The schedule object below |
Required |
Interactivity, and thus the interactivity
parameter, is not supported with scheduled triggers. Use a link trigger to take advantage of interactivity.
inputs
object The inputs
of a trigger map to the inputs of a workflow. You can pass any value as an input.
There is also a specific input value that contains information about the trigger. Pass this value to provide trigger information to your workflows!
Field | Type | Description |
---|---|---|
data.user_id |
string | A unique identifier for the user who created the trigger |
The following snippet shows a user_id
input being set with a value of data.user_id
, representing the user who created the trigger.
...
inputs: {
user_id: {
value: "{{data.user_id}}"
}
},
...
schedule
object Field | Description | Required |
---|---|---|
start_time |
ISO date string of the first scheduled trigger | Required |
timezone |
Timezone string to use for scheduling | |
frequency |
Details on what cadence trigger will activate. See The frequency object below |
|
occurrence_count |
The maximum number of times trigger will run | |
end_time |
If set, this trigger will not run past the provided ISO date string |
frequency
object Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: once |
Required |
on_days |
The days of the week the trigger should activate on | |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
|
on_week_num |
The nth week of the month the trigger will repeat |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T15:00:00Z",
timezone: "asia/kolkata",
frequency: {
type: "once",
},
},
};
Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: hourly |
Required |
on_days |
The days of the week the trigger should activate on | |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
Required |
on_week_num |
The nth week of the month the trigger will repeat |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T14:00:00Z",
end_time: "2022-05-01T14:00:00Z",
frequency: {
type: "hourly",
repeats_every: 2,
},
},
};
Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: daily |
Required |
on_days |
The days of the week the trigger should activate on | |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
Required |
on_week_num |
The nth week of the month the trigger will repeat |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T14:00:00Z",
end_time: "2022-05-01T14:00:00Z",
occurrence_count: 3,
frequency: { type: "daily" },
},
};
Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: weekly |
Required |
on_days |
The days of the week the trigger should activate on | Required |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
Required |
on_week_num |
The nth week of the month the trigger will repeat |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T14:00:00Z",
frequency: {
type: "weekly",
repeats_every: 3,
on_days: ["Friday", "Monday"],
},
},
};
Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: monthly |
Required |
on_days |
The days of the week the trigger should activate on | Required |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
Required |
on_week_num |
The nth week of the month the trigger will repeat | Required |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T14:00:00Z",
frequency: {
type: "monthly",
repeats_every: 3,
on_days: ["Friday"],
on_week_num: 1,
},
},
};
Field | Description | Required |
---|---|---|
type |
How often the trigger will activate: yearly |
Required |
on_days |
The days of the week the trigger should activate on | |
repeats_every |
How often the trigger will repeat, respective to frequency.type |
Required |
on_week_num |
The nth week of the month the trigger will repeat |
const schedule: ScheduledTrigger = {
name: "Sample",
type: TriggerTypes.Scheduled,
workflow: "#/workflows/example",
inputs: {},
schedule: {
start_time: "2022-03-01T14:00:00Z",
frequency: {
type: "yearly",
repeats_every: 2,
},
},
};
The response will have a property called ok
. If true
, then the trigger was created, and the trigger
property will be populated.
Your response will include a trigger.id
; be sure to store it! You use that to update
or delete
the trigger if need be. Perhaps consider storing it in a datastore.
A newly created trigger is accessible to anyone inside the workspace. You can manage who can access the trigger using the access
Slack CLI command.
Required Flag | Description | Example Argument |
---|---|---|
--grant |
A switch to grant access | |
--trigger-id |
The trigger_id of the desired trigger |
Ft123ABC |
Set one of the following flags to grant access to different groups. If no flag is selected you will be prompted to select one within the Slack CLI.
Flag | Description | Example Argument |
---|---|---|
--app-collaborators |
A switch to grant access to all app collaborators | |
--channels |
The channel_id of desired channels |
C123ABC, C456DEF |
--everyone |
A switch to grant access to all workspace member | |
--users |
Only users with the specified user_id will be able to access the app |
U123ABC, U456DEF |
The following example command grants access to the trigger FtABC123
for users U123ABC
and U456DEF
, as well as for channels C123ABC
and C456DEF
.
slack trigger access --trigger-id FtABC123 --users U123ABC,U456DEF --channels C123ABC,C456DEF --grant
Required Flag | Description | Example Argument |
---|---|---|
--revoke |
A switch to revoke access | |
--trigger-id |
The trigger_id of the desired trigger |
Ft123ABC |
Set one of the following flags to revoke access to different groups. If no flag is selected you will be prompted to select one within the Slack CLI.
Flag | Description | Example Argument |
---|---|---|
--channels |
The channel_id of desired channels |
C123ABC, C456DEF |
--users |
Users with the specified user_id will no lonber be able to access the app |
U123ABC, U456DEF |
The following example command revokes access to the trigger FtABC123
for users U123ABC
and U456DEF
and channels C123ABC
and C456DEF
.
slack trigger access --trigger-id FtABC123 --users U123ABC U456DEF --channels C123ABC,C456DEF --revoke
Make an update to a pre-existing trigger with the CLI by using the slack trigger update
command. Provide the same payload you used to create the trigger in its entirety, in addition to the trigger ID.
slack trigger update --trigger-id Ft123ABC --trigger-def "path/to/trigger.ts"
You can update a runtime trigger, but the trigger must be updated in its entirety. Use the same structure as client.workflows.triggers.create()
but for client.workflows.triggers.update
with the additional trigger_id
parameter.
client.workflows.triggers.update<typeof ExampleWorkflow.definition>({
trigger_id: "FtABC123",
type: "<specific-trigger-type>",
name: "My trigger",
workflow: "#/workflows/myworkflow",
inputs: {
input_name: {
value: "value",
}
}
});
You can delete a trigger with the slack trigger delete
command.
slack trigger delete --trigger-id FtABC123
Deleting a runtime trigger deletes that specific trigger created in one instance of the Workflow. This means that you'll need to have stored the trigger_id
created for that instance. Your app will continue to be able to create triggers until you remove the relevant code.
You can delete a runtime trigger by using client.workflows.triggers.delete()
.
client.workflows.triggers.delete({
trigger_id: "FtABC123"
});