External action plug-in

 The following topics are discussed in this document:

Purpose of this Document

This document provides procedural information for developers to create a plug-in and establish integration between ServiceDesk Plus and various other third party applications.

About External Action Plugin

A complete request workflow requires different tasks to be performed by the Support team. Occasionally, the Support team might involve third party applications to accomplish certain tasks by accessing the concerned applications, which may exceed the application limit.

Thus, to overcome the tedious process of bringing in the third party applications to perform the tasks, such as issue tracker integration, active directory account creation and new mail account creation, you can avail the External Action Plug-in option in ServiceDesk Plus. This option aids the Support team in performing various third party related operations right from the 'Requests' page just by clicking the 'Actions' menu.

 

Scenario:

Consider an organization using ServiceDesk Plus for their customer support and JIRA for bug tracking. Here is where the external action plug-in framework comes into play, using which they can build integration between ServiceDesk Plus and JIRA. As a result, they can create JIRA issues from the 'Actions' menu of 'Requests' page.

 

External Action Plugin

x_plugin 
Skills Required to Develop the External Action Plugin

Knowledge in the following areas is required to work on the plug-in:

Setting Up the Plug-in

 The plug-in is designed to have an implementation class and can be invoked through a menu. The menu can be configured under the 'Admin' module of ServiceDesk Plus.

Implementation Class

The Java class should extend the 'DefaultActionInterface' and provide the implementation through the 'execute' method. The required import classes are available in 'AdventNetHelpDesk.jar' and 'AdventNetServiceDeskCommon.jar' found under:

"[SCP_HOME]applicationsextractedAdventNetSupportCenter.eearAdventNetHelpDesk.ear".
 

 

package com.manageengine.servicedesk.actionplugin.sample;

import com.manageengine.servicedesk.actionplugin.executor.ActionInterface

import com.manageengine.servicedesk.actionplugin.executor.ExecutorData

public class SampleActionImplementation extends DefaultActionInterface

{

public JSONObject execute(ExecutorData executorData) throws Exception

{

ExecutorData data = executorData;

 

ActionMenuData menuData = data.getActionMenuData();

String menuName = (String) menuData.getMenuName();

JSONObject scpValuesObj  = data.getDataJSON();

 

//You can have your implementation here

//Return type should be JSON

 

}

}

 

The Execute Method:

 The implementation will be defined on the execute method with the parameter ExecutorData Object:

Executor Data:

The ExecutorData object is a parameter to the Execute method. Using this, we can get the details about the menu that is invoked using the getActionMenuData() method. This returns an object called ActionMenuData:

i) ActionMenuData - This provides information about the menu from which the action is invoked.

Below are the methods available to extract values and their respective data types:
       

Parameter

Return Value

getMenuName

 

Returns the name of the action menu that is invoked.

String

getDisplayText

 

Returns the display name of the menu that is invoked.

String

getExecutorClass

 

Returns the name of the Java execution class specified for this menu.

String

getAllowedRoles

 

Returns the list of roles that are allowed to use this menu.

ArrayList

getAllowedTemplates

 

Returns the list of templates in which this menu will be available.

ArrayList

 

ii) JSON Data- The details of the request from which the menu has been triggered can be obtained by invoking the getDataJSON method in ExecutorData. This will return the details as a JSON object:

A sample data would look like below:
 

 {

    "WORKORDERID": "1",
    "REQUESTER": "Guest",
    "CREATEDBY": "administrator",
    "CREATEDTIME": "1469685688321",
    "DUEBYTIME": "1469692888321",
    "RESPONSEDUEBYTIME": "-1",
    "FR_DUETIME": "-1",
    "RESPONDEDTIME": "0",
    "RESOLVEDTIME": "0",
    "COMPLETEDTIME": "0",
    "SHORTDESCRIPTION": "",
    "TIMESPENTONREQ": "0hrs 0min",
    "SUBJECT": "Testing for Bulk SMS",
    "REQUESTTEMPLATE": "Default Request",
    "MODE": "E-Mail",
    "SLA": "Medium SLA",
    "ASSET": "",
    "DEPARTMENT": " HR  Department",
    "EDITORID": "null",
    "EDITING_STATUS": "0",
    "IS_CATALOG_TEMPLATE": "false",
    "SITE": "Singapore Support",
    "ISVIPUSER": "No",
    "SERVICE": "",
    "CATEGORY": "Software",
    "SUBCATEGORY": "MS Office",
    "ITEM": "Install",
    "TECHNICIAN": "Heather Graham",
    "TECHNICIAN_LOGINNAME": "Heather",
    "STATUS": "Open",
    "PRIORITY": "Medium",
    "LEVEL": "Tier 2",
    "IMPACT": "",
    "URGENCY": "High",
    "IMPACTDETAILS": "-",
    "REQUESTTYPE": "Incident",
    "APPROVAL_STATUS": "",
    "CLOSURECODE": "",
    "CLOSURECOMMENTS": "",
    "FCR": "false",
    "YETTOREPLYCOUNT": "",
    "GROUP": "Hardware Problems",
    "DESCRIPTION": "",
    "Test": ""
}

 

                                            --------------------------------------------------------------------------------------------------------------------

 

Request Operations Supported By Default

With this information customers can write their own implementation code for perform the necessary operation. Now, there are two ways to update a ticket. The first option is to use the REST API support available in SDP and update the request or perform operations like adding a worklog, notes, resolution etc., The second is to use the default return functionality supported by action plugin framework.

The execute method returns a JSON Object. By default, adding of notes and updating a request is supported if the returned JSON complies with the supported format.

 

a. Adding Notes to a Request
 

 

{

"message":"Request Added Successfully",

"result":"success",

"operation":[

{

"INPUT_DATA": [

{

"notes": {

"notestext":"Tickethas been created in JIRA and information populated in SDP"

}

}],

"OPERATIONNAME":"ADD_NOTE"

}],

}

 

 

b. Updating a Request
 

 

{

"message":"Request Added Successfully",

"result":"success",

"operation":[

{

"INPUT_DATA": [

{

"Jira ID":"35",

"Jira Key":"SDP-3",

"self":"http://jira-server/rest/api/2/issue/35"

}],

"OPERATIONNAME":"UPDATE_REQUEST"

}],

}

 

 

Default Integration (integration with JIRA)

For configuring Request Actions Menu
 

 

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

<menus>

<menu name=""JiraIntegration"" refresh="true">

<displaytext>SCP to Jira Integration</displaytext>

<roles>

<role>ModifyRequests</role>

</roles>

<template>

<template>System Defined Template</template>

</templates>

<invoke>

<class>com.manageengine.supportcenter.integrations.jira.action.JiraActionImplementation</class>

</invoke>

</menu>

<menu name=""SDP Integration"" refresh="true">

<displaytext>SCP to SDP Integration</displaytext>

<roles>

<role>ModifyRequests</role>

</roles>

<templates>

<template>System Defined Template</template>

<template>testing</template>

</templates>

<invoke>

<class>com.manageengine.supportcenter.integrations.jira.action.SDPActionImplementation</class>

</invoke>

</menu>

</menus>

 

 

For JIRA Integration

Note: We will be providing a default implementation for JIRA. For this customers needs to define another xml which will have the JIRA specific implementations.
 

 

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

<menus>

<!-- The menu name should match the one specified in the ActionMenu xml -->

<menu name="JiraIntegration">

<--Specifies the input parameters that should be passed to JIRA-->

<request>

<!-- Credentials need to login to JIRA -->

<username>administrator</username>

<password>administrator</password>

<!-- URL to invoke to perform the operation -->

<url>http://localhost:8080/rest/api/2/issue/</url>

<!-- Params to be passed to the URL -->

<param>

<name>project</name>

<type>projectpicker</type>

<value>SCP</value>

</param>

<param>

<name>Issuetype</name>

<type>select</type>

<value>Bug</value>

<!-- Dynamic parameters can be specified by a $ prefix. In this case, the value for the variable will be taken from SDP and passed. -->

 

</param>

<param>

<name>summary</name>

<type>textfield</type>

<value>$subject</value>

<param>

<name>priority</name>

<type>select</type>

<value>$priority</value>

</param>

<param>

<name>description</name>

<type>textarea</type>

<value>$description</value>

</param>

<param>

<name>labels</name>

<type>labels</type>

<value>$JIRA_ISSUE_ID</value>

</param>

<param>

<name>environment</name>

<type>textarea</type>

<value>$description</value>

</param>

<param>

<name>duedate</name>

<type>datepicker</type>

<value>$dueByTime</value>

</param>

<param>

<name>customfield_10002</name>

<type>url</type>

<value>$Company Website</value>

</param>

<param>

<name>customfield_10100</name>

<type>url</type>

<value>$JIRA_SelectList</value>

</param>

<param>

<name>customfield_10200</name>

<type>float</type>

<value>$Jira Numeric Field</value>

<param>

<name>customfield_10300</name>

<type>textfield</type>

<value>$Jira_Text Field</value>

</param>

<param>

<name>customfield_10301</name>

<type>datetime</type>

<value>$Jira_Date Time</value>

</param>

<param>

<name>customfield_10302</name>

<type>datepicker</type>

<value>$Jira_Date Picker</value>

</param>

<param>

<name>customfield_10303</name>

<type>userpicker</type>

<value>$Jira_User Picker</value>

</param>

<param>

<name>customfield_10304</name>

<type>grouppicker</type>

<value>$Jira_Group Picker</value>

<param>

<name>customfield_10306</name>

<type>textarea</type>

<value>$Jira_Free Text Field</value>

</param>

</request>

<success>Successfully Integrated with Jira and the Jira id is : $id</success>

<failure>Failed to Integrate to jira</failure>

<!-- Specifies the fields that are to be updated after the action is executed -->

<response>

<param>

<!-- name indicates the attribute in the return JSON object received from JIRA API -->

<name>JIRA_ISSUE_ID</name>

<!-- value indicates the SDP field that should be updated with the JIRA value -->

<value>$ id</value>

</param>

<param>

<!-- name indicates the attribute in the return JSON object received from JIRA API -->

<name>JIRA_ISSUE_URL</name>

<!-- value indicates the SDP field that should be updated with the JIRA value -->

<value>$ self</value>

</param>

<!-- In any note needs to be added at the end of the operation, then it needs to be specified here. $message will take the value from the json object returned by JIRA. Hardcoded messages can also be given -->

<notes>

<note>Ticket is created in jira with key : $key And with Id: $id</note>

<note>Ticket is created in jira with issueID : $id</note>

</notes>

</response>

</menu>

<menus>