Jira Integration Help
Building a story map in CardBoard then pushing it to Jira
The first thing to understand with the CardBoard to Jira integration is that it will only sync Epics and Stories. When building your boards, put your epics in the first row in CardBoard. The first row will turn into epics in Jira when synced. All other rows in CardBoard will turn into stories in Jira. Also, a story under an epic will be linked in Jira. It works best when you push to a new Jira project without any issues in it yet. If you do have epics and stories in the project you choose to sync with, those epics and stories will be brought into CardBoard.
Here’s an example of how to do it
On-Premise Jira Server
If you plan on connecting to your company’s on-prem Jira, you need to make sure that you can see it from the Internet. CardBoard cannot connect to Jira instances that are hidden behind a firewall. CardBoard works beautifully with Jira Cloud.
Signing into Jira
You have two ways to supply your credentials to Jira by either using an API token or OAuth. For your Jira Instance URL, you need to enter the URL of your cloud version (for example: https://cardboardit.atlassian.net) or on-prem version.
Next, enter your Username and API Token or Password. In May of 2019, Jira stopped supporting Basic Authentication for Jira Cloud users. Instead, create API Tokens and enter the token in the API Token or Password field. On-prem users may still be able to enter their passwords.
If something wasn’t entered correctly, CardBoard will either tell you:
- Your Jira Instance URL is invalid
- Authentication failed due to your credentials not being correct.
If you use SSO to connect to Jira, you will need to use OAuth. OAuth is a more secure form of authenticating that uses a token instead of a user’s credentials.
IMPORTANT: At this time we only support OAuth with Jira Server and not Jira Cloud. When OAuth is out of beta in Jira Cloud, we will implement it.
Before using OAuth to authenticate, you need to set it up and configure it in Jira.
In Jira, click > Applications > Application links.
In the “Enter the URL of the application you want to link” field, enter the CardBoard app URL, https://app.cardboardit.com, and then click Create new link.
You’ll get a warning that “No response was received from the URL you entered”. Ignore it and click Continue.
Now, give it an Application Name (e.g. CardBoard) and keep the Application Type as Generic Application.
Record the values for Shared secret. You will use this in CardBoard later to authenticate.
Make sure you check the Create incoming link checkbox. Then click Continue.
On the next screen of the Link Applications dialog, enter the consumer details for the client
- Consumer key =
- Consumer name = CardBoard
- Public key = Enter the public key below:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
Then click Continue. The Application Link should be created successfully.
In CardBoard, enter your Jira Instance URL, for the Consumer Key enter “OauthKey”. For the Consumer Secret, enter “example”.
For more information, see:
Configuring Jira to use Story Points
If you want to do story pointing or estimating in CardBoard, you need to configure your Jira instance correctly. Also, make sure you use whole numbers for your estimates or your sync with Jira will fail. This video can help you enabling syncing of Story Points.
Open the Jira Issue from CardBoard
Once you are synced with Jira, you can open the Issue directly from CardBoard. To do this, expand the card, then click “Open in Jira”.
Deleting cards when synced with Jira
Be careful when you delete cards in CardBoard. When you re-sync with Jira, they will be deleted in Jira.
Can I sync one board to multiple projects? How about multiple boards to the same project?
As of now, you can only sync one CardBoard board to one Jira project and everything is transferred — there is no selective sync. That is, if you make a change in CardBoard that change will be synced to your project. Same for the other way around, when you make a change in a project and sync with CardBoard, your board will reflect that change. Unlike blackholes, all information is retained and transferred.
You can, however, connect multiple boards to a single project where all those boards will contain the same data as the other boards and the project. (We recommend this only with a very intentional meaning behind doing so.)