In order to use JIRA synchronization you need to create a connection between your workspace and JIRA instance. This process needs a JIRA Administrator on JIRA side and 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.
Connect your workspace to a JIRA instance
Setting up application link
For two-way synchronization with password-less authentication you’ll need to set up an application link in JIRA first.
- As a workspace administrator in StoriesOnBoard from the workspace dashboard open Manage / Integration settings
- Enter your JIRA instance url
After that 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.
- Open up JIRA Add-on Settings / Application links with the provided link
- 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)
- 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)
- In the next popup window enter application name: StoriesOnBoard and click Continue
- If the link is created successfully edit it by clicking on the Edit link next to it:
- Choose “Incoming authentication” from the popup
- For the Consumer Key and Consumer Name enter: StoriesOnBoard
- For the Public Key copy and paste:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
- 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)
- Click on “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 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.
- 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.
- Click on Enable Integration to create the webhook
You can check the created webhook in JIRA by navigating to JIRA Administration (in the top right menu) / System / WebHooks (somewhere bottom left). You should see a screen similar to this:
- Now your StoriesOnBoard workspace is connected to your JIRA instance.
You can connect your story maps with your JIRA projects following the instructions in the next section.
Setting up the webhook manually
- Click on “I'll do it manually”
- Open JIRA’s Webhook management screen from JIRA Administration (in the top right menu) / System / WebHooks (somewhere bottom left)
- Click on “Create a WebHook”
- Fill the name and URL with the values provided by StorieOnBoard
- In the “Events” section check the following “Issue related events”: created, updated, deleted
- Scroll down and click on Create, then you should see a message similar to this:
- Back in StoriesOnBoard click on Enable Integration
- Now your StoriesOnBoard workspace is connected to your JIRA instance
I assume that you already have a story map and a project in JIRA. Please create them if they are not exist yet. I’m using the MapShop sample map in this guide.
- In StoriesOnBoard open the story map and from there open Board settings
- On Tool integration tab select JIRA and click Connect (watch out for the blocked popup!)
- 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.
- Select the JIRA project you’d like to sync with and click on Link project
- 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)
- 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 “New Features” created in JIRA and for example if a New Feature has an “In Review” state in JIRA, it will be imported as “Ready”. It also means that bugs, tasks, subtasks created in JIRA won’t be imported into StoriesOnBoard.
Similar to this setup is recommended for most projects. It means that on your story maps you’ll get a high level overview, where you can plan your releases and in JIRA you’ll have the details needed for the implementation.
- Select which fields you’d like to sync with JIRA
If sync name and description 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 (after a refresh).
- 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
- 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”.
- If the connection is established, you’ll see the following message on 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.
Congratulations! Your story map is connected to a JIRA project. Read along to find out how to keep your map and your JIRA project in sync.
Important notice: we’ve found an issue with OnDemand JIRA’s webhooks. StoriesOnBoard won’t get notified about changes of issues status, title and description in JIRA. You can use the JIRA integration till then, you can send cards to JIRA or import issues from JIRA and sync title and description changes from StoriesOnBoard to JIRA. We are working on this issue with Attlassian Support.
Update: From 19th April JIRA OnDemand webhooks are working properly. If you have any problems, please contact us using the feedback widget in the bottom-right corner of the app.