External Action Plug-in
Purpose of this Document
This document provides procedural information for developers to create a plug-in and establish integration between SupportCenter Plus and various third party applications.
About the External Action Plug-in
A complete request workflow requires a different set of tasks that has to be performed by the Support team. Occasionally the Support team might involve third party apps to accomplish certain tasks by accessing the concerned apps and perform the necessary operations, which is beyond the application limit.
To overcome the tedious processes of accessing the third party app for performing 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 SupportCenter Plus. The external plug-in option aids the Support team to perform various third party related operations right from the Request page through a click on the Request Actions menu.
|
Scenario:
For example, an organization uses SupportCenter Plus for their customer support and JIRA for bug tracking. Using the external action plug-in framework they can build integration between SCP and JIRA, through which JIRA issues can be created from SCP request actions menu.
|
Skills Required to Develop this Plug-in
Knowledge on the following areas will be required to work on the plug-ins:
Setting Up the Plug-in
Every plug-in should have an implementation class and can be invoked through a menu. The menu can be configured under SCP's Admin module.
Menu Configuration
The menu (Action Menu) can be configured under Admin --> Helpdesk Settings --> Menu Invocation. For more information on configuring the menu, refer "Menu Invocation". You can connect to third party apps from this menu.
Implementation Class
The Java class should extend the DefaultActionInterface and provide the implementation through the execute method. The required import classes are available on AdventNetHelpDesk.jar and AdventNetServiceDeskCommon.jar found under "[SCP_HOME]\applications\extracted\AdventNetSupportCenter.eear\AdventNetHelpDesk.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
}
}
|
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. From this we can get the information of the menu that has been invoked using the getActionMenuData() method. This returns an ActionMenuData object.
-
ActionMenuData – This is the information about the menu from which the action is invoked.
-
Method: getActionMenuData()
- Returns: ActionMenuData
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
|
- 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.
-
Method: getDataJSON()
- Returns: JSONObject
A sample data would look like below,
|
{
"product":"Printer",
"item":"test",
"level":"Tier 2",
"phone":"23456787",
"userTimeFormat":"MMM d, yyyy hh:mm a",
"contract":"Acme Contract",
"jobTitle":"Acme",
"productID":"001",
"supportRep":"Adam Smith",
"respondedTime":"0hrs 0min",
"dueByTime":"Jun 20, 2013 04:09 PM",
"requestID":"007",
"statusID":"Open",
"subAccountID":"221",
"isFirstResponseOverDue":"false",
"accountID":"123",
"productType":"Hardware",
"businessUnit":"General",
"mobileNo":"9999999999",
"Region":"US",
"subAccount":"Acme",
"Customer Type":"Reseller",
"isOverDue":"false",
"subCategory":"test",
"priority":"high",
"timeSpentOnRequest":" ",
"group":"Defective Item Group",
"completedTime":" ",
"firstResponseDueByTime":" ",
"account":" ",
"updatedTime":"Jun 20, 2013 03:57 PM",
"category":"Defective Item Issue",
"mode":"Phone Call",
"createdBy":"administrator",
"supportPlan":" ",
"supportPlanType":" ",
"status":"Open",
"contactEmail":" ",
"contractNumber":" ",
"createdTime":"Jun 20, 2013 03:09 PM",
"contact":"Guest",
"contactID":"2",
"License Status":"Customer",
"hasAttachments":"false",
"description":"Printer is not working",
"secondEmail":" ",
"supportRepCostPerHour":"0.0",
"subject":"Printer Problem"
}
|
For compilation, use AdventNetHelpDesk.jar, AdventNetServiceDeskCommon.jar in the class path that are found under "[SCP_HOME]\applications\extracted\AdventNet
SupportCenter.eear\AdventNetHelpDesk.ear\" and json.jar found under "[SCP_HOME]\server\default\lib\".
|
Note
|
Values from the JSON can be extracted through available Java library and pushed into another application to perform desired operations.
|
Return From Execute Method:
The execute method should return a JSONObject and it can contain success/failure message which will be added in the history and displayed on a pop up in SCP. A sample return JSONObject with message and result would look like,
|
{
"message":"Request Added Successfully",
"result":"success"
}
|
Below are the default operations that can be performed in SupportCenter Plus with the JSON returned from the execute method.
a. Adding Notes to a Request
|
{
"message":"Request Added Successfully",
"result":"success",
"operation":[
{
"INPUT_DATA": [
{
"notes": {
"notesText":"Sample Text"
}
}
],
"OPERATIONNAME":"ADD_NOTE"
}
]
}
|
b. Updating a Request
|
{
"message":"Request Added Successfully",
"result":"success",
"operation":[
{
"INPUT_DATA": [
{
"Custom Field1":"35",
"Custom Field2":"AAA-3",
"Custom Field3":"XXX"
}
],
"OPERATIONNAME":"EDIT_REQUEST"
}
]
}
|
c. Adding Note and Updating a Request
|
{
"message":"Request Added Successfully",
"result":"success",
"operation":[
{
"INPUT_DATA": [
{
"notes": {
"notesText":"Sample Text"
}
}
],
"OPERATIONNAME":"ADD_NOTE"
},
{
"INPUT_DATA": [
{
"Custom Field1":"35",
"Custom Field2":"AAA-3",
"Custom Field3":"XXX"
}
],
"OPERATIONNAME":"EDIT_REQUEST"
}
]
}
|
|
Note
|
You can update default fields and the additional fields of the request with the values returned from another application either via the default return of the execute method (See, Execute Method) or using the API methods available in SupportCenter Plus. (See, API Documentation)
|
If you would like to perform other operations like adding timeentry, adding resolution, etc., then you can do it using REST API directly in your code.
Upon invoking the action from the Actions menu, an entry will be added to the history details say, "Menu invoked is (integration name)" then your implementation class will be called. The reply received from your application will be updated over again in the history and a message will be shown in a pop up. If the menu configuration has 'refresh' parameter set to "true" then the request details page will be reloaded.
