Understanding Triggers and Outcomes in Relay

Box Relay is a flexible and powerful way to automate routine and repeatable business processes that are centered around content. In Relay, you define those processes by creating workflows. Those workflows consist of two parts: triggers and outcomes. Triggers are events that initiate Relay workflows. Outcomes are the results that occur from completing Relay workflows.

Box provides a robust set of pre-built workflow templates, appropriate for a range of business lines and with pre-defined triggers and outcomes, that you can modify as you see fit. You may wish to try using a template to more quickly familiarize yourself with workflow components and to get started with Relay right away.

Tip

When you're comfortable creating workflows, you may also wish to begin sharing your workflows as customized templates for others throughout your organization to use.

This topic explains the triggers and outcomes available in Relay workflows.

Relay Triggers

There are several types of triggers that you can choose to begin a workflow in Relay:

• File events: actions that happen to a file within a parent folder, such as a file move or download
• Folder events: actions that happen to a folder within a parent folder, such as a folder move or share
• Files with metadata: actions that happen to a file with specified metadata attributes
• Task events: actions that happens to a file or folder within a parent folder as part of a workflow, such as a task being completed, approved, or rejected
• Manual start events: a workflow started on a file or folder by a user
• File Request events: requests made for a file 
• Scheduled events: a specified date
• Sign events: actions that happen to an electronic signature in a file, such as complete, cancelled, expired, or declined

The options you can configure for a Relay trigger depend on which trigger you choose.

File event options

Here, you are starting the workflow by selecting the file event.

Then you choose the type of file event. For example, this workflow may begin when a file is uploaded, copied, or moved. It may begin when a file is locked or unlocked. It may begin when a watermark is added, or when a security classification is applied. 

Your next choice is to specify where this event is to take place -- that is, in which folder the file resides or to which it will be moved or copied. To do this, click the Select a folder box and follow the prompts to specify the folder you want.

(If you select Classification Applied as your event, before you select a folder Relay prompts you to select the type of classification to apply. More on classifications in Box.)

• If the selected folder has a classification label, the label will be displayed next to the folder name.

• If any classification-based security policies apply to the folder, a short description will inform you about the restrictions. Click the icon next to the description to view the policy details.

Folder event options

Here, you are starting the workflow by specifying the type of event that happens to or with a folder.

Then you choose the folder event. For example, this workflow may begin when a new folder is created, or when an existing folder is copied, moved, or deleted, or when a collaborator added.

And as with a file event, you must specify where this event is to take place -- that is, the folder in which this triggered folder resides, or to which it will be moved or copied. To do this, click the Select a folder box and follow the prompts to specify the folder you want.

If the selected folder has a classification label, the label will be displayed next to the folder name.

File with metadata options

Here, you are starting the workflow when a metadata template you specify is applied to a file.

Then you choose which metadata template.

You can also add one or more pairs of metadata attributes and values to further filter the content that initiates the workflow. In that way you can be highly granular with the type of file around which you want to build your workflow -- for example, a contract from a specific vendor that exceeds a specific budget amount.

To do this, after you select the metadata template, click Add a condition. The Select an attribute menu displays. Click the Select an attribute down arrow to display a drop-down list of all the possible metadata values you can specify.

In the below example, you're limiting the workflow to files with the Background Check Alert metadata template applied and whose start date is July 21.

As with file and folder events, your next choice is to specify in which folder this event is to take place. To do this, click the Select a folder box and follow the prompts to specify the folder you want.

Task event options

Here, you are starting or continuing the workflow with a task event.

And then you select when the assignee has completed a general task.

... or has approved or rejected an approval task.

Manual start options

Here, the workflow does not kick off automatically, with no intervention on your part.  Instead, you partially pre-configure a workflow, directly from a document or set of documents that already exist in a Box folder.  Another individual -- the workflow starter -- selects one or more files, completes the incomplete steps of the workflow (such as designating task assignees), and only then manually initiates the workflow.  

A manual workflow is especially useful when task assignees vary -- for example, when a contract must be reviewed by different sets of corporate executives who are assigned by different department heads.  More details on manual start workflows.

File Request options

File Request is a separate feature, available to every paid Box Business Plan account (or higher).  Basically, File Request enables you to create a Web form in seconds that anyone can use to upload content to Box. When you specify File Request as a workflow trigger, the workflow launches automatically each time someone completes your File Request form and uses it to submit content to the Box folder you’ve designated.

This is especially useful when gathering content from someone is the first step in a workflow.  For example, Finance teams can use File Request to solicit vendor invoices and have Relay route those invoices through an approval process.  More details on using a File Request to kick off a workflow.

Scheduled event options

Here you can create a Relay workflow and schedule it to begin at a later date, and at regular occurrences (daily, weekly, monthly, and so on) so you only need to activate it once.

Among the reasons you may wish to do this:

• Month-end close process – review and approval of financial statements at the end of each month to close the books
• R&D capitalization check – engineering confirmation that quarterly resource allocations are correct for capitalization purposes
• Business review – department leads update quarterly objectives in a shared PowerPoint deck
• Compliance check – once a year employees across an organization confirm they’ve read the employee handbook

Your next choice is to specify a start date, a repeat frequency (daily, one or more times a week, monthly, annually), and an end date (at a designated time, after a certain number of occurrences, or never, if there is no end date).  Click each box to display a drop-down menu from which you can then click your desired options.

Sign event options

Relay allows you to define workflows based on the results of electronic signature events in Box Sign. Here, you are starting the workflow by selecting a Sign event.

Your next choice is to select a Sign event for the workflow, and then select which folder those Sign events will occur.

Outcome actions

The next step, regardless of what trigger you have chosen, is to specify an outcome. The choices in selecting an outcome vary somewhat.

• With file events the process of specifying an outcome is essentially the same as that of selecting a trigger, and is self-explanatory. 
  • If the selected file has a classification label, the label will be displayed next to the file name.

• • If any classification-based security policies apply to the file, a short description will inform you about the restrictions. Click the icon next to the description to view the policy details.

• • If the selected file is a Sign request file, you can choose between a file with or without a signing log.

• With folder events the process of specifying an outcome is also essentially the same as that of selecting a trigger, with one exception:
  • If you select Apply Classification as the folder outcome, you then must also click the Select a classification drop-down arrow and click the security classification you want (collaborators only, company employees only, short-term sharing, and so on).
  • Optionally, if you want the classification policy you select to take precedence over all other security classifications that may be in place on that folder's files and subfolders, check Overwrite all existing classifications with this value.

If you select a folder name that already exists, you can choose to use the existing folder instead of creating a new folder. Select Use existing folder when present to avoid creating a new folder.

If you decide to not use the existing folder and leave the checkbox unmarked, the workflow creates a new folder with a timestamp added at the end of the folder name.

Dynamic Naming

If you select copy, rename, or create (folders only) as the file/folder outcome, you can use dynamic variables to create folder or file names. These variables dynamically reference certain attributes without the need to hardcode the names within workflow.

• Available variables include:
  • current date
    • Example formats include: Month “DD” “YYYY”, “MM” “DD” “YYYY”, Month “YYYY”
  • Metadata attributes from file requests, and workflow folder,
    • Current outcome folders and files for Enterprise users.
  • file/folder names used within a trigger or current workflow outcome
  • Name of the folder that triggered the workflow
    • This variable references the folder modified in the trigger
• You can include both static and dynamic text when renaming, copying, or creating a folder or file.

*Metadata attributes from current outcome file or folders available for Enterprise plans and above.

Metadata outcome options

The process for creating metadata and task outcomes differs from creating metadata and task events. These are explained below.

As a result of a trigger event, you can:

• specify the file or folder to which you want to apply a metadata template, then specify the metadata template you want to apply.
• add or update metadata attributes in that template

Here’s an example:

• You apply a “press release” metadata template to a newly-created press release.
  • One of the attributes in this template is “Status.”
• You create a workflow such that, as the press release is developed, its status changes with each step, from “in progress” to “in review” to “approved.”

To apply a metadata template as an outcome and specify an attribute to change:

1. Under What is the next action? click Add Metadata.
2. Under What file or folder do you want to apply metadata to? click the down arrow and select the file.
   
   • This adds the template to the file or folder you’ve just specified.
3. Under What metadata would you like to apply? click anywhere in the box to display a list of the metadata templates.
4. Click the template you want.
5. To add a new metadata attribute-value pair, click Add a Value. Then click Select an attribute.
   • From the list of attributes that displays, locate the attribute you want to update, and then click the down arrow next to it to select a value.

Repeat the above steps and add discrete metadata outcomes to change the metadata attribute value to appropriately reflect the status of the workflow. For example, in the press release workflow, select the Status attribute and add a discrete value for in review when the release forwards to a reviewer, and when the release is ready to be published create an outcome with a status attribute of approved.

Get more information on creating a metadata structure for your enterprise.

Dynamic Naming with outcomes

When using metadata templates to build folder or file outcomes, you can use dynamic naming to reference the attributes you select. However, if you select a template that contains attributes your selected file or folder does not have, the missing attributes are indicated as missing in following the format upon execution of  the workflow.: “(missing){attribute title}”

Task outcome options

As the result of a trigger event, you can assign a task. For example, when a vendor uploads a contract proposal to the folder you specify, you can configure Relay to assign a task on that file to a specific individual for review or approval. You can also re-route the workflow if someone rejects the task they've been assigned. Regardless, when a task is approved or completed, Relay automatically moves the workflow forward.

Any one of the four triggers can result in a task outcome.

To create a task outcome

1. In the Outcome box, click Assign a Task.

2. Decide what type of task this is. If this you want the assignee merely to accept or reject the task -- for example, approving or rejecting a budget -- under What type of task would you like to assign? click Approval Task. For any other activities -- for example, copy editing a blog or filling out an invoice -- click General Task.
3. Under What are the task details? click the Assignee(s) box and begin typing the name or email address of the assignee. Relay displays a list of possible assignees. Click the assignee you want.
   • You can assign a task to the person who first initiated this workflow. This person displays in the list of possible assignees as the Workflow Starter. This is useful when you create a workflow that could be initiated by any number of people -- for example, when any one person from a group of loan underwriters submits a loan application for review and approval. (In one specific circumstance the workflow starter may not be the person who initiates the workflow. For details, see the note at the bottom of this article.)
   • You can assign a task to multiple individuals.
   • If you do assign a task to multiple individuals, every assignee must complete the task before Relay advances the workflow. If instead you want the workflow to move forward when just one assignee completes the task, check Only one assignee is required to complete this task.
4. In the Message box, enter a specific description of the task.
5. Optionally, enter the number of days or hours you want to allow the individual to complete this task.
6. In the Assign the task to a file box, specify on which file the task is to be assigned.
   
   

If a task assignee rejects the task, by default Relay ends the workflow. You have three options:

1. Do nothing and preserve the End the flow default.
2. Send Relay back to an earlier task outcome, essentially rerunning the workflow from that point forward.
3. Assign a general task.
   • You can assign this general task to the workflow starter, if you wish.

To send Relay back to an earlier task outcome

• Click Go to Outcome [outcome step #].
  • You must select a previous task outcome (either general or approval). For example, if someone rejects a task you cannot select a file copy or metadata update action.
  • You cannot select a task outcome later in the workflow.

To assign a general task

1. Click Assign a general task.
   • This can help you establish a review cycle. For example, if the vice president rejects a contract, you can route the contract back to the original sales rep. The sales rep can modify the terms of the contract accordingly and the workflow eventually makes its way back to the VP for approval.
   • You can only assign a general task -- not an approval task.
2. Choose what happens after this general task completes. Either:
   • continue the process from a previous task outcome; or
   • continue the process from the task outcome for which you've configured the rejection route.

As with other events, Relay logs and tracks rejected tasks. It tracks steps that have been repeated due to a rejection as separate successive events.

Notification outcomes 

Use notification outcomes to apprise stakeholders of key developments in workflow progress -- for example, when a process has ended or a file has been rejected.  Relay sends an automatic message to the people you designate, via the Box Web app and email.  If you're the workflow creator, you can customize the message Box sends, to ensure clarity or suggest another action for the message recipients.

More on rejection routing

More on creating a new workflow

More on file and folder security classification

More on watermarking

More on using Box File Request