External Action Plugin

     

     

    About External Action Plugin

    Requests usually contain tasks that need several third party apps for their completion. Example: Active Directory account creation, issue tracker integration, new mail account creation and so on. To work on such requests the technician has to accomplish these tasks by accessing the concerned third party apps, perform the necessary operations and then populate the request template with the details obtained. This has been the procedure so far. Since this process might seem tedious to some, a feature - by name External Action Plugin - enabling technicians to perform various third-party related actions right from the request template at the click of a button has been introduced.The objective of External Action Plugin is to connect to any third party app - needed for processing requests - via XML codes that contain the code needed for integration with third party apps.

     

    External Action Plugin

    x_plugin

    Integration with Third Party Applications

    To integrate ServiceDesk Plus with third party apps you have to modify the file Request_ActionMenu.xml situated in the location: [SDP Home]/server/default/conf to suit your requirements.

     

     Note

    note

    1. You can connect to third party apps from Actions menu of the respective Request's Details Page.

    2. Actions Menu can be customized as per your requirement via External Action Plugin

     

    Skeleton Code (along with dummy attributes) for Integrating SDP with Third Party Apps:

     

    <menus>

    <menu name="Add Jira Ticket" refresh="true">

    <displaytext>Create a JIRA ticket</displaytext>

    <roles>

    <role>SDAdmin</role>

    </roles>

    <template>

    <template>Default Request</template>

    </templates>

    <invoke>

    <class>com.manageengine.servicedesk.actionplugin.sample.JIRAIntegration</class>

    </invoke>

    </menu>

    </menus>

     

    The above stated code integrates issue tracking software JIRA with ServiceDesk Plus via 'Add Jira Ticket' menu option that is added to the Actions menu. The statement com.manageengine.servicedesk.actionplugin.sample.JIRAIntegration (which calls for class JIRAIntegration) does this operation.

     

     Note

    1. In the above code JIRA Integration Class - part of ServiceDesk Plus by default - is invoked to bring about integration with ServiceDesk Plus.

    2.Since we are dealing with tickets (requests) it becomes necessary to decide 'who gets access to it' and also the 'template to be used' while generating it. These are done using <roles> and <template> tags respectively.

     

    Table illustrating various tags used in the code (along with their purpose):



    Tags

    Description

    Example

    menus

    contains all menus you create under Actions menu; serves as root to all the menus.

    <menus></menus>

    menu

    created individual menus - under Actions menu - each of which is identified using a unique 'name' attribute

    <menu>JIRA Integration</menu>

    <menu>SDP Integration</menu>

    display text

    configures Text to be displayed in User Interface (UI); can be in i18N format (like "sdp.action.createticket") but should have the corrosponding key in '*.properties' file under 'custom/i18n/*

    <displaytext>SCP to Jira Integration</displaytext>

    <displaytext>SCP to SDP Integration</displaytext>

    roles

    contains all roles (access permission) for accessing/viewing Actions Menu configured via External Action Plugin

    <roles></roles>

    role

    creates roles (access permission) for accessing/viewing Actions Menu configured via External Action Plugin

    <role>SDADMIN</role>

    <role>SDGUEST</role>

    templates

    Refers to various templates associated with Requests; optional tag that won't be required when all templates are taken into consideration

    <templates></templates>

    template

    Refers to an unique template to be associated with Requests (like Incident Template, Reply Template etc.,)

    <template>default template</template>

    <template>system defined template</template>

    invoke

    Tag responsible for invoking the necessary action (like tagging a request with ID etc.,)

    <invoke></invoke>

    class

    Refers to Class with which the needed action is scripted

    <class>JiraActionImplementation</class>



    Configuring your Integration

    Customize SDP (Actions Menu) to integrate with third party apps for performing request related operations by extending the DefaultActionInterface based on your requirements.



     Note

    1. DefaultActionInterface is the interface that allows external actions to be performed on an entity (in this case, the Actions Menu)

    2. An implementation of the ActionInterface Class should be specified in the .xml file.



    Extending the DefaultActionInterface:

     

     

    package com.manageengine.servicedesk.actionplugin.sample;

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

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

    public class JIRAIntegration extends DefaultActionInterface

    {

    public JSONObject execute(ExecutorData executorData) throws Exception {

     

    }

    }

     



    Methods available in ExecutorData are:

    Package: com.manageengine.servicedesk.actionplugin.executor.ExecutorData

    a. getActionMenuData( )

     

    Parameter

    Return Value

    Action

    getMenuName

    String

    gets the name of the action menu

    getDisplayText

    String

    gets the display name for the action menu

    getExecutorClass

    String

    gets the configured implementation class

    getRefresh

    Boolean

    gets info related to whether the page should be refreshed or not)

    getAllowedRoles

    Array

    gets info about list of allowed roles; is empty when not configured

    getAllowedTemplates

    Array

    gets info about list of allowed templates; remains empty when not configured



    b.getDataJSON( )

     

    Will return JSONObject of the request from where the menu is invoked. Sample data would be like:


    {

    "WORKORDERID":"4",

    "REQUESTER":"Guest",

    "CREATEDBY":"administrator",

    "DUEBYTIME":"-1",

    "RESPONSEDUEBYTIME":"-1",

    "CREATEDBY":"administrator",

    "FR_DUETIME":"-1",

    "RESPONDEDTIME":"0",

    "RESOLVEDTIME":"0",

    "COMPLETEDTIME":"0",

    "SHORTDESCRIPTION":"The printer is not working from the machines that are in the 10th floort",

    "TIMESPENTONREQ":"0hrs 0min",

    "SUBJECT":"Printer not working",

    "REQUESTTEMPLATE":"Default Request",

    "MODE":" ",

    "SLA":" ",

    "ASSET":" ",

    "DEPARTMENT":" ",

    "SITE":" ",

    "CATEGORY":" ",

    "SUBCATEGORY":" ",

    "ITEM":" ",

    "TECHNICIAN":" ",

    STATUS":"Open",

    "PRIORITY":" ",

    "LEVEL":" ",

    "IMPACT":" ",

    "URGENCY":" ",

    "IMPACTDETAILS":" ",

    "REQUESTYPE":" ",

    "CLOSURECODE":" ",

    "CLOSURECOMMENTS":" ",

    "GROUP":" ",

    }

     

     

     



    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://seshadri-0040: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>


     

     

     

     

    Copyright © 2017, ZOHO Corp. All Rights Reserved.