Asana integration
The Asana integration brings Asana tasks and projects into Sharkly: bind a workspace, discover and preview projects, import them, and optionally link an Asana project to a Space as a sync link that keeps receiving changes. Open it from Integrations under Asana.
Connect a workspace
- Open Integrations and select Asana.
- Enter the Asana personal access token; when the token can see more than one workspace, also enter the workspace ID.
- Confirm, and Sharkly validates the connection; a successful validation saves an organization-level connection.
Create the personal access token in Asana's developer console under your account's apps. An Asana connection is workspace-scoped: a credential that spans multiple workspaces is refused rather than resolved to the first one, so add the workspace ID you intend to bind.
The connection is shared by the organization: every member uses this one Asana credential, and rotating or disabling it affects the whole organization's Asana integration. Tokens are encrypted at rest; only the last four characters are shown afterwards. Rotate a token from Manage connection on the integration page instead of deleting and rebinding; completed imports and sync links are unaffected.
Import
The import wizard walks: confirm connection → choose a project → map statuses and users → confirm the import.
- Connection: confirm the saved credentials are usable.
- Scope: the wizard discovers the Asana projects the connection can read; pick one and the target Space.
- Preview: read and preview the tasks in that project to confirm the range; retry from this step if the read fails.
- Statuses and users: review how Asana task statuses map to Sharkly statuses, and decide how source users are handled (map to members, invite, or import as external accounts).
- Confirm: start the import.
The import only reads Asana; it never changes anything there. Asana tasks are normalized into Sharkly Tasks, and assignees who cannot be matched to an Organization member are captured as external accounts with the same rules as a Jira import.
Incremental re-imports
Importing the same Asana source into the same Space again does not duplicate tasks — only changed content is followed up. To refresh historical data, roll back the previous import in the import history and import again.
Import history
Each import is a job record. The import history on the integration page shows progress and failures, and lets you cancel, resume, or roll back a job. A rollback deletes only the tasks that import created and that still belong to it; tasks created by earlier imports, and any local edits, are neither deleted nor reverted, and the continuous sync associated with that import is turned off.
Incremental sync
Import moves history; to keep following Asana-side changes, use a sync link to pair an Asana project with a Sharkly Space:
- Choose New sync on the integration page; the wizard covers configuration (connection, project, target Space, direction), status mapping, user mapping, and import options.
- The direction is either Asana to Sharkly only (Asana changes are read in) or Bidirectional (changes are written both ways).
- The final step enables the link, and it starts receiving changes on a schedule.
Sync receives changes from enabled links on a schedule; Sync now on a link receives immediately, and the organization-level Sync all links runs every enabled link once. The import wizard's last step also offers Enable sync after import.
Enabling and disabling are separate from deletion: Stop syncing (disconnect) pauses changes and keeps the configuration for later re-enable in the sync settings; Delete sync removes the configuration. Imported tasks are unaffected either way.
Asana webhook registration stays manual: the Webhook guidance on the integration page provides the callback URL (the secret generated with the credential verifies signatures) to configure on the Asana side; without a webhook, sync still works on its polling schedule.
Outbound behavior
The write-back scope follows the "outbound sync fields" shown on the link's configuration: a bidirectional Asana link currently writes back a task's title and description, while statuses (open / completed) are read in but never written out; posting a comment on a task can optionally send it to Asana, and comment edits and deletes never travel back.
Troubleshooting
Where do I create the personal access token?
Create it in Asana's developer console under your account's apps, then paste it into the bind form.
Where do I find the workspace ID?
The workspace ID is the numeric identifier (gid) of an Asana workspace, visible in Asana URLs and API responses. It is needed only when the token can see more than one workspace.
Does the import write back to Asana?
Import and incremental sync follow Asana tasks into Sharkly; a bidirectional link writes back only task titles and descriptions, plus new comments explicitly sent to Asana. Other edits and deletes never travel back.