JIRA Assets 연동 가이드
=====================================

가이드 개요
---------------

  이 문서는 IT 자산관리(ITAM) 목적으로 활용되는 JIRA Assets과 네트워크 접근제어 시스템인 Genian ZTNA의 연동을 위한 설정 방법에 대한 가이드입니다. 
  
  JIRA Assets은 Genian ZTNA에서 탐지된 네트워크 노드 정보를 자동으로 수집하여 자산 데이터베이스(CMDB)에 등록합니다. 이를 통해 IT 자산의 실시간 현황 파악 및 통합 관리가 가능합니다.
  
  Genian ZTNA의 Workflow 기능을 이용하여 노드 탐지 시 자동으로 JIRA Assets에 자산을 등록하거나 업데이트할 수 있도록 합니다.  

**권장 버전**

   .. csv-table::
       :header: "제품명", "버전", "참고"
       :widths: 25 30 45

       "JIRA Service Management", "Premium 이상", "Assets 기능 포함"
       "Genian ZTNA", "v6.0.41 이상", "Workflow 기능 지원"



연동의 목적
-------------------

Genian ZTNA와 JIRA Assets 연동은 다음의 효과를 제공합니다. 

   **실시간 자산 현황 파악** 

     네트워크에 연결된 모든 장비를 자동으로 탐지하여 JIRA Assets에 등록함으로써, 수동 입력 없이 실시간으로 IT 자산 현황을 파악할 수 있습니다. 

   **자산 관리 업무 효율화**

     Genian ZTNA의 노드 정보(IP, MAC, OS, 사용자 등)를 JIRA Assets와 연계하여 자산 관리 담당자가 통합된 관점에서 자산을 관리할 수 있으며, 자산 변경 이력을 자동으로 추적할 수 있습니다. 

   **IT 서비스 관리 향상**

     JIRA Service Management와 통합하여 장애 티켓 발행 시 해당 자산 정보를 즉시 확인할 수 있어 신속한 문제 해결이 가능합니다.




사전준비 사항
------------------------------

   **JIRA Assets 사전준비**

     **OAuth 2.0 앱 생성 및 권한 설정** 

     본 항목은 Genian ZTNA가 JIRA Assets API 호출 시 사용되는 OAuth 2.0 인증 정보를 생성하는 부분에 대한 설명입니다. 

     1. Atlassian Developer Console(https://developer.atlassian.com/console/myapps/)에 접속합니다.
     
     2. 'Create' > 'OAuth 2.0 integration'을 선택하여 새로운 앱을 생성합니다.

     3. 'Permissions' 탭에서 다음 권한을 추가합니다:

        - read:cmdb-object:jira
        - write:cmdb-object:jira
        - read:cmdb-schema:jira
        - delete:cmdb-object:jira

     4. 'Authorization' 탭에서 'Callback URL'을 설정합니다: https://oauth.pstmn.io/v1/callback

     5. 'Settings' 탭에서 'Client ID'와 'Secret'을 복사하여 안전하게 보관합니다.


     **Access Token 발급하기**

     OAuth 2.0 인증을 통해 Access Token을 발급받습니다. Postman 등의 도구를 사용할 수 있습니다.

     .. csv-table::
         :header: "설정 항목", "설정 값", "참고"
         :widths: 25 30 45

         "Token URL", "https://auth.atlassian.com/oauth/token", " "
         "Grant Type", "Authorization Code", " "
         "Client ID", "앱 생성 시 발급받은 값", " "
         "Client Secret", "앱 생성 시 발급받은 값", " "
         "Scope", "read:cmdb-object:jira write:cmdb-object:jira", "필요한 모든 scope 추가"

     발급받은 Access Token은 1시간 동안 유효하며, Refresh Token을 사용하여 갱신할 수 있습니다.


     **Cloud ID 확인하기**

     JIRA Cloud 인스턴스의 고유 ID를 확인합니다.

     GET https://api.atlassian.com/oauth/token/accessible-resources API를 호출하여 'id' 필드 값을 확인합니다.

     예시: 12345678-1234-1234-1234-123456789abc


     **Workspace ID 및 Schema ID 확인하기**

     JIRA Assets 관리 페이지에서 사용할 Workspace와 Schema의 ID를 확인합니다.

     .. csv-table::
         :header: "항목", "예시 값", "확인 방법"
         :widths: 25 30 45

         "Workspace ID", "41497d77-f29d-4a13-a8c9-89b35dfb18e2", "Assets 설정 페이지 URL 참조"
         "Schema ID", "2", "ITAM 스키마 설정 페이지 참조"
         "Object Type ID (Windows PC)", "51", "Object Type 목록에서 확인"
         "Object Type ID (Mac)", "50", "Object Type 목록에서 확인"
         "Object Type ID (Red Hat Linux)", "13", "Object Type 목록에서 확인"
         "Object Type ID (Windows Server)", "14", "Object Type 목록에서 확인"


   **Genian ZTNA 노드 타입 코드**

   Genian ZTNA에서 사용하는 NodeType 코드는 다음과 같습니다:

   .. csv-table::
       :header: "NodeType 코드", "설명", "참고"
       :widths: 20 30 50

       "20", "PC (데스크톱/노트북)", "일반 사용자 PC"
       "40", "서버", "Windows Server, Linux Server 등"
       "30", "네트워크 장비", "스위치, 라우터 등"
       "10", "프린터", "네트워크 프린터"


   **Attribute ID 확인하기**

    자산 등록 시 사용할 속성의 ID를 확인합니다.

    GET /objecttype/{objectTypeId}/attributes API를 호출하여 다음 속성의 ID를 확인합니다:

    .. csv-table::
        :header: "속성명", "Attribute ID", "필수 여부"
        :widths: 30 20 20

        "Name", "100", "필수"
        "IP Address", "157", "권장"
        "OS 버전", "115", "권장"
        "도메인 이름", "122", "서버 전용"



   **Networking 사전 준비사항** 

       Genian ZTNA Policy Center와 JIRA Cloud 간의 통신을 확인합니다. HTTPS(TCP/443)를 사용하며, 다음 도메인에 대한 접근이 필요합니다:

       - auth.atlassian.com (OAuth 인증)
       - api.atlassian.com (API 호출)
       - *.atlassian.net (JIRA 인스턴스)

       방화벽 정책에서 상기 도메인에 대한 HTTPS 통신을 허용해야 합니다.


연동을 위한 Genian ZTNA 설정
------------------------------------------ 

  **Workflow용 연동 정보 설정하기**  

   Workflow에서 사용할 JIRA Assets 연동 정보를 설정합니다.

   Workflow 편집 화면 좌측 상단의 *'>>'* 버튼을 클릭하여 연동 정보 영역을 열고 다음 변수를 추가합니다:

   .. csv-table::
       :header: "변수명", "설정 값", "참고"
       :widths: 25 35 40

       "request.cloudId", "your-cloud-id-here", "JIRA Cloud 인스턴스 ID"
       "request.workspaceId", "your-workspace-id-here", "Assets Workspace ID"

   .. note::
      - 연동 정보는 `${connInfo.request.cloudId}` 형식으로 Workflow 내에서 참조됩니다.
      - OAuth Token은 HTTP Request 노드의 Authorization 헤더에 직접 입력합니다.

   .. warning::
      **보안 주의사항:**
      
      - Access Token은 1시간마다 만료됩니다. 프로덕션 환경에서는 Refresh Token을 사용한 자동 갱신 로직 구현을 권장합니다.
      - API Key, Cloud ID, Workspace ID는 민감한 정보입니다. 문서나 스크린샷 공유 시 반드시 마스킹하세요.
      - Authorization 헤더의 토큰 값은 절대 공개하지 마세요.
      - ZTNA 서버 IP 주소는 내부 네트워크 정보이므로 외부 공개를 피하세요.
      - 실제 환경에서는 위 예시의 `your-cloud-id-here`, `your-workspace-id-here`, `your-api-key-here`, `your-ztna-server` 값을 실제 값으로 대체하세요.


  **Workflow 전체 구조**

   다음은 JIRA Assets 자동 등록 Workflow의 전체 흐름도입니다.

   .. figure:: ../images/jira-assets-workflow-diagram.png
      :align: center
      :width: 100%
      :alt: JIRA Assets Workflow 전체 구조

      JIRA Assets 자동 등록 Workflow 전체 흐름도

   .. tip::
      **Workflow 구성 요소:**
      
      - **상단 경로 (Windows PC)**: ZTNA IP정보 조회 → 조건검사 PC and Windows → JIRA CMDB IP주소 조회 → CMDB 등록 결과 조건 → ZTNA IP정보 조회 → JIRA CMDB 자산 등록
      - **하단 경로 (서버)**: ZTNA IP정보 조회 → 조건검사 서버 and Red Hat → JIRA CMDB IP주소 등록 조회 → 조회결과 조건 → ZTNA IP정보 조회 → JIRA CMDB 자산 등록
      
      **주요 분기점:**
      
      - **조건검사 PC and Windows**: NodeType=20 확인 (True → Windows PC 경로, False → 서버 경로)
      - **조건검사 서버 and Red Hat**: NodeType=40 AND NL_PLATFORM="Red Hat Linux" 확인
      - **등록 결과 조건**: total=0 확인 (미등록 자산만 등록)


  **자산 등록 Workflow 생성하기**  

   상단 메뉴에서 *'Workflow'* 를 클릭하여 Workflow Console로 이동한 후 '작업선택'을 누르고 '생성'을 선택하여 다음과 같이 입력합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 30 45

       "Workflow 이름", "JIRA CMDB 연동", " "
       "설명", "네트워크 노드를 JIRA Assets에 자동 등록", " "
       "트리거", "Event Hooks", "외부 이벤트 수신 시 실행"

   .. note::
      - 본 문서의 예제는 Event Hooks를 트리거로 사용합니다.
      - Event Hooks는 Genian ZTNA의 로그 필터 기능을 통해 특정 이벤트(노드 탐지, IP 변경 등) 발생 시 Workflow를 호출합니다.
      - 트리거 유형은 "노드 탐지됨", "스케줄", "수동 실행" 등 다양하게 설정할 수 있습니다.


**Windows PC 등록 프로세스**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Windows PC를 JIRA Assets에 등록하는 프로세스는 다음 6단계로 구성됩니다.

   
   **Step 1: ZTNA IP정보 조회 (첫 번째)**

   Genian ZTNA에서 탐지된 노드의 상세 정보를 조회합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "ZTNA IP정보 조회", " "
       "메소드", "GET", " "
       "Request URL", "https://your-ztna-server:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All&ip=Equal=false&ip=${request._IP}", " "
       "헤더 - accept", "application/json", " "
       "헤더 - Authorization", "Basic [인증정보]", "ZTNA API 인증 토큰"
       "Body", "${request._IP}", "트리거에서 전달받은 IP 주소"
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답을 저장"

   .. note::
      - `${request._IP}`는 Event Hooks 트리거에서 전달되는 노드의 IP 주소입니다.
      - Body 필드에 `${request._IP}` 값을 입력하여 조회할 IP를 지정합니다.
      - 이 API 호출로 노드의 NodeType, NL_OSTYPE, NL_NODEID, NL_IPSTR 등의 상세 정보를 조회합니다.


   **Step 2: 조건검사 PC and Windows**

   조회한 노드가 Windows PC인지 판단합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "IfElse (조건 분기)", " "
       "이름", "조건검사 PC and Windows", " "
       "조건 로직", "AND", "두 조건 모두 만족해야 함"
       "조건 - 변수", "${[p092.result[0].NodeType]}", "Step 1의 응답에서 노드 타입 추출"
       "조건 - 연산자", "같은값", " "
       "조건 - 비교값", "20", "NodeType 20 = PC"
       "True 시", "Step 3 (JIRA CMDB IP주소 조회)", "NodeType이 20(PC)인 경우"
       "False 시", "서버 분류 프로세스로 이동", "PC가 아닌 경우"

   .. note::
      - `p4d0`는 Step 1 (ZTNA IP정보 조회) 프로세스의 고유 ID입니다.
      - Windows PC 프로세스에서 사용됩니다.
      - 스크린샷에서는 NodeType만 체크하고 있습니다 (값 20).
      - AND 조건으로 설정되어 있지만 실제로는 조건이 하나만 있습니다.


   **Step 3: JIRA CMDB IP주소 조회**

   해당 IP 주소가 이미 JIRA Assets에 등록되어 있는지 확인합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "JIRA CMDB IP주소 조회", " "
       "메소드", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/aql", " "
       "헤더 - Content-Type", "application/json", " "
       "헤더 - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 토큰"
       "Body", "아래 JSON 참조", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답 저장"

   Body 내용::

       {
         "qlQuery": "\"IP Address\" = \"${[p4d0.result[0].NL_IPSTR]}\"",
         "page": 1,
         "resultPerPage": 10
       }

   .. note::
      - `${[p4d0.result[0].NL_IPSTR]}`는 Step 1에서 조회한 노드의 IP 주소입니다.
      - AQL(Assets Query Language)을 사용하여 IP 주소로 자산을 검색합니다.
      - 응답의 `totalFilterCount` 필드로 등록 여부를 확인할 수 있습니다.


   **Step 4: CMDB 등록 결과 조건**

   검색 결과를 바탕으로 신규 등록이 필요한지 판단합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "IfElse (조건 분기)", " "
       "이름", "CMDB 등록 결과 조건", " "
       "조건 로직", "AND", " "
       "조건 - 변수", "${[p10b.total]}", "Step 3의 검색 결과 개수"
       "조건 - 연산자", "같으면", " "
       "조건 - 비교값", "0", " "
       "True 시", "Step 5 (ZTNA IP정보 조회)", "미등록 자산, 등록 진행"
       "False 시", "워크플로우 종료", "이미 등록된 자산"

   .. note::
      - p10b은 Step 3 (JIRA CMDB IP주소 조회)의 프로세스 ID입니다.
      - total 필드로 검색된 자산의 개수를 확인합니다.
      - `p482`는 Step 3 프로세스의 고유 ID입니다.
      - `totalFilterCount`가 0이면 미등록 자산이므로 등록 프로세스를 계속 진행합니다.
      - 0이 아니면 이미 등록된 자산이므로 중복 등록을 방지하기 위해 워크플로우를 종료합니다.


   **Step 5: ZTNA IP정보 조회 (두 번째)**

   자산 등록을 위해 노드 정보를 다시 조회합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "ZTNA IP정보 조회", " "
       "메소드", "GET", " "
       "Request URL", "https://your-ztna-server:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All&ip=Equal=false&ip=${request._IP}", " "
       "헤더 - accept", "application/json", " "
       "헤더 - Authorization", "Basic [인증정보]", "ZTNA API 인증 토큰"
       "Body", "${request._IP}", "트리거에서 전달받은 IP 주소"
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답을 저장"

   .. note::
      - Step 1과 동일한 API를 다시 호출합니다.
      - 최신 노드 정보를 가져와서 JIRA Assets에 등록합니다.


   **Step 6: JIRA CMDB 자산 등록 (Windows PC)**

   Windows PC를 JIRA Assets에 등록합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "JIRA CMDB 자산 등록", " "
       "메소드", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/create", " "
       "헤더 - Content-Type", "application/json", " "
       "헤더 - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 토큰"
       "Body", "아래 JSON 참조", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "등록 결과 저장"

   Body 내용::

       {
         "objectTypeId": "51",
         "attributes": [
           {
             "objectTypeAttributeId": "100",
             "objectAttributeValues": [{"value": "${[pe65.result[0].NL_FQDN]}"}]
           },
           {
             "objectTypeAttributeId": "157",
             "objectAttributeValues": [{"value": "${[pe65.result[0].NL_IPSTR]}"}]
           },
           {
             "objectTypeAttributeId": "115",
             "objectAttributeValues": [{"value": "${[pe65.result[0].NL_PLATFORM]}"}]
           }
         ]
       }

   .. note::
      - objectTypeId "51"은 JIRA Assets의 Windows PC Object Type입니다.
      - Attribute ID 100: Name (FQDN/호스트명)
      - Attribute ID 157: IP Address
      - Attribute ID 115: Platform (플랫폼 정보)
      - Step 5에서 조회한 노드 정보(pe65)를 사용하여 자산을 생성합니다.


**서버 등록 프로세스**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   서버(Red Hat Linux 등)를 JIRA Assets에 등록하는 프로세스입니다.


   **Step 1: ZTNA IP정보 조회 (첫 번째)**

   Genian ZTNA에서 탐지된 노드의 상세 정보를 조회합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "ZTNA IP정보 조회", " "
       "메소드", "GET", " "
       "Request URL", "https://your-ztna-server:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All&ip=Equal=false&ip=${request._IP}", " "
       "헤더 - accept", "application/json", " "
       "헤더 - Authorization", "Basic [인증정보]", "ZTNA API 인증 토큰"
       "Body", "${request._IP}", "트리거에서 전달받은 IP 주소"
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답을 저장"

   .. note::
      - `${request._IP}`는 Event Hooks 트리거에서 전달되는 노드의 IP 주소입니다.
      - Body 필드에 `${request._IP}` 값을 입력하여 조회할 IP를 지정합니다.


   **Step 2: 조건검사 PC and Windows**

   먼저 Windows PC인지 확인합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "IfElse (조건 분기)", " "
       "이름", "조건검사 PC and Windows", " "
       "조건 로직", "AND", "조건 설정"
       "조건 - 변수", "${[p4d0.result[0].NodeType]}", "Step 1의 응답에서 노드 타입 추출"
       "조건 - 연산자", "같은값", " "
       "조건 - 비교값", "20", "NodeType 20 = PC"
       "True 시", "Windows PC 등록 프로세스", "NodeType이 20(PC)인 경우"
       "False 시", "Step 3 (조건검사 서버 and Red Hat)", "PC가 아닌 경우"


   **Step 3: 조건검사 서버 and Red Hat**

   서버이면서 Red Hat Linux인지 판단합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "IfElse (조건 분기)", " "
       "이름", "조건검사 서버 and Red Hat", " "
       "조건 로직", "AND", "두 조건 모두 만족해야 함"
       "조건 1 - 변수", "${[p4d0.result[0].NL_PLATFORM]}", "Step 1의 응답에서 플랫폼 정보 추출"
       "조건 1 - 연산자", "같으면", " "
       "조건 1 - 비교값", "Red Hat Linux", "Red Hat Linux 플랫폼"
       "조건 2 - 변수", "${[p4d0.result[0].NodeType]}", "Step 1의 응답에서 노드 타입 추출"
       "조건 2 - 연산자", "같으면", " "
       "조건 2 - 비교값", "40", "NodeType 40 = 서버"
       "True 시", "Step 4 (CMDB 등록 결과 조건)", "Red Hat 서버인 경우"
       "False 시", "워크플로우 종료", "다른 OS 타입"

   .. note::
      - NodeType 40은 Genian ZTNA에서 서버를 나타냅니다.
      - NL_PLATFORM에서 "Red Hat Linux"와 정확히 일치하는지 확인합니다.
      - p4d0는 Step 1 (ZTNA IP정보 조회)의 프로세스 ID입니다.


   **Step 3-1: JIRA CMDB IP주소 등록 조회**

   해당 IP 주소가 이미 JIRA Assets에 등록되어 있는지 확인합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "JIRA CMDB IP주소 등록 조회", " "
       "메소드", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/aql", " "
       "헤더 - Content-Type", "application/json", " "
       "헤더 - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 토큰"
       "Body", "아래 JSON 참조", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답 저장"

   Body 내용::

       {
         "qlQuery": "\"IP Address\" = \"${[p4d0.result[0].NL_IPSTR]}\"",
         "page": 1,
         "resultPerPage": 10
       }

   .. note::
      - `${[p4d0.result[0].NL_IPSTR]}`는 Step 1에서 조회한 노드의 IP 주소입니다.
      - p4d0는 Step 1 (ZTNA IP정보 조회)의 프로세스 ID입니다.
      - AQL(Assets Query Language)을 사용하여 IP 주소로 자산을 검색합니다.


   **Step 4: 조회결과 조건**

   JIRA Assets에서 해당 IP 주소로 등록된 자산이 있는지 확인합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "IfElse (조건 분기)", " "
       "이름", "조회결과 조건", " "
       "조건 로직", "AND", " "
       "조건 - 변수", "${[pe9a.total]}", "JIRA CMDB 조회 결과 개수"
       "조건 - 연산자", "같으면", " "
       "조건 - 비교값", "0", " "
       "True 시", "Step 5 (ZTNA IP정보 조회)", "미등록 자산"
       "False 시", "워크플로우 종료", "이미 등록된 자산"

   .. note::
      - pe9a는 Step 3-1 (JIRA CMDB IP주소 등록 조회)의 프로세스 ID입니다.
      - total 필드로 검색된 자산의 개수를 확인합니다.


   **Step 5: ZTNA IP정보 조회 (두 번째)**

   자산 등록을 위해 노드 정보를 다시 조회합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "ZTNA IP정보 조회", " "
       "메소드", "GET", " "
       "Request URL", "https://your-ztna-server:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All&ip=Equal=false&ip=${request._IP}", " "
       "헤더 - accept", "application/json", " "
       "헤더 - Authorization", "Basic [인증정보]", "ZTNA API 인증 토큰"
       "Body", "${request._IP}", "트리거에서 전달받은 IP 주소"
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "전체 응답을 저장"

   .. note::
      - Step 1과 동일한 API를 다시 호출합니다.
      - 최신 노드 정보를 가져와서 JIRA Assets에 등록합니다.


   **Step 6: JIRA CMDB 자산 등록 (Red Hat 서버)**

   Red Hat Linux 서버를 JIRA Assets에 등록합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "HTTP Request", " "
       "이름", "JIRA CMDB 자산 등록", " "
       "메소드", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/create", " "
       "헤더 - Content-Type", "application/json", " "
       "헤더 - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 토큰"
       "Body", "아래 JSON 참조", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(빈칸)", "등록 결과 저장"

   Body 내용::

       {
         "objectTypeId": "13",
         "attributes": [
           {
             "objectTypeAttributeId": "100",
             "objectAttributeValues": [{"value": "${[p4c5.result[0].NL_SERVICE]}"}]
           },
           {
             "objectTypeAttributeId": "157",
             "objectAttributeValues": [{"value": "${[p4c5.result[0].NL_IPSTR]}"}]
           },
           {
             "objectTypeAttributeId": "115",
             "objectAttributeValues": [{"value": "${[p4c5.result[0].NL_PLATFORM]}"}]
           }
         ]
       }

   .. note::
      - objectTypeId "13"은 JIRA Assets의 서버 Object Type입니다.
      - Attribute ID 100: Name (서비스명)
      - Attribute ID 157: IP Address
      - Attribute ID 115: Platform (플랫폼 정보)
      - p4c5는 Step 5 (ZTNA IP정보 조회)의 프로세스 ID입니다.
      - Step 5에서 조회한 노드 정보를 사용하여 자산을 생성합니다.


   **Workflow 플로우 요약**

   **Windows PC 등록 플로우:**

   1. **ZTNA IP정보 조회** (p4d0): Genian ZTNA API를 호출하여 탐지된 노드의 상세 정보 조회 (Body에 `${request._IP}` 포함, accept 헤더 사용)
   2. **조건검사 PC and Windows**: NodeType=20(PC) 확인 → True일 경우 진행
   3. **JIRA CMDB IP주소 조회** (p10b): JIRA Assets에서 해당 IP 주소로 등록된 자산이 있는지 AQL로 검색
   4. **CMDB 등록 결과 조건**: total=0 확인 → True(미등록)일 경우 진행
   5. **ZTNA IP정보 조회** (pe65): 최신 노드 정보를 다시 조회 (Body에 `${request._IP}` 포함, accept 헤더 사용)
   6. **JIRA CMDB 자산 등록**: Object Type 51(Windows PC)로 자산 등록 (NL_FQDN, NL_IPSTR, NL_PLATFORM)

   **서버 등록 플로우:**

   1. **ZTNA IP정보 조회** (p4d0): Genian ZTNA API를 호출하여 탐지된 노드의 상세 정보 조회 (Body에 `${request._IP}` 포함, accept 헤더 사용)
   2. **조건검사 PC and Windows**: NodeType=20(PC) 확인 → False일 경우 다음 단계로
   3. **조건검사 서버 and Red Hat** (p7cb): NL_PLATFORM="Red Hat Linux" AND NodeType=40(서버) 확인 → True일 경우 진행
   4. **JIRA CMDB IP주소 등록 조회** (pe9a): JIRA Assets에서 해당 IP 주소로 등록된 자산이 있는지 AQL로 검색
   5. **조회결과 조건**: total=0 확인 → True(미등록)일 경우 진행
   6. **ZTNA IP정보 조회** (p4c5): 최신 노드 정보를 다시 조회 (Body에 `${request._IP}` 포함, accept 헤더 사용)
   7. **JIRA CMDB 자산 등록**: Object Type 13(서버)로 자산 등록 (NL_SERVICE, NL_IPSTR, NL_PLATFORM)

   .. tip::
      - 실제 운영 환경에서는 Mac OS, Windows Server 등 다양한 OS 타입에 대한 조건 분기를 추가할 수 있습니다.
      - 각 OS 타입마다 별도의 IfElse 노드와 HTTP Request 노드를 추가하여 확장 가능합니다.
      - Windows PC 프로세스와 서버 프로세스는 동일한 방식으로 `${request._IP}`를 사용하고 accept 헤더로 인증합니다.
      - 프로세스 ID는 괄호 안에 표시된 실제 값을 참조하세요.


   **템플릿 변수 참조 방법**

   Workflow에서 사용되는 주요 템플릿 변수:

   **Windows PC 등록 프로세스:**

   - `${request._IP}`: Event Hooks 트리거에서 전달된 IP 주소
   - `${[p4d0.result[0].NodeType]}`: Step 1 ZTNA IP정보 조회 - 노드 타입 코드
   - `${[p4d0.result[0].NL_IPSTR]}`: Step 1 ZTNA IP정보 조회 - IP 주소
   - `${[p10b.total]}`: Step 3 JIRA CMDB IP주소 조회 - 검색된 자산 개수
   - `${[pe65.result[0].NL_FQDN]}`: Step 5 ZTNA IP정보 조회 - FQDN/호스트명
   - `${[pe65.result[0].NL_IPSTR]}`: Step 5 ZTNA IP정보 조회 - IP 주소
   - `${[pe65.result[0].NL_PLATFORM]}`: Step 5 ZTNA IP정보 조회 - 플랫폼 정보

   **서버 등록 프로세스:**

   - `${request._IP}`: Event Hooks 트리거에서 전달된 IP 주소
   - `${[p4d0.result[0].NodeType]}`: Step 1 ZTNA IP정보 조회 - 노드 타입 코드
   - `${[p4d0.result[0].NL_PLATFORM]}`: Step 1 ZTNA IP정보 조회 - 플랫폼 정보
   - `${[p4d0.result[0].NL_IPSTR]}`: Step 1 ZTNA IP정보 조회 - IP 주소
   - `${[pe9a.total]}`: Step 3-1 JIRA CMDB IP주소 등록 조회 - 검색된 자산 개수
   - `${[p4c5.result[0].NL_SERVICE]}`: Step 5 ZTNA IP정보 조회 - 서비스명
   - `${[p4c5.result[0].NL_IPSTR]}`: Step 5 ZTNA IP정보 조회 - IP 주소
   - `${[p4c5.result[0].NL_PLATFORM]}`: Step 5 ZTNA IP정보 조회 - 플랫폼 정보

   **공통 변수:**

   - `${connInfo.request.cloudId}`: 연동 정보에 저장된 JIRA Cloud ID
   - `${connInfo.request.workspaceId}`: 연동 정보에 저장된 JIRA Workspace ID

   .. note::
      - 프로세스 ID (p4d0, p10b, pe65, p7cb, pe9a, p4c5 등)는 실제 Workflow마다 다를 수 있습니다.
      - Response Body Template을 비워두면 전체 응답이 저장되며, 이후 단계에서 JSON 경로로 참조할 수 있습니다.
      - Windows PC 프로세스와 서버 프로세스 모두 `${request._IP}` (언더스코어 포함)를 사용합니다.
      - 모든 프로세스에서 accept 헤더와 Authorization 헤더를 사용하여 ZTNA API 인증을 수행합니다.


   **Step 7: 성공 로그 기록 (선택 사항)**

   자산 등록이 성공하면 로그를 기록합니다.

   .. csv-table::
       :header: "설정 항목", "설정 값", "참고"
       :widths: 25 35 40

       "액션 타입", "Log", " "
       "이름", "log_success", " "
       "레벨", "Info", " "
       "메시지", "아래 메시지 참조", " "

   메시지 내용::

       ✅ JIRA Assets 등록 완료
       FQDN: ${[pe65.result[0].NL_FQDN]}
       IP 주소: ${[pe65.result[0].NL_IPSTR]}
       플랫폼: ${[pe65.result[0].NL_PLATFORM]}
       등록 시간: ${_CURRENT_TIME}

   .. note::
      - 로그 메시지에는 Step 5 또는 Step 6에서 조회한 최신 노드 정보를 사용합니다.
      - Windows PC는 pe65, 서버는 p4c5 프로세스 ID를 참조합니다.


   **에러 핸들러 설정**

   API 호출 실패 시 처리할 에러 핸들러를 설정합니다.

   .. csv-table::
       :header: "에러 코드", "처리 방법", "참고"
       :widths: 20 40 40

       "401 Unauthorized", "토큰 갱신 후 재시도", "Access Token 만료"
       "403 Forbidden", "관리자에게 알림", "권한 부족"
       "400 Bad Request", "요청 파라미터 검증 및 로그", "잘못된 요청"
       "429 Too Many Requests", "30초 대기 후 재시도", "Rate Limit 초과"
       "5xx Server Error", "5분 후 재시도", "JIRA 서버 오류"



JIRA Assets에서 자산 확인하기
------------------------------------------

  **자산 목록 확인**

   JIRA Service Management에 로그인하여 'Assets' 메뉴로 이동합니다.

   'ITAM' 스키마를 선택하고 다음 Object Type에서 등록된 자산을 확인할 수 있습니다:

   - PC > Windows
   - PC > Mac OS
   - 서버 > Red Hat Linux
   - 서버 > Windows Server

  
  **자산 상세 정보 확인**

   등록된 자산을 클릭하면 다음 정보를 확인할 수 있습니다:

   .. csv-table::
       :header: "속성", "설명", "예시"
       :widths: 25 35 40

       "Name", "노드 식별자", "WIN-PC-001"
       "IP Address", "IP 주소", "192.168.1.100"
       "OS 버전", "운영체제 정보", "Windows 11 Pro"
       "도메인 이름", "FQDN", "pc001.genians.local"
       "Created", "등록 일시", "2024-01-22 16:30:15"
       "Updated", "최종 수정 일시", "2024-01-22 16:30:15"

   .. tip::
      JIRA Assets에서 제공하는 변경 이력(History) 기능을 활용하면 각 자산의 모든 변경 사항을 추적할 수 있습니다.



활용 시나리오
---------------------------------------------

  **시나리오 1: 신규 장비 자동 등록**
  
   네트워크에 새로운 Windows PC가 연결되면 Genian ZTNA가 자동으로 탐지하고, Workflow를 통해 JIRA Assets의 'Windows' Object Type에 자동으로 등록됩니다. IT 관리자는 별도의 수동 입력 없이 자산 현황을 실시간으로 파악할 수 있습니다.

  
  **시나리오 2: 자산 정보 업데이트**
  
   기존 PC의 OS가 업그레이드되면(예: Windows 10 → Windows 11), Genian ZTNA가 변경을 탐지하고 JIRA Assets의 'OS 버전' 속성을 자동으로 업데이트합니다.


  **시나리오 3: 장애 티켓 발행 시 자산 정보 활용**
  
   사용자가 JIRA Service Management를 통해 PC 장애 티켓을 발행하면, 해당 PC의 IP 주소를 기반으로 JIRA Assets에서 자산 정보(OS 버전, 설치 소프트웨어 등)를 즉시 확인하여 신속한 문제 해결이 가능합니다.


  **시나리오 4: 자산 변경 이력 추적**
  
   JIRA Assets의 변경 이력 기능을 통해 특정 자산의 IP 주소 변경, OS 업그레이드 등의 모든 변경 사항을 시간순으로 추적할 수 있습니다.



API 참조
---------------------------------------------

  **주요 API 엔드포인트**
  
   .. csv-table::
       :header: "API", "메소드", "용도"
       :widths: 40 15 45

       "/object/aql", "POST", "AQL 쿼리로 자산 검색"
       "/object/create", "POST", "새로운 자산 등록"
       "/object/{id}", "PUT", "자산 정보 업데이트"
       "/object/{id}", "DELETE", "자산 삭제"
       "/objectschema/{id}", "GET", "스키마 정보 조회"
       "/objecttype/{id}/attributes", "GET", "Object Type의 속성 목록 조회"


  **인증 헤더 형식**
  
   모든 API 호출 시 다음 헤더를 포함해야 합니다::

       Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1...
       Accept: application/json
       Content-Type: application/json


  **AQL(Assets Query Language) 쿼리 예시**
  
   IP 주소로 검색::

       "IP Address" = "192.168.1.100"

   
   여러 조건 검색::

       "IP Address" = "192.168.1.100" AND "OS 버전" LIKE "Windows%"


   Object Type으로 필터링::

       objectType = Windows



문제 해결
---------------------------------------------

  **401 Unauthorized 오류**
  
   - 원인: Access Token 만료 또는 권한 부족
   - 해결: Refresh Token으로 새로운 Access Token 발급
   - 확인: Developer Console에서 필요한 모든 scope가 추가되었는지 확인


  **403 Forbidden 오류**
  
   - 원인: JIRA Assets 접근 권한 부족
   - 해결: JIRA Assets → ITAM Schema → Settings → Roles에서 사용자 또는 그룹에 '개체 스키마 사용자' 역할 부여


  **400 Bad Request 오류**
  
   - 원인: 잘못된 Attribute ID 또는 Object Type ID
   - 해결: GET /objecttype/{id}/attributes API로 올바른 ID 확인
   - 확인: Object Type ID가 스키마 내에 존재하는지 확인


  **429 Too Many Requests 오류**
  
   - 원인: API Rate Limit 초과
   - 해결: 응답 헤더의 'Retry-After' 값만큼 대기 후 재시도
   - 권장: Workflow에서 요청 속도 제한 설정 (초당 2회 이하)


  **자산이 중복 등록되는 경우**
  
   - 원인: IP 주소 검색 조건이 정확하지 않음
   - 해결: AQL 쿼리에서 IP 주소 완전 일치 검색 사용
   - 확인: Step 2의 조건 분기가 올바르게 동작하는지 로그 확인



참고 자료
---------------------------------------------

  **Atlassian 공식 문서**
  
   - JIRA Assets API: https://developer.atlassian.com/cloud/jira/service-desk/rest/api-group-assets/
   - OAuth 2.0 인증: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
   - AQL 가이드: https://support.atlassian.com/jira-service-management-cloud/docs/use-assets-query-language-aql/


  **Genian ZTNA Workflow 가이드**
  
   - :ref:`workflow` (Workflow 개요 및 공통 설정)
   - :ref:`workflow-httprequest` (HTTP Request 프로세스)
   - :ref:`workflow-ifelse` (조건 분기 프로세스)
   - :ref:`workflow-loop` (반복 프로세스)