Tips & recommendations

Organizing custom reports and data exports with portfolios

It is common for customers to use the API to export Asana data. You can use portfolios as a container for the Asana data you want to access with your script/app.

For instance, if you want to export data from certain Asana portfolios and projects, start by creating a new portfolio. Then add all of the projects and portfolios you want to report on to this new portfolio. For reference, here is an overview of how portfolios work in Asana.

Once all of your target data is in this new top-level portfolio, you can create a custom exports script to pull all this data via the API. A high-level approach could be:

1. Requesting the portfolio items from the top-level portfolio
2. Collect the GIDs for all of the projects in your portfolio
3. If the item is another portfolio, request its items until you are down to just a collection of the projects that are nested within your top-level portfolio
4. For each project, request all of its tasks

Here is a code example for a script that uses this approach to pull data from next portfolios and exports it to a CSV: Github repo for the portfolios export script

Working with portfolios and other collections of objects

• Consider using a recursive function if you want to request the data from within nested objects (e.g. portfolios of portfolios or nested subtasks).
• Requests will often return compact representations of objects. Use the opt_fields parameter to get the exact data you need.

For example, to get the names, custom fields, and owners for the items in a portfolio, use something like:
GET /portfolios/portfolio_gid/items?opt_fields=name,custom_fields.(name|display_value),owner

Connect your app to the Asana user interface

App Components are an advanced feature that allow you to visually connect your custom app to the Asana UI. You can use app components to display customized widgets, forms, and rules to create a custom in-product experience for your users.

🚧

Build defensively

When building your app, do not assume API behavior that isn't explicitly documented. We are continually adding features to the Asana product to meet the needs of our customers. As a consequence, the API needs to change along with the web app so that customers can programmatically access new features.

We do everything possible to avoid breaking changes. However, this isn’t always possible. Developers who build defensively encounter fewer disruptions from these changes.