Sections: Overview | Get started | feature guides | Tutorials | Resources | Export project statuses to CSV | Introduction | What you'll build | Try it! | Test data | Tutorial | App structure | Starter code | 1. Create the boilerplate | 2. Parse and validate user input | 3. Extract projects from the portfolio | 4. Consolidate data | 5. Generate the CSV and download | 6. Clean up | Data access | Complete code | Conclusion | Extending this application | What's next Overview Build an app with Asana Object hierarchy Common use cases Get started API explorer Developer sandbox Quick start guide FAQ feature guides Authentication Personal access token OAuth OAuth Code Samples / Libraries OAuth scopes OpenID Connect API Input/output options Batch requests Custom fields Custom external data Dates and times Rich text Rate limits Errors Pagination SCIM Audit log events Deprecations Workspace events Graph exports App components Building app components App components on tasks App components on rules UI builder Troubleshooting App component approval checklist Incoming web requests Manage your app Share your app App listing guidelines Publish your app Update your app Script Actions How to write a Script Action script FAQ Webhooks Tutorials Export project statuses to CSV Automate status reports with Google Apps Scripts Resources API reference Client libraries JavaScript Migration guide: v3 Python Migration guide: v5 Ruby Java PHP MCP Server Using Asana's MCP Server Compatible MCP Clients Connecting Coding Clients to Asana's V2 server Integrating with Asana's MCP Server MCP Tools Reference Examples App component examples Custom field analysis Portfolio to CSV export Script action examples Triage bot Using bots Postman Collection Changelog Powered by Export project statuses to CSV Build a custom reporting solution using Asana's API Introduction Asana is the source of truth for many organizations’ work management. It is the essential tool for understanding who is doing what by when . With so much rich data in Asana, teams often want to learn about how well work is getting done. Asana provides a suite of both native reporting tools and powerful integrations with common reporting solutions like Power BI and Tableau to help you translate and review this data in an organized, easily digestible format. Alongside these universal tools, Asana also provides a platform for building custom reporting solutions -- made possible by a flexible API . Asana’s API provides a means for software and scripts to read information from inside Asana, input information from outside Asana, and automatically react when things change. In this tutorial, you will learn how to export project statuses to a CSV so that project statuses can be used to build reports in other tools. What you'll build By following this tutorial, you'll build a basic reporting application that reads projects from a portfolio , then exports status updates from those projects into a CSV. Portfolios are available to all Business and Enterprise customers . To learn more about status updates, check out our guide . Try it! Before you build it yourself (or if you'd simply like to run the application as an end-user), you can demo the complete application by following these brief steps: Get a personal access token (PAT). This token is used by the application to make requests against Asana's API Get the GID of a portfolio . This is the existing portfolio for which you'd like to generate a CSV report. For example, if the link to your portfolio is https://app.asana.com/0/portfolio/12345/list , the GID of your portfolio is 12345 📘 Test data If you do not have a portfolio with nested projects and status updates that you’d like to test with, you can follow these brief steps to create that data. We recommend doing this in a developer sandbox or other test workspace: Click on each of these links to automatically import four projects with included test data: Project 1 , Project 2 , Project 3 , Project 4 Create a portfolio ( learn how to create a portfolio ) Add the newly-created projects into the newly-created portfolio ( learn how to add work to a portfolio ) Download the project here on your local machine Open index.html in your browser Select Generate CSV after providing your PAT and portfolio GID Tutorial After following this tutorial, you'll have created a basic reporting application that reads project from a portfolio then exports status updates from those projects into a CSV. You will be able to: ✅ Work with objects in the object hierarchy in Asana ✅ Create and use a personal access token for making API requests ✅ Set up input/output options to customize the responses received from your API requests ✅ Build and a run a local script to: GET a user to verify the personal access token GET portfolio items , which may include both projects and portfolios Parse status updates from projects and export them to a CSV App structure Under the hood, the application uses vanilla JavaScript, HTML, and CSS. No third party libraries or frameworks are used in this application. The applications consists of just three files: File Description index.js Entry point of the application. The single runExport() function is run when the user clicks the Generate CSV button on the main index.html page. This script also contains numerous helper (i.e., utility) functions and variables, defined outside runExport() . index.html The user interface of the application. Users submit their personal access token and the identifier (i.e., GID) of a portfolio to generate a CSV of project status updates in that portfolio style.css Basic stylesheet for the application You are also welcome to skip immediately to the complete application code on GitHub . The end of this tutorial also includes the complete application code for review. Starter code This tutorial will guide you through building the complete application step-by-step. To help you get started more quickly (and to help focus on simply building the business logic for the application), we've provided the basic structure and styles for the user interface, which presents a web page for users to enter their personal access token and portfolio GID. index.html style.css

Report: Status updates from all projects in a portfolio

Instructions

This tool is used to generate a CSV of project records, from a nested portfolio structure in Asana. To use this tool, you'll need a personal access token and a link to the top-level portfolio you'd like to export. Enter these details in the form below, and a CSV file will be generated to download. You may be prompted to approve or allow downloads from this page. Note that you'll only be able to export projects and portfolios that you have access to and can view in Asana.

Personal access token

For information on how generate your own personal access token, navigate to https://developers.asana.com/docs/personal-access-token

You should treat this token like a password! It allows programmatic access to Asana as you, so it is best saved in a password manager or private vault. If you have any reason to think a token may have been compromised, you can reset it or delete it in the developer console. See documentation at: https://developers.asana.com/docs/developer-console

Portfolio GID

To obtain your portfolio GID, simply navigate to your portfolio in the Asana app, and copy the GID from the URL itself. For example, if the link is "https://app.asana.com/0/portfolio/12345/list", you should copy 12345. See documentation at: https://developers.asana.com/reference/portfolios

Personal access token

Portfolio GID

#errorbox { background-color: red; color: white; align-self: center; width: auto; } body { height: 100vh; width: 100vw; display: flex; justify-content: center; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; } #mainform { width: 60%; margin: auto; align-self: center; display: flex; flex-direction: column; justify-content: space-around; align-items: flex-start; } .input-block { display: block; min-width: 25%; margin-top: 1rem; margin-bottom: 1rem; } input { width: 100%; display: block; } .form-rounded { border-radius: 10px; } .button { display: block; font-size: 14px; width: 100%; color: #ffffff; background-color: #4573d1; padding: 10px 18px 10px 18px; margin-bottom: 30px; border-radius: 10px; } You won't need to know all the inner workings of these files, so feel free to copy and paste these files directly. The two key takeaways to note in the provided index.html file are: Two input fields with the IDs pat (personal access token) and portfolio (portfolio GID). This information is captured and used by the JavaScript code in index.js to make requests against Asana's API A submit button with the ID submit . When clicked, this button simply invokes the runExport() function When put together, we have the main user interface for the application: Through the rest of the tutorial, we'll build the aforementioned runExport() function. runExport() carries out several tasks in sequence: Create the boilerplate Parse and validate user input Extract projects from the portfolio Consolidate data Generate the CSV and download Clean up 1. Create the boilerplate To begin, we'll first create a new index.js file, then define a single asynchronous runExport() function inside it. Note that unless explicitly noted as a "helper function" (or "helper map"), the code snippets in this tutorial will all be written sequentially into the body of runExport() . index.js: runExport() body const runExport = async () => { }; As the first line in runExport() , we'll start a timer. This is purely for performance logging as part of the user experience. As additional boilerplate, we'll also temporarily disable the submit button (i.e., Generate CSV ) while the function is running, provide the user with a loading indicator, then reset any errors that were previously displayed on the page. index.js: runExport() body const start = new Date(); const submitBtn = document.getElementById("submit"); submitBtn.disabled = true; submitBtn.value = "Please wait..."; document.getElementById("errorbox").innerText = ""; 2. Parse and validate user input Recall that the user interface prompts the user to enter both their personal access token and portfolio GID. This information is captured in the elements with ID pat and portfolio , respectively. We'll first parse the values for this information from the page, then perform some basic validation to check user inputs when the user submits the form. index.js: runExport() body const pat = document.getElementById("pat").value; const portfolio_gid = document.getElementById("portfolio").value; if (pat === "" || portfolio_gid === "") { const message = "Please provide input to both fields to continue"; postError(message); return; } if (!portfolio_gid || isNaN(portfolio_gid) || portfolio_gid.length < 3) { const message = "Your portfolio GID is invalid. Please check it and try again"; postError(message); return; } In the case of invalid inputs, we'll invoke a postError() helper function that prints a useful error message for the user, then allow the user to resubmit the form with modified inputs. Here is postError() , defined outside the runExport() function. index.js: helper functions // Helper function (i.e., defined outside of the main runExport() function) function postError(message) { document.getElementById("errorbox").innerText += message; document.getElementById("submit").disabled = false; document.getElementById("submit").value = "Generate CSV"; return; } Finally, we'll verify the validity of the personal access token provided by the user. To "test" the token, we'll make an API request to GET /users/{user_gid} , using the special me identifier in place of a user GID, which refers to the authenticated user. index.js: runExport() body const httpHeaders = { Authorization: `Bearer ${pat}` }; const resp = await fetch(`https://app.asana.com/api/1.0/users/me`, { headers: httpHeaders, }); if (!resp.ok) { const message = "Your personal access token is invalid. For documentation, see: https://developers.asana.com/docs/personal-access-token"; postError(message); return; } After making our GET request to the https://app.asana.com/api/1.0/users/me , we'll display an error on the page and stop execution if we do not receive a 200 OK response back. 3. Extract projects from the portfolio Now that we know that we can make validated API requests, we'll begin to extract project data from the user-provided portfolio. Still within runExport() , we'll invoke an asynchronous helper function called extractProjectsFromPortfolio() . This function will return a list of all projects under a specified portfolio (including all projects nested in child portfolios within the top-level parent portfolio): index.js: runExport() body const projects = await extractProjectsFromPortfolio( portfolio_gid, httpHeaders ); Here is the helper function extractProjectsFromPortfolio() defined, which we'll examine step-by-step: index.js: helper functions // Helper function (i.e., defined outside of the main runExport() function) async function extractProjectsFromPortfolio(portfolio_gid, httpHeaders) { try { let items = await getAsanaPortfolioItems(portfolio_gid, { headers: httpHeaders, }); let projects = []; let portfolioPromises = []; for (let item of items) { if (item["resource_type"] === "project") { let newItem = { ...flattenProjectFields(item) }; projects.push(newItem); } else if (item["resource_type"] === "portfolio") { portfolioPromises.push( extractProjectsFromPortfolio(item["gid"], httpHeaders) ); } } let portfolioResults = await Promise.all(portfolioPromises); projects.push(...portfolioResults.flat(3)); return projects.flat(3); } catch (error) { console.log(error); postError( "Something went wrong... inpect the page to view the dev console or wait and try again" ); } } Within extractProjectsFromPortfolio() , we first get all items from a portfolio with the help of yet another asynchronous helper function: getAsanaPortfolioItems() . The main purpose of this function is to make an API request to GET /portfolios/{portfolio_gid}/items and return its response: a list of items from the user-provided portfolio. Here is getAsanaPortfolioItems() defined: index.js: helper functions // Helper function (i.e., defined outside of the main runExport() function) async function getAsanaPortfolioItems(portfolio_gid, headers) { const maxRetries = 10; let retryCounter = 0; while (retryCounter < maxRetries) { const resp = await fetch( `https://app.asana.com/api/1.0/portfolios/${portfolio_gid}/items?opt_fields=name,resource_type,archived,color,created_at,current_status_update.(created_by.name|status_type|created_at|text),notes,modified_at,public,owner.name,start_on,due_on`, headers ); if (resp.ok) { const results = await resp.json(); return results.data; } if (resp.status >= 400 && resp.status != 429 && resp.status != 500) { const errorMessage = errorCodeMap[resp.status] || ""; document.getElementById("errorbox").innerHTML += errorMessage; break; } retryCounter++; const wait_time = retryCounter * retryCounter * 120; await new Promise((resolve) => setTimeout(resolve, wait_time)); } return []; } // Helper map (i.e., defined outside of the main runExport() function) const errorCodeMap = { 400: "Something went wrong with the request. Check your portfolio GID. For more information on portfolios, see: https://developers.asana.com/reference/portfolios", 401: "You are not authorized to get this portfolio. Check that you pasted your personal access token correctly and that your portfolio GID is correct", 403: "You are not authorized to get this portfolio. Check that you pasted your personal access token correctly and that your portfolio GID is correct", 404: "We couldn't find that portfolio. Check your portfolio GID. For more information on portfolios, see: https://developers.asana.com/reference/portfolios", }; In making the API request, getAsanaPortfolioItems() is set up to work within the rate limits of Asana's API. Additionally, note that in our GET request to https://app.asana.com/api/1.0/portfolios/${portfolio_gid}/items , we also appended opt_fields to customize the exact properties we want returned in the response (see input/output options for more details on usage). Continuing with the execution of extractProjectsFromPortfolio() -- we'll next take either one out of two differe

What it does

Available capabilities

Tags

Ways to use it