Create a Sync Rule | mgm Marketplace App Documentation

📘 What you will learn here

On this page you will learn how Jira administrators create a sync rule from start to finish, from source and target, sync direction and triggers to field mapping, with every setting in the order the editor shows it.

Before you start

Create a connector for the Jira Cloud site you want to sync with. Without one, the target connector list is empty and shows No connectors yet. Create a connector.
Know which spaces, work types and statuses on This Jira site you want to sync, and which space on the other site should receive them.

Creating a rule has two steps: Configuration, then Field mapping. Field mapping unlocks after you save the configuration.

Step 1: Configuration

Go to Sync rules and select Create sync rule. The New sync rule page opens, marked Draft.
In Rule name, enter a name for the rule.

Source

In the Source panel, under Connector, select This Jira site. This is the only source you can choose.
Under Scope, select Edit source scope. Choose how to filter work items:
- Basic: select Spaces, Work types and Statuses. Work types and statuses become available after you select at least one space. Anything left empty means “all”. With nothing selected, the scope reads All work items.
- Advanced JQL: enter a JQL query, for example project IN ('PROJ') AND issuetype = Bug. When you switch from Basic, your current selection is turned into JQL for you.
Select Done.

Switching from Advanced JQL back to Basic clears your JQL and any selected spaces, work types and statuses. JQL can't be converted back to basic filters.

Target

In the Target panel, under Connector, select the connector for the other Jira Cloud site.
Under Space, select Select space, choose the target space, and select Done. The target space is required: it's where Sync Bridge creates the linked work items.

Sync direction

Under Sync direction, turn on one or both directions. A label next to the heading summarizes your choice.

Setting	What it does	Notes
Push (source → target)	Sends changes from This Jira site to the target. The first push for a work item creates a work item in the target space and links the two. Later pushes update it.	On by default.
Pull (target → source)	Brings changes from the linked target work items back to This Jira site.	Off by default. Pull only updates work items that are already linked; it doesn't create new work items on This Jira site.

At least one direction must be on.

Push triggers

When Push is on, choose what starts a push. Turn on at least one.

Trigger	What it does	Notes
Manual	Run on demand with a Sync button.	The button is in the Sync Bridge panel on a work item.
Jira events	Sync automatically when something changes in the source.	Select the events: Work item created, Work item updated, Status changed, Priority changed, Comment added, Comment edited, Comment deleted, Attachment added, Attachment deleted. Work item updated fires on any field change, including status and priority.
API	Start a sync from Jira automation or another service.	Shows the Endpoint and View example request. You add API tokens after the rule is saved. See API Tokens and Sync Trigger API.

Pull triggers

When Pull is on, choose what starts a pull. Turn on at least one.

Trigger	What it does	Notes
Manual	Pull on demand from the Sync Bridge panel on a work item.	Off by default.
Scheduler	Check the target for changes on a schedule.	On by default. Pick a preset (Every 5 minutes, Every 15 min, Hourly, Daily at 9:00) or enter a Cron expression.

The cron expression has 6 fields: second, minute, hour, day-of-month, month, day-of-week. For example, 0 */15 * * * * runs every 15 minutes. Leave it blank to check every 5 minutes. Below the field, the editor describes the schedule and shows the next three runs in UTC.

Pull runs at most every 5 minutes. If your schedule is more frequent, the editor warns you and the pull still runs every 5 minutes.

Per-work-item sync switch (optional)

Turn on Per-work-item sync switch to let people turn this rule on or off for individual work items. Choose a default (On by default or Off by default) and who can use the switch. It applies to both push and pull. See Permissions and Per-Work-Item Sync Control.

Save the configuration

Select Save and continue. Sync Bridge creates the rule and opens the Field mapping tab.

A new rule is saved turned on. Its triggers can start syncing as soon as you save it. If you aren't ready, turn off Enabled at the top of the rule, then select Save changes, until you've finished field mapping.

Step 2: Field mapping

Under Field mappings, select Add field mapping for each field you want to sync. For each row, choose the source field, the target field, the direction and a transform (Direct copy, Value map, Smart value or Static value).
Map Summary and Work type. Both are required, because Sync Bridge needs them to create work items in the target space.
Under Special contents, turn on and set up Comments, Attachments and Status if you need them.
Select Save changes.

For details, see Field Mapping, Smart Values and Transformations, Status Mapping, Comments Sync and Attachments Sync.

Turn the rule on or off

Use the Enabled switch at the top of the rule (then Save changes), or the Enabled switch in the rule's row on the Sync rules page.

After the rule syncs its first work item, you can no longer change its connectors or scope. See Settings Locked After Work Items Are Synced.

Messages you might see

Message	What to do
Enter a rule name.	Enter a name in Rule name.
Select a source connector. / Select a target connector.	Select a connector in the Source or Target panel.
Select a target space.	Select Select space in the Target panel and choose a space.
Enter a JQL query, or switch to basic.	Your source scope is set to Advanced JQL with an empty query.
Turn on push, pull or both.	Turn on at least one direction.
Turn on at least one push trigger: manual, Jira events or API.	Push is on but has no trigger.
Turn on at least one pull trigger: manual or schedule.	Pull is on but has no trigger.
Enter a valid cron expression, for example 0 /15 * * *.	Fix the cron expression or leave it blank.
Map these required Jira fields before saving: Summary, Work type.	Add field mappings for the listed fields.
Your trial allows up to 3 sync rules. Upgrade to add more.	Delete a rule you don't need, or upgrade your license.