The Asana integration is currently in beta. Contact your Technical Account Manager for access.
Overview
The Asana integration lets you pull live data from your Asana workspace into Matik dynamic content. We currently support pulling data from Asana tasks, projects, users, portfolios, and portfolio items.
Once connected, you select an Asana workspace, choose a resource type, optionally filter and sort the results, and pick the fields you want returned.
Connecting Asana as a Data Source
Asana supports two authentication methods. Choose the tab that matches how you want Matik to access your workspace.
Access Via Access Token
Paste an Asana token into the Access Token field. Two token types are supported:
- Personal Access Token (PAT): Generated at app.asana.com/0/my-apps. A PAT is scoped to the user who created it, so Matik will only see what that user can see in Asana.
- Service Account Token: Available on Asana Enterprise+. A Service Account Token sees every portfolio in the workspace, not just the portfolios owned by the connecting user. Use this token type if you want full-workspace portfolio access. See Asana's documentation on Service Accounts for setup steps.
Access Via OAuth2
Switch to the Access Via OAuth2 tab and click Connect to Data Source. A popup opens to Asana's authorization page where you sign in and grant Matik access. Matik requests read-only scopes for projects, tasks, portfolios, users, custom fields, attachments, jobs, tags, teams, and workspaces.
OAuth tokens are tied to the authenticating user. As with a PAT, the user's portfolio visibility is limited to the portfolios they own in Asana.
Note: Asana's API only returns the full set of workspace portfolios when the request is made from a Service Account. With a PAT or OAuth token, Matik can only scope portfolio queries to owner=me, so users will only see portfolios they own. To browse all portfolios in a workspace, connect Matik using a Service Account Token.
Building Dynamic Content from Asana
When you create dynamic content backed by Asana, you'll move through a short configuration flow:
- Workspace: Pick the Asana workspace to query. The dropdown is populated from the workspaces your token can see.
- Resource Type: Choose what you want to fetch — Tasks, Projects, Users, Portfolios, or Portfolio Items.
- Portfolio (Required only when Resource Type is Portfolio Items): Pick the portfolio whose items you want to return.
- Return Fields: Select which fields appear in your output. Standard and custom fields are both available.
- Filters: Narrow the results. See Filtering Results.
- Sort: Optionally pick a field to sort by and choose ascending or descending.
Tasks
Returns tasks from the selected workspace. Asana's task search endpoint requires at least one filter. You'll see an error if you try to run a task query without one. Common starting filters include Projects, Assignee, Tags, Sections, or Name or description contains.
The Sections filter picker only loads sections from a specific project. To use it, first add a single Projects filter pointing to one project; the Sections picker will then show sections from that project.
Projects
Returns projects from the selected workspace. Filters are optional — running with no filters returns all projects the token can see.
Users
Returns users from the selected workspace. Filters are optional.
Portfolios
Returns portfolios visible to your token. With a Service Account Token, this is every portfolio in the workspace. With a PAT or OAuth token, this is only the portfolios the connecting user owns.
Portfolio Items
Returns the items (typically projects) inside a specific portfolio. You must choose a portfolio from the Portfolio dropdown before the query will run.
Filtering Results
Filters narrow the results returned from Asana. Each filter row has three parts: a Field, an Operator, and a Value. Available fields and operators depend on the resource type — for example, Tasks support filters on Assignee, Projects, Tags, Due dates, and more, while Portfolios only support Name/description and Owner.
Operators include includes any of, excludes, includes all of, is before, is after, is, contains, is set, equals, starts with, ends with, is less than, and is greater than.
Filter Value Modes
Each filter value has two modes, selectable from the toggle above the value editor:
- Asana: Pick a value directly — a date picker for dates, a dropdown for enums, a multi-select for projects, tags, users, and so on. The picker is populated from your workspace.
-
Matik: Reference a Matik input using
&:input_namesyntax. At generation time, the value the consumer chooses for that input is substituted into the filter. Use this for templates where the same dynamic content needs to work across different projects, assignees, or date ranges.
Custom Fields
Custom fields defined at the workspace level can be used as both filter fields and return fields. Supported operators depend on the custom field type.
Return Fields
Return fields determine which columns appear in the output. You can pick from standard Asana fields (name, assignee, due date, projects, etc.) and from custom fields defined in your workspace.
Note: Custom fields are defined at the workspace level. They may not exist on every task or project returned, so those columns can be empty for some rows.
Sorting
Use the Sort By dropdown to choose a single field to sort by, and the direction toggle to switch between ascending and descending. Leave it unset to use Asana's default ordering.
Limitations
- Portfolio visibility depends on token type. Only Service Account Tokens can list all portfolios in a workspace. PAT and OAuth connections are limited to portfolios the connecting user owns.
- Tasks require at least one filter. Asana's API does not allow an unfiltered task search.
-
Users can be scoped by workspace OR team, not both. If a
Teamfilter is set, the query is scoped to that team and the workspace scope is ignored. - Row cap per query. Asana queries return up to 10,000 rows. Refine your filters if you expect more results.
- Rate limits surface as generic API errors. When Asana rate-limits a request, the error is returned as a generic Asana API error. Retry after a short delay.
Troubleshooting
| Error Message | Cause | Resolution |
|---|---|---|
Failed to connect to Asana API: 401 - ...
|
The token is invalid, expired, or revoked. | Regenerate the Personal Access Token at app.asana.com/0/my-apps and paste it back into the Access Token field, or reconnect via OAuth. |
Asana connection failed: ...
|
The connection test could not reach Asana — typically a credential or network issue. |
Verify the token is correct, the user account is still active in
Asana, and your network allows outbound calls to
app.asana.com.
|
At least one filter is required for tasks. Try filtering by projects.any, tags.any, assignee.any, sections.any, or text.
|
Asana's task search endpoint won't accept an unfiltered query. |
Add at least one filter — for example, a Projects,
Assignee, Tags, Sections,
or Name or description contains filter.
|
Asana did not recognize "..." as a valid ID for the ... filter. Switch the filter value to an Asana value to pick from a list, or enable mapped inputs so users can select a name and pass the associated Asana gid.
|
A filter value is a free-text string where Asana expects a gid (e.g., a project name typed in instead of selected). | Switch the filter to Asana value mode and pick from the dropdown, or use a mapped Matik input that resolves to the correct gid. |
Invalid JSON query string
|
The stored dynamic content query is malformed. | Re-open the dynamic content, reselect the workspace and resource type, then save. |
Asana API error: 429 - ...
|
Asana rate-limited the request. | Retry after a short delay. If you see this consistently, reduce the frequency of presentations using Asana data or split queries across fewer concurrent runs. |
Asana API error: ... - ...
|
Asana returned an HTTP error on the data fetch — for example, a permissions issue, a missing resource, or a bad filter value. | Check that the connecting user still has access to the workspace, project, or portfolio referenced. Re-pick filter values from the Asana dropdowns to make sure each value is still valid. |
Error querying Asana
|
Matik couldn't load dropdown options (workspaces, projects, fields, etc.) for the dynamic content form. | Reload the form. If the error persists, re-test the data source connection — the token may have expired or had its scopes revoked. |
Comments
0 comments
Article is closed for comments.