•••
 
Documentation   /   Reference: workflows   /   Workflow actions
 
 

Workflow actions

 

Item structure

Workflow code is a list of items. Each item starts with --#item: on its own line, followed by one directive per line. Leave a blank line between items.

--#item:
---depends_on:{earlier_item_id}
---id:{unique_id}
---alias:{item_alias}
---task_stage:{string}
---title:{string}
---description:{string}
---action:{action_name}
---options:{options}
---block:{true|false}
---optional:{true|false}
---undoable:{true|false}
---clearance_level:{adviser|admin|senior|email_address(es)}
---due:{number} {unit} FROM {timestamp} NOTIFY {email_addresses}
---filter[0-9]+|filter:answer {MATCH_TYPE} {value}
---filter[0-9]+|outcome:{later_item_id}
---outcome:{later_item_id}

Common directives

Directive Required Description
---id Always Unique ID for the item. Lowercase letters, numbers and underscores. Used by depends_on, outcomes, filters, the API and Data Studio, and as the variable holding the item's answer.
---action Always The action. See the table below.
---depends_on No The ID of the earlier item this one follows. The item only shows once that item is done and its outcome is this item. Without it, the item shows from the start.
---outcome No The ID of the item that follows this one. Ignored if the item has filters.
---filter[0-9]+|filter No A condition on the answer: answer {MATCH_TYPE} {value}. See Match types.
---filter[0-9]+|outcome No The ID of the item that follows when the filter with the same number matches.
---alias No A second name. Can be shared by several items; {{alias}} returns the last one answered.
---title Unless hidden The item's heading. Accepts variables and most logic statements.
---description No Instructions shown under the title. Accepts variables, logic statements and ~~~ line breaks.
---task_stage No Groups items into stages, for navigation within a task and for Data Studio's Stage column.
---options Often Action-specific setting, such as a template key or a URL.
---block No true stops later items being completed until this one is done. Default false.
---optional No true lets users skip the item. Default false.
---undoable No true lets users undo the item later. Default false.
---clearance_level No Who can complete the item: adviser, admin, senior (adviser or admin), or a comma-separated list of email addresses.
---due No A due date, with optional reminders. See Starting and managing tasks.

---title, ---description, ---optional, ---undoable and ---clearance_level don't apply to hidden actions (hidden, auto_email, sms, include_document, update_document, delete_document, payload with hidden output).

Actions and their directives

Action Action-specific directives Answer
specific_document options (template key, required), button_text, pass_variables Document key
auto_document options (template key, required), stage (create, lock, send, finalise), button_text, pass_variables Document key
copy_document options (document key, ID or alias, required), pass_variables New document key
get_document options (document key, required), done_at:1 (required) Document key
include_document options (document key, required), done_at:1 (required) Document key
update_document options (document key, ID or alias, required), pass_variables (required)
delete_document options (document key, ID or alias, required)
question options (question text, required), answer[0-9]+|text (required) Chosen answer text
text_input input_type (text, textarea, amount), mini_label, start_text, small_msg, string_format, default_value, button_text Text entered
dropdown options (required), mini_label, small_msg, default_value, button_text Value chosen
date mini_label, small_msg, default_value, button_text Date chosen
attachment Attached file
done
notify to (required), cc, bcc, subject (required), body (required)
auto_email from, to (required), cc, bcc, subject (required), body (required)
sms to (required), body (required)
stop options (done_at, document_key({id}), document_sent({id}), skipped({id})), block:true
wait options ({number} {unit} FROM {timestamp}, required), block:true, optional:true
hidden answer (required), done_at:1 The answer
text_output done_at:1
redirect options (URL, required), done_at:1
kill options (reason), block:true
include options (workflow key, required)
payload options (URL, required), method, content_type, pass_variables, custom_headers, save_output, look_at, output_pattern, look_at_fail, output_pattern_fail, hide_output, can_refresh Response, if saved
hook string_format The value received

Each action is described, with examples, in the Actions chapter: Document actions, Question and input actions, Communication actions, Flow control actions and Integration actions.

Value formats

Format Used by Syntax
Passed variables pass_variables, custom_headers, the API's passed {key_1}_IS_{value_1}_AND_{key_2}_IS_{value_2}
Option list dropdown options "Option 1","Option 2" or "value[:]Label","value[:]Label"
New line Any text directive ~~~
Email list to, cc, bcc, clearance_level Comma-separated addresses

Workflow introduction

Text above the first item, followed by a line containing only [[CHECKLIST]], is shown as the task's introduction:

Use this workflow for every new permanent hire.

[[CHECKLIST]]

--#item:
---id:first_step
...

Kitchen-sink example

--#item:
---depends_on:salary
---id:approval
---alias:sign_off
---task_stage:Approvals
---title:Approve the salary of {{salary}}
---description:Check it's within the band for {{job_title}}.~~~Reject if not.
---action:question
---options:Do you approve this salary?
---answer1|text:Approve
---answer2|text:Reject
---block:true
---undoable:true
---clearance_level:senior
---due:2 days FROM now NOTIFY {{manager_email}}
---filter1|filter:answer EQUALS Approve
---filter1|outcome:make_offer
---filter2|filter:answer EQUALS Reject
---filter2|outcome:tell_recruiter