When you provide a Forge Teamwork Graph connector and a customer sets up your connector, Atlassian ingests connected third-party data into Teamwork Graph on behalf of the customer.

For a step-by-step tutorial on building a connector, see Build a Teamwork Graph connector.

Declare capabilities

Add an optional capabilities block to your connector module in manifest.yml. These values are displayed to customer admins on the configuration screen before they enable your connector.

1
2
modules:
  graph:connector:
    - key: my-connector
      name: My Connector
      capabilities:
        replicatesPermissions: true
        syncFidelity: mirror
        supportsIncrementalSync: true
      icons:
        light: resource:icon-light
        dark: resource:icon-dark
      objectTypes:
        - atlassian:document
      datasource:
        # ... your datasource configuration

Properties

Property	Type	Allowed values	Default (if omitted)	Description
`replicatesPermissions`	boolean	`true`, `false`	omitted	Whether the connector mirrors source-system access controls into Teamwork Graph. If `false` or omitted, all ingested data is visible to every user in the Atlassian workspace.
`syncFidelity`	enum	`append`, `upsert`, `mirror`	omitted	`append` = new objects only. `upsert` = new objects and updates to existing objects. `mirror` = new objects, updates, and deletes so Teamwork Graph always reflects current source state. `mirror` is recommended.
`supportsIncrementalSync`	boolean	`true`, `false`	omitted	Whether the connector supports delta sync (only changes since the last run). If `false` or omitted, each sync is a full re-ingestion.

The entire capabilities block is optional. If omitted, the admin configuration screen displays "Capabilities not declared by developer," which may reduce customer confidence. Only the fields listed above are accepted.

For the full manifest reference for this module, see Teamwork Graph connector.

Maintain connector documentation

Your connector must be accompanied by developer documentation covering all of the following:

Data scope — the object types, fields, and source systems your connector ingests.
Permissions handling — whether you replicate source permissions or apply workspace-wide access; state the implications clearly.
Sync behavior — sync cadence, whether incremental sync is supported, and how updates and deletions propagate.
Data deletion — what happens when data is deleted at the source. If deletions are not synced, explicitly state that removing stale data requires disconnecting the connector.
Customer controls — admin settings available for scoping data, managing permissions, or pausing sync.

Link your documentation from your Marketplace listing and keep it current as your connector evolves. This documentation is referenced in the admin consent screen.

Data policies and compliance

Your connector must comply with Teamwork Graph data policies. Do not ingest data types outside the supported object type set. For the full list of restrictions and compliance requirements, see Limitations and considerations.

Data deletion responsibilities

Approach	Behavior	Developer requirement
Mirror (recommended)	Sync deletions from the source so Teamwork Graph always reflects current source state.	Implement delete propagation. No additional documentation required beyond standard sync docs.
Disconnect-only	Deletions are not synced. All ingested data persists in Teamwork Graph until the admin disconnects the connector.	Document this limitation prominently in your connector docs and Marketplace listing. State that admins must disconnect to remove stale data.

If your connector does not sync deletions, you must clearly state this in your developer documentation. Customers with strict data-retention policies may not enable connectors that lack deletion support.

When an admin disconnects a connector instance, Atlassian automatically removes all data ingested by that connection from Teamwork Graph. Your onConnectionChange handler with action DELETED is the signal to stop ingestion and clean up any app-side resources (for example, stopping sync jobs or removing webhooks). You do not need to call any deletion APIs yourself on disconnect.