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.

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–5 in Order

Step 0: Prerequisites

Check Node.js (node -v, requires 22+), Forge CLI (forge --version), and login (forge whoami). Install missing tools:

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>
  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 2: Scaffold the Connector App

Run from the skill directory (the directory containing this SKILL.md). --dev-space-id is optional:

python3 -m scripts.scaffold_connector \
  --name <app-name> \
  --connector-name "<Human Readable Name>" \
  --object-type atlassian:document \
  --directory <parent-directory>

Add --dev-space-id <id> only if you have the ID from a previous step.

Object type selection — pick the type that best matches the content being ingested (see Object Types table). For mixed content, use atlassian:document as the default.

Form config flag — add --has-form-config if the admin must provide API credentials or connection details (typical for external systems). 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):

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:

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',
      permissions: [{
        accessControls: [{
          principals: [{ type: 'EVERYONE' }],   // or restrict to specific users
        }],
      }],
      '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',
        },
      },
    },
  ],
});

if (!result.success) {
  console.error('setObjects 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 | | image/ | IMAGE | | video/ | VIDEO | | audio/* | AUDIO | | Other | OTHER |

getObjectByExternalId — look up a single object

const { graph } = require('@forge/teamwork-graph');

const data = await graph.getObjectByExternalId({
  externalId: 'unique-id-from-source',
  objectType: 'atlassian:document',
  connectionId,
});
if (data.success) console.log(data.object);

Step 4: Deploy and Install

You MUST run the deploy script — do not only give the user manual forge deploy commands.

The deploy script lives in the forge-app-builder skill, not in this skill. Derive its directory from t