Introducing the Box Relay Workflow API

Box Developers
Jul 31, 2018 · 4 min read

Most businesses today operate in a world in which a large portion of their employees’ day is filled with manual, repetitive tasks — like pulling and updating information in various places or checking in with colleagues on the latest status of a project. These inefficiencies, combined with a lack of interconnected systems, is not only expensive for the business, but also slows down revenue-generating and cost-saving processes.

Existing workflow and ECM tools available today fail to solve this challenge because they don’t seamlessly fit into how and where work actually gets done. These tools are too static and difficult to use and often require heavy lifting from IT organizations to be effective.

Last year, we disrupted the workflow market with Box Relay, the first workflow solution designed specifically to help employees across the enterprise automate their own everyday processes. Co-developed with IBM, Box Relay is already accelerating collaboration, standardizing processes and reducing the risk of losing details in email.

Today, we are excited to announce three new features for Box Relay, including the new Relay Workflow API. This API expands the way businesses can use Box Relay, enabling you to integrate Relay with other business systems in your enterprise, such as your CRM, HCM or ERP systems, to launch Relay workflows based on activity in these systems or to trigger activity in another system when a Relay workflow is complete.

For example, some of the ways you could use the Relay Workflow API would be to:

  • Launch an employee onboarding workflow in Relay whenever a new employee record is created in an HCM system
  • Launch an account assignment workflow in Relay whenever a new account is added to a CRM system
  • Launch a mitigation workflow whenever a form response indicates there is a technical issue with your product

What can the Relay Workflow API do?

The new Relay Workflow API allows you to launch Relay workflows and retrieve the statuses of those workflows from within your application. It also allows you to view which workflow templates have been published in your instance of Box Relay. In this initial release, the Relay Workflow API can:

Get a list of published workflow templates, which allows you to see a list of all the templates published in your instance of Box Relay. This will allow you to see the template id, template name, state, and publish date of these templates.

Launch a Relay workflow, defining the owner of the workflow, the title of the workflow, the description and any files in Box that should be attached to the workflow object.

Here’s an example of launching a Relay workflow using cURL:

curl https://api.box.com/graphql \
-X POST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/graphql" \
-d 'mutation { launchWorkflow( templateId: "62204E80-0000-C298-A67E-90C8B4CBA64F" name: "MY WORKFLOW" description: "DESCRIPTION OF THE WORKFLOW" owner: "17738362" fileId: "5000948880" timeZone: "America/New_York" ) { id name description state } }'

Get the status of Relay workflows, including which users are associated with your workflows, what the outstanding tasks in your workflow are and what steps your workflows are currently on.

Here’s an example of how you can get a list of all workflows using cURL:

curl https://api.box.com/graphql \
-X POST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/graphql" \
-d '{ templates(id: "62204E80-0000-C298-A67E-90C8B4CBA64F") { count pageInfo { hasNextPage hasPreviousPage startCursor endCursor } items { id name description state published publishedBy { id } created createdBy { id } referenceName version modified modifiedBy { id } workflows { items { id } } } } }'

To check the status of a Relay workflow, you can look at the state parameter in the response (as highlighted in bold below):

{
"data": {
"templates": {
"count": 1,
"pageInfo": {
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "NjIyMDRFODAtMDAwMC1DMjk4LUE2N0UtOTBDOEI0Q0JBNjRG",
"endCursor": "NjIyMDRFODAtMDAwMC1DMjk4LUE2N0UtOTBDOEI0Q0JBNjRG"
},
"items": [
{
"id": "62204E80-0000-C298-A67E-90C8B4CBA64F",
"name": "MY WORKFLOW",
"description": "DESCRIPTION OF THE WORKFLOW",
"state": "Active",
"published": "2018-03-13T17:00:43Z",
"publishedBy": {
"id": "267675817"
},
"created": "2018-03-13T17:00:35Z",
"createdBy": {
"id": "267675817"
},
"referenceName": "myWorkflow",
"version": "1.0",
"modified": "2018-03-13T17:00:43Z",
"modifiedBy": {
"id": "267675817"
},
"workflows": {
"count": 5,
"items": [
{
"id": "62AB1E70-0000-C109-89D5-CFDCA7AFDF2D"
},
{
"id": "62AB3430-0000-C118-AAC8-8278E79280C5"
},
{
"id": "62AB3600-0000-C191-B7EF-EB067BC04E60"
},
{
"id": "62AB3740-0000-C1D3-9EB0-C924D2F29DDA"
},
{
"id": "633B0D70-0000-C19E-9B1E-670A5144B8A7"
}
]
}
}
]
}
}
}

The Relay Workflow API is generally available now to any customers using Box Relay. To get started, head over to the Box Developer site to check out the API documentation.

If you’re interested in learning more about Box Relay, please box.com/relay or reach out to learn more.

More From Medium

Also tagged Workflow

Top on Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade