Tutorials

Working with files

Files can be uploaded to Podio, but they don't stand on their own, they are always attached to another object. Files can be attached to Items, Tasks, Comments, and Status Messages. The maximum allowed file size is currently 100MB and there are a few types of files that you can't upload at all. The documentation for the Files area has a list of all disallowed file types

This article covers how to upload a file, how to attach a file and how to download a file.

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 setup in a test space. Finally you should enter a bug into the app so we have one item we can attach files to.

Uploading a file

The upload file operation lets you upload any file. Since we're dealing with binary data for most files, this operation is not using JSON as the input format, but multipart/form-data. This is the same format the browser uses when uploading a file through a HTML form and is supported by pretty much every HTTP library. Our Podio client libraries abstract this away and all you need is a local file and its name to upload a file to Podio:

php ruby 

File.open("/path/to/example.jpg") do |example_file|
  Podio::FileAttachment.upload(example_file, "example.jpg")
end

This will return a full JSON-formatted result similar to this:

json 

{
  "mimetype": "image/jpg",
  "created_on": "2011-07-11 11:41:44",
  "replaces": [],
  "link": "https://files.podio.com/35424",
  "file_id": 35424,
  "description": null,
  "size": 106499,
  "created_via": {},
  "created_by": {},
  "name": "example.jpg"
}

This is the same result you get when you request a single file. The most important information is the file_id and the link. The file_id is needed to now attach this file to an Item, Task, Comment or Status Message. The link is the URI this file has inside Podio, which you could use to display or download the file.

We only uploaded the file so far, which is not really that useful, since it won't show up anywhere in Podio. So the next step is to attach it.

Attaching a file

The attach file operation lets you attach a file to a Item, Task, Comment or Status Message. The object you're attaching to has to exist when you call this operation and you need to know its id. This is how you would attach a file to an Item with the id 42:

php ruby 

Podio::FileAttachment.attach(35424, "item", "42")

The operation raises an exception if anything goes wrong, otherwise attaching the file was successful.

The more common operation is creating a new object, a task for example, and at the same time attaching a file. This would be done like this:

php ruby 

File.open("/path/to/example.jpg") do |example_file|
  new_file    = Podio::FileAttachment.upload(example_file, "example.jpg")
  new_task_id = Podio::Task.create(:text => "Task with file", :file_ids => [new_file.file_id])
end

This way the uploaded file is attached to the task right away and returned as part of the result when you look up this task. You don't need to manually call the attach operation and you can also attach multiple files at once.

Downloading a file

There are two ways of displaying or downloading a file: Every file object has link attribute, which contains the full URI to that file inside Podio. In order to access it, you need to be logged in to Podio and have rights to view this file. Depending on your use case, that might be enough.

php ruby 

file = Podio::FileAttachment.find(42)
puts file.link

Opening that URI in your browser displays the file when you're logged in to Podio. You can also directly download the file from the API, if you send along the OAuth Authorization header in your request. For Ruby and PHP there are built-in methods on the file objects to use:

php ruby 

File.open('/tmp/downloaded_file', 'w') do |downloaded_file|
  file = Podio::FileAttachment.find(42)
  downloaded_file.write(file.raw_data)
end