1. Overview and Architecture

This integration enables tickets on SDP On-Premise to automatically create issues in Jira Cloud. When a technician clicks the button on the SDP ticket details page, the process begins, and a new issue is created in Jira.

1.1 Integration Flow

1.2 Information Required Before Installation

2 Network / Firewall Installation

A firewall rule is required to access Jira Cloud from the SDP server. If this step is skipped, a connection to Jira cannot be established from the Deluge script.

2.1 Required Firewall Rule

2.2 Connection Test — CMD (On Server)

 curl -v https:// JIRA_DOMAIN .atlassian.net

2.3 Connection Test from Deluge

Run the following test script under SDP Admin > Automation > Custom Functions:

 testUrl = "https:// JIRA_DOMAIN .atlassian.net";
 response = invokeurl
 [
 url: testUrl
 type: GET
 ];
 info response.toString();
 return response.toString();

3 Steps to Prepare for Jira

3.1 Creating Tokens via the Jira API

3.2 Creating a Base64 Authorization String

Jira REST API uses a combined Base64 encoding of email and API token for Basic Auth.

Using Windows CMD:

 echo -n " email@firma.com : API_TOKEN " | base64

Using the online tool:

Go to https://www.base64encode.org . Enter email@firma.com :API_TOKEN and click the "Encode" button.

3.3 Finding Jira Field IDs

Finding the Project ID:

 curl --request GET \
 --url "https:// JIRA_DOMAIN .atlassian.net/rest/api/3/project/search" \
 --user " email@firma.com : API_TOKEN " \
 --header "Accept: application/json"

Finding Issue Type ID:

 curl --request GET \
 --url "https:// JIRA_DOMAIN .atlassian.net/rest/api/3/issuetype/project?projectId= PROJECT_ID " \
 --user " email@firma.com : API_TOKEN " \
 --header "Accept: application/json"

Finding Custom Field IDs:

 curl --request GET \
 --url "https:// JIRA_DOMAIN .atlassian.net/rest/api/3/field" \
 --user " email@firma.com : API_TOKEN " \
 --header "Accept: application/json"

In Response, find the corresponding "id" values by searching for the domain names. Example:

3.4 Testing with Postman

Method: POST | URL: https://JIRA_DOMAIN.atlassian.net/rest/api/3/issue
Authorization: Basic Auth | Username: email | Password: api_token

 {
 "fields": {
 "project": { "key": " PROJE_KEY " },
 "issuetype": { "id": " ISSUE_TYPE_ID " },
 "summary": "Test Ticket",
 "description": {
 "type": "doc", "version": 1,
 "content": [{
 "type": "paragraph",
 "content": [{ "type": "text", "text": "Test description" }]
 }]
 },
 "customfield_ XXXXX ": "value"
 }
 }

4 SDP Callback Custom Function

The Callback Function is the structure that contains the Deluge script to send a POST request to the Jira API. PageScript triggers this function by calling it via the URL.

4.1 Creating Callback Functions

Admin > General Settings > Automation > Callback Functions > New

4.2 Deluge Script

 // ============================================
 // SDP -> Jira Cloud Integration
 // Callback Custom Function
 // ============================================

 // 1. Retrieve ticket information from the SDP API
 sdpUrl = "https:// SDP_LOKAL_URL /api/v3/requests/" + request_id;
 sdpHeaders = {
 "authtoken": " SDP_AUTH_TOKEN ",
 "PORTALID": "1"
 };
 sdpResponse = invokeurl
 [
 url: sdpUrl
 type: GET
 headers: sdpHeaders
 ];
 requestObj = sdpResponse.get("request");

 // 2. Item - Module Mapping
 // Update according to customer environment.
 modulMap = Map();
 modulMap.put(" SDP_ITEM_NAME_1 ", " JIRA_MODULE_VALUE_1 ");
 modulMap.put(" SDP_ITEM_NAME_2 ", " JIRA_MODULE_VALUE_2 ");
 // Add other items here...

 sdpItem = requestObj.get("item").get("name");
 sdpModul = moduleMap.get(sdpItem);
 if(sdpModul == null || sdpModul == "")
 {
 sdpModul = " DEFAULT_MODUL ";
 }

 // 3. Obtain SDP areas
 sdpSubject = requestObj.get("subject");

 // Clean the description from the HTML.
 sdpDescriptionRaw = requestObj.get("description");
 sdpDescription = sdpDescriptionRaw
 .replaceAll("<[^>]*>", "")
 .replaceAll("&nbsp;", " ")
 .replaceAll("&", "&")
 .replaceAll("&lt;", "<")
 .replaceAll(">", ">");

 sdpTicketID = requestObj.get("id");

 // Convert historical data to Jira format (yyyy-MM-dd)
 sdpDetectDateRaw = requestObj.get("created_time").get("display_value");
 sdpDetectDate = sdpDetectDateRaw
 .toDate("MMM dd, yyyy hh:mm a")
 .toString("yyyy-MM-dd");

 // 4. Send a POST request to the Jira API
 jiraUrl = "https:// JIRA_DOMAIN .atlassian.net/rest/api/3/issue";
 headers = Map();
 headers.put("Authorization", "Basic BASE64_STRING ");
 headers.put("Content-Type", "application/json");

 body = "{\"fields\":{" +
 "\"project\":{\"key\":\" PROJE_KEY \"}," +
 "\"issuetype\":{\"id\":\" ISSUE_TYPE_ID \"}," +
 "\"summary\":\"" + sdpSubject + "\"," +
 "\"description\":{\"type\":\"doc\",\"version\":1," +
 "\"content\":[{\"type\":\"paragraph\"," +
 "\"content\":[{\"type\":\"text\"," +
 "\"text\":\"" + sdpDescription + "\"}]}]}," +
 "\" customfield_TICKET_NO_ID \":" + sdpTicketID + "," +
 "\" customfield_ISLEM_KODU_ID \":\"-\"," +
 "\" customfield_MODUL_ID \":[{\"value\":\"" + sdpModul + "\"}]," +
 "\" customfield_IS_UNIT_ID \":[{\"name\":\" IS_UNIT_VALUE \"}]," +
 "\" customfield_DATE_ID \":\"" + sdpDetectDate + "\"" +
 "}}";

 response = invokeurl
 [
 url: jiraUrl
 type: POST
 parameters: body
 headers: headers
 content-type: "application/json"
 ];

 // 5. Return the result
 returnObj = Collection();
 if(response.get("key") != null)
 {
 returnObj.insert("result":"success");
 returnObj.insert("message":"Jira issue created: " + response.get("key"));
 }
 else
 {
 returnObj.insert("result":"failure");
 returnObj.insert("message":"Error: " + response.toString());
 }
 return returnObj;

4.3 Variable Reference Table

5 SDP Page Script — Button Setup

PageScript adds a "Create JIRA Ticket" button to the SDP ticket details page. When the technician clicks the button, the Callback Function is triggered.

5.1 Creating Page Scripts

Admin > General Settings > Page Scripts > New

5.2 Page Script Code

 // ============================================
 // SDP -> Jira Cloud | Page Script
 // Request Details Page - Create Jira Button
 // ============================================

 $CS.addButton("edit", "Create JIRA Ticket", function(){

 // Get Ticket ID from URL
 var woID = window.location.href.match(/woID=(\d+)/);
 var requestId = woID ? woID[1] : null;

 if(!requestId){
 alert("Request ID could not be received!");
 return;
 }

 // Callback Function URL
 // NOTE: The technician's access URL must be in the same domain as the CORS (Coordinated Domain)
 var callbackUrl = "https:// SDP_TEKNISYEN_URL /AppIntegrations" +
 "?serviceName=callbackFunctions" +
 "&api_name=create_jira_issue" +
 "&auth_token= CALLBACK_AUTH_TOKEN " +
 "&PORTALID=1";

 // Encode arguments and send via POST
 var bodyData = "arguments=" +
 encodeURIComponent('{"request_id":"' + requestId + '"}');

 var promise = fetch(callbackUrl, {
 method: "POST",
 headers: {"Content-Type": "application/x-www-form-urlencoded"},
 body: bodyData
 });

 promise.then(function(response){
 return response.text();
 }).then(function(text){
 try {
 var result = JSON.parse(text);
 var output = result.output;
 if(output && output.result === "success"){
 alert("Jira ticket successfully created!\n" + output.message);
 } else {
 alert("Could not create Jira ticket!\n" +
 (output ? output.message : text));
 }
 } catch(e){
 alert("Server response: " + text);
 }
 }).catch(function(err){
 alert("Connection error: " + err);
 });

 }, {
 "class": "btn btn-default btn-xs ml10",
 "style": "background-color: #e57373; color: white; border-color: #e57373;"
 });

5.3 Finding Callback Auth Tokens

6 Troubleshooting

6.1 Authentication Test (Deluge)

 testUrl = "https:// JIRA_DOMAIN .atlassian.net/rest/api/3/myself";
 headers = Map();
 headers.put("Authorization", "Basic BASE64_STRING ");
 response = invokeurl
 [
 url: testUrl
 type: GET
 headers: headers
 ];
 info response.toString();
 return response.toString();

7 New Customer Setup Checklist

Complete the following steps in order for each new customer installation.