Skip to content
AndonDocs
GitHub
Change Andon

Integrations internals

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

How connections are stored, how write-back and Linear’s comments run, and how the one-time tracker import works, for people changing that code. The user guides are Integrations and Import from a tracker.

Connections

integrations holds the workspace’s connections (is_default, name; secret_name is the Vault entry the token is kept under, or the server’s keyring). team_connections holds each team’s pick, with a mapping of key_prefixes and writeback that overrides the connection’s. private.integration_for resolves a team’s connection (its own pick, a parent’s, else the default) and private.integration_config_for its settings, so imports, link resolving and write-back all follow the pick. Migration 20261110064100_workspace_connections.

Tokens go through integration-secrets, which checks each with the provider before keeping it and never returns it. The write-back switches are each provider’s events in apps/board/src/lib/integrations.ts.

Asana sign-in

Connect with Asana sends the browser to Asana’s consent page with a state signed for this org and person with the client secret (valid 10 minutes). Asana returns to /settings/integrations/asana?code=…&state=…, and the page passes both to integration-secrets (oauth_finish), which checks the state, swaps the code for an access and a refresh token, and keeps them together; config.auth records pat or oauth. asanaToken (apps/server/src/functions/shared/asana.ts) refreshes an OAuth token within five minutes of expiry; a refused refresh sets the connection’s last_error. Rotating the client secret only restarts consents in flight.

The app’s scopes, when it uses granular ones, must cover what the import, the sync and write-back do: users, workspaces, teams, projects and tasks read, stories and attachments read, webhooks create and delete, and tasks and stories write.

Write-back

Asana write-back runs in apps/server/src/functions/shared/asana-writeback.ts, through links-writeback. Each attempt is a writeback event on the card’s latest run and stays on its outbox row for a week. The outbox has no client access; the Sync health panel calls tracker-import {action: 'asana_health'}, which checks the caller’s role, then reads the outbox and the import list.

Linear comments

import_issue_comments (service role only, migration 20261112143225_linear_comments) copies up to 500 comments when a card is made from an issue, keyed by <issue id>/<comment id> in card_comments.external_ref, so a second import adds no copies. Comments the write-back posted are skipped. In a run’s {{comments}} they are marked from Linear.

The tracker import

The tracker-import function (/api/fn/tracker-import and the tracker-import job) runs apps/server/src/functions/shared/tracker-import-job.ts.

  • Readers and the dry run are pure: packages/shared/src/tracker-parse.ts and tracker-import.ts, which the job imports from @andon/shared. parseTrello reads both Trello’s export and its API pages; parseAsana reads Asana’s REST pages.
  • Slices. The job works in slices with a lease (import_job_claim) and queues the next itself (import_job_kick → private.call_function). Where the database can’t call functions, the open Settings page drives it.
  • Writes: import_job_prepare (team, statuses, projects, cycles, milestones, fields, former members), import_job_card (a card with its comments and links), import_job_relations, import_job_templates and import_job_apply_templates, import_job_finish.
  • Idempotence. A card is found again by card_links (org, provider, external_id); a comment, status, cycle or field by private.import_refs; a project or milestone by its tracker id; a file by card_attachments.source_ref.
  • Rate limits. One request at a time per tracker: Trello 120 ms apart, Asana 400 ms. A 429 waits as asked, up to a minute.
  • Trello’s API. The key and token are one secret (<key>:<token>, apps/server/src/functions/shared/trello.ts), sent in the Authorization: OAuth … header, never a URL. The board is read in the export’s shape, then the comment and create actions are paged past the first 1,000.
  • Asana reading (apps/server/src/functions/shared/asana-import.ts, asanaReadSlice): workspace, team, users and projects; each project’s sections and task pages (100 a page); subtasks at any depth; then each task’s stories and attachments. The bundle grows in the job until it’s all read. A file’s signed download_url is fetched fresh (GET /attachments/{gid}) when it is copied, and the token never goes with the download.
  • Asana sync. Each synced project is an asana_webhooks row. The handshake’s X-Hook-Secret is kept like a token and answered only for a subscription made in the last ten minutes. A delivery must carry a valid X-Hook-Signature (HMAC-SHA256 of the body) or gets 401; an unknown subscription gets 410. Deliveries queue task ids (asana_sync_enqueue); asana_sync_kick runs tracker-import {action: 'sync'}, which rereads them in batches. asana_sync_claim keeps a sync and a re-run apart. Deliveries arrive at asana-webhook (/functions/v1/asana-webhook on the server).
  • Former members. former_members rows; cards.former_assignee_id and card_comments.former_author_id point at them. The email is in private.former_member_emails. invite_former_member calls create_invite from the private address, and link_former_member sets former_members.user_id. Migration 20261108192317_tracker_import.

Not covered yet

  • fixtures/asana/move-team.json and fixtures/trello/board-export.json are built from the providers’ API references, not captured from real workspaces.
  • A Jira XML export’s components and affected versions aren’t read.