Sync Rule Reference | mgm Marketplace App Documentation

📘 What you will learn here

On this page you will learn what every sync rule option means: its editor label, its JSON key in export files, allowed values, default and notes.

It's for Jira administrators and for tools that read or generate sync rule export files. For a guided walkthrough, see Create a Sync Rule.

General

Option	JSON key	Values	Default	Required	Notes
Rule name	`name`	Text	Empty	Yes	Configuration tab. On duplicate or import, a name already in use gets a suffix: `Name (2)`, `Name (3)`, …
Enabled	`enabled`	On, Off	On	Yes	Switch at the top of the editor and in the Sync rules list. A rule must be off before you can delete it. Duplicated and imported rules are always off. Not included in export files.

Connectors and scope

Option	JSON key	Values	Default	Required	Notes
Source: Connector	`sourceConnectorRef` (export file)	This Jira site (`CURRENT_JIRA_CLOUD`)	None	Yes	Locked after work items are synced.
Target: Connector	`targetConnectorRef` (export file)	A Jira Cloud connector	None	Yes	Must differ from the source; This Jira site can't be the target. Locked after work items are synced.
Edit source scope: Basic / Advanced JQL	`sourceScope.mode`	`simple` (Basic), `advanced` (Advanced JQL)	`simple`	Yes	Locked after work items are synced.
Spaces	`sourceScope.projectKeys`	List of space keys	Empty (all spaces)	No	Basic mode.
Work types	`sourceScope.issueTypeIds`	List of work type IDs	Empty (all work types)	No	Basic mode. Needs at least one space selected.
Statuses	`sourceScope.statusIds`	List of status IDs	Empty (all statuses)	No	Basic mode. Needs at least one space selected.
JQL	`sourceScope.jql`	JQL query	Empty	Yes in Advanced JQL mode	In Basic mode, Sync Bridge also stores JQL generated from your selection. Switching back to Basic clears it.
Target: Space	`targetScope.projectKey`	A space key on the target site	None	Yes	Where pushes create work items. Locked after work items are synced.

Details: Settings Locked After Work Items Are Synced.

Sync direction

Option	JSON key	Values	Default	Required	Notes
Push (source → target)	`pushEnabled`	`true`, `false`	`true`	Yes	Creates the target work item on first push, then updates it.
Pull (target → source)	`pullEnabled`	`true`, `false`	`false`	Yes	Updates linked work items only; never creates work items on This Jira site.

At least one of Push and Pull must be on. The Sync rules list shows the result as Push only, Pull only or Both directions.

Push triggers

Option	JSON key	Values	Default	Required	Notes
Manual	`triggers.manual`	`true`, `false`	`false`	Yes	Sync button in the Sync Bridge panel.
Jira events	`triggers.listenerEnabled`	`true`, `false`	`false`	Yes	Push when a selected event happens on a work item in scope.
Jira events: event list	`triggers.listenerEvents`	`ISSUE_CREATED` (Work item created), `ISSUE_UPDATED` (Work item updated, any field change), `STATUS_UPDATED` (Status changed), `PRIORITY_UPDATED` (Priority changed), `COMMENT_CREATED` (Comment added), `COMMENT_UPDATED` (Comment edited), `COMMENT_DELETED` (Comment deleted), `ATTACHMENT_CREATED` (Attachment added), `ATTACHMENT_DELETED` (Attachment deleted)	Empty	Yes (may be empty)	Kept when Jira events is turned off.
API	`triggers.apiEnabled`	`true`, `false`	`false`	Yes	Needs API tokens, created after the rule is saved. Tokens aren't duplicated, exported or imported. See API Tokens.

When Push is on, at least one push trigger must be on.

Pull triggers

Option	JSON key	Values	Default	Required	Notes
Manual	`pullTriggers.manual`	`true`, `false`	`false`	Yes	Pull from the Sync Bridge panel on a work item.
Scheduler	`pullTriggers.scheduler.enabled`	`true`, `false`	`true`	Yes	Checks the target for changes to linked work items.
Cron expression	`pullTriggers.scheduler.cronExpression`	6-field cron (second minute hour day-of-month month day-of-week), or empty	Empty (every 5 minutes)	Yes (may be empty)	Presets: Every 5 minutes `0 /5 * * `, Every 15 min `0 /15 * * * `, Hourly `0 0 * * `, Daily at 9:00 `0 0 9 * *`. Times are UTC. Pull runs at most every 5 minutes.

When Pull is on, at least one pull trigger must be on.

Per-work-item sync switch

Option	JSON key	Values	Default	Required	Notes
Per-work-item sync switch, Default for matching work items	`perIssueControl.mode`	`ALWAYS` (switch off), `OPT_OUT` (On by default), `OPT_IN` (Off by default)	`ALWAYS`	No (absent means `ALWAYS`)	Turning the switch on selects On by default.
Who can use the switch	`perIssueControl.grants`	List of: `{"type":"PERMISSION","permission":"ADMINISTER" \| "ADMINISTER_PROJECTS" \| "EDIT_ISSUES"}` (Jira administrators, Project administrators, Anyone who can edit the work item), `{"type":"USER","accountIds":[…]}`, `{"type":"GROUP","groupIds":[…]}`, `{"type":"PROJECT_ROLE","roleIds":[…]}`	Empty	At least one entry when mode isn't `ALWAYS`	Matching any one entry is enough. Each list needs at least one value. See Permissions and Per-Work-Item Sync Control.

Field mappings

Field mapping tab. Each row is one entry in fieldMapping. Details: Field Mapping and Smart Values and Transformations.

Option	JSON key	Values	Notes
Source field / target field	`sourceField`, `targetField`	Jira field ID, for example `summary` or `customfield_10010`	Which side is required depends on direction and transform.
Direction	`direction`	`SOURCE_TO_TARGET`, `TARGET_TO_SOURCE`, `BOTH` (Both directions)	Required.
Transform	`transformType`	`DIRECT` (Direct copy), `VALUE_MAP` (Value map), `SMART_VALUE` (Smart value), `STATIC` (Static value)	Required.
Transform settings	`transformOptions`	`entries` (Value map pairs `{source, target}`), `template` (Smart value), `value` (Static value, text or list)	Value map needs at least one complete pair; Smart value needs a template; Static value needs a value.
Enabled	`enabled`	`true`, `false`	Required.
(row order)	`order`	Integer, 0 or more	Required.

Summary and Work type must be mapped.

Comments, attachments and status

Field mapping tab, under Special contents. Stored under specialContent.

Option	JSON key	Values	Default	Notes
Comments	`comment.enabled`, `comment.direction`	On/Off; `SOURCE_TO_TARGET`, `TARGET_TO_SOURCE`, `BOTH`	Off; `SOURCE_TO_TARGET`	See Comments Sync.
Comments: transform	`comment.transformType`, `comment.transformOptions.template`	`DIRECT` or `SMART_VALUE` (template required)	`DIRECT`
Comments: Visibility, Author filters	`comment.filters.privacy`, `comment.filters.author`	Privacy: `Public`, `Internal`, `All`. Author mode: `ANY`, `ALLOW`, `BLOCK` with `accountIds`	No filters	`ALLOW` and `BLOCK` need at least one person.
Attachments	`attachment.enabled`, `attachment.direction`	On/Off; `SOURCE_TO_TARGET`, `TARGET_TO_SOURCE`, `BOTH`	Off; `SOURCE_TO_TARGET`	See Attachments Sync.
Also sync attachments that already exist; Added in the last (days)	`attachment.backfillExisting`, `attachment.backfillWindowDays`	`true`/`false`; positive whole number	`false`; none	The day window can only be set when existing attachments are synced.
Attachments: File type, File size, Uploader filters	`attachment.filters.fileType`, `.fileSize`, `.uploader`	File type mode `ALLOW`/`BLOCK` with `extensions` (lowercase, no dot); size `largerThanBytes`/`smallerThanBytes`; uploader mode `ANY`/`ALLOW`/`BLOCK` with `accountIds`	No filters	Files over 200 MB are never synced.
Status	`status.enabled`, `status.projectMappings`	On/Off; a list of space mappings, each with work type groups and transition mappings	Off; empty	Each source or target work type can be in only one group per space mapping. See Status Mapping.

Validation summary

Rule name, source connector, target connector and target space are required.
Source and target connectors must be different, and This Jira site can only be the source.
At least one of Push and Pull must be on.
Push on needs at least one push trigger; Pull on needs at least one pull trigger.
A cron expression must be valid or empty.
Advanced JQL mode needs a JQL query.
A per-work-item switch that isn't ALWAYS needs at least one grant.
On a trial license, a site can have up to 3 sync rules.

Export file format

Export files are JSON. Import accepts files up to 5 MB with up to 25 rules. See Duplicate, Import and Export Sync Rules.

Top-level key	Meaning
`kind`	Always `slg-sync-rules`. Files with another value are rejected.
`version`	File format version. The current version is `2`. Import rejects files from a newer version.
`exportedAt`	Export time, ISO 8601.
`connectors`	The connectors the rules refer to: `ref` (connector ID on the exporting site), `label`, `type` (`jira_cloud`) and `baseUrl`. No credentials. This Jira site isn't listed.
`rules`	1 to 25 rules. Each has `name`, `sourceConnectorRef`, `targetConnectorRef`, `sourceScope`, `targetScope`, `pushEnabled`, `pullEnabled`, `triggers`, `pullTriggers`, optional `perIssueControl`, `fieldMapping` and `specialContent` (`comment`, `attachment`, `status`). No other keys are allowed; there is no `enabled` key, because imported rules are always off.

A connector ref of CURRENT_JIRA_CLOUD means This Jira site. Space keys, work type IDs, status IDs, custom field IDs, transition IDs and account IDs are copied as they are, so check them after importing on another site.

Example export file (trimmed)

JSON

{
  "kind": "slg-sync-rules",
  "version": 2,
  "exportedAt": "2026-10-12T08:00:00.000Z",
  "connectors": [
    { "ref": "k3Jd9x", "label": "Customer site", "type": "jira_cloud", "baseUrl": "https://customer.atlassian.net" }
  ],
  "rules": [
    {
      "name": "Support escalations",
      "sourceConnectorRef": "CURRENT_JIRA_CLOUD",
      "targetConnectorRef": "k3Jd9x",
      "sourceScope": { "mode": "simple", "projectKeys": ["SUP"], "issueTypeIds": [], "statusIds": [], "jql": "project IN ('SUP')" },
      "targetScope": { "projectKey": "ESC" },
      "pushEnabled": true,
      "pullEnabled": true,
      "triggers": { "manual": true, "listenerEnabled": true, "listenerEvents": ["ISSUE_CREATED", "ISSUE_UPDATED"], "apiEnabled": false },
      "pullTriggers": { "manual": false, "scheduler": { "enabled": true, "cronExpression": "0 */15 * * * *" } },
      "perIssueControl": { "mode": "ALWAYS", "grants": [] },
      "fieldMapping": [
        { "order": 0, "sourceField": "summary", "targetField": "summary", "transformType": "DIRECT", "transformOptions": {}, "direction": "BOTH", "enabled": true },
        { "order": 1, "sourceField": "issuetype", "targetField": "issuetype", "transformType": "DIRECT", "transformOptions": {}, "direction": "SOURCE_TO_TARGET", "enabled": true }
      ],
      "specialContent": {
        "comment": { "enabled": true, "direction": "BOTH", "transformType": "DIRECT", "transformOptions": {} },
        "attachment": { "enabled": false, "direction": "SOURCE_TO_TARGET", "backfillExisting": false },
        "status": { "enabled": false, "projectMappings": [] }
      }
    }
  ]
}