Workflows API Getting Started Guide
If you like using a board to organise your work and need to move your tasks across multiple stages, the Workflows API will allow you to do this. In this guide we'll show you how to get started by creating a new board for your project and adding 3 stages to it (To Do, Doing and Done).
We'll then show you how to list these stages and view their unique IDs, so that you can add tasks to the stages.
Finally you'll learn how to move a task from one stage to the next as your work progresses. In the example below we will assume you are working with a project that has a projectId of 12345.
This guide assumes you have read through our Getting Started with the Teamwork.com API guide and know your URL and API key.
Let's get started.
Create a new board for your project
{
"workflow": {
"name": "my project workflow",
"projectId": {projectId},
"projectSpecific": true
}
}In the response, you should see a workflow object. Let's store its ID as a variable that we can use later:
Store the workflow ID below, you will need to use later:
//pseudocode
const workflowId = response.workflow.id;By default, each workflow is created with a default "backlog" stage, and this is where all tasks will reside until moved. If you want to add more stages to your board, you will need to call the following endpoint:
Add three stages to a board
{
"stages": [
{
"color": "#e12d42",
"name": "To Do"
},
{
"color": "#f7c6c7",
"name": "Doing"
},
{
"color": "#f7c6c7",
"name": "Done"
}
]
}We need to get a list of the task lists so that we can find the list we want to add a task to:
GET /projects/api/v3/workflows/{workflowId}/stages.json
Store the IDs of any stages you will need to use later:
//pseudocode
const toDoColumnID = response.stages.filter((stage) => stage.name === "To Do"))?.id;
const doingColumnID = response.stages.filter((stage) => stage.name === "Doing"))?.id;
const doneColumnID = response.stages.filter((stage) => stage.name === "Done"))?.id;We need to get a list of the task lists so that we can find the list we want to add a task to:
GET /projects/api/v3/workflows/{workflowId}/stages.json
Store the ID below, you will need to use later:
//pseudocode
const targetTaskListID = response.tasklists.find((list) => list.name === "Developer Tasks")?.id;Now lets move the task across the board to the next stage:
POST /projects/api/v3/workflows/{workflowId}/stages/{doingStageID}/tasks.json
Response for
{
"task": {
"name": "New Task"
},
"workflows": {
"stageId": toDoColumnId,
"workflowId": workflowId
}
}We need to store the ID of the new task so we can move it across the board:
//pseudocode
const newTaskID = response.task.id;Now lets move the task across the board to the next stage:
POST /projects/api/v3/workflows/{workflowId}/stages/{doingStageID}/tasks.json
Response for
{
"taskIds": [
newTaskID
]
}The above request can also be used to move multiple tasks to a stage at once if you add more task IDs to the taskIds array.
So we've now created a new board on a project, added multiple stages to the board, added a task to the board and moved the task across the board. We hope this helps you get started using workflows!
Feedback
If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.