Flask-AtlassianConnect

Flask-AtlassianConnect helps to do all the heavy lifting for creating Atlassian Connect based integrations using a Flask application

Installation

Install Flask-AtlassianConnect with pip command:

$ pip install Flask-AtlassianConnect

or check out development version:

$ git clone git://github.com/halkeye/flask_atlassian_connect.git

How to Use

Flask-AtlassianConnect is pretty easy to use. You give it a flask application. Tell it where to save/load installation info from, and the rest are simple decorators

Basic usage:

from flask import Flask
from flask_atlassian_connect import AtlassianConnect

app = Flask(__name__)
ac = AtlassianConnect(app)

@ac.webhook('jira:issue_created')
def handle_jira_issue_created(client, event):
    pass

if __name__ == '__main__':
    app.run()

When your app is all up and running, access /atlassian_connect/descriptor to get to your atlassian connect descriptor file.

Configuration

  • APP_NAME =

  • ADDON_NAME = “Marketplace App Name”

  • ADDON_KEY = “Marketplace Addon Key”

  • ADDON_DESCRIPTION = “Description”

  • ADDON_VENDOR_URL = ‘https://saucelabs.com’

  • ADDON_VENDOR_NAME = ‘Sauce Labs’

Template Variables

  • atlassian_jwt_post_url - If used in your template form, it will automatically validate and pull client info again

Customizing

Decorators

API

Configuration

class flask_atlassian_connect.AtlassianConnect(app=None, client_class=<class 'flask_atlassian_connect.client.AtlassianConnectClient'>)

This class is used to make creating an Atlassian Connect based addon a lot simplier and more straight forward. It takes care of all the authentication and authorization for you.

You will need to provide a Client class that contains load(id) and save(client) methods.

init_app(app)

Initialize Application object stuff

Parameters

app (flask.Flask) – App Object

lifecycle(name)

Lifecycle decorator. See external lifecycle documentation

Example:

@ac.lifecycle("installed")
def lifecycle_installed(client):
    print "New client installed!!!!"
    print client

Payload:

{
    "key": "installed-addon-key",
    "clientKey": "unique-client-identifier",
    "sharedSecret": "a-secret-key-not-to-be-lost",
    "serverVersion": "server-version",
    "pluginsVersion": "version-of-connect",
    "baseUrl": "http://example.atlassian.net",
    "productType": "jira",
    "description": "Atlassian JIRA at https://example.atlassian.net",
    "serviceEntitlementNumber": "SEN-number",
    "eventType": "installed"
}
Parameters

name (string) –

Which atlassian connect lifecycle to handle.

At time of writing, the following are the only options:

  • installed

  • uninstalled

  • enabled

  • disabled

Each of the above will call your Client’s save and load methods

module(key, name=None, location=None)

Module decorator. See external modules documentation

Example:

@ac.module("configurePage", name="Configure")
def configure_page(client):
    return '<h1>Configure Page</h1>', 200
Parameters

  • key –

    A key to identify this module.

    This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

    Keys must only contain alphanumeric characters and dashes.

  • location – The location in the application interface where the web section should appear. For the Atlassian application interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or navigation list in the UI.

  • name – A human readable name.

tasks()

Function that turns a collection of tasks suitable for pyinvoke

Example:

from app.web import ac
ns = Collection()
ns.add_collection(ac.tasks())
webhook(event, exclude_body=False, **kwargs)

Webhook decorator. See external webhooks documentation

Example:

@ac.webhook("jira:issue_created")
def jira_issue_created(client, event):
    print "An issue was just created!"
    print "Take a look at this:"
    print event
Parameters

  • event (array) – Specifies the named event you would like to listen to (e.g., “enabled”, “jira:issue_created”, etc.)

  • exclude_body – Specifies if webhook will send JSON body when triggered. By default, a webhook will send a request with a JSON body.

  • filter – Filter for entities that the webhook will be triggered for. Refer to the documentation on filtering for details.

  • propertyKeys – Specifies entity properties which will be returned inside JSON body. If not specified no properties will be returned.

webpanel(key, name=None, location=None, **kwargs)

Webpanel decorator. See external webpanel documentation

Example:

@ac.webpanel(key="userPanel",
    name="Employee Information",
    location="atl.jira.view.issue.right.context",
    conditions=[{
        "condition": "project_type",
        "params": {"projectTypeKey": "service_desk"}
    }])
def employee_information_panel(client):
    return 'this is issue %s' % request.args.get('issueKey')
Parameters

  • key –

    A key to identify this module.

    This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

    Keys must only contain alphanumeric characters and dashes.

  • location – The location in the application interface where the web section should appear. For the Atlassian application interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or navigation list in the UI.

  • name – A human readable name.

Anything else from the external webpanel docs should also work

Fallback Client Model

class flask_atlassian_connect.AtlassianConnectClient(**kwargs)

Reference implementation of Client object

Variables

  • clientKey – Confluence/Jira/Etc Unique Identifier

  • sharedSecret – Shared secret between instance and addon

  • baseUrl – Url for Confluence/Jira/Etc

static all()

Returns a list of all clients stored in the database

Returns

list of all clients

Return type

list

static delete(client_key)

Removes a client from the database

Parameters

client_key – jira/confluence clientKey to load from db

static load(client_key)

Loads a Client from the (internal) database

Parameters

client_key – jira/confluence clientKey to load from db

Return type

Client or None

static save(client)

Save a client to the database

Parameters

client – Client object (Default Class or overriden class) to save

Licensing and Author

This project is licensed under Apache2. See LICENSE for the details.

I’m Gavin Mogan. Feel free to open tickets if you need help. This was something that worked for me so I thought I’d share.

Indices and tables