- Help Center
- Apps
Asana
Asana
The Asana app lets editors create, link, and manage Asana tasks directly from a Contentful entry. Instead of switching to Asana to check status or leave a note, editors can see and update the linked task — assignee, due date, description, dependencies, section, comments, and supported custom fields — right from the entry sidebar.
Overview
The Asana app is useful for teams that already track content-related work (reviews, approvals, translations, launches) as Asana tasks and want that status visible without manually keeping Contentful and Asana in sync.
The Asana app works best when your Asana workspace and project are already set up, and your team has a consistent naming convention for tasks tied to content work.
Requirements
Before using the Asana app:
You must have space admin access to install and configure the app in a Contentful space.
You need an Asana account with access to the workspace (and, typically, the project) you want to connect to Contentful.
To use Automations that run without a logged-in user (for example, triggered by entry publish), an Asana Personal Access Token (PAT) should also be added as a fallback credential during setup.
The content types you want the Asana sidebar to appear on should already exist; the app does not create or modify content types (other than a small internal content type it manages for storing task links).
Usage
Step 1: Install the Asana app
Install the app from the Contentful Marketplace or an internal app definition, then open its configuration screen.
Step 2: Connect to Asana
Click Connect to Asana.
A popup opens Asana’s authorization screen.
Approve access.
The popup closes and the config screen shows a Connected status.
NOTE: Only the connection’s refresh token is stored. Access tokens are generated on demand and never saved long-term.
Step 3 (Optional): Add an API key for Automations
Contentful Automations run without a logged-in user, so OAuth alone isn’t enough to power them. To support Automations:
Click Add an API key.
Paste an Asana Personal Access Token.
Click Test key to confirm it’s valid.
Skip this step if you don’t plan to use Automations.
Step 4: Set defaults and scope the sidebar
Select a default Workspace.
Select a default project (used when creating tasks and searching for tasks to link).
Choose which content types should show the Asana sidebar.
Click Save.
Step 5: Create or link a task from an entry
Open an entry of an enabled content type.
In the sidebar:
To create a task: enter a task name (or leave blank to use the entry’s title) and click Create Asana task. The task’s description automatically includes a link back to the entry. If a task with the same name already exists, the app warns you and lets you link to it instead of creating a duplicate.
To link an existing task: search by task name within your configured workspace/project, or paste a task URL or GID, then select it. The entry link is added to the task’s description if it isn’t already there.
To add more tasks: use Add additional task to link secondary tasks to the same entry.
Writer note: add screenshot of the sidebar’s create/link/search UI.
Step 6: Manage the task
Click Manage task on any linked task to open the full task editor. You can:
View status, created/modified dates, and tags (read-only).
Edit assignee (search by name), due date, description, dependencies (search and add/remove), section (if the project uses sections), and supported custom fields.
Toggle subtask completion.
Read recent comments (with a “show more” option) and post a new one.
Edits are staged locally and only sent to Asana when you click Save changes — except posting a comment, which happens immediately. Click Close to discard unsaved edits.
Automatic activity comments
Whenever an editor saves changes to an entry with a linked task, the app posts a short comment (“This entry was edited in Contentful.”) to that task’s activity feed. To avoid noisy threads, this is limited to one comment per entry per hour.
Configuring automations
The Asana app exposes a set of Automations actions so you can build your own publish- or update-triggered workflows, for any content type, in Settings > Automations. A typical recipe looks like:
Create a new Automation and choose a trigger (for example, Entry published or Entry changed).
Add an Action step and choose one of the Asana app’s actions below.
Map the entry’s fields to the action’s inputs.
Save and enable the Automation.
Actions available to Automations:
Action | Use it to | Key inputs |
|---|---|---|
Create Asana task | Create a new task from an entry (for example, on publish) | Task title, task notes, Contentful entry ID, optional field IDs to pull title/notes from the entry, optional project/workspace override, optional duplicate-name check |
Update Asana task | Change a task’s own fields | Task GID/URL or entry ID, plus any of: title, notes, completed, assignee, due date, dependency to add/remove, section |
Sync Asana task from entry | Push several entry-driven field changes to the linked task in one step | Entry ID, plus any of: title, notes, completed, assignee, due date, section |
Update Asana custom field | Set a custom field’s value on a task | Task GID/URL or entry ID, custom field GID, field type, JSON-encoded value |
Add Asana comment | Post a note to a task’s activity feed without changing its fields | Task GID/URL or entry ID, comment text |
Get Asana task details / Search Asana tasks | Look up a task’s current state or find tasks by name | Task ID, or workspace/project + search query |
List Asana workspaces / Search Asana projects / List Asana project sections / Search Asana users | Look up IDs needed to configure other actions | Workspace GID, project GID, or search query |
Example recipes:
Auto-create a task on publish: Trigger on Entry published, call Create Asana task with the entry’s title/notes fields mapped in.
Push a status field into Asana: Trigger on Entry changed, call Update Asana custom field (or Sync Asana task from entry) to reflect the entry’s status on the linked task.
Record a field change as a comment: Trigger on Entry changed, call Add Asana comment with a message built from the changed field’s new value.
NOTE: The app ships with one built-in example of publish-triggered task creation, wired to a specific internal content type and field setup used during development. For your own content types, use the Create Asana task/Sync Asana task from entry actions in a custom Automation as described above, rather than relying on that built-in example.
Supported custom field types
The task editor can read and edit the following Asana custom field types:
Text
Number
Single-select
Multi-select
Date
People.
NOTE: Other types (rich text, formula, lookup, template, portfolio) are shown read-only with a note that they aren’t editable yet.
Limitations
The app does not create or modify Asana custom fields — only updates existing ones.
Subtasks can be marked complete/incomplete, but not created, renamed, or reassigned from Contentful.
Comments can be read and posted, but not edited or deleted, from Contentful.
Task search and linking are limited to the workspace/project configured for the app (or passed explicitly to an action).
Unlinking a task in Contentful does not delete or archive it in Asana.
OAuth tokens and the optional API key are stored at the app installation level, not per user.
Troubleshooting
The sidebar doesn’t show up on an entry
Confirm the entry’s content type is one of the content types selected in the app’s configuration screen.
“Connect to Asana” doesn’t complete
Make sure popups aren’t blocked for your Contentful domain, then try again. If access was revoked from Asana’s side, you need to reconnect.
Automations aren’t running
Confirm an Asana API key has been added and tested in the config screen — Automations run without a logged-in user, so the OAuth connection alone isn’t enough to power them.
Creating a task fails or times out
If the entry was just created or changed, the app retries briefly while entry data settles. If it still fails, confirm the mapped title/notes field IDs exist on that content type.
A custom field won’t save, or the task won’t refresh after saving
This usually means the field’s value no longer matches a valid option in Asana (for example, a deleted dropdown choice). The change is still saved; refresh the task in Asana to confirm.
FAQs
Does the app keep Contentful and Asana continuously in sync?
Not automatically in both directions. Editors push changes to Asana on demand (via Save changes or Automations). Asana-side changes aren’t pulled back into Contentful.
Can one Asana task be linked to more than one entry?
Yes. Linking an existing task from a second entry adds that entry’s link to the task’s description rather than creating a new task.
Can I link more than one task to the same entry?
Yes, using “Add additional task” in the sidebar.
What happens to the Asana task if I unlink it in Contentful?
Nothing — unlinking only removes the connection in Contentful. The task remains untouched in Asana.
Can I edit Asana custom fields of any type?
Only text, number, single-select, multi-select, date, and people fields. Other types show as read-only.