Skip to main content
Skip table of contents

Workflow Status Sync

Requirements

  • A user with a Jira Admin rights and Project Admin rights is required for

    • retrieving the statuses ids

    • retrieving the workflow transition ids

  • Config requirements

    • status ids and the target transition ids steps (please see demo videos how this is retrieved)

Demo Workflow status sync - One Way

YAML 
# add this new section syncSettings
syncSettings:
  # add workflowStatus section under syncSettings
  workflowStatus:
    enabled: true
    # set the systems unique identifier
    identifierForPropertyKeys: "alpha-server-to-beta-server"
    # set direction to one-way - source to target
    direction: one-way
    mappings:
      workflows:
        # ex. we'll add basicworkflow to handle workflows of task
        basicworkflow:
          issueTypes: #issue types that will use this workflow mapping
            - task
          # a workflow should have sourceToTarget and or targetToSource
          # sourceToTarget
          #  - used in one-way sync direction
          #  - used in two-way sync direction
          sourceToTarget:
            # ex. when source ticket is moved to work in progress (10304) target will try to transition to start in progress (11)
            10304: # status id - work in progress
              default: 11 # transition id - start in progress
            10001: # status id - done
              default: 61 # transition id - mark as done
            4: # status id - reopened
              default: 71 # transition id - reopen issue
            10301: # status id - pending
              default: 41 # transition id - pending

Demo Workflow status sync - Two Way

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # set the systems unique identifier
    identifierForPropertyKeys: "alpha-server-to-beta-server"
    # set direction to two-way
    direction: two-way
    # add conflict resolution
    conflictResolution:
      serverPriority:
        enabled: true
        server: source
      latestStatusChangePriority:
        enabled: false
    mappings:
      workflows:
        basicworkflow:
          issueTypes:
            - task
            - sub-task
          sourceToTarget:
            1:
              default: 51
            10301:
              default: 41
            10304:
              default: 11
            4:
              default: 71
            10001:
              default: 61
          # targetToSource
          #  - used in two-way sync direction
          targetToSource:
            # ex. when target ticket is moved to work in progress (10304) source will try to transition to start in progress (11)
            10304: # work in progress
              default: 11 # start progress
            1:
              default: 51
            10301:
              default: 41
            4:
              default: 71
            10001:
              default: 61

Workflow status sync full configuration

Enable sync workflow status

YAML 
serverfrom:
  ...
serverto:
  ...
pushJQL:
  ...
# add workflowStatus under syncSettings
syncSettings:
  workflowStatus:
    enabled: true

Add workflow status sync direction (required)

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # direction - one-way or two-way workflow status sync.
    # one-way - source to target
    # two-way - source to target and target to source
    direction: two-way

Add ignore unmapped transitions (optional)

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # Default false. Setting to true will ignore transitions that are not mapped.
    ignoreUnmappedTransitions: true

Adding workflow identifier for workflow transitions (optional)

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # identifierForPropertyKeys - identifier for issue properties
    identifierForPropertyKeys: "alpha-server-to-beta-server"

This identifierForPropertyKeys adds a unique identifier to changes made by your sync, helping track which system made which updates to a ticket. Think of it as a "label" that says "this change came from this sync."

Though this configuration is currently optional, we strongly recommend adding it to new configurations as a best practice.

Add conflict resolution (required for two-way sync)

There are 2 options to solve a conflict. Conflict is when both source and target issue's status was updated by a user before the sync runs.

  • serverPriority

    • this setting will let jira sync decide which server/issue takes priority on the two-way workflow status sync.

    • this is more used if there's a server that should be the source of truth.

  • latestStatusChangePriority

    • this setting will let jira sync choose the server/issue which has the most recent status change

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    direction: two-way
    # conflictResolution - setting for two way status sync to determine how to handle conflict.
    # conflict means both source and target was changed before sync.
    # choose only one. serverPriority or latestStatusChangePriority
    conflictResolution:
      # serverPriority - this setting will let jira sync decide which server takes priority if there's a conflict
      serverPriority:
        enabled: true
        # server choices (source or target)
        server: source
      # latestStatusChangePriority - this setting will use the issue with the most latest status change if there's a conflict
      latestStatusChangePriority:
        enabled: false

Add a workflow mapping (required)

  • We can add a new workflow mapping and the issue types that uses this workflow

    • Workflow name can be anything that represents your workflow

      • IssueTypes

        • issues types listed here will try to use this workflow mapping

        • e.g. if the issue to be synced is of type 'task' then this will be the workflow mapping that will be used.

      • SourceToTarget

        • mapping for source issue status to target issue transition

        • required for one-way and two-way sync direction

      • TargetToSource

        • mapping for target issue status to source issue transition

        • required for two-way sync direction

Configure a one-way workflow status sync

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # set direction to one-way
    direction: one-way
    # start add mappings on this section
    mappings:
      workflows:
        # ex. we'll add basicworkflow to handle workflows of task and sub-task
        basicworkflow:
          # issueTypes - issue types listed here will try to use this workflow mapping
          # the list is not case-sensitive but should match the issue type names
          issueTypes:
            - task
            - sub-task
          # a workflow should have sourceToTarget and or targetToSource
          # sourceToTarget
          #  - used in one-way sync direction
          #  - used in two-way sync direction
          sourceToTarget:
            # ex. when source ticket is moved to open (1) target will try to transition to back to open (51)
            1: # status id - open
              default: 51 # transition id - back to open
            10301:
              default: 41
            10304:
              default: 11
            4:
              default: 71
            10001:
              default: 61

Configure a two-way workflow status sync

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # set direction to two-way
    direction: two-way
    # add conflict resolution
    conflictResolution:
      serverPriority:
        enabled: true
        server: source
      latestStatusChangePriority:
        enabled: false
    mappings:
      workflows:
        basicworkflow:
          issueTypes:
            - task
            - sub-task
          sourceToTarget:
            1:
              default: 51
            10301:
              default: 41
            10304:
              default: 11
            4:
              default: 71
            10001:
              default: 61
          # targetToSource
          #  - used in two-way sync direction
          targetToSource:
            # ex. when target ticket is moved to work in progress (10304) source will try to transition to start in progress (11)
            10304: # work in progress
              default: 11 # start progress
            1:
              default: 51
            10301:
              default: 41
            4:
              default: 71
            10001:
              default: 61

Configure workflow sync with multiple workflow mapping

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    direction: two-way
    conflictResolution:
      serverPriority:
        enabled: true
        server: source
      latestStatusChangePriority:
        enabled: false
    mappings:
      # workflows - we can add multiple workflow mapping under workflows. we can name it anything we want.
      workflows:
        # ex. we'll add basicworkflow to handle workflows of task and sub-task
        basicworkflow:
          issueTypes:
            - task
            - sub-task
          sourceToTarget:
            1:
              default: 51
            10301:
              default: 41
          targetToSource:
            10304:
              default: 11
            1:
              default: 51
        # ex. we'll add commonworkflow to handle workflow of service request
        commonworkflow:
          issueTypes:
            - service request
          sourceToTarget:
            10109:
              default: 851 # waiting for customer - respond to customer
            10301:
              default: 871 # pending - pending
          targetToSource:
            10109:
              default: 851 # waiting for customer - respond to customer
            10301:
              default: 871 # pending - pending

Configure a mapping with Status that has multiple possible transition steps

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    direction: two-way
    conflictResolution:
      serverPriority:
        enabled: true
        server: source
      latestStatusChangePriority:
        enabled: false
    mappings:
      workflows:
        basicworkflow:
          issueTypes:
            - task
            - sub-task
          sourceToTarget:
            # ex. when source ticket is moved to in progress (3) target will try to transition to in progress (891) or back to in progress if the target status is in resolved (5)
            3:
              # transitions - used when there are multiple possible transition steps that can go to a status
              transitions:
                5: 931 # if target status is resolved (5) , use this transition - back to in progress
                default: 891 # in progress - in progress
            10109:
              default: 851
            10301:
              default: 871
            5:
              default: 761
            10138:
              default: 901
            10302:
              default: 911

Configure a mapping that ignores a specific status

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    direction: two-way
    conflictResolution:
      serverPriority:
        enabled: true
        server: source
      latestStatusChangePriority:
        enabled: false
    mappings:
      workflows:
        commonworkflow:
          issueTypes:
            - service request
          sourceToTarget:
            3:
              transitions:
                5: 931
                default: 891
            10109:
              default: 851
            10301:
              default: 871
            5:
              default: 761
            10138:
              default: 901
            10302:
              default: 911
            # ex. when source ticket is moved to closed (6) target will ignore this and will not transition
            6: # closed
              default: _ignore_
            10104:
              default: 901

Alternative to using _ignore_ is to set syncSettings.workflowStatus.ignoreUnmappedTransitions to true.

This will ignore all transitions that are not mapped.

Multi-Server Sync Setup

A multi-sync scenario occurs when you need to connect three or more systems in a chain, where a middle system acts as a bridge between others. For example: Alpha Server ↔ Beta Server ↔ Gamma Server.

In this setup, Beta Server is the "relay" that needs to:

  • Receive changes from Alpha Server and forward them to Gamma Server

  • Receive changes from Gamma Server and forward them to Alpha Server

The challenge is that each sync uses a functional user to make updates. Normally, changes by functional users are ignored. However, in a chain, you need one sync to detect and process the functional user changes made by another sync.

This is where we configure the following multi-sync setup.

Setting the workflow sync to include changes from configured user

Pre-requisites:

  • Both of these configurations must be set for multi-sync scenarios to work properly:

    • identifierForPropertyKeys - Uniquely identifies which sync made a change.

    • includeConfiguredUserChangesOn - Allows changes made by your functional user to be processed.

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    # identifierForPropertyKeys - Pre-requisite configuration
    identifierForPropertyKeys: "alpha-to-relay"
    # includeConfiguredUserChangesOn - optional setting to include status changes made by the configured sync user
    # Options:
    #   - "source": Include changes made by the configured user on the source server.
    #   - "target": Include changes made by the configured user on the target server.
    #   - "both": Include changes made by the configured user on both servers
    # When enabled, status changes made by the configured user will be synchronized
    includeConfiguredUserChangesOn: "both"

Example of Multi-Sync Server Configurations with a three server sync chain

Alpha Server to Relay (Beta) Server

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    identifierForPropertyKeys: "alpha-to-relay"
    includeConfiguredUserChangesOn: "target"

  • identifierForPropertyKeys: "alpha-to-relay": Uniquely identifies changes made by this sync

  • includeConfiguredUserChangesOn: "target": Beta is the target in this sync relationship, and we need to check for functional-user changes on Beta that came from the Beta↔Gamma sync

Relay (Beta) to Gamma Server

YAML 
syncSettings:
  workflowStatus:
    enabled: true
    identifierForPropertyKeys: "relay-to-gamma"
    includeConfiguredUserChangesOn: "source"

  • identifierForPropertyKeys: "replay-to-gamma": Uniquely identifies changes made by this sync

  • includeConfiguredUserChangesOn: "source": Beta is the source in this sync relationship, and we need to check for functional-user changes on Beta that came from the Alpha↔Beta sync.

Important Notes

When to use source

Use when the server receiving changes from other syncs is the source in your sync configuration. Beta is the source in Beta↔Gamma, so we use source to check for functional-user changes on Beta.

When to use target

Use when the server receiving changes from other syncs is the target in your sync configuration. Beta is the target in Alpha↔Beta, so we use target to check for functional-user changes on Beta.

When to use both

Use when a server is in the middle of a longer chain and needs to receive changes from syncs on both sides.

Example: Alpha ↔ Beta ↔ Gamma ↔ Delta

In this four-server chain, the configuration for Beta ↔︎ Gamma Server would need includeConfiguredUserChangesOn: "both".

Sync Workflow Status one-way (deprecated)

This is the previous configuration for the sync workflow status. This is still working for one-way workflow status sync. This has now been deprecated and is only maintained for compatibility with older configurations.

YAML 
serverfrom:
  ...
  syncWorkflowStatus: true
   workflowStatusFieldMapping:
     mapping:
       # status_id : transition: id
       10000: 11
       # in progress - escalate
       3: 21
       # done - resolve
       10001: 31

Ignoring a status one-way - prevents transitioning (deprecated)

YAML 
syncWorkflowStatus: true
  workflowStatusFieldMapping:
    mapping:
      # status_id : transition: id
      # ignore to do status
      10000: _ignore_
      # in progress - escalate
      3: 921
      # done - resolve
      10001: 761

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close