| Copyright | (c) Robert Massioli 2014 |
|---|---|
| License | APACHE-2 |
| Maintainer | rmassaioli@atlassian.com |
| Stability | experimental |
| Safe Haskell | None |
| Language | Haskell2010 |
Snap.AtlassianConnect
Contents
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.
- initConnectSnaplet :: Plugin -> SnapletInit b Connect
- data Connect = Connect {}
- class HasConnect m where
- type HostName = Text
- type UserKey = Text
- type UserEmail = ByteString
- type IssueKey = Text
- type IssueId = Integer
- type ProjectKey = Text
- type ProjectId = Integer
- type IssueSummary = Text
- data UserDetails = UserDetails {}
- data IssueDetails = IssueDetails {}
- getLifecycleResponse :: Handler b a (Maybe LifecycleResponse)
- data LifecycleResponse = LifecycleResponseInstalled {}
- type ClientKey = Text
- data Tenant = Tenant {
- tenantId :: Integer
- key :: TenantKey
- publicKey :: Text
- sharedSecret :: Text
- baseUrl :: ConnectURI
- productType :: Text
- type TenantKey = Text
- type TenantWithUser = (Tenant, Maybe UserKey)
- data PageToken = PageToken {}
- generateToken :: TenantWithUser -> UTCTime -> PageToken
- generateTokenCurrentTime :: TenantWithUser -> IO PageToken
- encryptPageToken :: AES -> PageToken -> ByteString
- decryptPageToken :: AES -> ByteString -> Either String PageToken
- defaultTimeoutSeconds :: ConnectSecond
- homeHandler :: Handler b Connect () -> Handler b Connect ()
- newtype ConnectURI = CURI URI
- getURI :: ConnectURI -> URI
- newtype ConnectSecond = CSecond Second
- getSecond :: ConnectSecond -> Second
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.
The Atlassian Connect Snaplet Context
Constructors
| Connect | |
Fields
| |
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.
Minimal complete definition
Methods
getConnect :: m Connect Source #
Atlassian Standard Types
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.
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 | |
Instances
data IssueDetails Source #
Represents simple issue details that every Atlassian JIRA issue will have.
Constructors
| IssueDetails | |
Fields
| |
Instances
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
| |
type ClientKey = Text Source #
Represents the 'client key' from the Atlassian Connect framework in the host product.
Represents an Atlassian Cloud tenant. Your Atlassian Connect add-on can be installed into multiple Atlassian Cloud tenants.
Constructors
| Tenant | |
Fields
| |
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
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
| |
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
getURI :: ConnectURI -> URI Source #
Get a regular URI from an Atlassian Connect URI
getSecond :: ConnectSecond -> Second Source #
Gets the Data.Time.Units representation of this Atlassian Connect second.