Technical description

Pushing Atlassian JIRA issues to Testlab as requirements

Using JIRA’s WebHooks technology it is possible to push issues (Stories, Tasks, etc) from JIRA to Testlab project as requirements. This is especially handy if a set of requirements (for example user stories) are managed in JIRA Agile and one wants to plan the testing for them in Testlab.

If you are more interested in how to see JIRA tickets as Issues in Testlab, please continue reading the page Jira Issues integration.

This integration method requires no plugins, so this integration method is available for both JIRA ondemand/cloud and for on-premise installed JIRA setups.

  • How it works

    After set up as instructed, when an issue in JIRA is created, edited or commented the changes are automatically propagated to Testlab and a new requirement is created for your project. Testlab maintains links between Testlab’s requirements and JIRA’s issues. For all requirements linked to JIRA, JIRA becomes the master of these requirements meaning, that the details of these requirements cannot be edited in Testlab.

    When configured for this requirements management integration, the behavior of Testlab’s user interface is changed as follows:

    • For all requirements linked to JIRA,
      • For fields pushed from JIRA, Testlab’s editing views become read-only. Fields not mapped from JIRA are editable in Testlab.
      • When viewing a requirement, the view contains a button that can be pressed to easily open up the linked issue in JIRA.
      • When commenting on a requirement, the user is automatically transferred to JIRA.
    • For all requirements not linked to JIRA (created to Testlab), the UI of Testlab will act normally.

  • Prerequisites

    1. You are using JIRA v5.2+, On-demand or On-premise installed variant.
    2. If you are using On-premise installed JIRA,
      1. make sure your JIRA server is able to access the internet and call Testlab’s API from https://yourcompany.melioratestlab.com/api
      2. your JIRA server should be accessible from Testlab servers as the integration synchronizes attached files and needs to be able to pull the files from your JIRA. If you need detailed IP information for firewall rules, please contact Testlab’s support for more details.
    3. You must have JIRA administration access to set up the needed Webhooks and user accounts.

  • How to get started

    To get started with integration follow the steps described below. If you have questions about these instructions or any problems with the set up please feel free to open up a support ticket in Testlab. We are happy to help you with your setup!

     

    1. Preliminary configuration at Testlab side
    • Go to Company management > API keys and configure an API key to be used for authentication for calls from JIRA to Testlab. Please see the Testlab’s Help-manual for configuration of API keys. Take note of the API key configured as it is needed later on for configuration at JIRA side.

     

    2. Preliminary configuration at JIRA side

    Add technical user account

    • Add a technical user account to JIRA for which Testlab will use to pull the needed content from your JIRA. Go to Users > Create user and add a new user for example named “Testlab User”. Please make sure that the user is added to a proper ‘jira-users’ user group. In JIRA Software, for example, this group is by default named as ‘jira-software-users’. Make sure to add a strong password to the user. If you already have created such an account when setting up JIRA integration with issues, the same user account can be used here and there is no need to create another.
    • Get an API token for your JIRA user. If integrating with JIRA Cloud, log in to https://id.atlassian.com/manage/api-tokens and click “Create API token” and proceed with the instructions provided. This token generated should be used as the password later on.

    This concludes the one-time setup of the integration. Continue on to instructions on how to set up the Testlab project to use the above integration setup and how to pick the synchronized requirements from your JIRA by configuring the needed WebHooks.

  • Integrate Testlab project with JIRA

    For all Testlab projects which you prefer to integrate with your JIRA some configuration steps need to be taken.

    • Log on to your Testlab (preferably as an administrator to make sure you have the needed permissions for the configuration) and select Testlab > Manage projects…
    • Select the project you want to integrate with your JIRA.
    • Choose the Integrations tab, Click Edit and as a Requirement management / Management system choose “JIRA” and enter the following:
      • JIRA URL: http://my.jira.com/jira
        Absolute root URL of the JIRA you are integrating the project with. This is typically the address you access your JIRA with your browser. For JIRA OnDemand, this is typically in format ‘http://myjira.atlassian.net’.
      • JIRA projects: your JIRA-project key
        The key/identifier of your JIRA project(s) which you wish to integrate to Testlab. You can specify multiple projects by separating the identifiers by a comma.
      • JIRA user name: testlabuser@somedomain.com
        Name of the technical user account created earlier. This user account will be used for fetching the content of the attached files when synchronizing issue details.
      • JIRA password: testlabuserapitoken (or password if applicable on your JIRA instance)
        Credentials for the above user account.
    • Click the “Verify Configuration” button to check that your JIRA settings are valid. We will try to contact your JIRA from the address provided with credentials set, fetch and verify that a project from your JIRA is found and verify, that the TESTLABDATA custom field is set up and present.
    • Click Save and you are done. Continue on to the next chapter to configure needed JIRA hooks for the issues you want to push to the project.

  • Selecting requirements from JIRA and pushing to a Testlab project

    When the preliminary set up is done and the Testlab project is configured for requirement management with your JIRA, you can configure the needed WebHooks to pick the relevant issues from the JIRA to be synchronized with the Testlab project. To do this,

    • Go to Administration > System > (Advanced) Webhooks and click “+ Create a WebHook“:
      • Name: Testlab requirements
      • URL: https://mycompany.melioratestlab.com/api/jirawebhook/requirement/REQUIREMENTFOLDER?testlabapikey=MYAPIKEY
        • Replace REQUIREMENTFOLDER with the requirement identifier of the folder in your Testlab project you want to push the requirements to with this hook. For example, if you have a folder “US” for your user stories, use …/requirement/US?… as your URL to push all your stories to this folder. If omitted, all requirements are created to your Testlab project’s requirement root.
        • Replace MYAPIKEY with the API key you configured earlier to your Testlab and, mycompany with your company identifier.
        • If you are using Testlab on-premise, replace everything before /api/… with the full address of your Testlab environment.
      • Exclude details: No
      • JQL: project = MYPROJECT and issueType in ('Story')

        Make sure to include the issue types from the project you want to synchronize to Testlab – if you are using different project schemes or you have customized your issues types make sure to include all issue types you wish to synchronize from your JIRA.
        The example above will

        • push all Story-typed issues from JIRA’s MYPROJECT to Testlab project with key “MYPROJECT” as requirements.
      • Events: “Issue Created, Issue Deleted, Issue Updated” and “Comment Created, Updated & Deleted” (if available in your JIRA)
    • Save the WebHook.

    If everything is set up correctly, creating a new Story to your JIRA project MYPROJECT should create the Story as a user story to your Testlab project.

    Keep in mind, that you can configure multiple WebHooks to your JIRA if needed. This way, you can pick the relevant issues and push them to the Testlab’s requirement hierarchy to folders you prefer.

  • Default mappings between Testlab and JIRA

    When configured, Testlab will map the fields from JIRA to Testlab.

    If you prefer to have these mappings configured for your project please open up a support ticket and we’ll customize them for you.

    JIRA Field JIRA value Testlab Field Testlab value
    Type New Feature, Improvement, Task, Sub-task, Bug Class Requirement
    Story, Epic User story
    Priority Trivial Importance Low
    Minor Normal
    Major High
    Critical, Blocker Critical
    Status To Do, Open Status * To Do (Ready if missing) *
    In Progress in Progress (Ready if missing) *
    Done Done (Ready if missing) *

    * When mapping the workflow status we always try to map to a status value from your requirement workflow as described above. Default workflows of Testlab do not have the statuses To Do, In Progress or Done and you have to configure them yourself if you prefer to track requirement progress from your JIRA. If workflow statuses are missing in Testlab, we automatically map them to the “Ready” status. The reason for this is that for example in JIRA Agile, workflow statuses are used for tracking the progress of the story’s implementation, not it’s design for which the workflow statuses are used in Testlab.

  • Frequently asked questions

    In short – what exactly does this do?

    You can integrate your JIRA issue tracker in a way, in which JIRA’s issues (Stories for example) can be pushed to your Testlab project as requirements to be a part of your specification to be tested. Requirement assets created to Testlab work normally – JIRA pushed requirements are only a part of your specification.

     

    Does this work with JIRA On-demand?

    Yes. The integration works via JIRA’s WebHooks which can be set up in JIRA On-demand and in addition, in JIRA instance installed on your own servers.

     

    From where exactly do I set this up with?

    Log in to your Testlab project, select Testlab > Manage project(s)… and choose the Integrations tab. All integrations which can be taken in use by yourself are configured per project from this view. Check the prerequisites and follow the instructions above in this document to set up the integration at JIRA side.

     

    I’m using custom workflows, how exactly can I set them up?

    As said, just drop us a line by contacting support from your Testlab (found in Testlab’s help menu). The default mappings for workflows and fields should work with default workflows out of the box, but we can easily make changes for you if requested.