Jira Server/DC Integration v1

High-Level overview.

StorYd Admins can create a connection to a Jira Server/DC instance. Once the StorYd Integration Plugin is installed on Jira, the connection can be initiated from the StorYd Application admin page. A Jira admin will then need to enable the connections from the Integration admin page, in Jira. Once enabled Users in the StorYd Application can define field mappings. This will map StorYd Epic fields to Jira fields. These mappings will be used to export StorYd Epic data into a Jira issue. Once a StorYd Epic is exported into Jira, It will create a link between the StorYd Epic and Jira issue.

Setting up a connection

Once the plugin is installed, navigate to the Managed Apps → Global Configuration (STORYD INTEGRATION).

In the Integration Configuration tab, enable the “Enable connection requests“. This setting allows integration connections to be initiated. This should be enabled while the connection to StorYd is being initialized but should be disabled once the connection has been initialized. This will prevent unwanted connection requests from StorYd servers.

Once this has been enabled navigate to the “Integration“ tab on the StorYd Application admin page. Click the plus icon to add a new integration.

In the popup select “Jira Server/Data-Center“ for the integration type, give the integration a relevant name (this can be changed later), enter the Jira base URL of your Jira instance (e.g. https://www.jira.examplecompany.com), and then click “ADD”.

Once added the popup will automatically close and you will see the integration that was created.

By default, the connection will be disabled in Jira after the connection is initiated. Navigate back to the Integration page in Jira Managed Apps → Global Configuration (STORYD INTEGRATION). Note, You will need to refresh this page if you already have it open. Once on this page, you should see a new Integration. This will display the Region, Company Domain, Company Name, and the enabled status, which by default will be disabled. Click the “Enabled” button to enable the integration.

Once enabled navigate back to the integration tab in the StorYd Application and click “Refresh Status”.

After the status has been refreshed, you should see the status change to “Connection is Active“.

At this point the connection is active and you can now perform integration actions. Since the connection has been initiated we can now disable the “Enable connection requests“ in Jira. Navigate back to the integration tab in Jira and disable this setting. This will prevent further unwanted connections request from being initiated and disabling this once the connection has been established is more secure.

Default User

When integration actions are performed, the Jira Integration Plugin will attempt to match users in Jira with the user who initiated the action (e.g. fetching available projects) based on the email address of users in both applications. If a matching user cannot be found the Plugin will use the “Default user”, this user can be set in the Integration Configuration page in Jira.

If the default user is empty and the Jira plugin cannot find a matching user in Jira, no information will be returned and there will be an error displayed in the StorYd application.

Creating a field mapping

Once the connection has been established admins and users can create field mappings. By default, only admins can create field mapping. Navigate to the integration tab on the StorYd Application admin page. For the integration you want to create a field mapping, select the menu icon, and then select “Field Mapping”.

This will open up a full-screen pop where Field mappings can be created.

Allowing non-admin users to create and save mappings

On the admin Field Mapping popup, in the bottom left, there is a setting called “Allow users to create, edit and save mappings“, enabling this will allow all users to create and save field mapping from the Epic export page.

Defining a field mapping.

In the field mapping popup, once users select a Jira project and Issue type. A “Jira Field” field will be displayed, this is all the fields available for the selected project and Issue type. Jira fields selected and added in this field will be used in the mapping.

Some fields can be added multiple times to allow multiple StorYd Epic fields to be exported into a single Jira field e.g. description.

Once a Jira field has been added to the mapping, for each Jira field added users need to select what StorYd Epic field will map into a particular Jira field

Field Mapping Types

Depending on the Jira field and selected StorYd epic field, users will need to select a mapping type

Different mapping types will map StorYd Epic data differently into a Jira field.

Direct

Direct mapping directly maps the value from the StorYd Epic field into the Jira field. For example, the “Epic Description” StorYd field can directly map into the description field. This will place the text content of the “Epic Description“ into the Jira field.

Match options to option

This mapping type is available when a StorYd option field (e.g. priority ) maps into a Jira option field (e.g. priority or select field). This mapping type will select the Jira option that matches the StorYd option. This will match based on the case-insensitive names of each option. Excluding the case, the options need to be an exact match, this includes characters like commas, dashes, etc.

options to option set

If this type is selected, users will need to select which StorYd options match to which Jira options. Select the edit icon to open up a popup menu

In the popup select a StorYd Option and Jira Option and click the add icon. This will be saved and displayed below the options fields in a list. This list shows what StorYd Options map to which Jira option.

Range

If a StorYd number field is selected to map into a Jira option field, users will be able to select a Range mapping type. This will allow the users to define different ranges of numbers that map into a Jira option. For example, numbers 0 to 50 will map into the Jira option called “Small size“.

Select the edit icon to open up a popup menu.

In the popup, users can select a range of numbers in the Range field and select a Jira option. Once the add icon is clicked, numbers in the Range field will be mapped to the selected Jira option. A list of Range mappings will be displayed under the Range and Options fields.

The “Max Range” field in the bottom left allows users to increase the max range in the Range Field. By default, users can only select a range between 0 and 100.

Pre-set Value

Users can select a StorYd field called “Pre-set Value“ to map into a Jira field. This is not an Epic field but allows users to set a preset value for the Jira field. If a Pre-set Value is selected users will either be presented with a text field or an options field, depending on the Jira field. Data put into the text field or option selected in the options field will be a pre-set value that will be used to set the Jira field.

Testing a field mapping

Once a field mapping is defined users can test the field mapping using the “TEST MAPPING“ button.

If the field mapping is unsuccessful there will be an error shown in the bottom left and if there are field errors, there will be a list of field errors displayed and a reason why the test failed.

Saving field mapping

If the test was successful you will be able to save the mapping or copy it to another project.

Saving the field mapping will save the current field mapping for the selected project and Issue Type. Once saved, if users navigate back the field mapping for that particular project and Issue Type the saved field mapping will be loaded.

Selecting “Copy to other projects“ will open a popup that will allow users to select specific projects or all projects. Once projects are selected users can select “Start Test“. This will run through all the selected projects and test/save the current field mapping against each project and the currently selected Issue Type (e.g. Epic).

Exporting data using field mapping

In the Epic view select the “Export information” option from the menu, after clicking the menu icon

Select the “Integrated Application (Export)“ in the export type field and then select the relevant integrated application from the dropdown option field.

Once selected and the Jira projects have been loaded, selected a Jira project and Issue type. If there is a saved mapping, this should be automatically loaded in.

Selected “TEST MAPPING”. If successful you will be able to select “EXPORT DATA”.

After a successful export, the fullscreen popup should close and you should see a successful message in the bottom left of the screen.

Expanding the Epic you should see an integrations section, listing the exported Issue. Exporting the data has created an integration link between the Jira Issue and StorYd Epic.

Creating integration links without exporting data

Users can create a link between a StorYd Epic and Jira Issue without exporting Data (note. Jira plugin version 1.0.2 and above is required).

In the Epic view select the “Export information” option from the menu, after clicking the menu icon

Select the “Integrated Application (Link)“ in the export type field and then select the relevant integrated application from the dropdown option field.

An “Issue Key“ field will then be displayed. Enter the Jira Issue Key you would like to create a link for and then click the “Create Link” button.

This will create a link between the Jira Issue and StorYd Epic.

Integration Links

After exporting a Epic there will be an integration link created between the StorYd Epic and Jira Issue.

This link can be seen in the integrations section on the StorYd Epic

And on the right-hand panel on the Jira Issue.

Each integration link has a clickable link that can be clicked. This will open a new tab to the URL of the linked item.

Network Information

StorYd to Jira

For version 1 of integration. All requests will be initiated from StorYd servers, these requests will be over HTTPS over port 443.

Requests will originate from the following IP addresses:

35.189.4.59 for the Australian region.
Unknown (non-static IP) for the development region/environment. If a static IP address is required for testing, please contact support.

All requests will only access routes starting with "/rest/storyd-integration/" on your Jira instance. E.g. https://<base-url>/rest/storyd-integratiom/latest/config/initiate-connection.

Jira to StorYd

As of version 1, no requests will be initiated from Jira. Although, during a request from StorYd servers, Jira may send a request to StorYd servers to validate tokens. Requests to validate tokens will be sent to

https://www.storydsoftware.com.au for the Australian region.
https://test.storydsoftware.app for the development region/environment.

There will be future releases where requests will initiate from Jira and send a request to StorYd servers, all requests will be sent to:

https://www.storydsoftware.com.au for the Australian region.
https://test.storydsoftware.app for the development region/environment.