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

In order to use Jira synchronization, you need to create a connection between your workspace and 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 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:

Connect your workspace to a Jira instance

Setting up application link

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

  1. As a Workspace Admin in StoriesOnBoard from the workspace dashboard          open Manage Workspace / Jira Integration settings:

2. Enter your Jira instance url (usually ending with ".atlassian.net")

Please note that you can use url's starting with "http://" or "https://".

After this, instructions will appear on the screen about how to set up the application link. You can follow those instructions or the one here in the blog post with illustrative screenshots.

On-premise Jira settings:
For a two-way synchronisation 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 Administrator role in Jira for setting this up.
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:,
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 bottom left 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 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 which 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:)

-----END PUBLIC KEY-----

(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 you 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.

Easy way (automatically)

1. Click on “Please set it up for me!” button in StoriesOnBoardPlease 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 temporary can cause problems later. After enabling popups you may have to click "Please set it up for me!" button again. Please remember that you need to be signed into Jira with a user that has Jira Administrator role for this to  work.

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

After clicking on “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 (on the left side  menu) / 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:


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


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

Connect your story map to a Jira project

  1. In StoriesOnBoard open a story map and navigate to the Integration settings menu:

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.


{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 means 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 estiomation 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’ statues, 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 in the top of the       settings dialog:

There you can

  • disable integration temporarily, if you don’t want to send new cards to Jira or sync their statuses, title and description for a while in either of the systems.
  • unlink project, if you’d like to connect your story map to another project in Jira (selecting another project will delete connections between cards and issues!)
  • disconnect Jira, if you’d like to connect to Jira with another user or connect to a different tool like Trello or Pivotal Tracker.

Importing cards from a Jira project:

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 synchronisation, you can also push all cards in a release (Also pushes the release if its not created in Jira) using the release's options dropdown menu:

Did this answer your question?