Tutorials
Working with items
In many ways, items can be said to be the core entities of Podio that many other things reference, either by being structure around them (e.g. organizations, spaces and apps) or by referencing them (e.g. tasks, comments, files etc.). Items are entries in an app. If you think of app as a table, items will be the rows in the table. Each item holds values for each field in the app. Refer to the documentation for the Items area for an overview of the different field types.
This article covers how to retrieve a single item, get all items in an app, create a new item, update items and delete items.
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 have the Bugs app or any other app (preferably one with many different field types) setup in a test space. Finally you should enter a few bugs into the app so we have some items to retrieve. Later it will also be explained how you can create items through the API.
Getting a single item
The get item operation lets you retrieve most information relevant for a single item. You can get the id of an item by going to a bug and clicking the small cloud icon on the right side of the gray action bar at the top of the item. Invoke the API method like this, replacing the id with your own:
Podio::Item.find(40815)
This will return a JSON-formatted result similar to this:
{
"app": {
"status": "active",
"name": "Bugs",
"item_name": "Bug",
"url_add": "https://podio.com/...",
"icon_id": 42,
"link_add": "https://podio.com/...",
"app_id": 196950,
"url": "https://podio.com/...",
"link": "https://podio.com/...",
"url_label": "bugs",
"config": {
"item_name": "Bug",
"icon_id": 42,
"type": "standard",
"name": "Bugs",
"icon": "42.png"
},
"space_id": 39096,
"icon": "42.png"
},
"user_ratings": {
},
"created_on": "2013-11-04 09:21:22",
"like_count": 0,
"comments": [
],
"last_event_on": "2013-11-04 09:21:22",
"linked_account_data": null,
"refs": [
],
"app_item_id_formatted": "3",
"subscribed": true,
"title": "API documentation is too boring",
"tags": [
],
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 09:19:07"
},
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"subscribed_count": 1,
"reminder": null,
"revisions": [
...
],
"ref": null,
"is_liked": false,
"files": [
],
"invite": null,
"ratings": {
"like": {
"average": null,
"counts": {
"1": {
"total": 0,
"users": [
]
}
}
}
},
"app_item_id": 3,
"link": "https://podio.com/...",
"item_id": 92534111,
"recurrence": null,
"fields": [
{
"status": "active",
"type": "text",
"field_id": 1307640,
"label": "Title",
"values": [
{
"value": "API documentation is too boring"
}
],
"config": {
"description": null,
"settings": {
"size": "small"
},
"required": true,
"mapping": null,
"label": "Title",
"visible": true,
"delta": 0,
"hidden": false
},
"external_id": "title"
},
{
"status": "active",
"type": "text",
"field_id": 1307645,
"label": "Description of problem",
"values": [
{
"value": "<p>It's just too boring.</p>"
}
],
"config": {
"description": "Enter a detailed description of the bug.",
"settings": {
"size": "large"
},
"required": false,
"mapping": null,
"label": "Description of problem",
"visible": true,
"delta": 1,
"hidden": false
},
"external_id": "description-of-problem"
},
{
"status": "active",
"type": "category",
"field_id": 46605074,
"label": "Status",
"values": [
{
"value": {
"status": "active",
"text": "Assigned",
"id": 3,
"color": "DCEBD8"
}
}
],
"config": {
"description": "Enter a status for the issue, and keep it up to date as the bug is worked on. It will then be possible to filter by bug status.",
"settings": {
"multiple": false,
"options": [
{
"status": "active",
"text": "Reported",
"id": 1,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Accepted",
"id": 2,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Assigned",
"id": 3,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Fixed",
"id": 4,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Duplicate",
"id": 5,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Rejected - works for me",
"id": 6,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Rejected - feature request",
"id": 7,
"color": "DCEBD8"
}
]
},
"required": true,
"mapping": null,
"label": "Status",
"visible": true,
"delta": 3,
"hidden": false
},
"external_id": "status"
},
{
"status": "active",
"type": "category",
"field_id": 46605075,
"label": "Priority",
"values": [
{
"value": {
"status": "active",
"text": "Medium",
"id": 2,
"color": "DCEBD8"
}
}
],
"config": {
"description": "Select the bugs priority. 'High' priority means that it should be fixed today, 'Medium' should be within a week, and 'Low' when there is time.",
"settings": {
"multiple": false,
"options": [
{
"status": "active",
"text": "Low",
"id": 1,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Medium",
"id": 2,
"color": "DCEBD8"
},
{
"status": "active",
"text": "High",
"id": 3,
"color": "DCEBD8"
}
]
},
"required": true,
"mapping": null,
"label": "Priority",
"visible": true,
"delta": 4,
"hidden": false
},
"external_id": "priority"
},
{
"status": "active",
"type": "contact",
"field_id": 1307642,
"label": "Developer assigned",
"values": [
{
"value": {
"mail": [
"fabricius@podio.com"
],
"profile_id": 6545,
}
}
],
"config": {
"description": "Assign a developer to fix the bug here. Tip: You don't have to assign a developer unless you know for sure who should fix it.",
"settings": {
"type": "space_users",
"valid_types": [
"user"
]
},
"required": false,
"mapping": null,
"label": "Developer assigned",
"visible": true,
"delta": 5,
"hidden": false
},
"external_id": "developer-assigned"
}
],
"rights": [
"grant",
"comment",
"delete",
"add_file",
"view",
"update",
"add_conversation",
"add_task",
"rate",
"subscribe"
],
"initial_revision": {
"item_revision_id": 167611126,
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 09:19:07"
},
"created_on": "2013-11-04 09:21:22",
"user": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 09:19:07"
},
"type": "creation",
"revision": 0
},
"current_revision": {
"item_revision_id": 167611126,
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 09:19:07"
},
"created_on": "2013-11-04 09:21:22",
"user": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 09:19:07"
},
"type": "creation",
"revision": 0
},
"external_id": null
} That is clearly a lot of data, since this operation returns not just the field values of the item, but also all entities referring the item: Comments, tasks, ratings and so on. To get just the field values and some basic details, use the get basic item operation
Podio::Item.find_basic(40815)
This gives us a slightly more compact result, but still with all the values of the item:
{
"app": {
"status": "active",
"name": "Bugs",
"item_name": "Bug",
"url_add": "https://podio.com/...",
"icon_id": 42,
"link_add": "https://podio.com/...",
"app_id": 196950,
"url": "https://podio.com/...",
"link": "https://podio.com/...",
"url_label": "bugs-api-example",
"config": {
"item_name": "Bug",
"icon_id": 42,
"type": "standard",
"name": "Bugs",
"icon": "42.png"
},
"space_id": 39096,
"icon": "42.png"
},
"created_on": "2013-11-04 09:21:22",
"last_event_on": "2013-11-04 09:21:22",
"app_item_id_formatted": "3",
"recurrence": null,
"title": "API documentation is too boring",
"participants": {
},
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 12:13:30"
},
"pinned": false,
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"subscribed_count": 1,
"reminder": null,
"ref": null,
"tags": [
],
"app_item_id": 3,
"link": "https://podio.com/...",
"item_id": 92534111,
"rights": [
"grant",
"comment",
"delete",
"add_file",
"view",
"add_conversation",
"add_task",
"rate",
"update",
"subscribe"
],
"fields": [
{
"status": "active",
"type": "text",
"field_id": 1307640,
"label": "Title",
"values": [
{
"value": "API documentation is too boring"
}
],
"config": {
"description": null,
"settings": {
"size": "small"
},
"required": true,
"mapping": null,
"label": "Title",
"visible": true,
"delta": 0,
"hidden": false
},
"external_id": "title"
},
{
"status": "active",
"type": "text",
"field_id": 1307645,
"label": "Description of problem",
"values": [
{
"value": "<p>It's just too boring.</p>"
}
],
"config": {
"description": "Enter a detailed description of the bug.",
"settings": {
"size": "large"
},
"required": false,
"mapping": null,
"label": "Description of problem",
"visible": true,
"delta": 1,
"hidden": false
},
"external_id": "description-of-problem"
},
{
"status": "active",
"type": "category",
"field_id": 46605074,
"label": "Status",
"values": [
{
"value": {
"status": "active",
"text": "Assigned",
"id": 3,
"color": "DCEBD8"
}
}
],
"config": {
"description": "Enter a status for the issue, and keep it up to date as the bug is worked on. It will then be possible to filter by bug status.",
"settings": {
"multiple": false,
"options": [
{
"status": "active",
"text": "Reported",
"id": 1,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Accepted",
"id": 2,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Assigned",
"id": 3,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Fixed",
"id": 4,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Duplicate",
"id": 5,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Rejected - works for me",
"id": 6,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Rejected - feature request",
"id": 7,
"color": "DCEBD8"
}
]
},
"required": true,
"mapping": null,
"label": "Status",
"visible": true,
"delta": 3,
"hidden": false
},
"external_id": "status2"
},
{
"status": "active",
"type": "category",
"field_id": 46605075,
"label": "Priority",
"values": [
{
"value": {
"status": "active",
"text": "Medium",
"id": 2,
"color": "DCEBD8"
}
}
],
"config": {
"description": "Select the bugs priority. 'High' priority means that it should be fixed today, 'Medium' should be within a week, and 'Low' when there is time.",
"settings": {
"multiple": false,
"options": [
{
"status": "active",
"text": "Low",
"id": 1,
"color": "DCEBD8"
},
{
"status": "active",
"text": "Medium",
"id": 2,
"color": "DCEBD8"
},
{
"status": "active",
"text": "High",
"id": 3,
"color": "DCEBD8"
}
]
},
"required": true,
"mapping": null,
"label": "Priority",
"visible": true,
"delta": 4,
"hidden": false
},
"external_id": "priority2"
},
{
"status": "active",
"type": "contact",
"field_id": 1307642,
"label": "Developer assigned",
"values": [
{
"value": {
"mail": [
"fabricius@podio.com"
],
"image": {
...
},
"profile_id": 6545,
}
}
],
"config": {
"description": "Assign a developer to fix the bug here. Tip: You don't have to assign a developer unless you know for sure who should fix it.",
"settings": {
"type": "space_users",
"valid_types": [
"user"
]
},
"required": false,
"mapping": null,
"label": "Developer assigned",
"visible": true,
"delta": 5,
"hidden": false
},
"external_id": "developer-assigned"
}
],
"initial_revision": {
"item_revision_id": 167611126,
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 12:13:30"
},
"created_on": "2013-11-04 09:21:22",
"user": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 12:13:30"
},
"type": "creation",
"revision": 0
},
"current_revision": {
"item_revision_id": 167611126,
"created_via": {
"url": null,
"auth_client_id": 1,
"display": false,
"name": "Podio",
"id": 1
},
"created_by": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 12:13:30"
},
"created_on": "2013-11-04 09:21:22",
"user": {
"user_id": 6545,
"name": "Casper Fabricius",
"url": "https://podio.com/users/6545",
"type": "user",
"image": {
...
},
"avatar_type": "file",
"avatar": 38740,
"id": 6545,
"avatar_id": 38740,
"last_seen_on": "2013-11-04 12:13:30"
},
"type": "creation",
"revision": 0
},
"external_id": null
} Many other operations exists in the items area that will give you a subset of the information you get in the full get item operation, if you don't require all information and want to be nice to our API servers.
Getting all items in an app
The get items operation lets you retrieve all items in an app:
Podio::Item.find_all(31060)
The result of this operation is a JSON array of items very similar to what is returned from the get basic item operation along with information about the total number of items.
Most operations returning a list of objects support options limiting and sorting the result, and get items is no exception. Further, this specific operation also support filtering the items by any field and value, but that is beyond the scope of this tutorial. Refer to the views area for more information.
If, say, you wanted to have a paginated and sorted list of the bugs inside your own project, assuming 20 bugs per page, getting page 2 and sorting by created_on can be done like this:
Podio::Item.find_all(31060, :limit => 20, :offset => 20, :sort_by => 'created_on')
Filtering results
Often you want to filter a list of items instead of getting all items in an app. You can pass field_ids as attributes to the get items operation to limit the items returned. For example:
# Get all bugs where the Developer is set to a specific user
# Assuming the field_id of the Developer field is 6058630
# And the user_id to filter on is 6374
Podio::Item.find_all(31060, :filters => {6058630 => 6374}, :sort_by => 'created_on')
You can also get items as an Excel file. Note that these operations return a file, and not a JSON object.
Creating a new item
You create an item using the add new item operation. While the operation optionally accepts an external id for your own reference and arrays of file ids and tags, the main part of the request is an array fields, each specifying either the field id or the external id of the field, along with an array of one or more values for the field.
Each field in an application has a numeric id, but it also gets an external_id assigned by the API: A text identifier generated from the label of the field, uniquely identifying the field within the app. When creating and updating item fields you can use either of these, however, we recommend the using the external_id as this will make your code more readable and your requests easier to debug.
Different fields require different values. For many fields, a single value is sufficent, such as for the text field and the number field (in the latter case, the value must be just a number, not a string with a number). Many fields supports multiple values, such as the contact field and the category field. Multiple values must be supplied in an array, however, if you set just one value an array is not required. Finally some fields have consists of several value properties, which is referred to as "sub_ids" in the documentation. One example is the money field, which requires both the monetary value and the currency, another is the date field, which works with a single date, but also support setting both a startdate and an enddate.
The items area provides an overview of the values supported by each field type, but this example should give you the general idea:
// Example request to add new item operation for the Bugs app.
// Not all of these fields are in the example app, but are added here for the sake of the example.
{
"fields": {
// The title field has only a single value
"title": "The API documentation is too boring",
// The status field (of the type category) is configured to only allow one value
"status": 1, // Category with id 1 is Low
// The developer field (of the type contact) can reference multiple profile_ids
"developer": [6374, 9834],
// The business value field (of the type money) requires two value properties: "value" and "currency"
"business_value": { "value": 5500, "currency": "USD" },
// The due date field (of the type date) supports two value properties: "start" and "end"
"due_date": { "start": "2011-05-06 11:27:20", "end": "2011-05-09 11:27:20" },
// But a date field also accepts just a single date
// (It's not allowed to supply the same field multiple times in the same request, though)
"due_date": "2012-01-04 10:22:35",
// An embed field allows users to provide multiple links each optionally with a connected thumbnail
"link": [{ "embed": 2648, "file": 93745 }, { "embed": 2652 }]
}
}
The code to generate the request shown above through one of our client libraries and create a new item looks like this:
Podio::Item.create(31060, {
:fields => {
'title' => 'The API documentation is too boring',
'developer' => [6545, 21158],
'business_value' => { :value => 5500, :currency => 'USD' },
'due_date' => { :start => '2011-05-06 11:27:20', :end => 3.days.from_now.to_s(:db) }
}
})
Note that a time of day is not required in a date field and that the end part is optional. Also, the 3.days.from_now.to_s(:db) syntax in the Ruby sample code will only work with the ActiveSupport gem loaded, such as in a Rails application.
Updating existing items
Item updating works very similar to creation, but instead of providing the app id as we do when creating items, you must specify the item id when updating.
You can update all field values in one operation or update the value of just a single field. One thing to keep in mind is that omitting a field when updating all field values will simply leave it's value unchanged, while including the field with a value of null will remove the field's value.
Podio::Item.update(210606, {
:fields => {
'title' => 'The API documentation is much more funny',
'business_value' => { :value => 20000, :currency => 'EUR' },
'due_date' => { :start => '2011-05-06 11:27:20', :end => 5.days.from_now.to_s(:db) }
}
})
Deleting existing items
Deleting an item is a simple DELETE call to /item/{item_id}. Using a client library it is done like this:
Podio::Item.delete(40825)