Asana

Connect an Asana workspace to run the work that lives in it from a process. metamorphOS creates and moves tasks across projects and board columns, assigns and schedules them, comments, attaches files, and searches a whole workspace. Asana can also notify metamorphOS when something changes, though that half is not available yet (see Keeping up with changes).

What you can do

• Tasks: create, read, update, complete and delete tasks, and create subtasks under them.
• Move work: add a task to a project, move it into a board column, or take it out of a project again. A task can sit in several projects at once, in a different column of each.
• Schedule and assign: set a due day or a due time, a start day, and the one person a task is assigned to.
• Dependencies: declare that a task waits on other tasks, and read the blocking edges back.
• Comments and activity: post a comment, and read a task’s full activity trail, which includes Asana’s own record of every change.
• Tags and followers: create tags, apply and remove them, and add followers so people are notified.
• Attachments: attach an uploaded file, or a link to a file that stays where it is.
• Projects and board structure: create, update, archive and delete projects, and add board columns.
• Search: find tasks across a whole workspace by text, assignee, project, tag, date range, and completion state.
• Lookups: resolve workspaces, teams, users, tags and custom fields to the identifiers the other actions need.

Before you start

You need a long-lived Asana token that metamorphOS sends with every call. Asana offers two kinds, and the connector accepts either:

• Service account token (Enterprise and Enterprise+). A super admin creates it in the Admin Console. It is not tied to a person and has access to the whole organization, including private projects.
• Personal access token (every tier). Created on a user account and acts as that user. Create it on a dedicated automation user, not on a colleague’s login: a task in a project the user cannot see simply is not found, and a token created by someone who later leaves stops working when their account is deactivated.

OAuth is not needed. It authorizes on behalf of a person and is meant for apps that act as their signed-in users.

Create the access token

Service account (Enterprise, super admin):

1. Open the Admin Console, then Apps, then Service accounts.
2. Choose Add service account, name it for where it will be used, for example metamorphOS production, and confirm.
3. Copy the token now. Asana shows it once and never again.

If Service accounts is missing from the Admin Console, the organization is not on an Enterprise tier. Use a personal access token instead.

Personal access token (any tier):

1. Sign in to Asana as the user the automation should act as.
2. Open app.asana.com/0/my-apps , or your profile photo, then Settings, Apps, Manage developer apps.
3. Under Personal access tokens, choose Create new token.
4. Name it for where it will be used, for example metamorphOS production, and accept the API terms.
5. Copy the token now. Asana shows it once and never again.

Connect in metamorphOS

Activate the Asana connector from the marketplace, add an account, and provide:

• Token: the service account token or personal access token from the previous step.
• Workspace: the identifier of the workspace this account works in.

Set the workspace once and the workspace-wide actions fill it in for you, so a single-workspace setup never passes it again. A process can still name a different workspace the account can reach.

To find the identifier, run the Get Workspaces action once. It needs no input and returns every workspace the account can see, with its identifier. It is also the first long number in any Asana URL: app.asana.com/1/<workspace>/project/<project>.

Find the identifiers your processes need

Everything in Asana is addressed by an identifier, a long number Asana calls a gid. The ones a process usually needs:

Working with custom fields

In most Asana workspaces the built-in task fields carry the title and the dates, and everything the business actually reports on lives in custom fields: status, spend, savings, owner, vendor, contract dates. Reading and writing them well is most of what an Asana integration does, so two points are worth knowing before you build.

Address a field by its identifier, never by its name. Field names are free text typed by whoever created the field, so they pick up trailing spaces and inconsistent capitalisation over time, and two fields can share a name. Run one of the custom field lookups above once, keep the identifiers, and reuse them. A choice field is set by the identifier of the option you want, not by the option’s label.

Read the typed value when you calculate, and the display value when you show. Every custom field carries both: a value in its own type (a number, a date, a chosen option) and a display value, which is a string formatted for people. The display value is the right thing to put in an email. It is the wrong thing to do arithmetic on.

[!TIP] Decide early which fields are reporting dimensions. A field typed as a choice or as a person can be grouped and counted reliably. The same information typed as free text will accumulate spelling variants and cannot be grouped later without cleaning it up first.

Keeping up with changes in Asana

Asana can notify a subscriber whenever something changes, and this connector carries the actions that manage such a subscription. metamorphOS cannot receive those notifications yet: Asana confirms a new subscription by having the receiver echo a value back inside the same request, and the webhook receiver does not do that, so a subscription created today is never confirmed.

Until it does, have a process read what it cares about on a schedule. Two ways, depending on what you need:

• Read on a schedule. Get Tasks narrowed to a project, with the modified since filter set to the previous run, returns only what changed. This is the simplest option and the one to start with.
• Follow the change feed. Get Events returns the changes to one task or project since the last time you asked. It is more precise, at the cost of keeping track of a token between runs. Its first call is expected to fail while it hands out that first token, which is normal rather than a misconfiguration.

Good to know

• A task belongs to projects, not to one project. Adding a task to another project does not move it, it adds a second membership, and the task then has a column in each. Use Add Task To Project and Remove Task From Project to change that. Setting the project list while updating a task does nothing.
• Moving a card across the board is Move Task To Section. The task has to already be in that project.
• Due day or due time, not both. Setting a due time clears the due day and the other way round. Pick the one your process means.
• A subtask is a task, but it is not in the project. It hangs off its parent, so it will not appear when you list the project’s tasks. Read it with Get Subtasks.
• Deleting a task deletes its subtasks. Deleting a project does not delete its tasks; they stay in the workspace and lose that membership. Prefer completing a task, or archiving a project, when you might want it back.
• Search does not see a change immediately. Asana indexes in the background, so a task created seconds ago may not be found yet. Never confirm a write by searching for it; read the task back instead.
• Search returns at most 100 matches and is not paged. Narrow it with filters rather than trying to walk through pages.
• List a project’s tasks by naming exactly one container. A project, or a board column, or a person plus a workspace. Asana refuses a combination.
• Comments are attributed to the connected account. A service account or shared automation user comments as itself, not as the person whose process triggered it.
• Tokens are revoked where they were created. Service account tokens in the Admin Console under Service accounts, personal access tokens under Manage developer apps. A revoked token fails every call until a new one is connected.