Technical description

Pushing Atlassian JIRA issues to Testlab

Issues of Meliora Testlab’s projects can be integrated into Atlassian JIRA issue tracker using JIRA’s WebHooks which allows for seamless real-time integration. This integration method requires no plugins, so this integration method is available for both JIRA on-demand/cloud and for on-premise installed JIRA setups.

This page describes how you integrate JIRA issue tickets to Testlab issues ( most often defects ). If you are interested in how to integrate JIRA tickets to be seen as Testlab requirements or user stories, please refer to the page Integrating Meliora Testlab requirements with Atlassian JIRA .

  • How it works

    With this integration strategy, JIRA becomes the master repository for issues. All issues are added to JIRA and all changes on issues are automatically pushed in real-time to your Testlab project. The data is replicated to Testlab’s database which allows for real-time analysis and reporting against added issues. Testlab maintains links between Testlab’s and JIRA’s issues.

    You can specify which JIRA projects are integrated with your Testlab project – you can even specify multiple JIRA projects.

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

    • For fields pushed from JIRA, Testlab’s editing views become read-only. Fields not mapped from JIRA are editable in Testlab.
    • When viewing an issue, the view contains a button that can be pressed to easily open up the issue in JIRA.
    • When commenting on an issue, the user is automatically transferred to JIRA.
    • If multiple JIRA projects are mapped to your Testlab project and an issue is added, the user has an option to choose which JIRA project the issue should be added to.

  • Prerequisites

    • You are using JIRA v5.2+, On-demand or On-premise installed variant.
    • If you are using On-premise installed JIRA,
      • make sure your JIRA server is able access the internet and call Testlab’s API from https://yourcompany.melioratestlab.com/api
      • 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.
    • You must have JIRA administration access to set up the needed Webhooks, user accounts, custom fields and Screen mappings as explained later.

  • 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. For JIRA OnDemand: Preliminary configuration at JIRA side

    These instructions apply only if you are using Atlassian JIRA OnDemand from Atlassian’s cloud. If you have JIRA which is installed on your own servers, see next chapter.

    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 or granted with needed permissions depending on your JIRA installation. 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 and take note of it, as you need it later on for configuration.
    • 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.

    Create and map the needed custom field

    • Your JIRA must have a separate screen configuration for creating issues. This allows for passing Testlab related data between systems without the need of having technical details visible on every JIRA screen.
      As you are using JIRA OnDemand by default, your JIRA projects should/might already have a project specific Screen which is mapped to “Create Issue” issue operation. If so, you should skip the creation of the new screen described below and bind the soon to be created custom field to these add Screens. You can read more about defining screens and associating screens with issue operations in the Atlassian OnDemand documentation.       If you don’t already have a fitting Screen for creating issues, you can create one as follows. First, make a copy of the Default screen. For this, go to Administration > Issues > Screens and click “Default screen” / Copy:

      • Name: Add screen
      • Description: Screen to add issues with

      The newly created “Add screen” must be configured to be shown by default for all issues added in JIRA. Go to Administration > Issues > Screen Schemes and click “Default Screen Scheme” / Configure. Continue on and click “+ Associate an Issue Operation with a Screen” and select

      • Issue Operation: Create Issue
      • Screen: Add screen

      Now, when you go to Administration > Issues > Screens, you should have a new screen in “Default Screen Scheme” scheme which is used when creating new issues in JIRA.

    • Add the following custom field to your JIRA. This field is used to pass information between Testlab and JIRA when adding new issues. Please go to Administration > Issues > Fields > Custom Fields and add a new field as follows:
      • Field type: Text Field (single line)
      • Name: TESTLABDATA
      • Description: Meliora Testlab related data (do not edit)
      • … and associate field Testlab to screens: Add screen (OR, the screen which you are using to create your issues with in your JIRA)
    • Add the newly created custom field to be visible on the screen you are using to create issues (“Add screen” if created as instructed). Go to Administration > Issues > Screens and click “Add screen” / Configure. Select the TESTLABDATA field to bind it to the screen in question.

     

    2. For JIRA installed on premises: Preliminary configuration at JIRA side

    Instructions in this section apply only if you are using Atlassian JIRA installed on your own servers.

    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 and take note of it, as you need it later on for configuration.
    • 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.

    Create and map the needed custom field

    • Your JIRA must have a separate screen configuration for creating issues. This allows for passing Testlab related data between systems without the need of having technical details visible on every JIRA screen.
      Note: If you have previously configured custom screen mappings to your JIRA you already might have the needed separate screen configuration for creating issues. If this is the case, you should not need to create new screen configurations and can skip this part. For example, if you have a “SCRUM” project created to your JIRA in Atlassian’s ondemand service with JIRA Software, you probably need assign the custom field to screens “SCRUM: Scrum Default Issue Screen” and “SCRUM: Scrum Bug Screen”.      First, make a copy of the Default screen. For this, go to Administration > Issues > Screens and click “Default screen” / Copy:

      • Name: Add screen
      • Description: Screen to add issues with

      The newly created “Add screen” must be configured to be shown by default for all issues added in JIRA. Go to Administration > Issues > Screen Schemes and click “Default Screen Scheme” / Configure. Continue on and click “+ Associate an Issue Operation with a Screen” and select

      • Issue Operation: Create Issue
      • Screen: Add screen

      Now, when you go to Administration > Issues > Screens, you should have a new screen in “Default Screen Scheme” scheme which is used when creating new issues in JIRA.

    • Add the following custom field to your JIRA. This field is used to pass information between Testlab and JIRA when adding new issues. Please go to Administration > Issues > Fields > Custom Fields and add a new field as follows:
      • Field type: Text Field (single line)
      • Name: TESTLABDATA
      • Description: Meliora Testlab related data (do not edit)
      • Search template (JIRA v5 only): None
      • Issue Types (JIRA v5 only): Any issue type
      • Choose applicable context (JIRA v5 only): Global context
      • … and associate field Testlab to screens: Add screen (OR, the screen which you are using to create your issues with in your JIRA)
    • Add the newly created custom field to be visible on the screen you are using to create issues (“Add screen” if created as instructed). Go to Administration > Issues > Screens and click “Add screen” / Configure. Select the TESTLABDATA field to bind it to the screen in question.

     

    3. WebHook configuration at JIRA side

    This section applies to both JIRA OnDemand and to JIRA installed on your own servers.

    • Go to Administration > System > (Advanced) Webhooks and click “+ Create a WebHook“:
      • Name: Testlab
      • URL: https://mycompany.melioratestlab.com/api/jirawebhook/issue?testlabapikey=MYAPIKEY
        Make sure to 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.
      • JQL: issueType in ('Bug', 'Improvement', 'New Feature', 'Task') and project = MyProject

        Make sure to include the issue types 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.
        If you have many projects in your JIRA, you really should limit the projects which trigger the push calls by specifying the project(s) in your JQL clause.

      • Events: “Issue Created, Issue Deleted, Issue Updated” and “Comment Created, Updated & Deleted” (if available in your JIRA)
      • Exclude body: Not checked

      This will configure a WebHook based event to your JIRA which will call the URL specified on every issue creation, deletion or update in your JIRA for issue types set.

     

    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.

  • 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 Issue tracker, choose “JIRA cloud” and enter the following:
      • JIRA URL: https://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 ‘https://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.
      • JIRA add parameters: issuetype=1&priority=3
        Default parameters passed to JIRA when creating new issues. The default parameters will create a Bug (issuetype=1) with Major priority (priority=3). Make sure to separate the parameters with & character. For more information on parameters JIRA supports, please see JIRA Knowledge Base. It is essential these parameters are correct. For example by default, when creating a new JIRA Software instance to Atlassian’s cloud, the issue type value for a “Bug” in SCRUM-project scheme is “10103”. In this case, you should set “issuetype=10103” to your JIRA add parameters. You should ask your JIRA administrator to provide you with the underlying ID of the preferred initial issue type you wish to initiate the issue creation from Testlab. You can also refer to the section “Finding out the field names and its possible values” in this JIRA article.
    • 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.
    • To verify that the integration works as expected
      • In Testlab, change your project to the one you integrated with if you are not already logged on to it, go to Issues view and click Add issue…
      • A new browser window should open up which points to your JIRA. Log in if needed, and enter some issue details for testing. At the bottom of the list of fields, you should have the TESTLABDATA field visible. This field can and should always be left untouched. Add the issue to your JIRA.
      • Change view back to Testlab, refresh the Issues view and verify, that the added issue is visible in your Testlab project.
      • Double click the issue in Testlab to open up the issue. Click the “Open in JIRA…” button and your JIRA browser window should load the details of the issue in question.
      • In JIRA, click More > Delete and confirm the deletion of the added test issue.
      • In Testlab, close the issue window, refresh the issue list and verify, that the issue is also removed from Testlab.

  • Default mappings between Testlab and JIRA

    When configured, Testlab will map the fields between Testlab and JIRA as described below.

    These mappings should work out-of-box with JIRA’s Simple workflow configuration (To Do -> In Progress -> Done) and with JIRA’s classic workflow (Open, In Progress, Resolved, Closed, Reopened). If you are using a custom workflow and prefer to have these mappings configured please open up a support ticket and we’ll customize them for you.

    Field Testlab value JIRA value
    Type Defect Bug
    New Feature New Feature
    Enhancement Improvement
    Other Task, Sub-task
    Priority Trivial Trivial
    Low Minor
    Normal Major
    High Critical
    Critical Blocker
    Resolution Open –
    Fixed Fixed, Done
    Won’t Fix Won’t Fix
    Duplicate Duplicate
    More Info Needed Incomplete
    Cannot Repeat Cannot Reproduce
    Status Open Open, To Do
    Assigned In Progress
    Resolved Resolved
    Closed Closed, Done
    Reopened Reopened

     

  • Frequently asked questions

    In short – what exactly does this do?

    You can integrate your JIRA issue tracker in a way, in which issues are created and updated in JIRA and pushed to your Testlab project as issues. Issue fields that are pushed from JIRA cannot be edited directly in Testlab but fields, which are not pushed (such as targeted milestone, related test case, etc) can still be edited in Testlab.

     

    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.

     

    What happens if I don’t set up the Testlab related custom field as instructed above?

    If for some reason you don’t set up the TESTLABDATA custom field to your JIRA as instructed, the integration works normally with the exception that during test execution, when jumping to JIRA to create a new issue the created issue won’t be tied to the test run as it should. All issues should be pushed to Testlab but the issues created in Testlab will be missing the related test run link, test case link, test run’s version, etc.

     

    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.

     

    I encounter ‘The issue type selected is invalid’ error when adding a new issue?

    The ‘issuetype’ parameter you have configured to the integration configuration in your Testlab project is invalid. You must configure a valid issue type identifier to this parameter in Testlab (Testlab > Manage projects… > Integrations > “JIRA add parameters”).

    To find out the values available for you, go to your JIRA and choose Administration > Issues > Issue types and hover your mouse on the “Edit” link. The id parameter in the link is the identifier you must use to create issues with the hovered issue type.