Craft.io allows for a seamless integration between Craft.io portfolio initiatives and Jira initiatives. This feature bridges the gap between your product management activities in Craft.io and your development and project management workflows in Jira, providing a comprehensive and unified experience across teams and work domains.

The integration reflects the relationships of initiatives and epics between Craft.io and Jira. This means that the hierarchical structure of initiatives and epics created in Craft.io will be accurately represented in Jira, and vice versa, which ensures seamless coordination and alignment between the two platforms, making it easier than ever to manage complex projects.

In this Article -

The first step of the integration is to connect Craft.io to Jira. Click Integrations from the Portfolio Settings menu on the top right of the navigation bar and choose 'Connect to Jira'.

You will be prompted to enter your Jira credentials. Please note an Administrator's permission is required to perform the connection.

This includes the Jira URL, Email/Username, API token/password and connection name.

When filling in the required information please make sure to remove any trailing white spaces from the end of the Jira URL. Also, use a unique naming convention for ‘Connection name’

To integrate with a Cloud Jira server, after specifying the URL, insert the email address that is used to log into Jira.

Then, an API token is required to authenticate Craft.io access to Jira on an ongoing basis.

Click here to learn how to create a Jira API token.

To integrate with an On-Premise Jira server, you may be required to whitelist Craft.io's Server IP addresses in your firewall. By doing so, Craft.io can connect to your JIRA server to create issues.
​

Craft.io IP address for whitelisting: 35.232.112.68 port 443
​

In addition to that, integrating with an On-premise Jira account requires you to insert the Password you use to log in to Jira instead of an API token.
​

After clicking ‘Next’ on the connection screen, you will have the ability to add a project to the integration.

Once the connection is in place, you will be directed to the Project Integration screen.

On this screen, you will later see all active integrations.
​

Click to add a new Project Integration.
​

Select the first Jira Project and board to sync with. You will be able to add additional projects to the connection later on.

Then, give a unique name to the integration.

Click 'Next' to continue.

In the ‘Field&Type Mapping’ screen you’re invited to map Craft.io item types (left column) with the corresponding Jira item types, and map fields you’ve set up in Craft.io as metadata with corresponding fields on Jira.

Primary Types mapping

Align your Initiatives in Craft.io (on the left), with your Initiatives in Jira (on the right).

Field mapping

In the following sections of the screen, you are able to map between fields in Craft.io and their corresponding fields in Jira.

Once finished the mapping, you can continue to perform a sync of your items ad-hoc, from Jira=>Craft.io.
​

At this point you can decide whether you want to sync all open issues from Jira, or alternatively, sync issues matching a JQL query.
​

​

Now you can integrate additional Jira Projects. Click ‘+Add another Jira Project’ and repeat the above steps for each of the Jira projects you would like to integrate with.

Additional authentication will not be required should you wish to integrate with Projects that sit under the same Jira instance.

At the bottom of the connection area, you can find instructions on how to sync Jira back to Craft.io. This can be done by setting up a webhook on Jira’s side, to get updates automatically.

Click to expand for the detailed steps to set up a webhook.

The detailed instructions include a unique URL that contains your portfolio ID.
Copy the URL to your clipboard and continue to the webhook configuration in Jira.
​

In Jira, go to Jira Settings > System, scroll down to the Advanced section and select Webhooks.

Click the + Create a Webhook button, and enter the required information:

Name - Enter a unique name for the Webhook listener.

Status - Select 'Enabled'.

In the "Events" section check all the boxes under Comment, Issue link, Issue, Version, Worklog, and Sprint (For example: under 'Issue' check the boxes for "created", "updated", "deleted").

Click 'Create'. Your two-way Craft.io-Jira integration is now enabled, and items will automatically sync via webhook from Jira to Craft.io.

The webhook needs to be set up only once per portfolio, assuming that all Jira projects that you integrated into the portfolio are from the same Jira instance. In case you integrate multiple Jira instances, the webhook will require configuration per Jira instance.
​

How can you tell if the webhook is connected or not?

On the Integrations screen, next to the connection name, you will find the webhook icon.the webhook icon will be lit in blue, to indicate when a webhook is connected and at least one event has been fired from Jira’s side.

For active integrations, the properties of the connection can be modified if and when needed.

Having the need to update integration settings is a common scenario, whether due to a need to change the API token or password for security reasons or because the person whose user’s credentials were used to create the connection is no longer in the company. For this reason, you have the ability to update the connection details, without having the need to disconnect.

Whether the company branding language changes or there has been a restructure that requires changing the name of the connection, this can be easily done with just a few clicks.

Performing this action will end the connection between Craft.io and the integrated Jira instance, along with all connected projects.

Note- Should the connection be recreated with the same project(s), the Craft.io item associated with the corresponding item in Jira will not be restored.