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)`. ## MCP Prerequisites | MCP Server | Purpose | | ------------- | ------------------------------------------------- | | **Forge MCP** | Manifest syntax, module config, deployment guides | | **ADS MCP** | Atlaskit components (only if adding Custom UI) | --- ## Agent Workflow — Complete Steps 0–7 in Order ### Step 0: Prerequisites Check Node.js (`node -v`, requires 22+), Forge CLI (`forge --version`), and login (`forge whoami`). Install missing tools: ```bash npm install -g @forge/cli ``` Tell the user to run `forge login` in their terminal if not authenticated. ### Step 1: Discover Developer Spaces > **Note:** `forge developer-spaces list` does NOT exist in Forge CLI 12.x. You cannot list developer spaces non-interactively. `forge create` requires an interactive TTY to select a developer space. Ask the user to run it themselves: ``` Tell the user: cd <parent-directory> ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector forge create --template blank <app-name> When prompted, select a Developer Space and let it complete. Come back when done. ``` The `--dev-space-id` flag in the scaffold script is optional and can be omitted — the script has been updated to skip it when not provided. ### Step 1.5: Discover Data & Map to Object Types **Do this before scaffolding.** Ask the user the following questions to determine the correct Teamwork Graph object type(s). Do not assume or default to `atlassian:document`. #### Questions to ask the user 1. **What external system or tool are you connecting?** e.g. Google Drive, ServiceNow, Salesforce, GitHub, Confluence, Slack, Figma, Zendesk 2. **What kind of content do you want to make searchable in Rovo?** Prompt with examples to help them identify it: - Files, pages, wiki articles, reports, PDFs → likely `atlassian:document` - Tasks, tickets, issues, bugs, stories → likely `atlassian:work-item` - Chat messages, emails, comments → likely `atlassian:message` or `atlassian:comment` - Projects, workspaces, boards → likely `atlassian:project` - Code repositories → likely `atlassian:repository` - Pull requests / merge requests → likely `atlassian:pull-request` - Git commits → likely `atlassian:commit` - Design files (Figma, Sketch) → likely `atlassian:design` - Video recordings → likely `atlassian:video` - Calendar events, meetings → likely `atlassian:calendar-event` - Threads, channels → likely `atlassian:conversation` - Customer accounts or organisations → likely `atlassian:customer-organization` - Team spaces or org units → likely `atlassian:space` 3. **Is the content a single type or a mix?** If mixed (e.g. a project management tool with tasks *and* documents), plan to ingest each as its own object type. The scaffold supports one primary type — you can add more `objectTypes` entries in `manifest.yml` later. 4. **Does the admin need to supply credentials (API key, URL, OAuth token) to connect?** Yes → use `--has-form-config` in the scaffold command. No (data comes entirely from within Atlassian) → omit the flag. 5. **How often does the source data change?** This determines the sync cadence. Use **orchestration** (`scheduleOrUpdateTask` + `taskRunner`) for all platform-managed refresh — it handles cadence, retry, and fan-out natively. Only use the legacy `scheduledTrigger` approach if you explicitly need a lightweight cron with no task tracking. | Frequency | Orchestration interval | |---|---| | Hourly | `scheduleInterval: { value: 1, timeUnit: 'hour' }` | | Daily | `scheduleInterval: { value: 1, timeUnit: 'day' }` | | Every N minutes (1–60) | `scheduleInterval: { value: N, timeUnit: 'minute' }` | | Static / one-off | No scheduled refresh needed — ingest once in `onConnectionChange` | Record the chosen interval before proceeding to Step 2. 6. **Who should be able to see the ingested content in Rovo Search?** This determines the `permissions.accessControls` on each object. Ask: - "Is all this content publicly accessible, or does the source system restrict who can see what?" - "Do you want Rovo Search results to respect those source-system permissions?" Map the answer to the correct principal model: | Source system access model | `accessControls` to use | |---|---| | Publicly accessible, no restrictions | `principals: [{ type: 'EVERYONE' }]` | | Specific named users have access | `principals: [{ type: 'user', id: '<atlassian-account-id>' }]` — one entry per user | | Team or group based (e.g. Confluence space, Google Workspace group) | `principals: [{ type: 'group', id: '<group-id>' }]` — one entry per group | | Private / owner only | single `user` principal with the owner's Atlassian account ID | | Mixed (per-object ACLs from the source) | fetch ACLs per item during ingestion and map each to a `user` or `group` principal | **Do NOT default to `EVERYONE`** unless the user explicitly confirms content is publicly accessible. Using `EVERYONE` on restricted content leaks data to users who shouldn't see it in Rovo Search. Record the chosen permission model before proceeding to Step 2. Reference it when writing the `setObjects` call in Step 3. #### Mapping decision Based on the answers, select the best-fit type from the Object Types table below. Only fall back to `atlassian:document` if the content genuinely has no better match (e.g. arbitrary file attachments). For types marked ❌ in the "Indexed in Rovo" column (`atlassian:build`, `atlassian:deployment`, `atlassian:test`), warn the user that those objects will not appear in Rovo Search or Rovo Chat. Record the chosen object type(s) and permission model before proceeding to Step 2. ### Step 2: Scaffold the Connector App Run from the **skill directory** (the directory containing this SKILL.md). Replace `<object-type>` with the type determined in Step 1.5. `--dev-space-id` is optional: ```bash python3 -m scripts.scaffold_connector \ --name <app-name> \ --connector-name "<Human Readable Name>" \ --object-type <object-type> \ --directory <parent-directory> ``` Add `--dev-space-id <id>` only if you have the ID from a previous step. **Object type** — use the type chosen in Step 1.5. Do NOT default to `atlassian:document` without first completing the discovery questions above. **Form config flag** — add `--has-form-config` if the admin must provide API credentials or connection details (determined in Step 1.5 question 4). Omit it for apps that operate entirely within Atlassian (no external credentials needed). > **If scaffold fails because `forge create` needs a TTY:** The scaffold script will print a manual fallback command. Have the user run `forge create` interactively, then continue from Step 3 — the scaffold script only needs to write `manifest.yml` and `src/index.js` after the directory exists. ### Step 3: Customize the Generated Code After scaffolding (or after the user runs `forge create` interactively): ```bash cd <app-name> npm install ``` The blank template generates `src/index.js` (JavaScript, not TypeScript). Edit it to add your API calls. The scaffold generates working handler skeletons; fill in your business logic. #### Key files to edit | File | What to change | | -------------- | ----------------------------------------------------------------------- | | `src/index.js` | `fetchExternalData()` — replace with your API calls | | `manifest.yml` | Add `permissions.external.fetch.backend` URLs for any external APIs | | `package.json` | Add `@forge/api`, `@forge/kvs`, `@forge/teamwork-graph` as dependencies | #### setObjects — ingest data into Teamwork Graph Use the `graph` named export — do NOT destructure `setObjects` directly: ```javascript const { graph } = require('@forge/teamwork-graph'); const result = await graph.setObjects({ connectionId, // required — the connectionId from the handler request objects: [ { schemaVersion: '1.0', id: 'unique-id-from-source', // unique per connectionId updateSequenceNumber: 1, displayName: 'My Document Title', url: 'https://source-system.example.com/doc/123', createdAt: '2024-01-15T10:00:00Z', // ISO 8601 lastUpdatedAt: '2024-01-20T14:30:00Z', // Use the permission model chosen in Step 1.5 question 6. // EVERYONE only if content is confirmed publicly accessible. // For user-restricted content: { type: 'USER', id: '<externalId from setUsers>' } // For group-restricted content: { type: 'GROUP', id: '<externalId from setGroups>' } permissions: [{ accessControls: [{ principals: [{ type: 'EVERYONE' }], }], }], 'atlassian:document': { type: { category: 'DOCUMENT', // see Document Categories table below mimeType: 'application/vnd.google-apps.document', }, content: { mimeType: 'application/vnd.google-apps.document', text: 'document title or snippet for search indexing', }, }, }, ], }); // Always check both success AND rejected — a call can partially fail. const rejected = result.results?.rejected ?? []; if (!result.success || rejected.length > 0) { console.error('setObjects ingestion failed', { connectionId, acceptedCount: result.results?.accepted?.length ?? 0, rejectedCount: rejected.length, rejected, error: result.error, }); } ``` - Max **100 objects per call** — batch large datasets with a loop - `id` must be unique per `connectionId` - `connectionId` is required in every `graph.setObjects()` call #### Document Categories (for `atlassian:document.type.category`) | MIME type | Category | |---|---| | `application/vnd.google-apps.document` | `DOCUMENT` | | `application/vnd.google-apps.spreadsheet` | `SPREADSHEET` | | `application/vnd.google-apps.presentation` | `PRESENTATION` | | `application/vnd.google-apps.folder` | `FOLDER` | | `application/pdf` | `PDF` |