Collaborate With Jira Cloud

Connect ReqView with Atlassian Jira Cloud to benefit from an integrated solution for application/product lifecycle management (ALM/PLM).

ReqView integration with Jira allows you to export requirements from ReqView documents to a Jira Cloud project. The integration supports Jira Software Cloud service hosting Scrum or Kanban team-managed (next-gen) and company-managed (classic) projects.

Workflow With Jira

Manage the development of your HW/SW product using the following workflow:

1. Capture and manage requirements, risks, and tests in ReqView
2. Export requirements from ReqView into a Jira Cloud project
3. Trace requirements between ReqView and Jira issues in both directions
4. Manage product development in Jira Cloud using an agile development process
5. Synchronize back the implementation status from Jira issues into ReqView

Set up Jira Integration

ReqView Connector for Jira

To make the integration between ReqView and Jira easier, we have created a new Atlassian Marketplace application ReqView Requirements Management Connector for Jira:

We recommend installing this application because it enables some features (such as tracing ReqView requirements from Jira issues) and improves the performance of requirements synchronization between ReqView and Jira. On the other hand, you do not need this application for testing the basic functionality of the integration.

To install this application:

1. Log into your Jira Cloud instance (as an administrator).
2. Click Apps and choose Find new apps in the top bar.
3. Search for "reqview" in the Atlassian Marketplace and click ReqView Requirements Management Connector for Jira result.
4. Click Get app in the app details screen.

Document Configuration

Because ReqView application has the integration with Jira disabled by default, click Edit, select Preferences, and tick Integrate with Jira to enable the integration.

To enable the integration with Jira for the current document, click File, select Jira and then Configure Synchronization:

In the Configure Synchronization With Jira dialog, configure the integration in JSON format using the following properties:

• jiraSiteUrl — URL of your Jira site. Open your Jira project in a web browser and copy the URL with the domain name only (e.g. https://mycompany.atlassian.net).
• jiraProjectKey — key of your Jira project. Open the list of all projects in Jira and copy the Key value of a selected project (e.g. MYPROJECT).
• jiraIssueType — type of exported Jira issues.
  • reqviewAttribute — ReqView custom attribute used for mapping to Jira issue types (e.g., "type" corresponding to an enumeration attribute).
  • mapping — JSON object describing how Jira issue types are mapped to ReqView documents objects.
    • key — Jira issue type (e.g., "Epic", "Story", or "Task").
    • value — the value of the ReqView custom attribute specified in reqviewAttribute property (e.g., "EPIC", "STORY", or "TASK").
• jiraFields — optional JSON object describing how the integration sets Jira issue fields, see Export Documents to Jira.
  • key — Jira issue field, only "Description" and "Summary" is supported now.
  • value — ReqView custom attribute or template column (e.g., "text" to set the Jira issue field from the ReqView system attribute storing the requirements description).
• reqviewAttributes — optional JSON object describing how the integration sets ReqView custom attributes from Jira issue fields. See Fetch Jira Issue Fields.
  • key — ReqView custom attribute (e.g. "jiraStatus" corresponding to a string attribute).
  • value — Jira issue field (e.g., "Status") or "$URL" for the URL link.

Notes:

• Jira allows only parent-child relationships between certain issue types (e.g., a Story can be created in an Epic; however, a Story cannot be created in a Task).
• Jira issue fields and their values should be specified in English.
• Jira Subtasks cannot be exported.

Example: Open the Example Project and configure the Jira integration to export the NEEDS document as follows:

{
  "action": "export",
  "jiraSiteUrl": "https://mycompany.atlassian.net",
  "jiraProjectKey": "MYPROJECT",
  "jiraIssueType": {
    "mapping": {
      "Epic": "EPIC",
      "Story": "STORY"
    },
    "reqviewAttribute": "type"
  }
}

ReqView will export epics and user stories from the NEEDS document into Jira project MYPROJECT hosted at Jira Cloud site https://mycompany.atlassian.net.

It will set the type of Jira issues according to the value of ReqView enumeration attribute type as follows:

• If type attribute equals to "EPIC" then the integration creates an Epic issue in Jira.
• If type attribute equals to "STORY" then the integration creates a Story issue in Jira.
• Else, the document object is not exported.

Jira Credentials

For security reasons, ReqView uses Jira API tokens to access Jira projects (not passwords). See Manage API tokens for your Atlassian account documentation page for more information on creating and managing Jira API tokens.

You can enter your Jira login email and API token in the Jira Credentials dialog during the first synchronization with the given Jira Cloud site:

Tick Remember checkbox to save the Jira credentials securely. To erase saved Jira credentials any time, click File select Jira, and then Clear Credentials.

Export Documents to Jira

To export the current document into Jira, click File, select Jira, and then Export Document. The integration iterates the document, creates new Jira issues or updates already exported issues by setting the following issue fields:

• Type — issue type based on the requirement type as defined by jiraIssueType configuration property.
• Summary — stores heading and id attributes of the exported requirement. Optionally, a custom attribute, or a template column defined in jiraFields configuration property may be used instead of heading attribute.
• Description — stores text attribute of the exported requirement. Optionally, a custom attribute, or a template column defined in jiraFields configuration property may be used instead.
• Parent — the parent issue corresponding to the parent object in the exported ReqView document, e.g., it preserves Epic / Story parent-child relationship.

ReqView is the owner of these Jira issue fields for the exported requirements. Jira users should not change them in Jira because the integration will overwrite these fields with the following export from ReqView.

However, you can use other issue fields to plan requirements and manage the development in Jira, e.g., Status, Assignee, or Sprint.

The export process also sets non-external custom attributes mapped to Jira issue fields in configuration property reqviewAttributes, see Document Configuration.

You can repeat requirements export to Jira for each updated document version. The process will update Jira issues created earlier or create new issues for new requirements created since the last export.

Requirements deleted (or purged) in ReqView will be marked as deleted in Jira using "[Deleted]" prefix of issue summary. You can query such issues based on the prefix to remove them permanently from Jira.

Example: Open the Example Project and configure the integration to export the NEEDS document so that the Description field of the exported Jira issues is set to user story description computed by ReqView template column Story:

{
  "jiraFields": {
    "Description": "Story"
  }
}

Fetch Jira Issue Fields

You can fetch information about exported Jira issues (e.g. issue URL, status, assignee, sprint, release versions) and display it in ReqView documents or traceability reports.

Fetched information from Jira is stored in custom attributes of the exported document. Define custom attributes storing Jira issues as read-only by readOnly flag set to true to disable editing of attribute values by the user. We also recommend setting the external flag to true for not saving fetched attribute values in the Project File or Project Folder. For more information on how to customize attributes for the current document, see Custom Document Attributes.

Example: In the Document Attributes dialog, define new external read-only custom attributes jiraUrl and jiraStatus to fetch the URL link and status of exported Jira issues as follows:

{
  "jiraUrl": {
    "name": "Jira URL",
    "type": "xhtml",
    "external": true,
    "readOnly": true
  },
  "jiraStatus": {
    "name": "Jira Status",
    "type": "string",
    "external": true,
    "readOnly": true
  },
  "jiraFixVersions": {
    "name": "Fix Versions",
    "type": "string",
    "external": true,
    "readOnly": true
  }
}

After defining custom attributes storing fetched information from Jira click File, select Jira, and Configure Synchronization. In the Configure Synchronization With Jira dialog, set the reqviewAttributes property to map the custom attributes to Jira issue fields.

Example: Map custom attribute jiraUrl to the URL link, jiraStatus to the status of exported Jira issues, and fixVersions to assigned release versions as follows:

{
  "reqviewAttributes": {
    "jiraUrl": "$URL",
    "jiraStatus": "Status",
    "fixVersions": "Fix versions"
  }
}

Note: You can also fetch a Jira custom field if it is a standard field type.

To fetch values of external custom attributes for the current document, click File, select Jira and then Update Document.

Note: Values of non-external custom attributes are set during export, see Export Documents to Jira. The procedure is the same as described above.

Trace Exported Requirements

If you enable the ReqView Connector for Jira, you will be able to trace requirements between ReqView and Jira in both directions by URL links.

Jira issues exported from ReqView contain a ReqView URL in a hidden property. To navigate from an exported Jira issue to the corresponding requirement in ReqView, click Open ReqView Connector in the Details right side pane and click Open in ReqView. In the Choose application to open the reqview link dialog, select ReqView application, optionally tick Always use this application to open reqview links, and finally click Open Link. For more information about ReqView URL links, see Share URL Links.

To navigate from a ReqView requirement to the corresponding Jira issue, define a custom attribute of xhtml type and map it to "$URL" in reqviewAttributes property of the document synchronization, as described in the previous section Fetch Jira Issue Fields.

Example: Synchronize NEEDS

You can try ReqView integration with Jira easily. We have configured the Example Project for exporting epics and users stories from the NEEDS document into your test Jira Cloud project.

1. Download the Example Project.
2. Open the project in ReqView, open NEEDS document, open the Configure Synchronization With Jira dialog, and replace "mycompany" and "MYPROJECT" to match your test project at Jira Cloud.
3. Optionally, enable the ReqView Connector for Jira at your Jira Cloud site.
4. Export epics and user stories from the NEEDS document.