Jira Push Integration

An extension of the Jira integration, Jira Push allows you to automatically push content from Matrix to Jira. The integration sets up a one-to-one link between the Matrix item and Jira and can update the Jira item if content changes in Matrix.

The integration is intended to be unidirectional, using Matrix as the source of truth. Items created in Jira have a link back to Matrix and are clearly marked as being managed by Matrix.

In addition to simply pushing content, the integration also supports some features that make it easier to track work:

• Epic/Story links: Categories in Matrix are marked as either Epic or Story types. When pushed to Jira, the resulting Jira items as created as Story or Epics and are linked in the same hierarchy.

• Signing gates: The sync process can be controlled by a gate, allowing for sync only when a Matrix item is approved.

• DrawIO content: Embedded DrawIO diagrams in Matrix are pushed to Jira as well, where they can be viewed with the Jira DrawIO integration.

• To Do status reset: If new content is pushed from Matrix to Jira, Jira items can be reset to the To Do state. This option makes sure developers are aware of a potential requirements change.

Workflow

For new items:

• Create items in Matrix

• Establish downlinks between parent (Epic) and child (Story) items

• Sign the Epics when ready for publishing (this can be turned off)

• Push the Matrix items to create or update Epics and Stories in Jira

For updates:

• Modify items in Matrix

• When prompted, allow push or manually push later

User Interface

When a Matrix item in a configured category is then the user will be presented with a confirmation dialog to either sync or skip the item. This dialog does not appear if a sign gate is enabled and the parent epic is not signed.

If the push is skipped it can be manually triggered using the Tools menu:

Pressing the Sync Jira item menu entry will trigger the push process.

The “SJT-7” button in the image above shows the Jira item the Matrix item is pushed to. Clicking on it will open the Jira UI. The same link will be displayed in the Tasks list of the item. The link is automatically maintained by the push process.

The “Unlink from Jira item” menu entry will remove the link and mark the Jira item as deprecated.

Setup

Jira Push requires the Jira Server extension to be used. This extension works with both Jira Cloud (hosted by Atlassian) and self-hosted. Unlike the Jira Cloud extension it requires the entry of a user and token (password).

Configure the project

Jira Push needs some additional information on the Matrix item to work:

One2One mapping

This is used to show the linked issue in Matrix:

• Create a "worflow" field with the name JiraID on each issue type

• Configure the Jira Server plugin with the settings for One2One by adding this section to the advanced settings

"one2OneMapping":{
  "projectId":"JST",
  "taskTypeId":"Epic",
  "statusOverwrites":[]
}

Gate

The gate/signoff field controls if an Epic and its stories are synced. For each Category that is considered an Epic, make sure it has a gate field.

• Create a "gateControl" field and assign the users that should be allowed to sync

  CODE

  "lines":[{
    "id":"g1",
    "users":["bob"],
    "hint":"Approve publishing to Jira",
    "hintDone":"Approved for Jira",
    "hintRejected":"Not approved for Jira, review"
  }]

Project Configuration

As a final step, configure all the Jira Push settings by going into the Extension settings of the project and selecting Plugin Settings Jira Push. You will see the screen above.