Collaborate With Jira Cloud

Connect ReqView with Atlassian Jira Cloud to benefit from an integrated solution for Application Lifecycle Management (ALM).

You can export requirements from ReqView to a Jira project to manage their development in Jira and fetch back into ReqView the information about the development progress. Optionally, you can also manage test cases and their execution as Jira issues using a plugin.

Notes: ReqView supports integration with Jira Software Cloud service hosting team-managed (next-gen) and company-managed (classic) projects. Jira projects must be created using Scrum or Kanban templates from the Software development category.

Workflow

You can use the following workflow to manage the development of your HW/SW product in ReqView and Jira:

1. Requirements Management: Capture and manage stakeholder, system, SW and HW requirements in ReqView. Optionally, manage also risks or tests in ReqView.
2. Export to Jira: Export a baseline of low-level requirements from a ReqView document into a Jira project to share them with the development team. Trace requirements between ReqView and Jira issues in both directions.
3. Agile SW Development: Manage SW development in Jira using an agile development process:
   • Decompose user stories to tasks.
   • Plan user stories and tasks using the Sprint issue field.
   • Assign user stories and tasks to developers using the Assignee.
   • Track the development progress of user stories using the Status issue field.
4. Test Management (optional): Manage test cases verifying user stories and capture test execution results in Jira Cloud.
   • Describe test cases.
   • Link test cases with user stories.
   • Plan test cases for execution.
   • Execute test plans and capture test results.
   • Create defects describing failed tests.
5. Update From Jira: Fetch information about the development status of exported Jira issues in the source ReqView document to display it in a Requirements Traceability Matrix (RTM).

Set up Jira Integration

Before using ReqView and Jira together, you need to install the ReqView Connector for Jira, configure the exported requirements document in ReqView, and create a Jira API token for ReqView. If you want to manage tests in Jira then you need also to set up a Jira test management plugin.

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 section Export Requirements to Jira below.
  • 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 issues. See section Update Requirements From Jira below.
  • key — ReqView custom attribute (e.g. “jiraStatus” string attribute).
  • value — fetched information from Jira
    • name of Jira issue field (e.g., “Status”)
    • $URL to fetch the URL of the Jira issue
    • $LinkedIssues(<issue_type>) to fetch URLs of linked Jira issues of a given type (e.g., $LinkedIssues(Test))
    • $Links(<link_type>) to fetch a list of URLs of Jira issues linked by a given link type (e.g. $Links(is tested by))

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 epics and user stories from the document NEEDS to your Scrum project hosted at Jira Cloud.

1. In the Jira cloud, find the URL of your Jira project in the browser address bar and the key of your Jira project key in the Project Settings > Details screen:

   

2. In ReqView Configure Synchronization With Jira dialog, set the URL of your Jira project in the jiraSiteUrl property and the key of your project in the jiraProjectKey property:

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

3. The property jiraIssueType.reqviewAttribute is set to “type” because ReqView custom enumeration attribute type is used for mapping of ReqView requirements to Jira issue types, see also Customize Attributes.

4. The property jiraIssueType.mapping is set to create Jira Epic or Story issues according to the value of ReqView attribute type as follows:

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

Jira Credentials

For security reasons, ReqView uses Jira API tokens to access Jira projects (not passwords). You need to create your private API token in Jira Cloud API Tokens screen:

See Manage API tokens for your Atlassian account for more information.

When ReqView connects to your Jira Cloud site the first time, you can enter your Jira login email and API token in the Jira Credentials dialog:

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

Note: If Jira Cloud returns error “Jira project was not found” then please double check if:

• jiraSiteUrl configuration property is set to your Jira project URL,
• jiraProjectKey configuration property is set to your Jira project ID,
• the entered API token is assigned to your Jira login email (is not assigned to another Jira user), and
• the entered API token is valid (not revoked).

Jira Permissions

Default Access:

When using the default settings of Jira projects, you don't need to do anything. You can synchronize data right away.

When your project has more complex user access settings, please check that editors who will synchronize data have adequate permissions. The settings differ for company-managed and team-managed projects.

Custom Access for Team-Managed Projects:

For team-managed projects, set the “Product role” of users to “Product admin” (Settings > User Management, three dots at the selected user > Show details) or assign users “Administrator role” for the selected project (Project Settings > Access).

Custom Access for Company-Managed Projects:

In company-managed projects, minimal users' permissions for synchronizing ReqView with Jira are “Create Issue”, “Edit Issue” and “Administer Project” (e.g., Jira Settings > Issues > Permission schemes, Permissions).

Note: If Jira Cloud returns error “You cannot edit the configuration of this project” then check if you have project permission Administer Projects.

Export Requirements 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: Export Jira issues with the Description field set to the value of attribute text (displayed in ReqView column Description):

{
  "jiraFields": {
    "Description": "text"
  }
}

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"
  }
}

Update Requirements From Jira

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

The information fetched from Jira is stored in custom attributes of the exported document. You can disable editing of attribute values by users by setting readOnly flag to true in the attribute definition. We also recommend setting the external flag to true to avoid 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 to fetch the issue URL, status, and release versions from the exported Story issues as follows:

{
  "jiraUrl": {
    "name": "Jira URL",
    "type": "xhtml",
    "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 the issue URL, an issue field fetched from Jira. You can fetch a Jira custom issue field if it is a standard field type. You can fetch also URLs of linked issues, for instance Test issues, see Manage Tests in Jira.

Example: Map custom attribute jiraUrl to the issue URL, jiraStatus to the status, jiraFixVersions to assigned release versions as follows:

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

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

Jira custom attributes created in ReqView first, then updated by values from Jira:

Note: Values of non-external custom attributes are set during export, see Export Requirements 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 Update Requirements From Jira.

Manage Tests in Jira

You can describe test cases in ReqView documents and link them to requirements by verification links conveniently. However, you also also choose to manage test cases and capture their execution results using a 3rd party Jira test management plugin, for instance Xray or Zephyr.

With these Jira plugins, you describe test cases as Test Jira issues providing information about tests steps, such as the action, test data, and expected results. Then, you link Test issues to Story issues to trace verified requirements. Finally, create test plans to schedule execution test cases, execute test plans, capture test results, and finally create defects describing found anomalies for each failed test.

Example: Manage tests in Jira using Xray plugin. See Xray documentation for more information how to install, configure and use Xray.

Test cases in Xray are described in Test Jira issues:

And, test coverage in Xray is displayed in Story Jira issues:

In ReqView, open the Document Attributes dialog and add new external read-only custom attribute to fetch URLs of linked Test issues from the exported Story issues:

{
  "jiraLinks": {
    "name": "Jira Links",
    "type": "xhtml",
    "external": true,
    "readOnly": true
  }
}

Then, open the Configure Synchronization With Jira dialog and map jiraLinks to URLs of linked Test issues as follows:

{
  "reqviewAttributes": {
    "jiraLinks": "$LinkedIssues(Test)"
  }
}

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. Enable the ReqView Connector for Jira plugin.
4. Optionally, enable a test management Jira plugin.
5. Export epics and user stories from the NEEDS document.