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.