Integrate Jira with CardBoard

Building a story map in CardBoard then pushing it to Jira

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.

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.

Signing into Jira

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.

Using OAuth

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.cardboarddedev.wpengine.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 = OauthKey
• Consumer name = CardBoard
• Public key = Enter the public key below:

—–BEGIN PUBLIC KEY—–
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApbtDjHkVHn+kVpeinaTE
UwR0QWLiESK5wD8aDOl6euKtN8yKqFOgmtKph+bC6ZTOFLIiX9n6vKLCXYgkrboz
/jNZ3AvZ977Wozep6qkhsj1OzCEf8gSCxnwfomeJ4991T9IZfcViDBOVbjc4Sgk0
UYZbj1XsRwyx1Bg3b+Txcqfd3y3qV/tlWJ+EQ9BdBV62YQn25FykteKX9/hot+dC
bTumvSY9xuMlhXI8iT0XNrVGctaFlqAcdFa3jiJyLkY381cQIzGGIohGlJoPoWhs
I27499ElmwZhCcp3UBeUzABEd9kMLrNMdkQZroB0gYAUlsXT2VVLeFPlvc1TqPf/
AQIDAQAB
—–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:

https://developer.atlassian.com/server/jira/platform/oauth/

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.)