The easiest way to create an add-on for JIRA and Confluence.
| Laravel | Package |
|---|---|
| 5.5.x | 1.2.x |
| 6.x | 1.3.x |
Install dependency via Composer
$ composer require "brezzhnev/atlassian-connect-core"Register route middleware jwt by adding to app\Http\Kernel.php the following line:
'jwt' => \AtlassianConnectCore\Http\Middleware\JWTAuth::classSet the authentication driver to jwt in config/auth.php:
'guards' => [
'web' => [
'driver' => 'jwt',
'provider' => 'users',
],
...Set the model class in config/auth.php providers section:
'providers' => [
'users' => [
'driver' => 'eloquent',
'model' => \AtlassianConnectCore\Models\Tenant::class,
],
...Register the subscriber in the app/Providers/EventServiceProvider.php:
/**
* The subscriber classes to register.
*
* @var array
*/
protected $subscribe = [
\AtlassianConnectCore\Listeners\PluginEventSubscriber::class
];Configure the database and run:
php artisan migrate
php artisan plugin:install
The command php artisan plugin:install will publish config, views and resources that you can change for your needs.
Also, it will create "dummy" tenant needed for local testing and developing without needing of installing the add-on on real JIRA or Confluence instances.
If your application returns the add-on descriptor on the request to URL
http://localhost:8000/atlassian-connect.jsonit means you are close to happiness and you can install the add-on.
Step 1. Make your application accessible
To install the add-on in the instance, you should be visible through the internet. For testing purposes the easiest way is to use ngrok.
Then you have it accessible, put your actual website URL to environment variable PLUGIN_URL.
Make sure your add-on is accessible via HTTPS, it is a requirement.
Step 2. Configure your JIRA / Confluence instance
Configure your add-on using config/plugin.php. Most values may be overwritten using env vars.
Step 3. Upload your add-on
Finally, you need to upload the add-on. Click "Upload add-on" and paste your public URL with descriptor path,
eg. https://d1ea31ce.ngrok.io/atlassian-connect.json or https://yourplugindomain.com/atlassian-connect.json
Step 4. Testing the successfulness
After the successful installation, on JIRA instance you may see "Your add-on" top menu item.
You also can go to the add-on general page by direct link :product_base_url/plugins/servlet/ac/sample-plugin/hello-page
Instead of
:product_base_urlyou should put your JIRA or Cofluence instance URL (eg.https://google-dev.atlassian.net).
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 the publishes you should use the following command:
php artisan vendor:publish --provider="AtlassianConnectCore\ServiceProvider"
To copy only specific publish you must call this command with option --tag.
The value can be public (to copy assets), views and config.
The following routes are registered by default:
GET /atlassian-connect.jsondescriptor contentsPOST /installedadd-on installed callbackPOST /uninstalledadd-on uninstalled callbackPOST /enabledadd-on enabled callbackPOST /disabledadd-on disabled callbackGET /hellosample page to persuade all working correctly
You may disable them by setting the config value plugin.loadRoutes to false.
You can use Descriptor facade to customize or create from scratch your own descriptor contents.
For example, you may customize it by adding to the app\Providers\AppServiceProvider in 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 theAppServiceProvideryou should haveRouteServiceProviderdefined aboveAppServiceProviderin yourapp.phpconfig.
In most cases of add-on development for Atlassian Product you need to perform requests to the instance.
For this case you can use JWTClient. It uses GuzzleHttp as HTTP client.
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 be instantiated automatically by resolving
your Tenant product type (JIRA or Confluence), but you always can use the specific paginator.
There are two paginators supported by default:
JiraPaginatorConfluencePaginator
You're always able to extend Paginator class and create your own.
Get a Confluence page content
use AtlassianConnectCore\Http\Clients\JWTClient;
/**
* Retrieve a Confluence page content.
*
* @return array
*/
public function pageContent(int $id): array
{
$client = new JWTClient($this->tenant); // or Auth::user() if you performing a request from the instance
return $client->get('rest/api/content/' . $id, [
'query' => [
'expand' => 'body.storage'
]
]);
}Get a JIRA issue
use AtlassianConnectCore\Http\Clients\JWTClient;
/**
* Retrieve an issue object.
*
* @return array
*/
public function viewIssue(string $key): array
{
$client = new JWTClient($this->tenant);
return $client->get('rest/api/2/issue/' . $key);
}The plugin provides a convenient way to handle incoming webhooks, based on habitual Laravel Events.
If you don't familiar with Laravel Events, please take a look at Laravel Docs
There are two ways to define webhook listeners:
1. Define listeners in the config/plugin.php
'webhooks' => [
'jira:issue_updated' => \App\Listeners\Webhooks\Issue\Created::class,
...
]2. Define listeners using the Webhook facade, for example:
Webhook::listen('jira:issue_created', function(\AtlassianConnectCore\Models\Tenant $tenant, \Illuminate\Http\Request $request) {
// ...
});As you can see, you can define event listener as a closure or as a string in Laravel-like syntax:
Webhook::listen('jira:issue_created', \App\Listeners\Webhooks\Issue\Created::class);
Webhook::listen('jira:issue_created', 'App\Listeners\Webhooks\Issue\Created@handle');You don't need to define the webhooks within your add-on descriptor, they will be described automatically.
<?php
namespace App\Listeners\Webhooks\Issue;
use Illuminate\Http\Request;
use AtlassianConnectCore\Models\Tenant;
class Created
{
/**
* Create the event listener.
*
* @return void
*/
public function __construct()
{
//
}
/**
* Handle the incoming webhook.
*
* @param \AtlassianConnectCore\Models\Tenant $tenant
* @param \Illuminate\Http\Request $request
*
* @return void
*/
public function handle(Tenant $tenant, Request $request)
{
// ...
}
}Your event listeners may also type-hint any dependencies they need on their constructors. All event listeners are resolved via the Laravel service container, so dependencies will be injected automatically.
plugin:installis a helper command that creates "dummy" tenant with the fake data and publishes package resources (config, views, assets)plugin:dummyprovides interactive way to set a tenant as "dummy" without manually editing database
Run the following in the package folder:
vendor/bin/phpunit
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent