forge-connector

Forge Connector

Builds a graph:connector Forge app that ingests external data into Atlassian's Teamwork Graph so it appears in Rovo Search and Rovo Chat.

Critical Rules

1. Must install in Jira — Apps using Teamwork Graph modules must be installed on a Jira site. Confluence-only installs will not work.
2. Never ask for credentials in chat — Direct users to run forge login in their own terminal.
3. Always run the scaffold script yourself — Do not only give manual instructions; run scripts/scaffold_connector.py to generate the boilerplate.
4. Always ask the user for their Atlassian site URL when install is needed — never discover or guess it.
5. Atlassian deletes data on disconnect — When action = 'DELETED', the app only needs to clean up local state; Atlassian removes the Teamwork Graph data automatically.
6. Handler arguments are passed directly — Forge passes the request object as the first argument to handlers, NOT nested under event.payload. Config values are at request.configProperties, NOT event.payload.config. This is the most common source of TypeError: Cannot destructure property of undefined errors.
7. Use @forge/kvs for storage — Import kvs from @forge/kvs. Do NOT use @forge/storage — its storage export is undefined at runtime in connector functions.
8. Use graph named export from @forge/teamwork-graph — The correct import is const { graph } = require('@forge/teamwork-graph'). Call graph.setObjects({ objects, connectionId }). Do NOT import setObjects as a named export directly.
9. validateConnectionHandler must return { success, message } — Do NOT throw an Error. Return { success: false, message: '...' } to reject, { success: true } to accept.
10. function declarations belong under modules — In manifest.yml, function: is a key under modules:, not a top-level key. Placing it at the top level causes a lint error.
11. formConfiguration uses form array with type: header — Do NOT use fields: or beforeYouBegin:. The correct format uses form: [{ key, type: header, title, description, properties: [...] }].
12. Scopes are read/write/delete:object:jira — Use read:object:jira, write:object:jira, delete:object:jira. The scopes read:graph:teamwork and write:graph:teamwork are invalid and will fail forge lint.
13. Set ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector on forge commands run for this skill — prefix forge invocations with this env var: ones you run in the shell (e.g. forge lint, forge logs, forge deploy) and the interactive forge create command you hand the user as a fallback. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are forge login and forge tunnel (user-run auth / live-dev commands).
14. Never ignore setObjects / setUsers / setGroups responses — Do NOT treat ingestion calls as fire-and-forget. Always check both response.success and response.results?.rejected. A call can partially fail: some objects are rejected while others are accepted, and response.success can be true even when rejected.length > 0.
15. Keep access control IDs consistent — When using USER or GROUP principals in permissions, the id value must exactly match the externalId used in the corresponding graph.setUsers() / graph.setGroups() call. Mismatched IDs (e.g. user-42 vs accountId:user-42) silently make objects invisible to users who should have access.
16. Use orchestration for refresh scheduling — When the user wants periodic re-ingestion, use graph.scheduleOrUpdateTask + a taskRunner handler (the platform-managed approach) instead of a scheduledTrigger. Orchestration handles cadence, retry, and fan-out natively. Only fall back to scheduledTrigger if the user explicitly needs a lightweight cron-style trigger without platform task tracking.
17. taskId must be a valid UUID — Both scheduleOrUpdateTask and scheduleChildTask require task.taskId to be a UUID string. Use uuid() (v4) for root tasks and uuidv5('<scanId>:<parentTaskId>:<itemId>', APP_NAMESPACE) for child tasks. Persist root task IDs in KVS so re-running onConnectionChange reuses the same ID (making it an update, not a competing schedule).
18. Write TaskInfo to KVS before scheduling; never delete it on completion — Always write the TaskInfo record to KVS keyed by taskId before calling scheduleOrUpdateTask or scheduleChildTask. On success, set completed: true on the record — do NOT delete it. Deleting causes duplicate deliveries to report ENTITY_NOT_FOUND and overwrite the earlier success.
19. Branch on response.error for orchestration responses — scheduleOrUpdateTask and scheduleChildTask return { status: 'ACCEPTED' } on success, not { success: true }. Check if (response.error) to detect failures — do NOT check if (!response.success).