> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/asana/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use the "Changed after" filter for large workspaces</strong></td><td>If your workspace has thousands of tasks, set the Changed after date to limit exports to recently modified records. This avoids timeouts and keeps your destination lean.</td></tr><tr><td><strong>Export Tasks and Users as separate sources in one data flow</strong></td><td>Add both Tasks and Users as sources, then use the Join transformation on assignee ID. This gives you a clean table with task details and assignee info combined — ideal for workload dashboards.</td></tr><tr><td><strong>Use Append to combine multiple workspaces</strong></td><td>If your team operates across multiple Asana workspaces or accounts, add each as a separate source and use the Append transformation to merge them into a single dataset.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Run incrementally, not as a full refresh</strong></td><td>For Tasks, use the Changed after filter combined with an Append destination mode. This adds only new or updated tasks each run rather than reloading everything — faster and less prone to timeouts.</td></tr><tr><td><strong>Schedule Stories exports less frequently</strong></td><td>Stories (comments and activity) grow quickly. A daily or weekly schedule is usually sufficient — hourly exports of Stories can be heavy on API calls and slow to process.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Extract custom fields with json_extract</strong></td><td>Custom fields come back as a JSON blob. Use Coupler.io's calculated column with json_extract to surface the specific fields you need — this makes downstream filtering and reporting much easier.</td></tr><tr><td><strong>Send data to BigQuery for large-scale analysis</strong></td><td>If you're tracking hundreds of projects or need historical trend data, BigQuery handles Asana's volume much better than a spreadsheet. Use incremental loads to keep costs low.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not connect a personal Asana project space. Asana's API blocks access to personal spaces entirely — you'll get a "Data cannot be fetched" error every time. Make sure you're using an organization workspace before setting up your data flow.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Verify your account is part of an organization workspace before connecting
* Use the Changed after filter to scope large Task exports
* Use json\_extract for custom fields you need as separate columns
* Test with a manual run before setting up a schedule
  {% endcolumn %}

{% column %}
**Don't**

* Expect to filter Tasks by project ID at the source level — do this post-import
* Try to export media attachments — only structured data is supported
* Export all Stories on a high-frequency schedule — it's slow and rarely necessary
* Assume empty columns are a bug — fields like completed\_by.name are only populated in specific conditions
  {% endcolumn %}
  {% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/project-management/asana/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.