Atlassian Connect Framework to build add-on for the JIRA and Confluence
Atlassian Connect Framework to build add-ons for the JIRA and Confluence
- Laravel 5.5
- PHP ~7.0
Install dependency via Composer
$ composer require brezzhnev/atlassian-connect-core
Register route middleware
jwt by adding to the
app\Http\Kernel.php following line
'jwt' => \AtlassianConnectCore\Http\Middleware\JWTAuth::class
Set authentication driver to
'guards' => [ 'web' => [ 'driver' => 'jwt', 'provider' => 'users', ], ...
Set model class in
config/auth.php providers section
'providers' => [ 'users' => [ 'driver' => 'eloquent', 'model' => \AtlassianConnectCore\Models\Tenant::class, ], ...
Register plugin events by adding to the
app/Providers/EventServiceProvider.php to the
listen property value following
\AtlassianConnectCore\Events\Installed::class => [ \AtlassianConnectCore\Listeners\CreateOrUpdateTenant::class ], \AtlassianConnectCore\Events\Uninstalled::class => [ \AtlassianConnectCore\Listeners\DeleteTenant::class ]
You can use any add-on events to register your own listeners
Register subscriber in the same file:
/** * The subscriber classes to register. * * @var array */ protected $subscribe = [ \AtlassianConnectCore\Listeners\PluginEventSubscriber::class ];
Configure database and run
php artisan migrate php artisan plugin:install
php artisan plugin:install will publish config, views and resources that you can change whatever you want.
Also, it will create "dummy" tenant needed for local testing and development without the need of installing the add-on in real JIRA or Confluence instance.
If your application returns the add-on descriptor on the request
http://localhost:8000/atlassian-connect.json it means you are close to getting it working and you can
install the add-on.
Firstly, you need to enable development options. Go to the "Manage add-ons" page. You'll see the link "Settings" at bottom of page. After clicking you'll see two checkboxes that must be selected. Apply your changes.
For installing the add-on in the instance it should see your server. If you working locally the easiest way is use ngrok.
After you are visible for the JIRA or Atlassian instance you should put your actual website URL to environment variable
PLUGIN_URL. Also, you need to configure your add-on by editing the file
config/plugin.php. Most values may be overwritten using env vars.
Then you need to upload the add-on. Click "Upload add-on" and paste your public URL with descriptor path,
Note: HTTPS is required
After successfully installing you can see "Your add-on" top menu item (in case of JIRA).
You also can go to the add-on general page by direct link
:product_base_url you should put your JIRA or Cofluence instance URL (eg.
If you see page working, the application configured and add-on installed correctly.
Instead of using
plugin:install you can perform actions manually.
To copy all publishes you should use following commands:
artisan vendor:publish --provider="AtlassianConnectCore\ServiceProvider"
To copy only specific publish you must call this command with option
Value can be
public (to copy assets),
After copying publishes you can see the file
config/plugin.php in your application. Please, use this configuration file to change add-on properties.
The following routes registered by default
GET /atlassian-connect.jsondescriptor contents
POST /installedadd-on installed callback
POST /uninstalledadd-on uninstalled callback
POST /enabledadd-on enabled callback
POST /disabledadd-on disabled callback
GET /hellosample page to persuade all working correctly
You can disable it by setting to
false config value
You can use
Descriptor facade to customize or create from scratch your own descriptor contents.
For example, you can customize it by adding to the
boot section the following:
Descriptor::base() // base descriptor contents ->setScopes(['admin' , 'act_as_user']) ->withModules([ 'webhooks' => [[ 'event' => 'jira:issue_created', 'url' => route('webhookHandlerRouteName') ]] ]) ->set('version', $this->getLatestPluginVersion());
Warning: if you are using
routehelper in the
AppServiceProvideryou should have
In most of cases in development add-on for Atlassian Product you need to perform requests to the instance.
For this case you should use
JWTClient. It uses GuzzleHttp as HTTP client and
if you want to have custom handling (middlewares etc.) you can pass client instance to the constructor.
If you want to send a request to an endpoint with pagination you should use
JWTClient::paginate method. In most cases
you don't need to pass paginator instance to the
JWTClient constructor because it will instantiate automatically by resolving
your Tenant product type (JIRA or Confluence), but you always can use specific paginator.
There are two paginators:
Of course you can extend
Paginator class and create your own.
plugin:installis a helper command that creates "dummy" tenant with fake data and publishes package resources (config, views, assets)
plugin:dummyprovides interactive way to set tenant as "dummy" without manually editing database
Run the following in the package folder:
- Implement descriptor builder and validator
- Implement webhooks manager
- Take out pagination and make more abstract
If you discover any security related issues, please email email@example.com instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.