30 Comments

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.

  1. As a workspace administrator in StoriesOnBoard from the workspace dashboard open Manage / Integration settings
     Integration settings menu
  2. Enter your JIRA instance url
    IntegrationSettings_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.
  3. Open up JIRA Add-on Settings / Application links with the provided link
  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)
    JIRA Configure Application Links
  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)
    JIRA_Configure_Application_Links_No_response
  6. In the next popup window enter application name: StoriesOnBoard and click Continue
    JIRA Application Links Add New
  7. If the link is created successfully edit it by clicking on the Edit link next to it:
    JIRA_Configure_Application_Links_added
  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:
    -----BEGIN PUBLIC KEY-----
    MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDBIGHlMcIxc4ACAnolhV940PEp
    uvbis5fxB0oum61r2XbnXCcJTIctI49Ncr3ffi7pm2dFBjxQH4z8nDuGzfnd712y
    0wLMyZeDCtEfbiZpxbRwhZLJDRpC1uD9J7hp382kXPkfm3+SaA09ztVIE8u/yLuU
    qyqIy/BbN7IW3UY67wIDAQAB
    -----END PUBLIC KEY-----
    JIRA_Configure_Application_Links_Incoming_Auth
  11. Scroll down, and hit save before closing the window
    JIRA_Configure_Application_Links_Incoming_Auth_Save

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

Webhook

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 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.
  2. Give StoriesOnBoard the permission to create the webhook for you by clicking on the Allow button
    JIRA_Connect_as_JIRA_admin_allow
    After clicking on “Allow” button, the window should close automatically.
  3. Click on Enable Integration to create the webhook
    Enable_Integration
    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:
    JIRA_check_webhook
  4. Now your StoriesOnBoard workspace is connected to your JIRA instance.
    JIRA_integration_is_established
    You can connect your story maps with your JIRA projects following the instructions in the next section.

Setting up the webhook manually

  1. Click on “I'll do it manually”
  2. Open JIRA’s Webhook management screen from  JIRA Administration (in the top right  menu) / System / WebHooks (somewhere bottom left)
    JIRA_WebHooks
  3. Click on “Create a WebHook”
  4. Fill the name and URL with the values provided by StorieOnBoard
    JIRA_New_WebHook_name_url
  5. In the “Events” section check the following “Issue related events”: created, updated, deleted
    JIRA_New_WebHook_events
  6. Scroll down and click on Create, then you should see a message similar to this:
    JIRA_WebHook_created
  7. Back in StoriesOnBoard click on Enable Integration
  8. Now your StoriesOnBoard workspace is connected to your JIRA instance
    JIRA_integration_is_established_manual

Connect your story map to a JIRA project

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.

  1. In StoriesOnBoard open the story map and from there open Board settings
    BoardSettings_menu
  2. On Tool integration tab select JIRA and click Connect (watch out for the blocked popup!)
    BoardSettings_ToolsIntegration_select_JIRA
  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).
    JIRA_Connect_project_allow
    The popup window should close after that.
  4. Select the JIRA project you’d like to sync with and click on Link project
    BoardSettings_ToolsIntegration_link_project 
  5. Select the issue type that should be created when new cards are sent to JIRA
    BoardSettings_select_issue_type
    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. Select which issue types should be imported from JIRA and map their JIRA statuses to StoriesOnBoard statuses
    BoardSettings_select_imported_issue_types_and_status_mappings
    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.
  7. Select which fields you’d like to sync with JIRA
    BoardSettings_select_which_fields_to_sync_from_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).
  8. Allow importing of new issues from JIRA for story map collaborators
    BoardSettings_import_options_enable_importing_of_new_cards_from_JIRA
    If checked, a new menu appears on the board where non-admin collaborators can also import issues from JIRA
  9. 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”.
    BoardSettings_save_confirmation
  10. If the connection is established, you’ll see the following message on the top of the settings dialog:
    BoardSettings_connected_to_JIRA
    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.



Comments

Comment by Christian

Is there a way to import my cards into a specific board of a project? When I go into the Tool Integration settings for my board, all I see is the JIRA project. Plus, I have it connected, but I'm still not seeing the cards imported....any help?

Comment by Arpi

Dear Christian,
After you set up the connection to JIRA, you can import issues from integration settings, or from the board's toolbar Tool integration / Import cards from JIRA menu.
If you have problems setting up the integration, please contact us using the feedback widget in the bottom right corner. We'll answer your questions within a few hours.
Thanks,

Comment by Daniel

Is there a way to import only stories from a specific sprint? Import seems to pull in closed stories too, it'd be great to have some control over this or to be prompted on what to pull in and then place them in batches or something.

Comment by Arpi

@Daniel, in the next release it will be possible to filter out closed stories when importing from JIRA (and Trello's archived cards, and Pivotal Tracker's accepted stories).

Comment by sarah

Hi, Is there any way of pulling the following into JIRA:
- story points
- sprint a story is associated to
thanks
Sarah

Comment by Mark Ulferts

We're a pretty large company with 20 development teams. We have one single project in Jira. We use a custom field for the team. It makes Jira management much easier for us to have a single project.

The problem I encountered was that I can't filter the import down from the full project. I'd be great if I could provide a JQL statement to be used for the integration sync.

I did try and sync our full project just to see what happens, but looks like you have a cap on the number of issues that can be imported. That's fine as it wouldn't have worked will for us anyway.

We really like your product and would indeed pay for it. Several projects here have adopted it's use, but without Jira integration the teams are only using it for initial planning. Thus, it's not sticky. They want to use it all the time as a better backlog view. Let me know if this request makes your list.

Thanks.

Comment by Arpi

Mark,

Thanks for the feedback! I'm answering it in e-mail, as I have additional questions.

Comment by Praseed

Hello.

We have started looking at this tool. We are comparing this to FeatureMap as well.
JIRA integration is not fully setup yet. When we do "Connect to JIRA" we receive a "the tool did not provide a request token" issue on Storiesonboard.
What are we missing? When we did the webhooks url, it navigated to our jira instance (non-cloud) fine.
Appreciate your help on this
Praseed

Comment by Arpi

Dear Praseed,

Please send a message using the feedback widget in the application. This way we can help you directly.

Thanks

Comment by Oliver Mott

Hi,
Just thought I would let you know that point no.3 is wrong. It says:
'3. Open up JIRA Add-on Settings / Application links ...', when in fact it's the 'Applications' section that the 'Application Links' link is under (not the Add-ons). I'm on the on-demand version, not sure if it's different with the on-premise, but thought it was worth mentioning.
Took me a while to find it, but now working really well.
Software looks great, many thanks! :)

Comment by Oliver Mott

Hi,

Thanks again for this software.

We've imported our tickets from JIRA but I don't think the 'Ignore closed issues on import' function is working correctly. I tried a second time to test (double checking that I had selected the option, plus not selecting the 'Closed' status under the story dropdown) but it seems to bring over tickets with status of 'Closed' regardless?

It's not a problem for me but thought I would mention it.

Many thanks! :)

Comment by Arpi

Thanks Oliver! We'll update the guide.
For ignoring the closed issues, could you contact us using the feedback widget? We'd like to ask more information about the issues that may not be public.

Comment by Davor Fisher

Hi,
I have this set up on our jira stage environment to be tested first; everything works except the issue once changed in jira does not reflect back on StoriesOnBoard! Is this due to the fact that i am doing the initial test in jira stage and not prod?

Thanks

Davor Fisher
Comment by Arpi

Dear Davor,
Integration shouldn't depend on wether you use stage or prod environment. Please contact us using the feedback widget in the bottom right corner, so we can find out why it's not working.

Thanks

Comment by Jason Knight

Is there a way to link a new card in SoB to an existing issue tracker item e.g. user story, trello card, etc? I have a large backlog and want to start using SoB, but the only way I know to synchronize cards with Jira is by importing a full backlog.

Comment by Liz

HI - can you use this feature on the free download trial?
I can't seem to login or find who is a Wsorkspace Administrator?

Thanks

Liz
Comment by Arpi

Jason,
I'm sorry, but currently there no way to connect existing cards to Jira issues. Please vote for it's feature request here: storiesonboard.uservoice.com/.../13136502-connect-a-card-to-an-existing-issue-in-jira
There's also another request that might help you about connecting to Jira by a JQL query for importing part of a Jira project: storiesonboard.uservoice.com/.../10373976-allow-for-importing-from-jira-based-on-a-query-ins
Please vote on it too, and leave a comment about why would you need it.
Thanks!

Comment by Arpi

Liz,
Please contact us using the feedback widget in the application's bottom right corner. We can help you better there.
Thanks,

Comment by Sushama

Is there a way to export the whole storyboard to a Jira project or do you have to do it one card at a time?

Sushama
Comment by Arpi

Sushama,
You can export all the cards in a release to Jira from the release's menu. Please let me know if that doesn't suit your needs.

Comment by Charles

I can't tell from a quick scan, but does this integration require punching a hole in our firewall to allow Stories on Board to connect? If so, it would be helpful to include a list of IP addresses we would have to whitelist for the connections.

Charles
Comment by Arpi

Hi Charles,
Yes, for the integration to work StoriesOnBoard needs to access your Jira instance.
The two IP addresses are: 54.88.136.216, 54.84.188.199
Thanks for bringing our attention that it is missing from the article!
Please feel free to contact us with the feedback widget in the app's bottom right corner if you need help with the Jira setup.

Comment by Jeff

I've set up JIRA integration and the white SoB cards push in fine as stories. How do I push the yellow cards into JIRA as Epics? Can I also push the blue cards in as Features? Cool product by the way.

thx

Comment by Sam

If a card has been deleted from JIRA, does it delete the card in the map? How can I know a card is or is not in JIRA?

Sam
Comment by Sam

Also, if I push a card from storymap to JIRA, it defaults to task. Can I create a card in such a way that when I push to JIRA, it is created as a story in JIRA?

Sam
Comment by Arpi

Sam,

I'm sorry for the late answer.
When a deletion occurs in any of the systems, this doesn't delete anything from the other system for safety reasons.
When an issue is deleted in JIRA, only the connection is deleted from the card in StoriesOnBoard. You can see that the small "network" icon disappears from the card's bottom right corner when it is not linked to a JIRA issue anymore.

When pushing a card to JIRA, it is pushed as the issues type that is selected in the Issue Tracker Integration settings of the board, under the Export options header.

If you have more questions, please feel free to contact us with the feedback widget at the bottom right corner of the app. We can answer questions made there within a few hours.

Comment by Sion

Is there anything on the roadmap to include the Jira issue number in the card when it is imported from Jira?

Post comment