App directoryDocsForumMy apps

Custom field analysis

Suggest Edits

Custom Field Analysis is an example script that makes requests against the Asana API, parses the responses, and generates a CSV report of all the custom fields in an Asana instance (i.e., workspace). Additionally, the script outputs a count of how frequently each field is used.

📘

Open source example

You can access this open source example script here in the devrel-examples repository. Comments are included within the files in the ./fieldanalysis folder to detail the script's business logic.

Example use case

As a "super admin" (i.e., Service Account user) of a workspace, you'll likely conduct regular audits of the data in that workspace. For example, in your analysis of how your company's users use Asana, you may want insights on the custom fields that exist in your Asana instance. This can include data such as:

  • Which custom fields have been created
  • How frequently each custom field is used
  • Who owns each custom field

You can obtain a basic report of such data using the custom field analysis script, which parses and outputs the data into a single, easily readable CSV file.

Then, as part of the audit, you can move forward with actions such as:

  • Reviewing and standardizing naming conventions in your workspace's custom fields (e.g., "State" vs "state", or "Monthly Recurring Revenue" vs "MRR")
  • Deprecating unused or "stale" custom fields
  • Programmatically updating certain custom fields

API endpoints

As a reference, the custom field analysis script leverages the following API endpoints:

HTTP methodURLDescription
GET/workspaces/{workspace_gid}/custom_fieldsGet a workspace's custom fields
GET/workspaces/{workspace_gid}/projectsGet all projects in a workspace
GET/users/{user_gid}Get a user
GET/workspaces/{workspace_gid}Get a workspace

Additionally, the script also makes use of opt fields and paginated requests.

Getting started

Requirements

This script is written using Python 3.8, though it should be compatible with most 3.x versions of Python.

To check the version of Python installed on your local machine, open your terminal and enter the following command:

python -V

If you need to install a newer version of Python, you can do so at https://www.python.org/downloads/

Note that if you install a newer version of Python, be sure to also install certificates (by running the "install certificates" script found in the Python folder).

Installation

Clone the script (located here) to your local machine. Then, in the root directory of the app, install requirements:

pip install -r requirements.txt

Usage

Before you begin, be sure to obtain a personal access token (PAT). This personal access token is how the script authenticates with Asana to create these projects as your Asana user.

Then, to use the custom field analysis script:

python runfieldanalysis.py

The script interactively asks for both your personal access token and workspace GID (you will also be given an option of possible workspaces to analyze). Note that large domains can take an extended period of time!

Output

The standard information outputted in the resulting CSV file are each field's:

  • gid
  • name
  • type
  • created_by (names and emails)
  • enum_options (names)

Along with the output above, the CSV file also indicates a count representing the number of projects the field is used in. Note that this does not include portfolios.

🚧

Complete data access

The accuracy of the custom field analysis script is limited by custom fields and projects that the authenticated user (i.e., through the personal access token) has access to.

For example, if user A creates a non-global custom field in a private project, user B (in the same workspace as user A) would not be able see it. That is, if user B uses the custom field analysis script, the resulting CSV and project count would not include those fields or projects.

For a complete representation of the data in a workspace, use a Service Account to perform such audits.

To get more information on a custom field, you can request the custom field record by using its GID with the Asana API, as documented here: GET /custom_fields/{custom_field_gid}

Rate limits

Due to the high volume of API calls this script makes, it may sometimes hit rate limits and need to set some delay between its API calls. The exact amount of delay will be printed to the console.

Because the script will be running many calls in parallel, note that this message may print multiple times (i.e., once for each API call that was blocked due to rate limiting). These wait times will not be additive, since the calls are running in parallel. Once the wait duration is up, each API call will be retried with increasing delay until it succeeds. After ~10 tries (which would take almost 3 minutes of attempts), the individual API call will be canceled.

Additional notes

  • All source code is contained within the fieldanalysis directory
    • fieldanalysis.py contains the main business logic of the script
    • menu.py contains the menu and a few helper functions to gather user input and map the CSV to the portfolio fields
  • The asanaUtils directory contains a client.py file, which handles formatting and sending API calls, along with handling rate limits

Updated about 1 year ago