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

  1. Click Connect to Asana.

  2. A popup opens Asana’s authorization screen.

  3. Approve access.

  4. 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:

  1. Click Add an API key.

  2. Paste an Asana Personal Access Token.

  3. 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

  1. Select a default Workspace.

  2. Select a default project (used when creating tasks and searching for tasks to link).

  3. Choose which content types should show the Asana sidebar.

  4. 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:

  1. Create a new Automation and choose a trigger (for example, Entry published or Entry changed).

  2. Add an Action step and choose one of the Asana app’s actions below.

  3. Map the entry’s fields to the action’s inputs.

  4. 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.