Object hierarchy
Asana is a work tracking and collaboration tool. This guide is designed to give developers a brief overview of how data in Asana is structured.
API reference
This guide is not meant to be exhaustive. Rather, the intention is to describe the fundamental elements of Asana to help you scope apps and avoid common points of confusion.
For an exhaustive list, descriptions, and properties of all objects in the API, visit the API reference.
Object relationships
The object hierarchy is largely informed by the Asana Work Graph -- a flexible system through which any piece of work can have a one-to-many relationship.
Likewise, objects in the API (e.g., tasks, projects, portfolios, etc.) can also be associated with one or more other objects. The following is a simplified example of how one workspace might organize its data:
For instance, a story may be associated with a task. This task may belong to one (or more) projects. That project (along with other related projects) may be shared with a particular team. And at the top, a workspace exists as the highest level of organization to organize that and other teams.
How work is organized
Tasks
Tasks are the basic unit of action in Asana. Tasks have many fields, including a single assignee, name, notes, followers (i.e., collaborators), likes, and comments (among others). Tasks inherit custom fields from their parent project(s). Custom fields values are set for each individual task.
In addition to standard Create / Read / Update / Delete operations, there are a few things to watch out for when working with tasks:
- Tasks can be orphaned and belong to no projects, they can belong to one project, or they can be multi-homed across two or more projects. The
membershipsfield is a collection of the projects with which the task is associated. - Tasks can be multi-homed as subtasks. For example, task A can be in project B and the same task A can also be a subtask of task C.
Quick start
For a tutorial on how to use the API to perform CRUD operations on a task, visit the quick start guide.
Projects
A project is a collection of tasks that can be viewed as a list, board, timeline, and calendar. Projects can only exist in a single organization or workspace and only belong to a single team. Projects can be public in the team or private to project members. Among the many fields associated with projects, they can have global (i.e., shared across the organization) or local (i.e., project-specific) custom fields. A project’s custom fields will be displayed on each task within the project.
Portfolios
Portfolios are collections of projects (or other portfolios). Custom fields can be added to portfolios in addition to standard fields that are displayed on every portfolio. These fields provide a high-level overview of the status of each project within the portfolio.
Sections
A section is a group of tasks within a project. Sections let you divide tasks into categories, workflow stages, priorities, and more.
Subtasks
A subtask is exactly the same as tasks in a project, except that one (and only one) of its parents is a task (although subtasks can also simultaneously be organized into projects). To check if a task has a subtask, include the num_subtasks field when fetching the parent task.
Things to note when working with subtasks:
- Subtasks do not inherit the projects of their parent tasks.
- There can be up to 5 levels of subtasks below a task. We do not recommend making sub-subtasks.
- There is no way to fetch all subtasks of all tasks in a project in a single request.
Goals
A goal is an object in the goal-tracking system that helps your organization drive measurable results. A goal can be listed at the workspace level (i.e., it is listed as part of the workspace's goals), team level, or individual user level.
How users are organized
Workspaces
A workspace is the highest-level organizational unit in Asana. All projects, tasks, and teams have an associated workspace.
Organizations
An organization is a special kind of workspace that represents a company. Organizations connect all the employees at a company using Asana in a single space based on the company’s shared email domain. In an organization, you can group your projects into teams.
Teams
Teams are a subset of users in an organization who collaborate on projects together. Every project in an organization is associated with one team. Team messages are not currently available in the API.
Users
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. Asana accounts are free and tied to individuals; Asana accounts grant access to one or more shared workspaces and organizations to collaborate with other Asana users.
Guest users
Users can invite clients, contractors, customers, or anyone else who does not have an email address at an approved organization email domain. These users join as organization guests. Guests have limited access in an organization. That is, guests can only see what is explicitly shared with them.
Note: It can be advantageous to use guests to create "bot" accounts. Due to the access restrictions, bots created from a guest account personal access token can be given fine-grained access to only the data that it needs to use.
Updated over 1 year ago