When a user adds a URL from your application to a Jira Product Discovery insight in an idea, Jira Product Discovery will try to unfurl it to retrieve more data, using a provider for your app. This data can then be used to prioritize ideas in Jira Product Discovery. This refapp shows you how to create one of these unfurl providers.
Jira Product Discovery currently supports 2 authentication mechanisms:
- API keys: the user pastes a user API key to authenticate with your app's API
- OAuth2 Authorization Code Grant Flow: the user authenticates with your app's API using this flow (recommended: it's more user friendly)
We've added 2 examples in this refapp:
-
An unfurl provider for Jira issue URLs, using API keys, which works for any issue link the user has access to, in the form of
https://<YOUR_SITE_NAME>.atlassian.net/browse/ISSUE-KEY-1
-
An unfurl provider for a slack message URL in a Slack workspace where a custom app was installed, in the form of
https://<YOUR_WORKSPACE>.slack.com/archives/C01736E6Z37/p1613475464011300
, using the OAuth2 Authorization Code Grant Flow
The unfurl providers are built on and hosted on Atlassian Forge, our development platform, talking to your app's API.
-
Install the Forge CLI using this guide: https://developer.atlassian.com/platform/forge/getting-started
-
Install dependencies for the project
npm i
-
Create a
.env
file from.env.default
and define missing variables (ignoreFORGE_APP_ID
for now). -
Generate a manifest from the template using the following command:
npm run manifest
- Once the Forge CLI is installed, create new app using this command (confirm app details rewrite when prompted):
forge register
- Find your
FORGE_APP_ID
using this command:
npm run forge:appInfo
-
Copy the generated
FORGE_APP_ID
back to.env
-
Deploy the app to the development environment (
--no-verify
is required)
forge deploy -e development --no-verify
- Install the app on a Jira site:
forge install -p Jira -s <YOUR_SITE_NAME>.atlassian.net
-
Open a Jira Product Discovery idea, open the Insights Tab and test unfurling a URL to a Jira issue. Something in the form of:
https://<YOUR_SITE_NAME>.atlassian.net/browse/ISSUE-KEY-1
(from the same site or another site should work, as long as the user has access to this URL). This should return a card with information about the Jira issue. -
Test a URL using OAuth2 authentication, we've added an example unfurling a link to a Slack message:
First, create a Slack app Create App
- Open the "OAuth & Permissions" tab
- Set
Redirect URL
tohttps://id.atlassian.com/outboundAuth/finish
. - In the
Scopes / User Token Scopes
section add the OAuth scopes listed inmanifest.yml
.
Then run the following command to set up the OAuth2 client for your custom Slack app in Forge:
npm run externalAuth:set -- --email $EMAIL --api-token $ATLASSIAN_API_TOKEN --forge-app-id $FORGE_APP_ID --forge-env $FORGE_ENV --service-key $EXTERNAL_AUTH_SERVICE_KEY --client-id $SLACK_CLIENT_ID --client-secret $SLACK_CLIENT_SECRET
With the following values:
$EMAIL
is your @atlassian.com email address$ATLASSIAN_API_TOKEN
: generate an Atlassian API token$FORGE_APP_ID
: runnpm run forge:appInfo
command to find your Forge app id- set
$FORGE_ENV
todevelopment
- set
$EXTERNAL_AUTH_SERVICE_KEY
toslack
$SLACK_CLIENT_ID
: Copy the value from the Slack app configuration, inBasic information / App Credentials / Client ID
$SLACK_CLIENT_SECRET
: Copy the value from the Slack app configuration, inBasic information / App Credentials / Client Secret
-
Go to Slack, in a public channel, and copy the link to a Slack message (Right click on a message > copy link). Open a Jira Product Discovery idea, open the Insights Tab and test unfurling that URL. It should return a card with information about the Slack message.
-
All set 🎉
-
In addition to pull model we support pushing data via API. Read more here
- All our example build on top of the
@atlassianintegrations/polaris-forge-object-resolver
library. The README available here: README