TerraTrue’s Jira integration makes it easy to create new launches from Jira issues. We’ll walk you through a few steps to create the integration. We’ll also discuss how to specify which Jira issues create launches and how to import existing Jira launches. Finally, we’ll provide detailed information about how you can automate custom questionnaires using Jira custom fields and create Jira issues based on custom questionnaire responses.
Jira integration setup
Step 1: Create an API token
To access your Jira instance, TerraTrue needs a way to authenticate with your system using an API token. It’s important to note:
- The Jira permissions granted by an API token will be the same as those of the account associated with the API token
- API tokens exist until they are revoked (deleted)
- API tokens are independent of a user’s login password, so revoking the token will not affect the Jira user’s login
To create an API token:
- Log in to Jira
- Go to https://id.atlassian.com/manage/api-tokens
- Click “Create API token”
- Save the token value so you can use it in a later step
Step 2: Enable the Jira Integration in Org Settings
- Log in to TerraTrue
- Navigate to Org Settings > Integrations > Jira or go to https://launch.terratrue.com/settings/integrations/jira
- Click the “Enable Jira Integration” toggle under the “Webhook Configuration” header
- Fill out the required fields as follows:
- Jira Instance URL: https://<your_Jira_instance>.atlassian.net
- Username: <Jira account username from step 1>
- API Token: <API token from step 1>
Step 3: Configure optional settings
When the Jira Integration is enabled, by default, only launches created by Jira are allowed. If you would still like to create TerraTrue launches in other ways, turn on the “Launch Flexibility” toggle.
Once enabled, you will have two options. If you would like to allow TerraTrue users to create launches without any restrictions, then choose “All launches” and click Save.
If you would like to limit the types of launches that can be created outside of Jira, select the “Launches with components” option. If selected, users will only be able to create launches outside of Jira when they are associated with a particular component. Simply specify the list of valid components and click Save.
By default, TerraTrue sends a label to the original Jira issue when a launch is completed. You can also configure TerraTrue to send comments to the original Jira issue when specific events, like completing a Data Spec, occur. To configure these optional comments, select the events you wish to track and then click Save.
Note: The creator of these optional comments will be the username specified in the Jira Integration.
Step 4: Define a webhook in Jira
- From the TerraTrue Jira Integration page, copy the URL in the Webhook section
- In Jira, navigate to Settings > System > Webhooks or go to https://<your_Jira_instance>.atlassian.net/plugins/servlet/webhooks
- Click “+ Create a WebHook”
- Fill out the name field and select enabled for status
- For the URL, paste in the webhook URL from TerraTrue
- In the Issue Related Events section, specify the Jira project or criteria for filtering in the JQL query box
- Under the Issues header, selected “created” and “updated”
- Save your new webhook
Customizing the Jira webhook
When configuring a webhook in the Issue Related Events section in Jira, we are given the ability to use JQL to determine which Jira issues will trigger the webhook. JQL is Jira’s search query language. Any search you would normally do in Jira can be directly copied into the Issue Related Events section of the webhook. This includes searches on multiple projects, field values, or any creative search strategy. You can find more information on JQL here.
Bulk importing Jira issues
Once you’ve configured the Jira Integration, newly created Jira issues will automatically create TerraTrue launches. If you would like to import existing Jira issues into TerraTrue, you can bulk import them through TerraTrue’s org settings.
- First, navigate to the Import Data setting and select Jira Integration.
2. Select the Jira project with the launches you would like to import and click Next.
3. Select the issues you would like to import, or use the checkbox at the top of the table to select all issues, and click Next.
4. You’ll now see a screen showing the status of the import.
5. Once imported, you can check the LaunchPad for your newly imported launches. Imported launches are automatically marked as complete and the Jira issue title, description, and due date are copied to the new launch. If a due date is not provided, then the due date is set three weeks from the creation date.
Automating custom questionnaires with Jira custom fields
When creating a launch from Jira, you have the option of storing the Jira issue’s custom fields and using them to pre-populate answers to custom questionnaires. This can save time and reduce the need for developers to switch between Jira and TerraTrue.
Today, TerraTrue only supports textfield, number, and date custom fields. Complex custom fields, like radio buttons, are not yet supported.
Step 1: Enable the optional Custom Fields setting
To get started, enabled the Custom Fields setting in TerraTrue’s Jira integration page.
Step 2: Select the custom fields you want to import
After enabling the Custom Fields setting, you’ll see a list of the available Jira custom fields. Each field you select will be sent to TerraTrue and can be used in custom questionnaires associated with a launch. Select the fields you want to be monitored and click save.
Step 3: Configure custom questionnaires
Head over to the Custom Questionnaires setting and click the custom questionnaire you would like to pre-populate. Find a question you would like to pre-populate and choose “Launch” and then “Custom Field” in the Prepopulation section.
Then select the Jira custom field you would like to pre-populate the question. Please note that only one custom field can be selected per question.
Step 4: Publish your changes
When you’re finished setting up your pre-population options, click Publish. Now this questionnaire will have its answers automatically completed based on the information entered in Jira custom fields.
Using the Jira Integration
Creating a launch using Jira
Before creating a launch using Jira, an admin in your org must configure the Jira integration. Part of the configuration process involves picking criteria that will automatically create TerraTrue launches when you open a Jira issue that satisfies those criteria.
The title, description, and due date of the TerraTrue launch will be automatically completed based on the Jira issue. If you don’t specify a due date, we’ll automatically set one three weeks from the date the launch was created.
Syncing launch status with Jira
When a review is marked complete in TerraTrue, we’ll automatically add a “TERRATRUE_COMPLETE” label to the Jira issue associated with the launch.
Creating Jira issues from custom questionnaire responses
With the Jira integration enabled, you can create Jira issues based on answers to questions in custom questionnaires.
To get started, you must first identify which Jira projects are available to custom questionnaire builders. Then custom questionnaire builders can simply add issue-creation triggers to individual questions.
Making Jira projects available to custom questionnaire builders
Administrators can expose a subset of Jira projects to custom questionnaire builders by selecting them in the Projects tab of the Jira integration settings. Simply click the “Add project” button, select a project from the drop-down menu, and then pick the default Jira issue type you would like to create (bug, epic, story, sub-task, or task).
Note: Please ensure that projects in Jira along with their issue types remain valid so that TerraTrue triggers continue to work.
Configuring Jira issue-creation triggers
You can create Jira issues from checkbox, text area, radio, and yes/no question types by turning on the “Create task in Jira” toggle. Once enabled, you’ll be asked to configure the following options:
- Issue Title – This text is used in the title of all new Jira issues created for this question. The related Launch number and title are appended to this value so it is clear which questionnaire response the issue relates to.
- Project – An available Jira project. Issues triggered for this question will be created in this project.
- Condition – A logical condition that, when combined with the Answer property and compared to a provided response to the question, can trigger the creation of a new issue. A list of conditions is provided for the user based on the question type.
- For example “Text Area” questions support ‘is empty’ and ‘is not empty’, but “Radio” questions support ‘is one of’ and ‘is not one of’.
- Answer – The answer(s) that should trigger the creation of an issue. Note this is not applicable to all question types.
- For example a “Text Area” question does not require an answer, but a “Radio” question may specify a Condition of ‘is one of’, with an answer of “Answer A”.
When an issue is created the description contains details about the question and answer that triggered its creation, including the respondent’s contact details. Links to the custom questionnaire and its parent launch are also included.
If the launch is deleted or restored or the related custom questionnaire is removed, we will update the issue with a comment describing the change. Issues are never deleted by TerraTrue.
As we’ve discussed, the Jira Integration is a bidirectional communication between Jira and TerraTrue. As a result, we ask you to provide a Jira username and API token so that we can authenticate with your Jira instance. TerraTrue will have access as that Jira user, so you may want to limit the Jira permissions provided to that Jira user to only those that are necessary.