README

关于

Atlassian Connect 平台的 Symfony Bundle

安装

步骤 1. 将包添加到 composer 依赖中

composer require thecatontheflat/atlassian-connect-bundle

步骤 2. 启用包

将包添加到 config/bundles.php

<?php

return [
    // ... other bundles
    AtlassianConnectBundle\AtlassianConnectBundle::class => ['all' => true],
]

步骤 3. 包配置

包描述符用于在 Atlassian 上安装您的应用。当请求描述符时，此配置将被转换为 JSON。

在 packages/atlassian-connect.yaml 中的示例配置

    atlassian_connect:
        dev_tenant: 1
        descriptor:
            key: 'your-addon-key'
            name: 'Your Add-On Name'
            description: 'Your Add-On Description'
            authentication:
            	type: jwt
            vendor:
                name: 'Your Vendor Name'
                url: 'https://marketplace.atlassian.com/vendors/1211528'
            baseUrl: 'https://your-production-domain.com/'
            lifecycle:
                installed: '/handshake'
            scopes: ['READ', 'WRITE', 'ACT_AS_USER'] # If you want get oauth_client_id need to add scope ACT_AS_USER
            modules:
                jiraIssueTabPanels:
                    -
                        key: 'your-addon-key-tab'
                        url: '/protected/list?issue=${issue.key}'
                        weight: 100
                        name:
                            value: 'Tab Name'

如果您需要在 dev/test 环境中覆盖任何配置，请在该环境的 packages/{env}/atlassian-connect.yaml 文件中覆盖该配置。

步骤 4. 安全配置

要配置安全部分，请使用以下配置在您的 security.yml 中。如果您有另一个具有 "^/" 模式的防火墙，请确保首先设置 jwt_secured_area 防火墙。

    security:
        enable_authenticator_manager: true
        providers:
            jwt_user_provider:
                id: jwt_user_provider
        firewalls:
            jwt_secured_area:
                custom_authenticators:
                    - AtlassianConnectBundle\Security\JWTAuthenticator
                pattern: "^/protected"
                stateless: true
                provider: jwt_user_provider
                # If you also need an entry_point
                entry_point: AtlassianConnectBundle\Security\JWTAuthenticator

步骤 5. 包含路由

将以下配置添加到 config/routes.yaml

    ac:
        resource: "@AtlassianConnectBundle/Resources/config/routing.php"

步骤 6.（可选）：配置许可证检查

要为特定路由执行许可证检查，请在您的 routing.yml 中指定 requires_license 默认值

    some_route:
        path: ...
        defaults:
            requires_license: true

步骤 7. 更新数据库

bin/console doctrine:schema:update --force

用法示例

签名请求

在您的 受保护 控制器操作中，您可以向 JIRA 实例发出签名请求

<?php declare(strict_types = 1);

namespace App\Controller;

use AtlassianConnectBundle\Service\AtlassianRestClient;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;

/**
 * @Route("/protected")
 */
class ProtectedController extends Controller
{
    /**
     * @Route("/", name="main")
     */
    public function index()
    {
        $client = $this->container->get(AtlassianRestClientInterface::class);
        // Or
        // $client = $this->container->get('atlassian_connect_rest_client');
        
        // If you are not in a security context fetch the tenant first
        // $client->setTenant($tenant);
        
        // If you want to impersonate the user
        // $client->actAsUser($this->getUser()->getUserName())
        
        // Send request from anonymous plugin user
        $issue = $client->get('/rest/api/2/issue/KEY-XXX');
        
        // Send request from choosen user
        $user = $client
            ->setUser('5ds4e4352a12451789b13243') // the accountId of the user in Jira/Confluence etc.
            ->get('/rest/api/2/myself')
        ;
        
        return new Response([$issue, $user]);
    }
}

许可白名单

您可以通过编辑相关表中的行并在字段 is_white_listed 中设置为 1 来白名单任何许可证。如果您还将 white_listed_until 设置为 -，您将能够设置白名单过期时间

开发环境

在开发环境中，将自动使用 ID 为 1 的租户。您可以通过将配置变量 atlassian_connect.dev_tenant 设置为 false 来禁用它，或使用另一个开发租户 ID。这将允许您为任何租户测试您的插件输出。

自定义租户实体

如果您需要向租户实体或您的应用实体关系添加更多属性，您可以像下面这样覆盖默认的租户实体

<?php
    namespace AppBundle\Entity;
    
    use Doctrine\ORM\Mapping as ORM;
    use AtlassianConnectBundle\Entity\TenantTrait;
    use AtlassianConnectBundle\Entity\TenantInterface;
    use Symfony\Component\Security\Core\User\UserInterface;
     
    /**
     * JiraTenant
     *
     * @ORM\Table()
     * @ORM\HasLifecycleCallbacks()
     * @ORM\Entity()
     */
    class JiraTenant implements UserInterface, TenantInterface
    {
        /**
         * @ORM\OneToMany(type="MyEntity", mappedBy="jiraTenant")
         */
        protected $myEntities;
    
        use TenantTrait;    
    
        // getters/setters for your custom properties
    }

并通过设置参数覆盖默认值

    atlassian_connect_tenant_entity_class: AppBundle\Entity\JiraTenant

为了使用它，您需要禁用 doctrine 自动映射

    auto_mapping: false
        mappings:
            AppBundle: ~

故障排除

无法在我的 Jira Cloud 插件上启动免费试用

创建您的插件后，您将能够通过 URL https://yourplugindomain.com/atlassian-connect.json 访问插件清单

您将能够在 Jira Cloud 的“管理插件”部分使用“上传插件”界面来设置它。但是，AtlassianConnectBundle 目前只支持“通过 Atlassian 支付”的模式，因此您将无法启动试用。

而不是直接使用清单 URL，您应该添加您的插件 私有列表，创建令牌，并获取如下清单 URL

https://marketplace.atlassian.com/files/1.0.0-AC/artifact/descriptor/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/atlassian-connect.json?access-token=xxxxxxxx

如果您从市场使用该 URL，您的试用将自动启动。

thecatontheflat / atlassian-connect-bundle

维护者

详细信息