JIRA Assets Integration Guide
=====================================

Guide Overview
---------------

  This document provides a configuration guide for integrating JIRA Assets, used for IT Asset Management (ITAM) purposes, with Genian ZTNA, a network access control system.
  
  JIRA Assets automatically collects network node information detected by Genian ZTNA and registers it in the asset database (CMDB). This enables real-time visibility and unified management of IT assets.
  
  Using Genian ZTNA's Workflow feature, assets can be automatically registered or updated in JIRA Assets when nodes are detected.

**Recommended Versions**

   .. csv-table::
       :header: "Product", "Version", "Notes"
       :widths: 25 30 45

       "JIRA Service Management", "Premium or higher", "Includes Assets feature"
       "Genian ZTNA", "v6.0.41 or higher", "Supports Workflow feature"



Integration Purpose
-------------------

Integration between Genian ZTNA and JIRA Assets provides the following benefits:

   **Real-time Asset Visibility**

     By automatically detecting all devices connected to the network and registering them in JIRA Assets, you can gain real-time visibility of IT asset status without manual entry.

   **Efficient Asset Management**

     By linking Genian ZTNA's node information (IP, MAC, OS, user, etc.) with JIRA Assets, asset managers can manage assets from a unified perspective and automatically track asset change history.

   **Enhanced IT Service Management**

     Integration with JIRA Service Management enables instant access to asset information when incident tickets are created, facilitating rapid problem resolution.




Prerequisites
------------------------------

   **JIRA Assets Prerequisites**

     **Create OAuth 2.0 App and Configure Permissions**

     This section describes how to create OAuth 2.0 authentication credentials used when Genian ZTNA calls the JIRA Assets API.

     1. Access the Atlassian Developer Console (https://developer.atlassian.com/console/myapps/).
     
     2. Select 'Create' > 'OAuth 2.0 integration' to create a new app.

     3. Add the following permissions in the 'Permissions' tab:

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

     4. Configure the 'Callback URL' in the 'Authorization' tab: https://oauth.pstmn.io/v1/callback

     5. Copy the 'Client ID' and 'Secret' from the 'Settings' tab and store them securely.


     **Obtain Access Token**

     Obtain an Access Token through OAuth 2.0 authentication. You can use tools like Postman.

     .. csv-table::
         :header: "Setting Item", "Setting Value", "Notes"
         :widths: 25 30 45

         "Token URL", "https://auth.atlassian.com/oauth/token", " "
         "Grant Type", "Authorization Code", " "
         "Client ID", "Value issued during app creation", " "
         "Client Secret", "Value issued during app creation", " "
         "Scope", "read:cmdb-object:jira write:cmdb-object:jira", "Add all required scopes"

     The issued Access Token is valid for 1 hour and can be renewed using a Refresh Token.


     **Verify Cloud ID**

     Check the unique ID of your JIRA Cloud instance.

     Call the GET https://api.atlassian.com/oauth/token/accessible-resources API and check the 'id' field value.

     Example: 12345678-1234-1234-1234-123456789abc


     **Verify Workspace ID and Schema ID**

     Check the IDs of the Workspace and Schema to use in the JIRA Assets management page.

     .. csv-table::
         :header: "Item", "Example Value", "How to Verify"
         :widths: 25 30 45

         "Workspace ID", "41497d77-f29d-4a13-a8c9-89b35dfb18e2", "Refer to Assets settings page URL"
         "Schema ID", "2", "Refer to ITAM schema settings page"
         "Object Type ID (Windows PC)", "51", "Check in Object Type list"
         "Object Type ID (Mac)", "50", "Check in Object Type list"
         "Object Type ID (Red Hat Linux)", "13", "Check in Object Type list"
         "Object Type ID (Windows Server)", "14", "Check in Object Type list"


   **Genian ZTNA NodeType Codes**

   NodeType codes used in Genian ZTNA are as follows:

   .. csv-table::
       :header: "NodeType Code", "Description", "Notes"
       :widths: 20 30 50

       "20", "PC (Desktop/Laptop)", "General user PC"
       "40", "Server", "Windows Server, Linux Server, etc."
       "30", "Network Device", "Switch, Router, etc."
       "10", "Printer", "Network Printer"


   **Verify Attribute IDs**

    Verify the IDs of attributes to use when registering assets.

    Call GET /objecttype/{objectTypeId}/attributes API to verify IDs for the following attributes:

    .. csv-table::
        :header: "Attribute Name", "Attribute ID", "Required"
        :widths: 30 20 20

        "Name", "100", "Required"
        "IP Address", "157", "Recommended"
        "OS Version", "115", "Recommended"
        "Domain Name", "122", "Server only"



   **Networking Prerequisites**

       Verify communication between Genian ZTNA Policy Center and JIRA Cloud. HTTPS (TCP/443) is used, and access to the following domains is required:

       - auth.atlassian.com (OAuth authentication)
       - api.atlassian.com (API calls)
       - ``*.atlassian.net`` (JIRA instance)

       Allow HTTPS communication to these domains in firewall policies.


Genian ZTNA Configuration for Integration
------------------------------------------

  **Configure Integration Information for Workflow**

   Configure JIRA Assets integration information to be used in the Workflow.

   Click the *'>>'* button in the upper left of the Workflow editing screen to open the integration information area and add the following variables:

   .. csv-table::
       :header: "Variable Name", "Setting Value", "Notes"
       :widths: 25 35 40

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

   .. note::
      - Integration information is referenced within the Workflow in the format `${connInfo.request.cloudId}`.
      - OAuth Token is entered directly in the Authorization header of the HTTP Request node.

   .. warning::
      **Security Precautions:**
      
      - Access Token expires every hour. For production environments, it is recommended to implement automatic renewal logic using Refresh Token.
      - API Key, Cloud ID, and Workspace ID are sensitive information. Always mask them when sharing documents or screenshots.
      - Never disclose the token value in the Authorization header.
      - Avoid publicly exposing ZTNA server IP addresses as they are internal network information.
      - In actual environments, replace the example values `your-cloud-id-here`, `your-workspace-id-here`, `your-api-key-here`, `your-ztna-server` with actual values.


  **Overall Workflow Structure**

   The following is the overall flowchart for the JIRA Assets automatic registration Workflow.

   .. figure:: ../images/jira-assets-workflow-diagram_EN.png
      :align: center
      :width: 100%
      :alt: JIRA Assets Workflow Overall Structure

      JIRA Assets Automatic Registration Workflow Complete Flowchart

   .. tip::
      **Workflow Components:**
      
      - **Upper Path (Windows PC)**: Retrieve ZTNA IP info → Check condition PC and Windows → Query JIRA CMDB IP address → CMDB registration result condition → Retrieve ZTNA IP info → Register JIRA CMDB asset
      - **Lower Path (Server)**: Retrieve ZTNA IP info → Check condition Server and Red Hat → Query JIRA CMDB IP address registration → Query result condition → Retrieve ZTNA IP info → Register JIRA CMDB asset
      
      **Key Decision Points:**
      
      - **Check condition PC and Windows**: Verify NodeType=20 (True → Windows PC path, False → Server path)
      - **Check condition Server and Red Hat**: Verify NodeType=40 AND NL_PLATFORM="Red Hat Linux"
      - **Registration result condition**: Verify total=0 (Register only unregistered assets)


  **Create Asset Registration Workflow**

   Click *'Workflow'* from the top menu to navigate to the Workflow Console, then click 'Select Task' and select 'Create' to enter the following:

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 30 45

       "Workflow Name", "JIRA CMDB Integration", " "
       "Description", "Automatically register network nodes to JIRA Assets", " "
       "Trigger", "Event Hooks", "Execute when external event is received"

   .. note::
      - The example in this document uses Event Hooks as the trigger.
      - Event Hooks call the Workflow when specific events (node detection, IP change, etc.) occur through Genian ZTNA's log filter feature.
      - Trigger types can be set variously such as "Node Detected", "Schedule", "Manual Execution", etc.


**Windows PC Registration Process**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   The process for registering Windows PCs to JIRA Assets consists of the following 6 steps.

   
   **Step 1: Retrieve ZTNA IP Information (First)**

   Retrieve detailed information of the node detected by Genian ZTNA.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Retrieve ZTNA IP Info", " "
       "Method", "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}", " "
       "Header - accept", "application/json", " "
       "Header - Authorization", "Basic [auth info]", "ZTNA API authentication token"
       "Body", "${request._IP}", "IP address passed from trigger"
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   .. note::
      - `${request._IP}` is the node's IP address passed from the Event Hooks trigger.
      - Enter `${request._IP}` value in the Body field to specify the IP to query.
      - This API call retrieves detailed information such as NodeType, NL_OSTYPE, NL_NODEID, NL_IPSTR of the node.


   **Step 2: Check Condition PC and Windows**

   Determine if the queried node is a Windows PC.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "IfElse (Conditional Branch)", " "
       "Name", "Check condition PC and Windows", " "
       "Condition Logic", "AND", "Both conditions must be satisfied"
       "Condition - Variable", "${[p092.result[0].NodeType]}", "Extract node type from Step 1 response"
       "Condition - Operator", "equals", " "
       "Condition - Compare Value", "20", "NodeType 20 = PC"
       "If True", "Step 3 (Query JIRA CMDB IP address)", "If NodeType is 20 (PC)"
       "If False", "Move to server classification process", "If not PC"

   .. note::
      - `p4d0` is the unique ID of Step 1 (Retrieve ZTNA IP Info) process.
      - Used in Windows PC process.
      - In the screenshot, only NodeType is checked (value 20).
      - Set as AND condition but actually only one condition exists.


   **Step 3: Query JIRA CMDB IP Address**

   Check if the IP address is already registered in JIRA Assets.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Query JIRA CMDB IP Address", " "
       "Method", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/aql", " "
       "Header - Content-Type", "application/json", " "
       "Header - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 token"
       "Body", "See JSON below", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   Body content::

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

   .. note::
      - `${[p4d0.result[0].NL_IPSTR]}` is the node's IP address retrieved in Step 1.
      - Uses AQL (Assets Query Language) to search for assets by IP address.
      - The `totalFilterCount` field in the response can verify registration status.


   **Step 4: CMDB Registration Result Condition**

   Determine if new registration is needed based on search results.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "IfElse (Conditional Branch)", " "
       "Name", "CMDB Registration Result Condition", " "
       "Condition Logic", "AND", " "
       "Condition - Variable", "${[p10b.total]}", "Number of search results from Step 3"
       "Condition - Operator", "equals", " "
       "Condition - Compare Value", "0", " "
       "If True", "Step 5 (Retrieve ZTNA IP Info)", "Unregistered asset, proceed with registration"
       "If False", "End workflow", "Already registered asset"

   .. note::
      - p10b is the process ID of Step 3 (Query JIRA CMDB IP Address).
      - Verify the number of assets found using the total field.
      - `p482` is the unique ID of the Step 3 process.
      - If `totalFilterCount` is 0, it's an unregistered asset, so continue the registration process.
      - If not 0, it's already registered, so end the workflow to prevent duplicate registration.


   **Step 5: Retrieve ZTNA IP Information (Second)**

   Retrieve node information again for asset registration.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Retrieve ZTNA IP Info", " "
       "Method", "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}", " "
       "Header - accept", "application/json", " "
       "Header - Authorization", "Basic [auth info]", "ZTNA API authentication token"
       "Body", "${request._IP}", "IP address passed from trigger"
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   .. note::
      - Call the same API as Step 1 again.
      - Retrieve latest node information to register in JIRA Assets.


   **Step 6: Register JIRA CMDB Asset (Windows PC)**

   Register Windows PC to JIRA Assets.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Register JIRA CMDB Asset", " "
       "Method", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/create", " "
       "Header - Content-Type", "application/json", " "
       "Header - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 token"
       "Body", "See JSON below", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store registration result"

   Body content::

       {
         "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" is the Windows PC Object Type in JIRA Assets.
      - Attribute ID 100: Name (FQDN/hostname)
      - Attribute ID 157: IP Address
      - Attribute ID 115: Platform (platform information)
      - Use node information retrieved in Step 5 (pe65) to create the asset.


**Server Registration Process**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Process for registering servers (Red Hat Linux, etc.) to JIRA Assets.


   **Step 1: Retrieve ZTNA IP Information (First)**

   Retrieve detailed information of the node detected by Genian ZTNA.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Retrieve ZTNA IP Info", " "
       "Method", "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}", " "
       "Header - accept", "application/json", " "
       "Header - Authorization", "Basic [auth info]", "ZTNA API authentication token"
       "Body", "${request._IP}", "IP address passed from trigger"
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   .. note::
      - `${request._IP}` is the node's IP address passed from the Event Hooks trigger.
      - Enter `${request._IP}` value in the Body field to specify the IP to query.


   **Step 2: Check Condition PC and Windows**

   First, check if it's a Windows PC.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "IfElse (Conditional Branch)", " "
       "Name", "Check condition PC and Windows", " "
       "Condition Logic", "AND", "Set condition"
       "Condition - Variable", "${[p4d0.result[0].NodeType]}", "Extract node type from Step 1 response"
       "Condition - Operator", "equals", " "
       "Condition - Compare Value", "20", "NodeType 20 = PC"
       "If True", "Windows PC registration process", "If NodeType is 20 (PC)"
       "If False", "Step 3 (Check condition Server and Red Hat)", "If not PC"


   **Step 3: Check Condition Server and Red Hat**

   Determine if it's a Red Hat Linux server.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "IfElse (Conditional Branch)", " "
       "Name", "Check condition Server and Red Hat", " "
       "Condition Logic", "AND", "Both conditions must be satisfied"
       "Condition 1 - Variable", "${[p4d0.result[0].NL_PLATFORM]}", "Extract platform info from Step 1 response"
       "Condition 1 - Operator", "equals", " "
       "Condition 1 - Compare Value", "Red Hat Linux", "Red Hat Linux platform"
       "Condition 2 - Variable", "${[p4d0.result[0].NodeType]}", "Extract node type from Step 1 response"
       "Condition 2 - Operator", "equals", " "
       "Condition 2 - Compare Value", "40", "NodeType 40 = Server"
       "If True", "Step 4 (CMDB Registration Result Condition)", "If Red Hat server"
       "If False", "End workflow", "Other OS type"

   .. note::
      - NodeType 40 represents a server in Genian ZTNA.
      - Check if NL_PLATFORM exactly matches "Red Hat Linux".
      - p4d0 is the process ID of Step 1 (Retrieve ZTNA IP Info).


   **Step 3-1: Query JIRA CMDB IP Address Registration**

   Check if the IP address is already registered in JIRA Assets.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Query JIRA CMDB IP Address Registration", " "
       "Method", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/aql", " "
       "Header - Content-Type", "application/json", " "
       "Header - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 token"
       "Body", "See JSON below", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   Body content::

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

   .. note::
      - `${[p4d0.result[0].NL_IPSTR]}` is the node's IP address retrieved in Step 1.
      - p4d0 is the process ID of Step 1 (Retrieve ZTNA IP Info).
      - Uses AQL (Assets Query Language) to search for assets by IP address.


   **Step 4: Query Result Condition**

   Check if there are any assets registered with the IP address in JIRA Assets.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "IfElse (Conditional Branch)", " "
       "Name", "Query Result Condition", " "
       "Condition Logic", "AND", " "
       "Condition - Variable", "${[pe9a.total]}", "Number of JIRA CMDB query results"
       "Condition - Operator", "equals", " "
       "Condition - Compare Value", "0", " "
       "If True", "Step 5 (Retrieve ZTNA IP Info)", "Unregistered asset"
       "If False", "End workflow", "Already registered asset"

   .. note::
      - pe9a is the process ID of Step 3-1 (Query JIRA CMDB IP Address Registration).
      - Verify the number of assets found using the total field.


   **Step 5: Retrieve ZTNA IP Information (Second)**

   Retrieve node information again for asset registration.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Retrieve ZTNA IP Info", " "
       "Method", "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}", " "
       "Header - accept", "application/json", " "
       "Header - Authorization", "Basic [auth info]", "ZTNA API authentication token"
       "Body", "${request._IP}", "IP address passed from trigger"
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store entire response"

   .. note::
      - Call the same API as Step 1 again.
      - Retrieve latest node information to register in JIRA Assets.


   **Step 6: Register JIRA CMDB Asset (Red Hat Server)**

   Register Red Hat Linux server to JIRA Assets.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "HTTP Request", " "
       "Name", "Register JIRA CMDB Asset", " "
       "Method", "POST", " "
       "Request URL", "https://api.atlassian.com/ex/jira/${connInfo.request.cloudId}/jsm/assets/workspace/${connInfo.request.workspaceId}/v1/object/create", " "
       "Header - Content-Type", "application/json", " "
       "Header - Authorization", "Basic [OAuth Token]", "JIRA OAuth 2.0 token"
       "Body", "See JSON below", " "
       "Response Type", "JSON", " "
       "Response Body Template", "(blank)", "Store registration result"

   Body content::

       {
         "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" is the Server Object Type in JIRA Assets.
      - Attribute ID 100: Name (service name)
      - Attribute ID 157: IP Address
      - Attribute ID 115: Platform (platform information)
      - p4c5 is the process ID of Step 5 (Retrieve ZTNA IP Info).
      - Use node information retrieved in Step 5 to create the asset.


   **Workflow Flow Summary**

   **Windows PC Registration Flow:**

   1. **Retrieve ZTNA IP Info** (p4d0): Call Genian ZTNA API to retrieve detailed information of detected node (include `${request._IP}` in Body, use accept header)
   2. **Check condition PC and Windows**: Verify NodeType=20 (PC) → If True, proceed
   3. **Query JIRA CMDB IP Address** (p10b): Search JIRA Assets for assets registered with the IP address using AQL
   4. **CMDB Registration Result Condition**: Verify total=0 → If True (unregistered), proceed
   5. **Retrieve ZTNA IP Info** (pe65): Retrieve latest node information again (include `${request._IP}` in Body, use accept header)
   6. **Register JIRA CMDB Asset**: Register asset as Object Type 51 (Windows PC) (NL_FQDN, NL_IPSTR, NL_PLATFORM)

   **Server Registration Flow:**

   1. **Retrieve ZTNA IP Info** (p4d0): Call Genian ZTNA API to retrieve detailed information of detected node (include `${request._IP}` in Body, use accept header)
   2. **Check condition PC and Windows**: Verify NodeType=20 (PC) → If False, proceed to next step
   3. **Check condition Server and Red Hat** (p7cb): Verify NL_PLATFORM="Red Hat Linux" AND NodeType=40 (Server) → If True, proceed
   4. **Query JIRA CMDB IP Address Registration** (pe9a): Search JIRA Assets for assets registered with the IP address using AQL
   5. **Query Result Condition**: Verify total=0 → If True (unregistered), proceed
   6. **Retrieve ZTNA IP Info** (p4c5): Retrieve latest node information again (include `${request._IP}` in Body, use accept header)
   7. **Register JIRA CMDB Asset**: Register asset as Object Type 13 (Server) (NL_SERVICE, NL_IPSTR, NL_PLATFORM)

   .. tip::
      - In actual production environments, you can add conditional branches for various OS types such as Mac OS, Windows Server, etc.
      - You can expand by adding separate IfElse nodes and HTTP Request nodes for each OS type.
      - Both Windows PC and Server processes use `${request._IP}` and authenticate with accept header in the same way.
      - Refer to the actual values shown in parentheses for process IDs.


   **Template Variable Reference Method**

   Main template variables used in Workflow:

   **Windows PC Registration Process:**

   - `${request._IP}`: IP address passed from Event Hooks trigger
   - `${[p4d0.result[0].NodeType]}`: Step 1 Retrieve ZTNA IP Info - Node type code
   - `${[p4d0.result[0].NL_IPSTR]}`: Step 1 Retrieve ZTNA IP Info - IP address
   - `${[p10b.total]}`: Step 3 Query JIRA CMDB IP Address - Number of assets found
   - `${[pe65.result[0].NL_FQDN]}`: Step 5 Retrieve ZTNA IP Info - FQDN/hostname
   - `${[pe65.result[0].NL_IPSTR]}`: Step 5 Retrieve ZTNA IP Info - IP address
   - `${[pe65.result[0].NL_PLATFORM]}`: Step 5 Retrieve ZTNA IP Info - Platform information

   **Server Registration Process:**

   - `${request._IP}`: IP address passed from Event Hooks trigger
   - `${[p4d0.result[0].NodeType]}`: Step 1 Retrieve ZTNA IP Info - Node type code
   - `${[p4d0.result[0].NL_PLATFORM]}`: Step 1 Retrieve ZTNA IP Info - Platform information
   - `${[p4d0.result[0].NL_IPSTR]}`: Step 1 Retrieve ZTNA IP Info - IP address
   - `${[pe9a.total]}`: Step 3-1 Query JIRA CMDB IP Address Registration - Number of assets found
   - `${[p4c5.result[0].NL_SERVICE]}`: Step 5 Retrieve ZTNA IP Info - Service name
   - `${[p4c5.result[0].NL_IPSTR]}`: Step 5 Retrieve ZTNA IP Info - IP address
   - `${[p4c5.result[0].NL_PLATFORM]}`: Step 5 Retrieve ZTNA IP Info - Platform information

   **Common Variables:**

   - `${connInfo.request.cloudId}`: JIRA Cloud ID stored in integration information
   - `${connInfo.request.workspaceId}`: JIRA Workspace ID stored in integration information

   .. note::
      - Process IDs (p4d0, p10b, pe65, p7cb, pe9a, p4c5, etc.) may differ for each Workflow.
      - If Response Body Template is left blank, the entire response is stored and can be referenced by JSON path in subsequent steps.
      - Both Windows PC process and Server process use `${request._IP}` (including underscore).
      - All processes perform ZTNA API authentication using accept header and Authorization header.


   **Step 7: Record Success Log (Optional)**

   Record a log when asset registration succeeds.

   .. csv-table::
       :header: "Setting Item", "Setting Value", "Notes"
       :widths: 25 35 40

       "Action Type", "Log", " "
       "Name", "log_success", " "
       "Level", "Info", " "
       "Message", "See message below", " "

   Message content::

       ✅ JIRA Assets Registration Complete
       FQDN: ${[pe65.result[0].NL_FQDN]}
       IP Address: ${[pe65.result[0].NL_IPSTR]}
       Platform: ${[pe65.result[0].NL_PLATFORM]}
       Registration Time: ${_CURRENT_TIME}

   .. note::
      - Use the latest node information retrieved in Step 5 or Step 6 in log messages.
      - Windows PC references pe65, Server references p4c5 process ID.


   **Configure Error Handlers**

   Configure error handlers to handle API call failures.

   .. csv-table::
       :header: "Error Code", "Handling Method", "Notes"
       :widths: 20 40 40

       "401 Unauthorized", "Retry after token renewal", "Access Token expired"
       "403 Forbidden", "Notify administrator", "Insufficient permissions"
       "400 Bad Request", "Validate request parameters and log", "Invalid request"
       "429 Too Many Requests", "Retry after 30 seconds wait", "Rate Limit exceeded"
       "5xx Server Error", "Retry after 5 minutes", "JIRA server error"



Verify Assets in JIRA Assets
------------------------------------------

  **Check Asset List**

   Log in to JIRA Service Management and navigate to the 'Assets' menu.

   Select the 'ITAM' schema and check registered assets in the following Object Types:

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

  
  **Check Asset Details**

   Click on a registered asset to view the following information:

   .. csv-table::
       :header: "Attribute", "Description", "Example"
       :widths: 25 35 40

       "Name", "Node identifier", "WIN-PC-001"
       "IP Address", "IP address", "192.168.1.100"
       "OS Version", "Operating system information", "Windows 11 Pro"
       "Domain Name", "FQDN", "pc001.genians.local"
       "Created", "Registration date/time", "2024-01-22 16:30:15"
       "Updated", "Last modified date/time", "2024-01-22 16:30:15"

   .. tip::
      Using the change history (History) feature provided by JIRA Assets, you can track all changes to each asset.



Use Case Scenarios
---------------------------------------------

  **Scenario 1: Automatic Registration of New Equipment**
  
   When a new Windows PC is connected to the network, Genian ZTNA automatically detects it and registers it to the 'Windows' Object Type in JIRA Assets through the Workflow. IT administrators can gain real-time visibility of asset status without manual entry.

  
  **Scenario 2: Asset Information Update**
  
   When an existing PC's OS is upgraded (e.g., Windows 10 → Windows 11), Genian ZTNA detects the change and automatically updates the 'OS Version' attribute in JIRA Assets.


  **Scenario 3: Utilize Asset Information When Creating Incident Tickets**
  
   When a user creates a PC incident ticket through JIRA Service Management, asset information (OS version, installed software, etc.) can be immediately accessed from JIRA Assets based on the PC's IP address, enabling rapid problem resolution.


  **Scenario 4: Track Asset Change History**
  
   Using JIRA Assets' change history feature, you can track all changes to specific assets chronologically, such as IP address changes, OS upgrades, etc.



API Reference
---------------------------------------------

  **Main API Endpoints**
  
   .. csv-table::
       :header: "API", "Method", "Purpose"
       :widths: 40 15 45

       "/object/aql", "POST", "Search assets with AQL query"
       "/object/create", "POST", "Register new asset"
       "/object/{id}", "PUT", "Update asset information"
       "/object/{id}", "DELETE", "Delete asset"
       "/objectschema/{id}", "GET", "Retrieve schema information"
       "/objecttype/{id}/attributes", "GET", "Retrieve Object Type's attribute list"


  **Authentication Header Format**
  
   All API calls must include the following headers::

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


  **AQL (Assets Query Language) Query Examples**
  
   Search by IP address::

       "IP Address" = "192.168.1.100"

   
   Multi-condition search::

       "IP Address" = "192.168.1.100" AND "OS Version" LIKE "Windows%"


   Filter by Object Type::

       objectType = Windows



Troubleshooting
---------------------------------------------

  **401 Unauthorized Error**
  
   - Cause: Access Token expired or insufficient permissions
   - Solution: Issue new Access Token with Refresh Token
   - Verification: Check if all required scopes are added in Developer Console


  **403 Forbidden Error**
  
   - Cause: Insufficient JIRA Assets access permissions
   - Solution: Grant 'Object Schema User' role to user or group in JIRA Assets → ITAM Schema → Settings → Roles


  **400 Bad Request Error**
  
   - Cause: Invalid Attribute ID or Object Type ID
   - Solution: Verify correct IDs with GET /objecttype/{id}/attributes API
   - Verification: Check if Object Type ID exists within schema


  **429 Too Many Requests Error**
  
   - Cause: API Rate Limit exceeded
   - Solution: Wait for 'Retry-After' value in response header and retry
   - Recommendation: Set request rate limit in Workflow (2 or fewer per second)


  **Duplicate Asset Registration**
  
   - Cause: IP address search condition is not precise
   - Solution: Use exact match search for IP address in AQL query
   - Verification: Check logs to verify Step 2 conditional branch is working correctly



References
---------------------------------------------

  **Atlassian Official Documentation**
  
   - JIRA Assets API: https://developer.atlassian.com/cloud/jira/service-desk/rest/api-group-assets/
   - OAuth 2.0 Authentication: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
   - AQL Guide: https://support.atlassian.com/jira-service-management-cloud/docs/use-assets-query-language-aql/


  **Genian ZTNA Workflow Guide**
  
   - :ref:`workflow` (Workflow Overview and Common Settings)
   - :ref:`workflow-httprequest` (HTTP Request Process)
   - :ref:`workflow-ifelse` (Conditional Branch Process)
   - :ref:`workflow-loop` (Loop Process)