이문서는 Atlassian SDK를 사용하여 Jira 플러그인 개발에 필요한 가이드라인을 제공합니다.

1.1. Architecture overview

Jira Server 용 플러그인을 구축하려면 Atlassian SDK를 통해 Atlassian 개발 플랫폼을 사용하게됩니다.

These are the major components in the Atlassian Plugin Development Platform:

Shared Access Layer (SAL). The API for accessing common services, regardless of the underlying Atlassian application interfaces. More...
Atlassian User Interface (AUI). A set of reusable, cross-browser tested JavaScript and CSS UI components. More...
Atlassian Template Renderer (ATR). API for rendering your textual content. More...
Atlassian Event. A library that allows plugins to send and consume internal messages. See the Javadoc.
Activity Streams. API for sending and consuming activity streams. More...
Gadgets. Framework for developing OpenSocial gadgets. More...
Universal Plugin Manager (UPM). The tool for installing, managing, upgrading, and diagnosing Atlassian plugins. More...
Atlassian REST Plugin Module. An Atlassian plugin module that you can use to create plugin points easily in Atlassian applications, by exposing services and data entities as REST APIs. More...
Trusted Apps. Protocol for authenticating Atlassian applications.
Application Links (AppLinks). API for interacting with AppLinks, an Atlassian plugin module that allows you to connect to external applications. More...
OAuth. Our OAuth implementation for accepting and sending authenticated requests.
Plugin Framework. The framework that executes the plugins and manages the available plugin modules. More...
Active Objects. For plugin data storage. An ORM layer that enables easier, faster and more scalable data access and storage than our old Bandana and PluginSettings APIs. More...
Speakeasy. A new, experimental extension mechanism for Atlassian's products. Useful for easy plugin prototyping. More...
JIRA Issue Collector. Library for collecting user feedback from any page.

1.2. 시작하기 전에

환경 구성

    - JDK (Java SE Development Kit) 8 또는 AdoptOpenJDK 8 설치합니다.
           Download : Oracle JDK 8 Downloads 
    - 2990 포트 제거 (지라서버가 사용하는 포트는 2990 포트 입니다.)

    - System PATH 설정하기
      Mac OS 일경우 
        java path 설정과 뒷부분에서 설치할 Atlassian maven 설정 Path 도 설정합니다.

bagjaehyeong-ui-MacBookPro:~ jhpark$ vi ~/.bash_profile
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home
MAVEN_HOME=/Applications/Atlassian/atlassian-plugin-sdk-6.3.12/apache-maven-3.2.1
export JAVA_HOME
export MAVEN_HOME
export PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin

Window OS 일경우

     환경변수 JAVA_HOME을 만들고 설치되어 있는 JDK의 위치를 입력해줍니다.Path에 %JAVA_HOME%\bin 
     
 
 
 javac 확인. : javac -version

1.3. Download and install the Atlassian SDK

아틀라시안 지라에서 제공하는 api 및 플러그인을 사용하기 위한 설치 파일입니다.

Windows 에서 설치(다운로드)
- https://marketplace.atlassian.com/download/plugins/atlassian-plugin-sdk-windows

Mac OSX (맥용 패키지 파일 다운로드)에서 설치

1. Download the PKG file.

Homebrew 로 설치 (패키지 파일로 설치가 어려울 경우 ) - 터미널 오픈

brew tap atlassian/tap

brew install atlassian/tap/atlassian-plugin-sdk

Debian, Ubuntu Linux 설치

     - Ubuntu와 같은 데비안 기반 Linux 시스템에서 apt-get 또는 aptitude를 사용하여 SDK를 설치할 수 있습니다.

1.First, set up the Atlassian SDK repositories:
sudo sh -c 'echo "deb https://packages.atlassian.com/debian/atlassian-sdk-deb/ stable contrib" >>/etc/apt/sources.list'

2.Download the public key using curl or wget:
wget https://packages.atlassian.com/api/gpg/key/public    

3.Add the public key to apt to verify the package signatures automatically:
sudo apt-key add public   

4.Then, run the install:
sudo apt-get update
sudo apt-get install atlassian-plugin-sdk

1.4. SDK를 올바르게 설정했는지 확인

bagjaehyeong-ui-MacBookPro:~ jhpark$ atlas-version

ATLAS Version:    8.0.16
ATLAS Home:       /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec
ATLAS Scripts:    /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/bin
ATLAS Maven Home: /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4
AMPS Version:     8.0.2
--------
Executing: /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4/bin/mvn --version -gs /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4/conf/settings.xml
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-18T03:33:14+09:00)
Maven home: /usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4
Java version: 1.8.0_231, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk1.8.0_231.jdk/Contents/Home/jre
Default locale: ko_KR, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.1", arch: "x86_64", family: "mac"
bagjaehyeong-ui-MacBookPro:~ jhpark$

1.5. Create a Test plugin project

Step 1. Atlassian SDK를 사용하여 플러그인 스켈레톤 구축

플러그인을 작성하려는 시스템의 디렉토리로 이동 합니다.
우리가 실행할 명령은 플러그인 디렉토리가 들어있는 폴더를 만듭니다.
명령 프롬프트 창에서 atlas-create-jira-plugin 명령을 사용하여 애드온 프로젝트 작성

     이 명령은 maven을 사용하여 JIRA 플러그인 스켈레톤을 빌드 할 것입니다. 
     실행중인 maven 명령과 사용중인 JIRA 버전을 보여주는 일부 로그가 화면에 나타납니다.

atlas-create-jira-plugin

명령어 실패시 :
if build fail → echo $java_home
vim~/.zshrc

atlas-mvn eclipse:eclipse

→build success!

문제있으면 cd~/.m2에서 지우면 됨

JAVA_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home

export JAVA_HOME

export PATH=$PATH:$JAVA_HOME/bin

4.플러그인에 대한 정보를 제공하라는 메시지가 표시됩니다. 다음과 같은 프롬프트에 적용합니다.

Define value for groupId: : com.atlassian.tutorial
Define value for artifactId: : myPlugin
Define value for version: 1.0.0-SNAPSHOT: : 1.0.0-SNAPSHOT
Define value for package: com.atlassian.tutorial: : com.atlassian.tutorial.myPlugin

5.세부 사항이 올바른지 확인한 후 진행할 준비가되면 Y를 입력합니다.

Confirm properties configuration:
groupId: com.atlassian.tutorial
artifactId: myPlugin
version: 1.0.0-SNAPSHOT
package: com.atlassian.tutorial.myPlugin
Y: : Y

6.Atlassian JIRA 플러그인의 기본 골격이 생성됩니다.

.
├── LICENSE
├── README
├── pom.xml
└── src
├── main
│ ├── java
│ │ └── com
│ │ └── atlassian
│ │ └── tutorial
│ │ └── myPlugin
│ │ ├── api
│ │ │ └── MyPluginComponent.java
│ │ └── impl
│ │ └── MyPluginComponentImpl.java
│ └── resources
│ ├── META-INF
│ │ └── spring
│ │ └── plugin-context.xml
│ ├── atlassian-plugin.xml
│ ├── css
│ │ └── myPlugin.css
│ ├── images
│ │ ├── pluginIcon.png
│ │ └── pluginLogo.png
│ ├── myPlugin.properties
│ └── js
│ └── myPlugin.js
└── test
├── java
│ ├── it
│ │ └── com
│ │ └── atlassian
│ │ └── tutorial
│ │ └── myPlugin
│ │ └── MyComponentWiredTest.java
│ └── ut
│ └── com
│ └── atlassian
│ └── tutorial
│ └── myPlugin
│ └── MyComponentUnitTest.java
└── resources
└── atlassian-plugin.xml

Step 2. 플러그인이 설치된 상태에서 JIRA 시작

설명:이 단계에서는 atlas-run 명령을 사용하여 애플리케이션 (이 예제에서는 JIRA)을 실행하고 플러그인을 설치합니다.

그런 다음 1 단계에서 생성 한 플러그인이 이미 설치되어 JIRA가 시작되었음을 확인합니다.

1.maven 설정 잡기

=> intellj 기준

maven 경로 설정 =/usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4

setiing.xml 설정=/usr/local/Cellar/atlassian-plugin-sdk/8.0.16/libexec/apache-maven-3.5.4/conf/settings.xml

2. 터미널을 오픈하고 명령어를 입력합니다.

설명: 이전에 생성 한 플러그인 스켈레톤의 정보를 사용하여 JIRA 및 필요한 다른 모든 플러그인을 다운로드 한 다음 플러그인이 설치된 상태에서 JIRA를 시작합니다.

 atlas-run

3.JIRA가 시작되면 명령 프롬프트 창에 이와 같은 내용이 표시됩니다

 [INFO] [talledLocalContainer] Aug 08, 2016 5:51:33 PM org.apache.catalina.startup.Catalina start
[INFO] [talledLocalContainer] INFO: Server startup in 234207 ms
[INFO] [talledLocalContainer] Tomcat 8.x started on port [2990]
[INFO] jira started successfully in 332s at http://DESKTOP-EF2CA9N:2990/jira
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit

3.Open a browser window and navigate to localhost:2990/jira

Username	admin
Password	admin

4.CTRL + D (OSX 및 Linux) 또는 CTRL + Z (Windows)를 사용하여 JIRA를 정상적으로 종료하십시오

5. 아틀라시안 sdk 명령어

- atlas-run : 지라 실행

- altals-debug : 디버깅

- atlas-mvn package : 패키징 및 메이븐 빌드

- Ctrl + D : 지라서버 종료

6. 명령어 확인

which atlas-mvn

1.6. 플러그인 수정

이전 단계에서는 JIRA 플러그인을위한 스켈레톤을 생성했습니다. 
튜토리얼의이 부분에서는 플러그인을 수정하여 JIRA 메뉴에 새 링크를 추가합니다. 
이렇게하려면 Atlassian SDK를 사용하여 웹 섹션 플러그인 모듈 및 웹 항목 플러그인 모듈을 작성해야합니다.

- 플러그인에 표시되는 조직 세부 사항 업데이트

 1.JIRA를 종료 한 후에도 여전히 myPlugin 디렉토리에 있어야합니다.
 2.선호하는 편집기에서 pom.xml 파일을 엽니다.
 3.파일에서 <organization> 요소를 찾으십시오. 다음과 같이 보일 것입니다.

<organization>
    <name>Example Company</name>
    <url>http://www.example.com/</url>
</organization>

4.다음과 같이 개인화 된 정보를 포함하도록 요소를 업데이트하세요.

<organization>
    <name>Atlassian SDK Tutorial</name>
    <url>http://developer.atlassian.com/</url>
</organization

5.명령 프롬프트 창으로 돌아가서 atlas-run을 입력하고 JIRA가 다시 시작될 때까지 기다립니다.
메시지가 표시되면 로그인
localhost : 2990 / jira / plugins / servlet / upm 경로를 사용하여 브라우저에서 추가 기능 관리 페이지를여십시오.
myPlugin 플러그인을 확장하여 변경 사항을보십시오.
완료되면 Ctrl + D를 사용하여 JIRA를 정상적으로 종료하십시오.

1.7. Atlassian Debug

Intellij IDEA에서 디버깅 호출 방법

터미널에서 아래 명령어 실행한다.
atlas-debug --jvmargs "-Xmx2048m -Datlassian.mail.senddisabled=false"
config 설정하기
1. Run -Edit Configration 클릭한다
2. Remote 선택한다
3. port 5005 기본포트
4. command line
  1. -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
5. Use module classpath - 프로젝트 모듈 추가
6. apply 적용 완료
프로젝트를 종료하고 다시 start 한다
디버깅 모드에서 추가하 프로젝트를 실행한다.

2.1. Atlassian AUI

1 Depth	2 Depth	3 Depth	링크
Atlassian User Interface	-		https://docs.atlassian.com/aui/
	Component documentation		https://docs.atlassian.com/aui/8.6.0/docs/inline-dialog.html
	Design Guide		https://www.atlassian.design/
		Logo	https://www.atlassian.design/guidelines/brand/logos
		Logo file Download	https://atlassian.design/guidelines/marketing/resources/logo-files
		Buttons	https://docs.atlassian.com/aui/8.6.0/docs/buttons.html

2.1. Atlassian SDK Modules

플러그인 개발에 필요한 기본적인 모듈

2.2.Active Objects plugin module(ORM) 객체-관계 매핑

자바 어플리케이션에서 관계형 데이터베이스를 사용하는 방식을 정의한 인터페이스이다.(JPA)

com.myapp.MyEntity 키를 가진 플러그인에 속하는 클래스 이름이 MyEntity 인 엔티티의 예를 보자.

이 엔티티의 테이블 이름은 AO_28BE2D_MyEntity입니다.

사용방법

atlassian-plugin.xml 파일을 열고 생성하고자 하는 엔티티를 선언하고 아래 그림과 같이 객체를 생성한 후에 플러그인을 컴파일한다.<참조>https://developer.atlassian.com/server/framework/atlassian-sdk/active-objects-plugin-module/#example

<atlassian-plugin name="Hello World" key="example.plugin.helloworld" plugins-version="2">
  <plugin-info>
    <description>A basic Active Objects module test</description>
    <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
    <version>1.0</version>
  </plugin-info>

  <ao key="ao-module">
    <description>The AO module for this plugin.</description>
    <entity>com.myapp.MyEntity</entity>
  </ao>
</atlassian-plugin>

<그림> 왼쪽에 MyEntity라는 샘플 java 파일을 작성하고 오른쪽에는 실제로 컴파일 후 생성된 테이블이 보여진다.

2.3.atlassian-plugin.xml 구조

터미널에서 atlas-create-jira-plugin-module

<?xml version="1.0" encoding="UTF-8"?>

<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2"> 
  <plugin-info> 
    <description>${project.description}</description>  
    <version>${project.version}</version>  
    <vendor name="${project.organization.name}" url="${project.organization.url}"/>  
    <param name="plugin-icon">images/pluginIcon.png</param>  
    <param name="plugin-logo">images/pluginLogo.png</param> 
  </plugin-info>  
  <!-- add our i18n resource -->  
  <resource type="i18n" name="i18n" location="sample"/>  

  <!-- add our web resources -->
  <web-resource key="sample-resources" name="sample Web Resources"> 
    <dependency>com.atlassian.auiplugin:ajs</dependency>

    <resource type="download" name="sample.css" location="/css/sample.css"/>  
    <resource type="download" name="sample.js" location="/js/sample.js"/>  
    <resource type="download" name="images/" location="/images"/>  
    <context>sample</context>
    <context>atl.admin</context>
  </web-resource>  

  <web-section name="mySection"  key="mySection" location="admin_plugins_menu" weight="1000">
    <description>The mySection Plugin</description>
    <label>plugin Section</label>
  </web-section>  

  <web-item name="myItem"  key="my-item" section="admin_plugins_menu/mySection" weight="1000">
    <description>The myItem Plugin</description>
    <label>plugin sample</label>
    <link>/plugins/servlet/myServlet</link>
  </web-item>  

  <rest name="my Rest Resource"  key="my-rest-resource" path="/custom" version="1.0">
    <description>The my Rest Resource Plugin</description>
  </rest>  

  <servlet name="my Servlet"  key="my-servlet" class="com.plugin.jira.servlet.myServlet">
    <description>The my Servlet Plugin</description>
    <url-pattern>/myServlet</url-pattern>
  </servlet>
</atlassian-plugin>

참조:Customize Atlassian products with apps

참조:https://developer.atlassian.com/server/jira/platform/

1.Jira Plugin 개발 가이드