/forge-connector

name: forge-connector
description: >
  Guides building and deploying Atlassian Forge Teamwork Graph connector apps that ingest
  external data into Atlassian's Teamwork Graph, making it searchable in Rovo Search and
  surfaced in Rovo Chat. Use when the user wants to build a Forge connector, ingest external
  data into Atlassian, connect a third-party tool (e.g. Google Drive, ServiceNow, Salesforce)
  to Atlassian, make external content searchable in Rovo, build a graph:connector module,
  use the @forge/teamwork-graph SDK, or implement onConnectionChange / validateConnection
  functions.
license: Apache-2.0
metadata:
  labels: "forge,rovo,jira,atlassian,teamwork-graph,connector"
  maintainer: mbanjan94
  namespace: cloud

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, de