Copyright	(c) Robert Massioli, 2014
License	APACHE-2
Maintainer	rmassaioli@atlassian.com
Stability	experimental
Safe Haskell	None
Language	Haskell2010

Snap.AtlassianConnect

Contents

Connect Snaplet
Atlassian Standard Types
Lifecycle and Tenant
Page Tokens
Routes Helpers
Connect Data Types

Description

This module provides an Snap Framework Snaplet for the Atlassian Connect framework. In order to use it in your snap application you just need to run initConnectSnaplet in your initialiser like so:

appConnect <- nestSnaplet "connect" connect (initConnectSnaplet myPluginDescriptor)

All you need to provide us with is a descriptor that you have generated using the atlassian-connect-descriptor library.

It is important to note that certain configuration values can be overriden with Environment Variables because they may be specific to the environment that you deployed the service to:

Use CONNECT_BASE_URL to override the Base Url in the Addon Descriptor.
Use CONNECT_SECRET_KEY to override the Page Token Secret Key.

To test that it has worked you can start your application and find your descriptor at: /connect/atlassian-connect.json

We will also automatically create a connect.cfg file for you in the snaplets/connect directory. If this does not happen then delete the snaplets/connect directory and restart your application. Please have a look inside the connect.cfg directory as there will be plugin specific setting that you will have to override. It is likely that you will want to override all of those configuration options.

Synopsis

Connect Snaplet

initConnectSnaplet :: Plugin -> SnapletInit b Connect Source

Initialise the Atlassian Connect part of this application. This gives you an Atlassian Connect configuration that comes with:

An Atlassian Connect configuration file.
The definition of what it means to be an Atlassian Connect Tenant.
Default routes for your Atlassian Connect Descriptor. (With automatic configuration injection of Plugin Keys / Names)
Page Token support
Host Whitelist Support

In short, it is the easy way to get up and running with Atlassian Connect in your Snap applications.

data Connect Source

The Atlassian Connect Snaplet Context

Constructors

Connect

Fields

connectAES :: AES: The AES key that will be used for Page Token support.
connectPageTokenTimeout :: Timeout: The Page Token Timeout (how long the token is valid for).
connectPlugin :: Plugin: The Atlassian Connect Descriptor for your Add-on.
connectBaseUrl :: URI: The URL that your Add-on will report as it's base URL. Especially useful if you are behind a load balancer.
connectHostWhitelist :: [HostName]: The suffixes in the hostname that should be allowed to be installed as Connect Add-ons.

class HasConnect m where Source

If a Snap application provides Atlassian Connect then it can impliment HasConnect to allow connect methods to be called easily.

Methods

getConnect :: m Connect Source

type HostName = Text Source

Represents a URL hostname

Atlassian Standard Types

type UserKey = Text Source

Represents an Atlassian User Key. This is guaranteed to be unique on any given tenant.

type UserEmail = ByteString Source

Represents an Atlassian User Email. This has no uniqueness guarantees; an email does not map to a unique user.

type IssueKey = Text Source

The Key of an Atlassian JIRA issue. They are usually in the format ProjectKey-IssueNumber. Please note that issues can be moved between projects so this is not guaranteed to remain constant.

type IssueId = Integer Source

The ID of an Atlassian JIRA issue. This id will never change and will always refer to the same issue. It is an immutable reference to a JIRA issue.

type ProjectKey = Text Source

The user visible key of an Atlassian JIRA Project. Project Keys are not guaranteed to remain the same forever.

type ProjectId = Integer Source

The project id of an Atlassian JIRA Project. The same project will always have the same project id. The project id is immutable for a given project.

type IssueSummary = Text Source

Represents an Atlassian JIRA Issue summary.

data UserDetails Source

Represents the user details of an Atlassian JIRA user.

Constructors

UserDetails
Fields userKey :: UserKey userEmail :: UserEmail

Instances

Show UserDetails Source
Generic UserDetails Source
type Rep UserDetails Source

data IssueDetails Source

Represents simple issue details that every Atlassian JIRA issue will have.

Constructors

IssueDetails
Fields issueKey :: IssueKey issueId :: IssueId issueSummary :: IssueSummary

Instances

Show IssueDetails Source
Generic IssueDetails Source
type Rep IssueDetails Source

Lifecycle and Tenant

getLifecycleResponse :: Handler b a (Maybe LifecycleResponse) Source

A convenience method to get a Lifecycle Response from the response body.

data LifecycleResponse Source

When an Atlassian Connect plugin is installed or uninstalled this is the lifecycle response that your add-on will be sent (in JSON). Use this data structure to handle lifecycle event data from the host application.

Constructors

LifecycleResponseInstalled
Fields lrKey :: Text lrClientKey :: ClientKey lrPublicKey :: Text lrSharedSecret :: Maybe Text lrServerVersion :: Maybe Text lrPluginsVersion :: Maybe Text lrBaseUrl :: ConnectURI lrProductType :: Maybe Text lrDescription :: Maybe Text lrEventType :: Maybe Text

Instances

Eq LifecycleResponse Source
Show LifecycleResponse Source
Generic LifecycleResponse Source
FromJSON LifecycleResponse Source
type Rep LifecycleResponse Source

type ClientKey = Text Source

Represents the 'client key' from the Atlassian Connect framework in the host product.

data Tenant Source

Represents an Atlassian Cloud tenant. Your Atlassian Connect add-on can be installed into multiple Atlassian Cloud tenants.

Constructors

Tenant

Fields

tenantId :: Integer: Your identifier for this tenant.
key :: TenantKey: The unique identifier for this tenant accross Atlassian Connect.
publicKey :: Text: The public key for this atlassian connect application.
sharedSecret :: Text: The shared secret for this atlassian connect application. Used for JWT token generation.
baseUrl :: ConnectURI: The base url of the Atlassian Cloud host application (product).
productType :: Text: The type of product you have connected to in the Atlassian Cloud. (E.g. JIRA, Confluence)

Instances

Eq Tenant Source
Show Tenant Source
Generic Tenant Source
FromJSON Tenant Source
type Rep Tenant Source

type TenantKey = Text Source

Represents a tenant key. The unique identifier for each Atlassian Connect tenant.

type TenantWithUser = (Tenant, Maybe UserKey) Source

When we get a tenant from Atlassian Connect we can also optionally reciever the user key that made the request. This structure reflects that possibility.

Page Tokens

data PageToken Source

Page Tokens are your way of providing a token to the client's browser and have them make trusted requests back to the Atlassian Connect application without having to go through the host product.

Constructors

PageToken
Fields pageTokenHost :: TenantKey The Atlassian Cloud tenant that this token was generated for. pageTokenUser :: Maybe UserKey The potential user that this token was generated for. pageTokenTimestamp :: UTCTime The time at which this token was generated. pageTokenAllowInsecurePolling :: Bool (Deprecated) This is currently unsupported. Don't use it.

Instances

Eq PageToken Source
Show PageToken Source
ToJSON PageToken Source
FromJSON PageToken Source

generateToken :: TenantWithUser -> UTCTime -> PageToken Source

Given a tentant, a potential user and a time generate a page token.

generateTokenCurrentTime :: TenantWithUser -> IO PageToken Source

Given a tenant and a potential user generate a token for the current time.

encryptPageToken :: AES -> PageToken -> ByteString Source

Given an AES context encrypt a page token into a bytestring.

decryptPageToken :: AES -> ByteString -> Either String PageToken Source

Given an AES context decrypt a page token.

defaultTimeoutSeconds :: ConnectSecond Source

The default timeout for a Page Token. It is likely that you will want to make this longer.

Routes Helpers

homeHandler :: Handler b Connect () -> Handler b Connect () Source

In old versions of Atlassian Connect, if you queried the application root and your Accept headers wanted an "application/json" response then they would return your Atlassian Connect descriptor and if the Accept headers requested "text/html" then they returned your applications home page. This is a convenience method to enable that behaviour to continue. If you use this method in your routes then you can make your home page behave in the same way. This is not required for an Atlassian Connect application so feel free to just return home page content on your home page and ignore this method.

Connect Data Types

newtype ConnectURI Source

An Atlassian Connect URI

Constructors

CURI URI

Instances

Eq ConnectURI Source
Show ConnectURI Source
FromJSON ConnectURI Source

getURI :: ConnectURI -> URI Source

Get a regular URI from an Atlassian Connect URI

newtype ConnectSecond Source

Represents a second for Atlassian Connect

Constructors

CSecond Second

Instances

Eq ConnectSecond Source
Show ConnectSecond Source
Configured ConnectSecond Source

getSecond :: ConnectSecond -> Second Source

Gets the Data.Time.Units representation of this Atlassian Connect second.