Manual Start Workflow API + Box Relay

We recently released two new API endpoints for Box Relay. The first allows you to get any workflows configured for a given folder. The other allows you to start a flow within a workflow that has a trigger type of WORKFLOW_MANUAL_START. This guide shows you how to use the new endpoints.

Prerequisites

• You will need to have a manual start flow created. Here is a guide you can reference.

Step One

Setup a Box application.To use these new endpoints, you will need to enable the following application scopes, which can be found in the configuration section of the Developer Console: Manage Box Relay, Read all files and folders stored in Box, and Write all files and folders stored in Box. Depending on your application’s authentication method, you may need to have an Admin reauthorize the application.

Step Two

After you have set up a workflow, use the GET endpoint to see all of the workflows on a given folder. Here is cURL example of using this endpoint:

curl -i -X GET "https://api.box.com/2.0/workflows?folder_id=324234"\
     -H "Authorization: Bearer <ACCESS_TOKEN>"

A portion of the response will look similar to the below.

Step Three

To start a WORKFLOW_MANUAL_START flow, use the POST endpoint. Some of the information you receive in the response from the above GET call is required. Specifically, the flow id, folder id, any outcome ids + their configureable information and any file ids to start the flow need to be placed in the request body. The workflow id is a path parameter.

Here is an example cURL call for starting a flow for one file. You can start a flow for up to 20 files at one time.

curl -i -X POST “https://api.box.com/2.0/workflows/<WORKFLOW_ID>/start" \
   -H “Authorization: Bearer <ACCESS_TOKEN>” \
   -d ‘{ 
      “type”: “workflow_parameters”, 
      “flow”: { 
       “id”: “<FLOW_ID>”,
       “type”: “flow” 
      }, 
      “files”: [{ 
         “type”: “file”, 
         “id”: “<FILE_ID>” 
      }],
      “folder”: { 
       “id”: “<FOLDER_ID>”, 
       “type”: “folder” 
      }, 
      “outcomes”: [ { 
          “id”: “<OUTCOME_ID>”, 
          “type”: “outcome”, 
          “task_collaborators”: { 
             “type”: “variable”, 
             “variable_type”: “user_list”, 
             “variable_value”: [{ 
                 “type”: “user”, 
                 “id”: “<USER_ID>” 
             }] 
           }, 
           “completion_rule”: { 
             “type”: “variable”, 
             “variable_type”: “task_completion_rule”,
             “variable_value”: “all_assignees” 
           }, 
           “file_collaborator_role”: { 
             “type”: “variable”, 
             “variable_type”: “collaborator_role”, 
              “variable_value”: “viewer” 
           } 
       }] 
   }’

If your flow has (an) outcome(s) that is/are configurable at flow start time, you will need to pass in an outcomes array object listing all configurable information for each outcome.

The above example shows an outcome example for assigning a task. You can list each user you want to assign the task to in the variable_value array object of the task_collaborators object.

Similarly, the completion_rule and file_collaborator_role object’s variable_value can include the values any_assignee/all_assignees and editor/viewer/previewer/uploader/previewer uploader/ viewer uploader/co-owner respectively.

More configurable outcome examples will be coming soon!

Successfully starting a flow will return a empty 204 response. Any outcomes from the flow can be verified in the main Box Web App.

SDK support

SDK libraries will be updated soon to support these endpoints! In the meantime, feel free to use our latest Postman Collection or cURL.

Feedback

• If you encounter any bugs or break/fix issues, please open a ticket directly with our product support team.
• If you have any how-to questions on API usage, please post on our developer forum.