Box Developer Blog
Published in

Box Developer Blog

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.

--

--

--

News and stories for working with the Box APIs

Recommended from Medium

Building the Business Case for Test Automation

RAM Forensics (Read data from RAM)

Webinar recording: Modern Cloud-native development using live streaming data

June Porto Tech & Creative Events

Industry Insights for Tech Newbies

A stock image of clouds

Can we override a static method in Java?

Programming: When Not To Follow Principles

What the winningest NFL coach (Don Shula) can teach us about IT projects

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alex Novotny

Alex Novotny

I’m a Box Developer Advocate, helping others learn how to maximize their investment through Box Platform.

More from Medium

Deploy and run a containerized web app with Azure App Service

How to enable Jumbo frames in AWS EC2 Windows Server !!

7 Options to Modernize Legacy Applications for Future

Analytics API are now in public beta!