Asana#

Asana is registered for API sync and sync-coupled user import. It pulls tasks and workspace users from Asana into a reviewable import session, then projects each task into the internal integrations task-create draft for operator review.

Capability	Method	Status
`SYNC`	Pull tasks from the Asana API	Built
`USER_IMPORT`	Bring Asana users into the task-import mapping	Built as part of API sync
`CSV_IMPORT`	Upload an Asana CSV export	Not built
`WEBHOOK`	—	Not built

The endpoints below live under /api/v1/providers/asana/.... They are generic - the same routes serve any registered provider by substituting the {provider} path segment. All routes require an organization-scoped user token (see Authentication).

Discovery#

GET /api/v1/providers/asana

{
  "status": "success",
  "data": { "provider": "asana", "capabilities": ["SYNC", "USER_IMPORT"] }
}

Credential Verification#

Asana personal access tokens can be stored and verified for API sync:

PUT /api/v1/providers/asana/credentials?organization_id=<id>
POST /api/v1/providers/asana/credentials/verify?organization_id=<id>

The token is treated as opaque: the service does not require a prefix. Verification sends the secret as an Asana bearer token and probes GET /workspaces?limit=1. Stored secrets are encrypted at rest and never returned by the credential endpoints.

Importing From the Asana API#

POST /api/v1/providers/asana/imports/sync?organization_id=<id>

Uses the stored, encrypted Asana token to discover visible workspaces, pull workspace users for the proposed user mapping, discover non-archived projects, and import incomplete project tasks with completed_since=now. The project task list requests the projection fields through opt_fields; the adapter falls back to GET /tasks/{gid} only if Asana returns a sparse task record.

The current generic sync endpoint has no provider-specific filter body, so Asana sync imports from every visible workspace/project the stored token can access. Use a token with the intended Asana visibility to control scope.

User Mapping#

Asana USER_IMPORT rides the sync flow. The adapter proposes mappings from:

workspace users returned by GET /workspaces/{gid}/users;
task creators and assignees found on synced task records.

The primary matching key is the Asana user gid; email is secondary when present. A present but unmapped assignee creates a blocking projectionError. A missing or unmapped creator leaves creatorId unset with a non-blocking mapping note.

Projection Field Coverage#

Asana source	TeamBoost draft field	Notes
`name`	`title`	Error if shorter than 2 characters
`resource_subtype`	`type`	`approval` maps to `REVIEW`; `default_task` and unknown values map to `OTHER` with a note
`notes`	`description`	`html_notes` is preserved in `descriptionJson`
`completed`	`status`	Completed tasks map to `COMPLETED`; imported incomplete tasks map to `NOT_STARTED`
No native priority	`priority`	Defaults to `UNKNOWN` with a mapping note
`created_by`	`creatorId`	Resolved through the user mapping when possible
`assignee`	`ownerId`	Present-but-unmapped assignee blocks confirm
`tags`	`labels`	Tag names pass through; TeamBoost creates/maps labels server-side
Sync project	`projectTitle`	If a task belongs to multiple projects, the sync project is primary and all project refs are preserved
First membership section	`taskGroupTitle`
`start_at` / `start_on`	`plannedStartDate`	Date-only `start_on` normalizes to UTC start-of-day
`due_at` / `due_on`	`plannedEndDate`	Date-only `due_on` normalizes to UTC end-of-day
Parent, dependencies, custom fields, permalink	`descriptionJson`	Preserved for review; not wired as TeamBoost relationships in this first unit

Not Built Yet#

Asana CSV import.
Standalone user-directory import endpoint.
OAuth app install flow.
Webhook registration and event verification.
Provider-specific sync filters in the generic sync request.