Contents:

Enlarge document: http://docs.storiesonboard.com/en/articles/999770-setting-up-synchronization-with-jira

If you are new to StoriesOnBoard but already a Jira user the setup process only takes a few clicks. To begin, click on the "Sign up with Jira cloud" on our sign-up page.

After that, a confirmation window should pop up, where you need to allow StoriesOnBoard to access your Jira instance.

The setup will be automatic, if you are creating a new story map you will have the option to create it based on an existing Jira project.

Please note that StoriesOnBoard is unable to create the webhook in Jira which is necessary for the two-way, real-time synchronization. That requires a user with "Jira Administrators global permission" and a step by step guide is available in the "Jira integration settings" menu.

In order to use synchronization with the server version of Jira, you need to create a connection between your workspace and the Jira instance. To successfully perform this process log in to Jira as a user with "Jira Administrators global permission" and as a Workspace Administrator in StoriesOnBoard. You just need to do the set it up once for a workspace.

After that, you can connect your story maps individually to Jira projects. This needs a Story map Admin in StoriesOnBoard and a user in Jira who have the privileges for creating issues and modifying their title and description.

If you like to read about some advanced features with Jira integration, please check out the link below:

For two-way synchronization with password-less authentication, you’ll need to set up an application link in Jira first.

In this menu, a step by step guide will help you.

For a two-way synchronization, you'll need to set up an application link between Jira and StoriesOnBoard. An application link is a trusted relationship between StoriesOnBoard and JIRA. You'll need a user with an Administrator role in Jira for setup.

If you are integrating with an on-premise Jira instance, you may need to whitelist StoriesOnBoard in your firewall so that it can make connections to your Jira server. StoriesOnBoard is using the following IP addresses for the connections:

54.88.136.216 and 54.84.188.199.
​

Please note, on-premise integration requires at least Jira Software version 6.1. Jira Cloud instances are always running the latest Jira Software version.
​
3. Open up Jira Settings from the upper right corner / Select Products and choose "Application links"

4. Create a new link for StoriesOnBoard with the following URL: https://app.storiesonboard.com (you can click on the input box in the StoriesOnBoard window and press ctrl+c to copy it)

5. If a popup window “Configure Application URL” appears with the error message           “No response was received from the URL…”, then just click Continue (it’s normal)

6. In the next popup window enter the application name: StoriesOnBoard with Generic Application. Tick 'Create incoming link' and click Continue.
(Please note that if you click on the other fields, there is a bug in Jira that makes these fields required to continue - You can click on cancel and restart the setup screen)

7. If the link is created successfully edit it by clicking on the Edit button next to it

If you haven't selected the 'Create incoming link' you have to configure the authentications manually:
​
(8. Choose “Incoming Authentication” from the popup)

(9. For the Consumer Key and Consumer Name enter: StoriesOnBoard)

(10. For the Public Key copy and paste:)

(11. Scroll down, and hit save before closing the window)

Now StoriesOnBoard is able to connect to Jira with OAuth, which means you don’t need to give your Jira password to StoriesOnBoard.

Now we need to set up the other way, Jira should be able to send updates to StoriesOnBoard when an issue is changed.
This can be set up in two ways. The easy way is to let StoriesOnBoard set it up for you by giving the permission, the hard way is to do it manually.

The easy way (automatically)

1. Click on the “Please set it up for me!” button in StoriesOnBoard. Please watch out for the "ask for permission" Jira popup as it may be blocked by your browser. When asked, please enable opening popups from storiesonboard.com permanently because enabling them just temporarily can cause problems later. After enabling pop-ups you may have to click on the "Please set it up for me!" button again. Please remember that you need to be signed into Jira with a user that has a Jira Administrator role for this to work.

2. Give StoriesOnBoard permission to create the webhook for you by clicking on       the Allow button

After clicking on the “Allow” button, the window should close automatically.

3. Click on Enable Integration and you should be able to see an established connection:

You can check if the webhook is created in Jira by navigating to Jira settings / System / WebHooks (scroll down - bottom left). 

You should see a screen similar to this:

Setting up the webhook manually

1. Click on “I'll do it manually”

2. Open Jira’s Webhook management screen from Jira Settings » System » WebHooks 

3. Click on “Create a WebHook”

4. Fill the name and URL in Jira with the values provided by StoriesOnBoard

5. Under the “Issue related events” section tick the following “Issue” events:

*created
*updated
*deleted

Under "Project related events" section tick the following "Version" events:

*released
*updated
*deleted

6. Scroll down and click on Create, then you should see the following message:

7.  Back in StoriesOnBoard click on Enable Integration

8. Now your StoriesOnBoard workspace is connected to your Jira instance

2. At the Issue tracker integration tab select Jira and click Connect to Jira (watch out for blocked popup!)

3. Allow StoriesOnBoard to create and modify issues on behalf of the logged-in user by clicking on the Allow button. The Jira user shouldn’t be a Jira Administrator, a       normal Jira user is enough for the synchronization (with the permission to create and modify issues).

The popup window should close after that.

4. Select the Jira project you’d like to sync with and click on Link project

5. Select the issue type that should be created when new cards are sent to Jira

Typically this would be New Feature or Story as StoriesOnBoard’s cards reflects these concepts in Jira. All the statuses of the selected issue type’s should be mapped to Jira statuses (see the next step)

6. Components, Priority, Labels, Epic Link:
You can set additional Jira fields with predefined values when pushing cards into Jira. Hint: you can use variables in labels. Labels are separated by spaces, commas, or semicolons.
​
​Variables:

{activity} The name of the activity the pushed subtask belongs to

{task} The name of the task the pushed subtask belongs to

{release} The name of the release the pushed subtask belongs to

{colorLabel} The label of the subtask's color

{activityColorLabel} The label of the activity's color which the pushed subtask belongs to

{taskColorLabel} The label of the task's color which the pushed subtask belongs to

{storymap} The name of this story map
​

7. Select which issue types should be imported from Jira and map their Jira statuses to StoriesOnBoard statuses:

The settings in the screenshot above mean that StoriesOnBoard will import “Story” created in Jira and for example, if a Story has an “In Progress” state in Jira, it will be imported as “Doing”. Unticked elements won't be synced from Jira, in this example Task, Sub-task and Bug will not be synced. 

8. You can also enable other collaborators to import from Jira and you can rule out issue types with closed or done statuses during import, using JQL you can set custom filters to only import cards meeting those parameters and filters. Please follow our article about JQL settings.

9. Select which fields you’d like to sync with Jira

If sync name, description, and estimation changes are checked, when a title or description changes in Jira or on your story map, the changes will be also visible in the other system.

10. Allow importing of new issues from Jira for story map collaborators

If checked, a new menu appears on the board where non-admin collaborators can also import issues from Jira.

11. Impersonation

12. Connect your map with the Jira project by saving the settings. A confirmation will be asked because after establishing the connection to a Jira project, the cards’ statuses will be set by the connected Jira issues’ statuses, which means you won’t be able to change them on the board and now they are all being reset to “Todo”.
Linked cards will have the corresponding status set at status mapping from Jira.

13. If the connection is established, you’ll see the following message at the top of the       Settings dialog:

There you can

Use the 'Tool integration' submenu to import and sync changes from Jira. This will pull the issues matching your filter settings from the designated Jira project.
​

Also, you can display the Jira keys on StoriesOnBoard cards:

Once your story map is connected to a Jira project, you can push from StoriesOnBoard to Jira using the card's extra setting key or by pressing the ALT-key and clicking on the card:

If you use release synchronization, you can also push all cards in a release (Also pushes the release if it's not created in Jira) using the release's options dropdown menu:

💡 Tip - Learn more about:
​
​Jira Hierarchy Synchronization

Release synchronization setup with Jira