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.

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

When 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 to 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 behaviour 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 an requirement, the view contains a button which can be pressed to easily open up the linked issue in JIRA.
    • When commenting on a requirement, user is automatically transferred to JIRA.
  • For all requirements not linked to JIRA (created to Testlab) the UI of Testlab will act normally.



  1. You are using JIRA v5.2+, On-demand or On-premise installed variant.
  2. You are using Testlab Enterprise edition or a Small business pack.
  3. If you are using On-premise installed JIRA,
    1. make sure your JIRA server is able 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.
  4. 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 in 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 with. 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 account when setting up JIRA integration with issues, the same user account can be used here and there is no need to create an another.
  • Get an API token for your JIRA user. If integrating with JIRA Cloud, log into 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 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 an 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 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 attached files when synchronizing issue details.
    • JIRA password: testlabuserapitoken (or password if applicable on your JIRA instance)
      Credentials for the above user account.
  • Click “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 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 an 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. Reason for this is that for example in JIRA Agile, workflow statuses are used for tracking the progress of 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 prerequisities 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 box, but we can easily make changes for you if requested.

Best-of-class cross-browser hosted SaaS quality and test management, testing and issue management tools to improve your quality. Site information.