# Asana Create, find and update tasks and subtasks in Asana, comment on them, move them between projects and sections, tag them, attach files, and manage projects, sections, tags and users. ## Connect Asana 1. In the sidebar, open **Connections** and press **Add connection**. 2. Type `asana` and choose **Asana**. 3. Press **Sign in with Asana**, then choose your account in Asana’s window and allow access. Sign in with Asana, or paste a personal access token (Asana › My settings › Apps › Developer console › Create new token). A token acts as the person who made it, in the workspaces they belong to. **What if it says “Asana sign-in isn’t set up here”?** Signing in with Asana needs a Asana app on this installation, and it has none yet. **On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.” **Self-hosted:** An admin of the installation sees **Set up Asana sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask. 1. Create an app in Asana’s developer settings ([Asana’s guide](https://app.asana.com/0/my-apps)). 2. In GoRunner, copy the **Redirect address to add in Asana’s developer settings**, and add it to the app. 3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**. [Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers) **Can I use my own Asana app?** Yes. In the sheet, open **Use your own Asana app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s. [Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you. ## Start a workflow Add a trigger and choose **Asana**. The trigger uses the same connection as the steps. ### On Asana Event Fires when Asana delivers events for the project, task, team or workspace below. Publishing the workflow registers an Asana webhook; unpublishing removes it. Every delivery is verified (X-Hook-Signature) and an unsigned or wrongly signed one is refused. Asana sends events in batches: the events of one delivery that match start one run, all of them under events, the first one's fields at the top. Asana's retry of a delivery starts no second run. Asana removes a webhook it could not deliver to for 24 hours; publish again to restore it. - **Watch · Required**: What to watch. A team or workspace delivers only project, goal, portfolio and membership events (Asana's rule). Options: A project (its tasks, subtasks, comments, sections), A task (it, its subtasks and comments), A team (its projects, goals, portfolios and members), A workspace (its projects, goals, portfolios and members). Default: A project (its tasks, subtasks, comments, sections). - **Workspace · Optional**: The workspace to watch, or the one to choose the project or team from. - **Project · Required**: The project to watch. Shows when **Watch** is **A project (its tasks, subtasks, comments, sections)**. - **Task · Required**: The task's id, or its link in Asana. Shows when **Watch** is **A task (it, its subtasks and comments)**. - **Team · Required**: The team to watch. Shows when **Watch** is **A team (its projects, goals, portfolios and members)**. - **On Changes To · Optional**: Which records' events start the workflow. Empty: every event of a project or task. A team or workspace takes Projects, Goals, Portfolios, Team members and Workspace members only, and needs at least one. Options: Tasks and subtasks, Comments and activity, Sections, Attachments, Projects, Tags, Team members, Workspace members, Project members, Goals, Portfolios. - **Events · Optional**: Which kinds of event start the workflow. Empty: all of them. Added and removed are a record put into or taken out of another (a task into a project or section). Options: Added, Changed, Removed, Deleted, Restored. - **Changed Fields · Optional**: Only changes to these fields count as Changed, comma-separated (Asana's field names). Empty: a change to any field. Shows when **Watch** is **A project (its tasks, subtasks, comments, sections)** or **A task (it, its subtasks and comments)**. A later step can use its data, such as `{{trigger.action}}`, `{{trigger.change}}`, `{{trigger.count}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps). ## Do things in Asana Add an **Asana** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields. - [Task](https://docs.gorunner.io/apps/asana#fields-f-task): Create · Get · Get Many · Update · Delete · Move to Section · Search - [Subtask](https://docs.gorunner.io/apps/asana#fields-f-subtask): Create · Get Many - [Task Comment](https://docs.gorunner.io/apps/asana#fields-f-taskcomment): Add · Get Many · Remove - [Task Tag](https://docs.gorunner.io/apps/asana#fields-f-tasktag): Add · Remove - [Task Project](https://docs.gorunner.io/apps/asana#fields-f-taskproject): Add · Remove - [Project](https://docs.gorunner.io/apps/asana#fields-f-project): Create · Get · Get Many · Update · Delete - [Section](https://docs.gorunner.io/apps/asana#fields-f-section): Create · Get Many - [Tag](https://docs.gorunner.io/apps/asana#fields-f-tag): Create · Get Many - [Attachment](https://docs.gorunner.io/apps/asana#fields-f-attachment): Upload · Get · Get Many · Delete - [User](https://docs.gorunner.io/apps/asana#fields-f-user): Get · Get Many Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps). ## Limits - A reply from Asana can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short. - When Asana says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again. Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list). ## For developers In the API, which calls apps pieces, Asana is `pieceId: "asana"` with `actionId: "asana"`, set by `resource` and an `operation_…` field, such as `operation_attachment`. Its trigger is `asanatrigger` / `asana_event`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field. It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions). ### Asana › Task ### Create - **Workspace · Optional**: The workspace: where a new task goes (unless it goes into Projects), the workspace to search, or the one an Assignee filter looks in. - **Name · Required**: The task's name. - **Projects · Optional**: Projects to put the task in: ids or links, separated by commas. With projects, the Workspace may be left empty. - **Notes · Optional**: The task's description, as plain text. - **Assignee · Optional**: Who does it: "me", an email address, or a user id. - **Due On · Optional**: The due date (YYYY-MM-DD). Set this or Due At, not both. - **Due At · Optional**: The due date and time (ISO 8601 with a zone, such as 2026-11-07T17:00:00Z). - **Start On · Optional**: The start date (YYYY-MM-DD). Asana needs a due date with it, later than the start. - **Custom Fields · Optional**: Custom field values by custom field id, such as {"1201234567890555": "High", "1201234567890556": 3}. An enum takes the option's id. - **More Fields · Optional**: Any other task property Asana takes, such as {"html_notes": "\…\", "resource_subtype": "milestone", "liked": true}. - **Tags · Optional**: Tag ids to put on the task, separated by commas. - **Followers · Optional**: Who follows the task: "me", email addresses or user ids, separated by commas. ### Get - **Task · Required**: The task's id, or its link in Asana. - **Fields · Optional**: The properties to return, comma-separated (Asana's opt_fields), such as name,assignee.name,due_on,custom_fields. Empty returns the whole record. ### Get Many - **Workspace · Optional**: The workspace: where a new task goes (unless it goes into Projects), the workspace to search, or the one an Assignee filter looks in. - **Project · Optional**: Tasks in this project. - **Section · Optional**: Tasks in this section of the project. - **Assignee · Optional**: Tasks assigned to "me", an email address or a user id, in the Workspace. Set a Project, a Section, or an Assignee with a Workspace. - **Completed Since · Optional**: Keep incomplete tasks and those completed since this time (ISO 8601). "now" keeps incomplete tasks only. - **Modified Since · Optional**: Only tasks changed since this time (ISO 8601). - **Return All · Optional**: Read every task, page by page (at most 2000; past that the step fails rather than stop early). Off by default. - **Limit · Optional**: How many tasks to return (1–2000). Default: 50. Shows when **Return All** is off. - **Fields · Optional**: The properties to return, comma-separated (Asana's opt_fields), such as name,assignee.name,due_on,custom_fields. Empty returns: name, resource_subtype, completed, completed_at, assignee.name, due_on, due_at, start_on, notes, permalink_url, created_at, modified_at, parent.name, projects.name, tags.name. ### Update - **Task · Required**: The task's id, or its link in Asana. - **Name · Optional**: A new name. Empty keeps the name. - **Completed · Optional**: Mark the task complete or incomplete. Options: Leave as is, Mark complete, Mark incomplete. Default: Leave as is. - **Notes · Optional**: The task's description, as plain text. - **Assignee · Optional**: Who does it: "me", an email address, or a user id. - **Due On · Optional**: The due date (YYYY-MM-DD). Set this or Due At, not both. - **Due At · Optional**: The due date and time (ISO 8601 with a zone, such as 2026-11-07T17:00:00Z). - **Start On · Optional**: The start date (YYYY-MM-DD). Asana needs a due date with it, later than the start. - **Custom Fields · Optional**: Custom field values by custom field id, such as {"1201234567890555": "High", "1201234567890556": 3}. An enum takes the option's id. - **More Fields · Optional**: Any other task property Asana takes, such as {"html_notes": "\…\", "resource_subtype": "milestone", "liked": true}. ### Delete - **Task · Required**: The task's id, or its link in Asana. ### Move to Section - **Task · Required**: The task's id, or its link in Asana. - **Project · Optional**: The project whose sections to choose from (it is not sent: the section belongs to it). - **Section · Required**: The section to move the task to. It goes to the top of the section and leaves the project's other sections. ### Search - **Workspace · Optional**: The workspace: where a new task goes (unless it goes into Projects), the workspace to search, or the one an Assignee filter looks in. - **Search Text · Optional**: Words in the task's name or description. Search needs a premium Asana workspace. - **Completed · Optional**: Completed tasks, incomplete ones, or both. Options: Either, Yes, No. Default: Either. - **Assignee · Optional**: Assigned to any of these: "me" or user ids, separated by commas. - **In Projects · Optional**: In any of these projects: ids or links, separated by commas. - **In Sections · Optional**: In any of these sections: ids, separated by commas. - **Tagged · Optional**: With any of these tags: ids, separated by commas. - **Subtasks · Optional**: Subtasks only, top-level tasks only, or both. Options: Either, Yes, No. Default: Either. - **Due After · Optional**: Due after this date (YYYY-MM-DD). - **Due Before · Optional**: Due before this date (YYYY-MM-DD). - **More Filters · Optional**: Any other filter of Asana's task search, by its name, such as {"modified_at.after": "2026-11-01T00:00:00Z", "custom_fields.1201234567890555.value": "High"}. - **Sort By · Optional**: The order of the results. Options: Last modified, Created, Due date, Completed, Likes, Best match. Default: Last modified. - **Oldest First · Optional**: Ascending order. Off puts the newest (or highest) first. Off by default. - **Limit · Optional**: How many tasks to return (1–100). Asana's search returns at most 100 per search, with no next page: narrow the filters to find more. Default: 50. - **Fields · Optional**: The properties to return, comma-separated (Asana's opt_fields), such as name,assignee.name,due_on,custom_fields. Empty returns: name, resource_subtype, completed, completed_at, assignee.name, due_on, due_at, start_on, notes, permalink_url, created_at, modified_at, parent.name, projects.name, tags.name. ### Asana › Subtask ### Create - **Parent Task · Required**: The task's id, or its link in Asana. - **Name · Required**: The subtask's name. - **Notes · Optional**: The task's description, as plain text. - **Assignee · Optional**: Who does it: "me", an email address, or a user id. - **Due On · Optional**: The due date (YYYY-MM-DD). Set this or Due At, not both. - **Due At · Optional**: The due date and time (ISO 8601 with a zone, such as 2026-11-07T17:00:00Z). - **Start On · Optional**: The start date (YYYY-MM-DD). Asana needs a due date with it, later than the start. - **Custom Fields · Optional**: Custom field values by custom field id, such as {"1201234567890555": "High", "1201234567890556": 3}. An enum takes the option's id. - **More Fields · Optional**: Any other task property Asana takes, such as {"html_notes": "\…\", "resource_subtype": "milestone", "liked": true}. ### Get Many - **Parent Task · Required**: The task's id, or its link in Asana. - **Return All · Optional**: Read every subtask, page by page (at most 2000; past that the step fails rather than stop early). Off by default. - **Limit · Optional**: How many subtasks to return (1–2000). Default: 50. Shows when **Return All** is off. - **Fields · Optional**: The properties to return, comma-separated (Asana's opt_fields), such as name,assignee.name,due_on,custom_fields. Empty returns: name, resource_subtype, completed, completed_at, assignee.name, due_on, due_at, start_on, notes, permalink_url, created_at, modified_at, parent.name, projects.name, tags.name. ### Asana › Task Comment ### Add - **Task · Required**: The task's id, or its link in Asana. - **HTML · Optional**: Write the comment in Asana's rich text HTML (\, \, \, \