Tutorials
Working with tasks
Tasks can be used as todo list for yourself and to assign work to be done to other people. While a task can be assigned to multiple people in Podio, this will in fact create a task for each assignee in the background. A powerful feature of tasks is it can reference - or be attached to - other API objects such a items and spaces. See the create task with reference operation for a full list. Tasks can also be private or public, they can have a due date, they can include one or more files and they can be organized with custom labels.
This article covers how to retrive a single task, how to get a list of tasks, how to create a new task and how to mark a task as completed. You can do many other things with tasks, refer to the documentation for the Tasks area for the full list.
Prerequisites
To follow this tutorial you should have setup a project with your preferred client library and be able to authenticate with the Podio API. You should also enter a few tasks, both on the global level and on a space.
Getting a single task
Figuring out the id of a task you have already created can be a bit tricky, but one way to it is to go to the task list and notice the id in the url when hovering over the task title. Another way is to create a task on an item. This will give you link in the sidebar with the task id in the url.
Once you have the id of one you tasks, you can retrieve information on the task like this:
Podio::Task.find(15126)
This will return a result similar to this:
{
"text" = > "Add jokes to documentation",
"status" = > "active",
"due_date" = > "2011-05-11",
"ref_link" = > "http://test.podio.com/devsiteexample/item/40825",
"description" = > "Please fix the referenced bug,",
"started" = > false,
"link" = > "http://podio.com/tasks/15126",
"completed_by" = > nil,
"ref_id" = > 40825,
"completed_on" = > nil,
"task_id" = > 15126,
"space_id" = > 7345,
"deleted_by" = > nil,
"external_id" = > nil,
"files" = > [{
"mimetype" = > "image/png", "created_on" = > "2011-05-06 12:51:42", "replaces" = > [], "file_id" = > 32812, "description" = > nil, "size" = > 55784, "created_via" = > {
"url" = > "", "display" = > false, "id" = > 1, "name" = > "Podio Development"
}, "created_by" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
}, "name" = > "attachments.png"
}], "labels" = > [{
"color" = > "BED9E2", "text" = > "work", "label_id" = > 30341
}, {
"color" = > "E9E9E9", "text" = > "devsite", "label_id" = > 30455
}], "private" = > false, "deleted_on" = > nil, "created_on" = > "2011-05-06 12:51:42",
"comments" = > [],
"group" = > nil,
"ref_title" = > "The API documentation is too boring",
"responsible" = > {
"link" = > "http://podio.com/-/contacts/6545", "avatar" = > 3209, "user_id" = > 6545, "profile_id" = > 6545, "type" = > "user", "name" = > "Casper Fabricius"
},
"created_by" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
},
"deleted_via" = > nil,
"created_via" = > {
"url" = > "", "display" = > false, "id" = > 1, "name" = > "Podio Development"
},
"completed_via" = > nil,
"ref_type" = > "item",
"ref" = > {
"link" = > "http://test.podio.com/devsiteexample/item/40825", "type" = > "item", "id" = > 40825, "data" = > {
"item_id" = > 40825, "app" = > {
"item_name" = > "Bug", "icon" = > "42.png", "app_id" = > 31060, "name" = > "Bugs (API example)"
}, "initial_revision" = > {
"created_on" = > "2011-05-06 12:51:42",
"created_by" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
},
"created_via" = > {
"url" = > "", "display" = > false, "id" = > 1, "name" = > "Podio Development"
},
"user" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
},
"type" = > "creation",
"revision" = > 0
}, "title" = > "The API documentation is too boring"
}, "title" = > "The API documentation is too boring"
},
}
If you scroll to the bottom of the above JSON, you will see that this particular task is referencing an item, specifically a bug on documentation humor level. Basic details about the item is included in the "ref" part of the hash. Further up in the response you will notice that the assigned person is returned in "responsible" with details about the contact, as well as information about the creator of the task in "created_by".
Getting a list of tasks
The recommended operation for getting a list of tasks is get tasks. It is quite advanced both in terms of offered response parameters and structure and content of the response. Amongst the parameters that can be given to filter the list are responsible, space, reference, due date and many more. The list can also be grouped by either "due_date", "created_by", "responsible", "app", "space" or "org" to display or parse tasks in the desired order. Also you can choose to get the full information on each task as shown in the JSON in the previous subsection if you set view to "full". And as for most list operations, you can specify the offset and the limit of the tasks to get.
Here is an example that gets the first 50 uncompleted tasks in a certain space grouped by due date:
Podio::Task.find_all(
:completed => 0,
:responsible => 6545,
:space => 7345,
:grouping => 'due_date',
:offset => 0,
:limit => 50
)
This will return a result similar to this:
[{
"status" = > "active", "due_date" = > "2011-05-09", "group" = > "upcoming", "task_id" = > 15126, "text" = > "Add jokes to documentation", "labels" = > [{
"color" = > "BED9E2", "text" = > "work", "label_id" = > 30341
}, {
"color" = > "E9E9E9", "text" = > "devsite", "label_id" = > 30455
}], "ref" = > {
"link" = > "http://test.podio.com/devsiteexample/item/40825", "type" = > "item", "id" = > 40825, "data" = > {
"item_id" = > 40825, "app" = > {
"item_name" = > "Bug", "icon" = > "42.png", "app_id" = > 31060, "name" = > "Bugs (API example)"
}, "initial_revision" = > {
"created_on" = > "2011-05-06 09:29:41", "created_by" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
}, "created_via" = > {
"url" = > "", "display" = > false, "id" = > 1, "name" = > "Podio Development"
}, "user" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
}, "type" = > "creation", "revision" = > 0
}, "title" = > "The API documentation is too boring"
}, "title" = > "The API documentation is too boring"
}
}, {
"status" = > "active", "due_date" = > nil, "group" = > "later", "task_id" = > 15119, "text" = > "sample task", "labels" = > [], "ref" = > {
"link" = > "http://test.podio.com/devsiteexample/item/40815", "type" = > "item", "id" = > 40815, "data" = > {
"item_id" = > 40815, "app" = > {
"item_name" = > "Bug", "icon" = > "42.png", "app_id" = > 31060, "name" = > "Bugs (API example)"
}, "initial_revision" = > {
"created_on" = > "2011-05-05 13:50:19", "created_by" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
}, "created_via" = > {
"url" = > "", "display" = > false, "id" = > 1, "name" = > "Podio Development"
}, "user" = > {
"user_id" = > 6545, "avatar" = > 3209, "name" = > "Casper Fabricius", "url" = > "http://podio.com/-/contacts/6545", "avatar_id" = > 3209, "type" = > "user", "id" = > 6545, "avatar_type" = > "file"
}, "type" = > "creation", "revision" = > 0
}, "title" = > "API documentation is too boring"
}, "title" = > "API documentation is too boring"
}
}]
When filtering by a space, as we do in the above example, not only tasks referencing the space directly will be returned. Tasks referencing items, apps and status messages in the space will also be included.
Creating a new task
New tasks can be created with or without a reference to an existing object using the create task with reference operation and create task operation respectively. For simplicity we will create a task that is not referencing an object:
Podio::Task.create(
:text => 'Add jokes to documentation',
:description => 'Please fix the bug',
:due_date => 3.days.from_now.to_s(:db), # Requires ActiveSupport / Rails
:responsible => 6545,
:label_ids => [30344]
)
We get the id of the new task back from the API.
Completing a task
Existing tasks can be updated and manipulated in many ways, but one interesting example is completing a task through the API. There is not much to it:
Podio::Task.complete(15127)