К основному содержанию
скилл CX Codex

forge-connector — скилл для Claude Code: что делает и как установить

Скилл forge-connector для Claude Code, создающий приложения коннекторов Atlassian Forge Teamwork Graph для передачи внешних данных в поиск Rovo.

Apache-2.0 453 установок ★ 33 обновлён 2026-10-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add atlassian/forge-skills --skill forge-connector -a claude-code
Открыть на GitHub

Что делает forge-connector

Скилл автоматизирует сборку и развёртывание коннекторов Atlassian Forge Teamwork Graph, интегрирующих сторонние источники в экосистему Atlassian. Он управляет структурой манифеста, настройкой модулей графа, обработкой вызовов и планированием задач через оркестрацию платформы. Для работы требуются Node.js версии 22 и выше, установленный Forge CLI, а также активная авторизация через forge login в терминале.

В процессе разработки скрипт генерирует шаблонный код, настраивает хранение данных через @forge/kvs и проверяет корректность областей видимости. Перед запуском команд окружения важно задавать переменную ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector, чтобы агент корректно фиксировал выполнение операций.

Какие задачи решает

  • создать коннектор для передачи внешних данных в Atlassian Teamwork Graph
  • интегрировать сторонние сервисы с поиском Rovo Search и Rovo Chat
  • настроить валидацию подключений и обработчики событий в приложении Forge
  • спланировать периодическую синхронизацию данных через встроенную оркестрацию

Примеры запросов агенту

  • Создай новый коннектор для интеграции внешнего источника данных с Atlassian Teamwork Graph
  • Проверь манифест Forge-приложения и настрою корректные области видимости для графа
  • Запусти скрипт создания шаблона коннектора и настрой обработчики подключения

Как установить forge-connector

1Через Skills CLI (Vercel)

npx skills add atlassian/forge-skills --skill forge-connector -a claude-code

2Вручную: положить файлы

~/.claude/skills/forge-connector/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/forge-connector/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о forge-connector

Как установить forge-connector в Claude Code?

Выполните в терминале команду npx skills add atlassian/forge-skills --skill forge-connector -a claude-code, а затем обратитесь к файлу ~/.claude/skills/forge-connector/SKILL.md.

Что делает forge-connector?

Скилл направляет агента при создании и развёртывании приложений Teamwork Graph, которые передают данные из внешних систем в продукты Atlassian для индексации в Rovo.

Что нужно для работы forge-connector?

Для работы требуются Node.js версии 22 и выше, установленный пакет @forge/cli и выполненный вход в систему через forge login.

Исходный текст

SKILL.md · Apache-2.0
---

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, 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` |
| `image/*` | `IMAGE` |
| `video/*` | `VIDEO` |
| `audio/*` | `AUDIO` |
| Other | `OTHER` |

#### getObjectByExternalId — look up a single object

```javascript
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 the path of this SKILL.md: go up two levels (`skills/forge-connector/` → `skills/`) then into `forge-app-builder/`. Run all commands below from that directory.

```bash
# Derive forge-app-builder skill dir from this SKILL.md's path:
# e.g. if this file is at /path/to/skills/forge-connector/SKILL.md
# then the deploy script dir is: /path/to/skills/forge-app-builder/

# If you have the site URL:
python3 -m scripts.deploy_forge_app \
  --app-dir <app-directory> \
  --site <site-url> \
  --product jira

# If you don't have the site URL yet, deploy first then ask:
python3 -m scripts.deploy_forge_app \
  --app-dir <app-directory> \
  --product jira \
  --deploy-only
# Ask: "What is your Atlassian site URL (e.g. yourcompany.atlassian.net)?"
python3 -m scripts.deploy_forge_app \
  --app-dir <app-directory> \
  --site <site-url> \
  --product jira \
  --skip-deps
```

### Step 5: Connect via Atlassian Administration

After deployment, tell the user to:

1. Go to **Atlassian Administration** → **Apps** → **[site]** → **Connected apps**
2. Find the app → **View app details** → **Connections** tab
3. Click **Connect** under the connector
4. Fill in any configuration fields (if `formConfiguration` was defined)
5. Click **Connect** — this triggers `onConnectionChange` with `action: CREATED` and starts data ingestion

### Step 6: Monitor with forge tunnel

Use `forge tunnel` during development to stream live logs directly to your terminal as the connector functions execute. This is the fastest way to catch errors in `onConnectionChangeHandler`, `validateConnectionHandler`, and `setObjects` calls without waiting for `forge logs`.

Tell the user to run this in their own terminal (it requires an interactive session):

```bash
cd <app-directory>
forge tunnel
```

With the tunnel active, any invocation of the connector functions (e.g. clicking "Connect" in Atlassian Admin, or triggering a scheduled re-ingestion) will stream output immediately. Look for:

- `[connector] Fetched N items` — confirms `fetchExternalData()` ran
- `[connector] Batch 1: N accepted, 0 rejected` — confirms `setObjects` succeeded
- Any uncaught errors or thrown exceptions from `validateConnectionHandler`

If the tunnel is not running, use `forge logs` instead to inspect past invocations:

```bash
# Most recent 50 log lines from development environment
forge logs -e development --limit 50

# Production logs for a specific site
forge logs -e production --site <your-site> --limit 50
```

**Tunnel vs logs — when to use which:**

| Situation | Use |
|---|---|
| Actively developing / testing the connection flow | `forge tunnel` — live streaming |
| Debugging a past invocation or production issue | `forge logs` |
| Connector function timed out before tunnel caught it | `forge logs` with `--limit 100` |

> **Note:** `forge tunnel` must be run by the user in an interactive terminal — do not attempt to run it via the agent.

### Step 7: End-to-End Verification (optional)

Before running any checks, ask the user:

> "Would you like to run end-to-end verification checks before deploying to production? This confirms the connection, ingestion, Rovo Search visibility, and permission boundaries are all working correctly."

If the user says **no** or wants to skip, move on — do not run or describe the checks.
If the user says **yes**, work through every check below in order.

#### Check 1 — Connection established

In **Atlassian Administration → Apps → Connected apps**, the connector should show status **Connected**. If it shows an error or pending state, go back to Step 6 and inspect `forge tunnel` or `forge logs` output.

#### Check 2 — `validateConnection` passed (if configured)

If the app has a `validateConnection` function, confirm the admin saw a success message when clicking **Connect**. If not, check logs for the return value — it must be `{ success: true }`, not a thrown error.

#### Check 3 — `onConnectionChange` fired and ingestion ran

In `forge logs` or the tunnel output, confirm:

```bash
forge logs -e development --limit 50
```

Look for all three signals:
- Handler was invoked: log line from `onConnectionChangeHandler` with `action: CREATED`
- Data was fetched: e.g. `[connector] Fetched N items`
- `setObjects` succeeded: e.g. `[connector] Batch 1: N accepted, 0 rejected`

If `setObjects` returned `{ success: false }`, the error detail is in `result.error` — surface it to the user and fix before continuing.

#### Check 4 — Objects visible in Rovo Search

1. Open Rovo Search on the Jira site (allow up to **5 minutes** for indexing after ingestion)
2. Search for a word that appears in at least one ingested object's `displayName` or content text
3. Filter by the connector's nickname (set by admin at connection time)

At least one result from the connector should appear. If nothing shows up after 5 minutes:
- Confirm `setObjects` logged `N accepted` with N > 0 (Check 3)
- Confirm the object's `permissions` match the logged-in user (an `EVERYONE` principal or a `user`/`group` principal that includes the test user)
- Re-check that `write:object:jira` scope is present in `manifest.yml` and the app was redeployed after any scope change

#### Check 5 — Permission boundary (skip only if `EVERYONE` was used)

If the connector uses `user` or `group` principals:
1. Log in as a user who **should** have access → confirm the object appears in Rovo Search
2. Log in as a user who **should not** have access → confirm the object does **not** appear

If a restricted object is visible to an unauthorised user, re-check the `accessControls` principals in `setObjects` and redeploy.

#### Check 6 — Rovo Chat references connector data

Ask Rovo Chat a question whose answer exists only in the ingested content, e.g.:

> "What is the status of [title of an ingested item]?"

Rovo Chat should cite the connector as a source. If it cannot find the content, Checks 3 and 4 likely have an unresolved issue.

#### Check 7 — Scheduled re-ingestion fires (if configured)

If a `scheduledTrigger` was added:
1. Temporarily set `interval: fiveMinutes` in `manifest.yml`, redeploy, and wait one cycle
2. Confirm `forge logs` shows a fresh ingestion run from `refreshIngestionHandler`
3. Restore the original interval and redeploy before going to production

#### Production readiness gate

If the user chose to run verification, only proceed to a production deploy (`forge deploy -e production`) when **all applicable checks above pass**:

| Check | Required for production |
|---|---|
| 1 — Connection established | Always |
| 2 — validateConnection passed | Only if `validateConnection` is configured |
| 3 — Ingestion ran without errors | Always |
| 4 — Objects visible in Rovo Search | Always |
| 5 — Permission boundary | Only if using `user`/`group` principals |
| 6 — Rovo Chat cites connector | Always |
| 7 — Scheduled re-ingestion fires | Only if `scheduledTrigger` is configured |

---

## Manifest Reference

> **Key rules:**
> - Scopes are `read:object:jira`, `write:object:jira`, `delete:object:jira` — NOT `read:graph:teamwork` / `write:graph:teamwork` (those fail `forge lint`)
> - `function:` is declared **under `modules:`**, not at the top level
> - Egress uses `address:` not a bare string (run `forge lint --fix` to auto-correct)
> - `formConfiguration` uses `form: [{ type: header, properties: [...] }]` — NOT `fields:` or `beforeYouBegin:`

### Minimal connector (no admin config, no OAuth)

Use when the app operates entirely within Atlassian — no external credentials needed.

```yaml
app:
  id: <generated-by-forge-create>
  runtime:
    name: nodejs24.x
    memoryMB: 256
    architecture: arm64

permissions:
  scopes:
    - read:object:jira
    - write:object:jira
    - delete:object:jira
    - storage:app

modules:
  graph:connector:
    - key: my-connector
      name: My Service
      capabilities:
        replicatesPermissions: false  # true if mirroring source-system ACLs into Teamwork Graph
        syncFidelity: mirror          # append | upsert | mirror (mirror is recommended)
        supportsIncrementalSync: false
      icons:
        light: https://cdn.example.com/logo.png
        dark: https://cdn.example.com/logo.png
      objectTypes:
        - atlassian:document
      datasource:
        onConnectionChange:
          function: on-connection-change

  function:
    - key: on-connection-change
      handler: index.onConnectionChangeHandler
```

### Connector with orchestration (platform-managed refresh)

Add an `orchestration.taskRunner` block to any connector variant to enable platform-managed periodic re-ingestion. Wire it alongside your existing `onConnectionChange` handler.

```yaml
modules:
  graph:connector:
    - key: my-connector
      name: My Service
      capabilities:
        replicatesPermissions: false
        syncFidelity: mirror
        supportsIncrementalSync: false
      icons:
        light: https://cdn.example.com/logo.png
        dark: https://cdn.example.com/logo.png
      objectTypes:
        - atlassian:document
      orchestration:
        taskRunner:
          function: task-runner-fn     # references the function key below
      datasource:
        onConnectionChange:
          function: on-connection-change

  function:
    - key: on-connection-change
      handler: index.onConnectionChangeHandler
    - key: task-runner-fn
      handler: index.taskRunner
      timeoutSeconds: 900             # optional: extend to 15 min for large datasets
```

> `timeoutSeconds` is only valid on a function referenced by a consumer module (like `orchestration.taskRunner`). Setting it on an unreferenced function fails manifest validation.

### Connector with admin form config (API key / URL)

Use when the admin must provide credentials to connect to an external system.
```yaml
app:
  id: <generated-by-forge-create>
  runtime:
    name: nodejs24.x
    memoryMB: 256
    architecture: arm64

permissions:
  scopes:
    - read:object:jira
    - write:object:jira
    - delete:object:jira
    - storage:app
  external:
    fetch:
      backend:
        - address: 'https://api.your-service.com'   # note: address: not a bare string

modules:
  graph:connector:
    - key: my-connector
      name: My Service
      capabilities:
        replicatesPermissions: false  # true if mirroring source-system ACLs into Teamwork Graph
        syncFidelity: mirror          # append | upsert | mirror (mirror is recommended)
        supportsIncrementalSync: false
      icons:
        light: https://cdn.example.com/logo.png
        dark: https://cdn.example.com/logo.png
      objectTypes:
        - atlassian:document
      datasource:
        formConfiguration:
          form:                          # use form:, NOT fields: or beforeYouBegin:
            - key: connectionDetails
              type: header
              title: Connection Details
              description: >
                Provide your My Service API credentials.
                Find them in My Service → Settings → API.
              properties:
                - key: apiKey           # camelCase keys — accessed as request.configProperties.apiKey
                  label: API Key
                  type: string
                  isRequired: true
                - key: apiUrl
                  label: API URL
                  type: string
                  isRequired: true
          validateConnection:
            function: validate-connection
        onConnectionChange:
          function: on-connection-change

  function:                              # function: is under modules:, NOT top-level
    - key: on-connection-change
      handler: index.onConnectionChangeHandler
    - key: validate-connection
      handler: index.validateConnectionHandler
```

---

## Handler Signatures

> **Critical:** Forge passes the request **directly as the first argument** — it is NOT wrapped under `event.payload`. Config form values are at `request.configProperties`, not `event.payload.config`. Getting this wrong causes `TypeError: Cannot destructure property of undefined`.

### onConnectionChange

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

exports.onConnectionChangeHandler = async (request) => {
  // request.action, request.connectionId, request.configProperties
  const { action, connectionId, configProperties } = request;

  if (action === 'DELETED') {
    // Atlassian removes Teamwork Graph data automatically on disconnect.
    // Only clean up locally stored credentials.
    await kvs.deleteSecret(connectionId);
    return { success: true };
  }

  // CREATED or UPDATED — persist credentials and ingest data
  await kvs.setSecret(connectionId, configProperties);
  await ingestAllData(connectionId, configProperties);
  return { success: true };
};
```

### validateConnection

```javascript
const { fetch } = require('@forge/api');

exports.validateConnectionHandler = async (request) => {
  // request.configProperties — NOT event.payload.config
  const { configProperties } = request;

  // Return { success: false, message } to reject — do NOT throw an Error.
  // Return { success: true } to accept.
  const response = await fetch(`${configProperties['apiUrl']}/health`);
  if (!response.ok) {
    return { success: false, message: 'Invalid API credentials. Please check your settings.' };
  }
  return { success: true, message: 'Connection validated successfully.' };
};
```

### refreshIngestion...

© atlassian · Apache-2.0 · atlassian/forge-skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
atlassian-mcp-server reason-machines Скилл подключает агента к Jira, Confluence и Compass через удалённый MCP-сервер Atlassian. Он пригодится для поиска и изменения данных из IDE. CX Codex +1 186установок jira-integration affaan-m Скилл jira-integration для Claude Code получает и разбирает задачи Jira, меняет их статус и добавляет комментарии. Запускается при работе с требованиями, критериями приёмки и обновлениями задач. CX Codex +1 6 800установок atlassian-mcp https://github.com/Jeffallan Скилл atlassian-mcp для работы с Jira и Confluence через MCP-серверы: запросы на JQL и CQL, создание тикетов, спринты, поиск страниц. CX Codex +1 4 800установок triage-issue atlassian Скилл triage-issue помогает разобрать баг-репорт или текст ошибки: ищет похожие тикеты в Jira, предлагает закомментировать существующий или завести новый. CX Codex +1 1 200установок atlassian-templates Alireza Rezvani Скилл atlassian-templates для Claude Code, который создаёт и правит шаблоны Jira и Confluence. Берёт на себя структуру страниц, макросы и стандартные блоки, чтобы контент в команде выглядел одинаково. CX Codex +1 680установок search-company-knowledge atlassian Скилл search-company-knowledge ищет информацию о процессах и системах одновременно в Confluence и Jira. Скилл пригодится, когда агенту нужно собрать факты из документации и тикетов со ссылками на источники. CX Codex +1 505установок

Из того же набора8

forge-app-builder Скилл forge-app-builder для Claude Code и Codex проектирует, создаёт и расширяет приложения Atlassian Forge для Jira и Confluence. Включается при работе с манифестом, интерфейсом UI Kit, Custom UI или бэкенд-логикой. CX Codex +1 552установок forge-app-review Скилл forge-app-review для Claude Code проводит аудит приложений Atlassian Forge перед релизом. Запускается по запросам на ревью манифеста, проверку готовности к деплою или общее качество кода. CX Codex +1 542установок forge-debugger Скилл forge-debugger для Claude Code, который ищет и исправляет ошибки в приложениях Atlassian Forge. Запускается при сбоях деплоя, пустом интерфейсе, ошибках резолвера и проблемах с правами. CX Codex +1 533установок forge-security-review Скилл forge-security-review для Claude Code проверяет безопасность приложений Atlassian Forge по коду и Forge-правилам. Запускается по запросу аудита, проверки авторизации или анализа изоляции арендаторов. CX Codex +1 442установок forge-cost-optimizer Скилл forge-cost-optimizer для Claude Code анализирует расходы приложений Atlassian Forge. Находит лишние вызовы функций, запросы к API, записи в хранилище и частые триггеры. CX Codex +1 418установок forge-onboarding Скилл forge-onboarding для Claude Code и Codex пошагово проводит через создание и деплой агента Forge Guru. Запускается при первом знакомстве с Atlassian Forge или Rovo. CX Codex +1 173установок forge-skills С набором скиллов и MCP-конфигурацией под Atlassian Forge. Скаффолдит приложения, проверяет их перед деплоем, чинит прод и держит агента в курсе API Forge. ★ 33звёзд репо

Ещё в каталоге

data-structure-protocol k-kolomeitsev Скилл data-structure-protocol создаёт граф зависимостей кодовой базы в папке .dsp/ и помогает агентам ориентироваться в архитектуре модулей, экспортах и причинах связей. CX Codex +1 ★ 67звёзд репо Forge Orchestrator nxtg-ai MCP-сервер Forge Orchestrator координирует одновременную работу Claude Code и других AI-инструментов в одном репозитории. Предотвращает конфликты правок с помощью блокировок файлов и единого графа задач. CX Codex +1 ★ 168звёзд репо Capability Graph Builder daffy0208 Скилл Capability Graph Builder строит поисковый граф возможностей из манифестов инструментов и проверяет связи через Codex. Пригодится при сборке базы знаний для оркестрации агентов. CX Codex +1 130установок floorplan haydenschmitty Скилл floorplan для Claude Code строит интерактивную карту кодовой базы в виде HTML-графа связей. Создаёт схему модулей и маршрутов по коду или чертит архитектуру по PRD. CX Codex +1 ★ 6 008звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой