- Scenario A: Project-to-project mirror
- Scenario B: Support → Dev escalation with sanitization
- Scenario C: Bi-directional support↔dev sync
- What to do next
This page walks through three typical configurations. Each one starts from a real problem, lists the editor settings, and points to caveats. Setting names and values match the sync editor reference. Use them as starting points - tighten or loosen policies once you have green runs.
Scenario A: Project-to-project mirror
Goal: Keep two Software projects in lockstep. New issues in one appear in the other; updates flow both ways. Use this for cross-team coordination or migration cutover.
Setup
| Section | Setting | Value |
|---|---|---|
| Basics | Project A | TEAM-A (Software) |
| Basics | Project B | TEAM-B (Software) |
| Basics | JQL filter A / B | empty (sync everything) |
| Fields | Rules | Summary, Description, Priority, Labels, Assignee - direction both, conflict strategy last_write_wins |
| Fields | When target field is missing | skip |
| Fields | Attempt type coercion | off |
| Issue types | Auto-map by name | accept all rows |
| Issue types | When source type is unmapped | Fail and route to dead-letter |
| Issue types | Sync Epics as the mapped target type | off |
| Status | Mapping | direct one-to-one in both directions (workflows are identical) |
| Status | When status is unmapped | fail |
| Comments | Direction | both |
| Comments | Author | original (falls back to the bot, then the app) |
| Triggers | Run on schedule | on, interval fiveMinute |
| Triggers | Trigger on Jira events | on - Issue created, Issue updated, Comment added |
| Deletion | Policy | Detach (default) |
Why these choices
failon unmapped issue types and statuses: identical workflows mean any unmapped item is a real config drift, not a routine gap.- Detach on deletion: a deleted issue on one side never deletes its counterpart. Recovery is easier than re-creation.
last_write_winson two-way fields: the default strategy ismanual_review, which also applies the first time a pair is compared - every differing value would land in Sync conflicts. Picklast_write_wins(orsource_of_truthwith a side) for fields that should simply follow the latest edit.
Caveats
- Two-way sync on a custom select field with different option sets needs value mappings. The Field schema diff flags unmapped options, and Auto-fill mapping by name fills the ones whose names match.
- Changes the app makes itself do not trigger new event runs, and copied comments are marked so they are never copied back. A loop can still come from your own automation that re-comments on update - exclude the sync’s identity in that automation.
Scenario B: Support → Dev escalation with sanitization
Goal: Customer-reported requests on a JSM service desk escalate to a Software dev project once flagged. Customer data is sanitized; the dev project only sees the technical content. The service project is Project B, as the editor expects for a pair with a service project.
Setup
| Section | Setting | Value |
|---|---|---|
| Basics | Project A | DEV (Software) |
| Basics | Project B | SUP (Service Management) |
| Basics | JQL filter A | empty (everything from DEV that has a counterpart) |
| Basics | JQL filter B | labels = "escalate" |
| Fields | Rules | Summary, Description, Priority, Labels - direction b_to_a, strategy source_of_truth = b |
| Fields | When target field is missing | skip |
| Issue types | B → A mapping | Incident → Bug, Service Request → Task |
| Issue types | When source type is unmapped | Use a default target type (default type on project A: Task) |
| Status | A → B mapping | DEV In Progress → SUP In Progress, DEV Done → SUP Resolved (with resolution Done) |
| Status | B → A mapping | SUP Waiting for support → DEV To Do |
| Comments | Direction | b_to_a (customer conversation to dev) |
| Comments | Author | bot (no customer identities on DEV) |
| JSM | Comment visibility | Internal (default) |
| JSM | Customer policy | Bot (use bot accountId) |
| JSM | Sanitization | Mask emails, Mask phone numbers, Mask URLs, Replace @mentions with @bot on; Replace reporter bot |
| JSM | Custom regex rules | one rule: pattern \b[A-Z]{2}-\d{6,10}\b, replacement [internal-id], scope All (mask internal vendor IDs) |
| JSM | Sync organizations / participants / approvers | off |
| Triggers | Trigger on Jira events | Issue updated (with JQL filter B, only escalated requests take part) |
| Deletion | Policy | Detach (default) |
Why these choices
- Direction-asymmetric: customer content is privileged. One-way
b_to_afor fields prevents accidental leakage the other way; only status flows back to SUP to keep support informed. - Customer policy Bot: requests created on SUP from DEV issues get the bot as reporter, never a developer’s or another customer’s identity.
- Internal comment visibility: anything written into SUP stays agent-only unless you change the mode.
- Custom rule for internal IDs: vendor-specific patterns the built-in options do not catch. See custom sanitization rules - patterns at risk of catastrophic backtracking are rejected on save.
Caveats
- The label
escalatemust be applied by a workflow rule or by an agent action, not the customer - customers cannot set labels via the portal. - If you later want comments flowing to the portal, switch Comment visibility and re-check the sanitization options: the editor shows a Portal safety check warning while comments are public and email or phone masking is off.
- Approvers are never answered by the sync, only audited. If dev needs to see “this needs CTO approval”, surface it as a separate field, not via the approval.
Scenario C: Bi-directional support↔dev sync
Goal: A tight loop between JSM and Software where developers comment in their tracker and customers see updates on their requests. Heavier setup but valuable when support and engineering are on the same team.
Setup
| Section | Setting | Value |
|---|---|---|
| Basics | Project A | DEV (Software) |
| Basics | Project B | SUP (Service Management) |
| Basics | JQL filter A | "Linked SUP Ticket" is not EMPTY (custom field linking back) |
| Basics | JQL filter B | issuetype = "Linked to Engineering" |
| Fields | Rules | Summary, Description, Priority - direction both, strategy manual_review (both sides are edited by people) |
| Fields | When target field is missing | fail (strict) |
| Issue types | Mapping | explicit rows in both tables (no auto-map) |
| Issue types | When source type is unmapped | Fail and route to dead-letter |
| Status | Mapping | both directions, vetted in the Workflow diff panel |
| Comments | Direction | both |
| Comments | Author | original (falls back to the bot, then the app) |
| JSM | Comment visibility | Preserve source - internal notes stay internal, public replies stay public |
| JSM | Customer policy | Original reporter (when possible) |
| JSM | Sanitization | off (trusted internal channel) |
| JSM | Sync participants / organizations | on |
| JSM | Sync approvers | on (read-only: differences are audited) |
| Triggers | Trigger on Jira events | Issue created, Issue updated, Comment added |
| Triggers | Run on schedule | on, interval hour (catch up after missed events) |
| Deletion | Policy | Detach (default) |
Why these choices
failon missing field / unmapped issue type: strict policy because both sides are in production and silent skips would let drift accumulate. Failed issues show up under Failed items and can be retried after the fix.- Preserve source for comments: keeps the customer-facing conversation clean while letting devs and agents see each other’s work.
- Approvers read-only: approvals stay anchored to the JSM workflow. The sync never approves or declines.
manual_reviewon two-way fields: concurrent edits on both sides land in Sync conflicts instead of overwriting each other.
Caveats
- Bi-directional status with two different workflows is the most fragile area. Spend extra time on the Workflow diff before going live, and remember a rejected transition is recorded under Workflow transition.
manual_reviewalso applies the first time a pair is compared, so the first backfill can fill Sync conflicts. Resolve them with Bulk apply A / Bulk apply B.- The pre-flight check is repeated automatically when older than 30 days, and the Notifications bell in the Admin Panel header lists paused syncs, failed runs, items stuck over 30 days and pending conflicts - check it weekly.
What to do next
- Pick the scenario closest to your case, copy the table, and adjust project keys.
- Open Admin Panel → Recipes → Two-project sync → New sync and configure it using the Quick start.
- Always click Run pre-flight check before enabling, and watch the first run in View activity.
When something does not look right, see Troubleshooting for the error categories and recovery options.
