Configure Asana as a data pipeline source ​

Set up Asana as a data pipeline source to extract work-management data, such as tasks, projects, portfolios, goals, and their related records, from the Asana REST API and sync it to your destination.

Use this guide to review the features and prerequisites, connect Asana as a data pipeline source, configure the pipeline, and understand the supported objects, sync modes, schema handling, and limitations.

Features supported ​

The following features are supported when you use Asana as a pipeline source:

• Cloud connectivity: Connects to the Asana REST API over https. An on-prem agent is not required.
• Object-level selection: Choose the supported objects you plan to sync when you configure the pipeline.
• Sync modes: The tasks object and the objects derived from it sync incrementally. All other objects use full sync.
• Custom field support: Workspace-level custom fields sync as dynamic columns on the tasks, projects, portfolios, and goals objects.
• Schema drift handling: Choose to auto-sync or block newly added fields in the source.
• Field-level data protection: Replicate field values as is or hash sensitive values before they reach your destination.
• Configurable sync frequency: Schedule syncs with time-based or cron-based schedules. The minimum interval is 15 minutes.

Prerequisites ​

Complete the following requirements before you configure Asana as a data pipeline source.

• An Asana account with access to the workspaces you plan to sync.
• Permission to authorize a third-party application through the Asana OAuth flow.

Supported connection types ​

Asana data pipelines support OAuth 2.0 authentication:

• OAuth 2.0: Authorizes Workato to read data from the Asana workspaces your account can access. Asana access tokens are long-lived and don't expire until you revoke them.

Connect to Asana ​

Complete the following steps to connect to Asana:

Configure the pipeline ​

Complete the following steps to configure Asana as your data pipeline source:

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

Supported objects ​

Asana data pipelines sync data from the Asana REST API. The following tables list supported objects, grouped by category. Each object syncs as a separate table in your destination.

Workspaces and people ​

These objects describe the workspaces the connection can access and the people and tags within them.

Projects ​

These objects describe projects and their structure and membership.

Custom fields ​

These objects describe the custom field definitions in Asana and the projects they're enabled on.

Tasks ​

These objects describe tasks and the records derived from them. All objects in this category sync as part of the task extraction, so they inherit the incremental behavior of the tasks object.

Portfolios and goals ​

These objects describe cross-project portfolios and organizational goals. They require a Business or Enterprise plan.

Sync modes ​

Asana data pipelines support full sync and incremental sync. Asana detects the sync mode for each object automatically.

Full sync ​

Full sync reads all available records for an object on each run. Every object except tasks and the objects derived from it uses full sync, including projects.

Incremental sync ​

Incremental sync reads only the records created or updated since the previous run. The tasks object and the objects derived from it sync incrementally. The stories object is append-only.

Refer to the Supported objects tables to see the sync mode for each object.

Delete tracking ​

Objects that sync in full support delete tracking. The pipeline compares each full sync against the previous run and marks records that no longer exist in Asana with a _workato_is_deleted column in your destination.

The tasks object and the objects derived from it sync incrementally and don't support delete tracking, because an incremental run reads only the records changed since the previous run and never observes a deletion.

Schema and data type handling ​

The connector applies specific handling to certain Asana field types when it replicates data to your destination.

Rich text fields ​

Several objects expose both a plain-text field and an HTML-formatted counterpart, such as notes and html_notes on tasks and projects. Both variants sync as separate columns, because the HTML variant carries formatting the plain-text variant doesn't.

Custom field columns ​

Asana workspaces maintain a library of custom field definitions that admins apply to projects. The connector handles custom field values on the tasks, projects, portfolios, and goals objects as follows:

• The custom_fields column contains a JSON object of all custom field values on the record, whether the field is scoped to the workspace or to an individual project, portfolio, or goal.
• Workspace-scoped custom fields also receive their own column, prefixed with cf_, so you can query them directly without unpacking the JSON. Locally-scoped fields appear only in the custom_fields JSON. When two locally-scoped fields share the same name, they collide in the JSON object and only the last value is retained.

Sensitive data handling ​

Asana objects can contain personally identifiable information (PII). The following objects commonly contain sensitive fields:

The notes and html_notes fields on tasks and projects are free-text and carry the highest risk, because users can enter phone numbers, addresses, or other personal data in descriptions. Custom fields of the people type also reference user records that include names and email addresses.

Use the Hash option in field-level data protection during pipeline configuration to protect PII before it reaches your destination. Workato recommends hashing user email addresses and free-text description fields for pipelines operating under GDPR or CCPA. Refer to the Configure the pipeline steps for more information.

Limitations ​

The following limitations apply when you use Asana as a data pipeline source:

Incremental sync is limited to tasks ​

Only the tasks object and the objects derived from it sync incrementally. All other objects, including projects, re-fetch their full record set on every run. Account for the full re-fetch when you set the sync frequency for large non-task objects.

Container read limit ​

Asana limits API reads to approximately 50,000 items within a single container, such as the tasks in a project or section. The limit applies to all objects, but you're most likely to reach it with tasks and their related objects. If a container exceeds the limit, Asana returns an error and the sync for that object fails.

The pipeline reduces the risk by reading tasks per section rather than per project, but a single section that holds more than 50,000 tasks still fails. The count includes completed tasks, because the pipeline extracts tasks regardless of completion status. Keep the number of tasks in any one section below this limit to avoid sync failures.

Refer to the Asana API limits documentation for more information.

Plan and workspace requirements ​

Certain objects require a specific Asana plan or workspace type:

Select only the objects your plan and workspace support. If you select a portfolio_memberships, goal_relationships, or team_memberships object without the required plan or workspace type, the sync fails with an error.

Minimum sync frequency ​

The minimum supported sync interval is 15 minutes. You can't trigger syncs more frequently than this.