Introduction
ManageEngine ServiceDesk Plus is a web-based, IT help desk software with integrated asset and project management built on an ITIL framework.
This document describes the ManageEngine ServiceDesk Plus On-Premise deployment.
OpsRamp supports bidirectional (outbound and inbound) integration.
OpsRamp Configuration
Install the Integration
- From All Clients, select a client.
- Go to Setup > Account.
- Select the Integrations and Apps tab.
- The Installed Integrations page, where all the installed applications are displayed. Note: If there are no installed applications, it will navigate to the Available Integrations and Apps page.
- Click + ADD on the Installed Integrations page. The Available Integrations and Apps page displays all the available applications along with the newly created application with the version.
- Search for ManageEngine ServiceDesk Plus using the search option available.
Note: Alternatively, you can use the All Categories option to search. - Click ADD on the ManageEngine ServiceDesk Plus tile. The Inbound tab is displayed.
Configure Outbound Integration
Follow these steps to configure Outbound integration:
Configure the Outbound (From OpsRamp to ManageEngine ServiceDesk Plus)
To configure the outbound, follow these steps:
- Map Attributes: From the Map Attributes window, enter the below information:
- OpsRamp Entity: Select the OpsRamp entity from dropdown.
- OpsRamp Property: Select the OpsRamp property from dropdown. It will change based on entity selection.
- meservicedeskplus Entity: Enter the ServiceDesk entity.
- meservicedeskplus Property: Enter the ServiceDesk property.
- Click +Property Value in the Property Values section, and enter meservicedeskplus Property Value and OpsRamp Property Value and click Save.
Note:- The Property values section appears based on the OpsRamp Property selected.
- To add property values, click +Property Value.
- To map more attributes, click +Entity.
- Click Add Map Attributes .
- Events: Events are for sending notifications when an action is performed on OpsRamp entities.
- Click Add in the Events section.
- Enter a name for the event.
- Select the Entity, Entity Type, and Entity Type Event from the drop-down lists.
- (Optional) Under Advanced Settings, enter the values for Property, Operator, and Value and click Save.
- From Actions:
- (Optional) Select Use Parent Configuration checkbox to inherit parent configuration.
- Enter the Endpoint URL.
Example:http://<servername>:<port number>/api/v3/requests/. - Select the Notification Type as REST API.
- Select the Authentication Type as None.
- Select the web method.
- (Optional) Select Use Parent Configuration checkbox to inherit parent configuration.
- Headers:
- Click +Add and enter/select the header name and value. Example:
- Name: Content-Type. Value: application/x-www-form-urlencoded.
- Name: Accept. Value: application/vnd.manageengine.sdp.v3+json.
- Click Save to save the header name.
- (Optional) Click +Add to add more headers
- Enter the Payload.
- Response:
- Click +Add and enter/select the response name and value.
Example:- Name: EXT_ENTITY_ID. Value: $request.id.
- Name: STATUS_MSG. Value: $response_status.status.
- Click Save to save the response name.
- (Optional) Click +Add to add more _response
Note: The event is created, only if you provide the response properties.
- Click +Add and enter/select the response name and value.
- (Optional) Attachment: In the Attachment section, provide inputs in the Process Type, Attachment Endpoint URL, and Web Method fields.
- Attachment Headers: In the Attachment Headers section, provide inputs in the Name and Value fields and click Save.
- Enter the payload in the Attachment Payload box.
- Enter the Key and Value in the Attachment Response section.
- Click Add Event. The event is added.
There are some actions you can perform on the Events.
See here for more details.
Integration response mapping configuration
Response mapping configuration is mainly based on the response payload that is received in third party payload; below are a few examples for response mapping configuration:
- sample response payload to mapping the id in response mapping:
{ "id":"INC0001", "type":"incident", "tool":"servicedesk" }external ticket id = $id
We need to append $ to the value - sample response payload to mapping the id in response mapping:
{ "result":{ "id":"INC0001", "type":"incident", "tool":"servicedesk" } }external ticket id = $result.id
- Sample response payload to mapping the id in response mapping
{ "result":[ { "ticketDetails":{ "id":"INC0001", "type":"incident", "tool":"servicedesk" }, "Description":{ "display_value":"testing description", "value":"validating" } } ] }external ticket id = $result[0].ticketDetails.id
- sample response payload to mapping the Incident Number in response mapping
{ "result": { "Incident Number": "INC0001", "type": "Incident" } }external ticket id = $result[‘Incident Number’]
- Failures: In the case of failure in integration, an Email is sent to the user about the failure in integration.
To configure failure notification:- Click add from the Failures section.
- Select notification type as Email.
- Enter the email address(es) in the To and CC fields
- Click Add Failure Notifications. The details are added.
- Click Finish. The integration is installed.
Actions on Integration
You can perform actions on an integration.
- See here for more information.
Actions on Event
Follow these steps to perform actions on the events:
- Click on the integration name.
- Navigate to Outbound tab > Events section.
- Hover over the event name.
- Click the actions (three dots) menu. A popup appears with options.
- Copy Id: To copy an event Id.
- Edit: To edit the event details.
- Save as: To save an event name.
- Validate: Validate if the event is successful.
- Select Json or Form.
- Json: Enter the payload and click Validate.
- Form: Enter the property and value in the fields and click Validate.
A green tick appears if the event is successful
- Json: Enter the payload and click Validate.
- Select Json or Form.
- Remove: To remove an event.
Audit Logs
View logs from the Audit Logs tab. You can view if the event was successful or not.
Integration event payloads
Create Incident
| Field | Value | ||||
|---|---|---|---|---|---|
| Endpoint URL | http://<servername>:<port number>/api/v3/requests | ||||
| Notification Type | REST API | ||||
| Authentication | NONE | ||||
| Web Method | POST | ||||
| Headers |
Click the Add icon to add multiple values. | ||||
| Payload |
|
Request payload
{
"request": {
"subject": "$incident.subject",
"description": "$incident.impact",
"request_type": {
"name": "Incident"
},
"requester": {
"name": "$incident.createdBy.fullName"
},
"priority": {
"name": "[@$incident.priority.name@]"
},
"status": {
"name": "[@$incident.status.name@]"
},
"impact_details": "$incident.impact",
"udf_fields": {
"udf_sline_301": "$incident.uniqueId"
}
}
}
Provide additional API field name in place of udf_sline_301
Response
{
"request": {
"ola_due_by_time": null,
"resolution": {
"resolution_attachments": [],
"content": null
},
"onhold_time": null,
"is_trashed": false,
"fr_sla_violated_group": null,
"id": "18",
"assigned_time": null,
"requester": {
"email_id": null,
"phone": "1234455",
"name": "administrator",
"mobile": "1234567890",
"profile_pic": {
"content-url": "/images/default-profile-pic2.svg"
},
"is_vipuser": false,
"id": "5",
"department": null
},
"cancel_requested_by": null,
"sla_violated_technician": null,
"item": null,
"has_resolution_attachments": false,
"impact": null,
"sla": null,
"priority": null,
"sla_violated_group": null,
"tags": [],
"has_notes": false,
"is_current_ola_violated": null,
"image_token": "f058d4bb03f0d3e5f6fded34057af6c97d78995a17032583dd27862de2fda7916133843ec290cfd17dea194c2a075e4aa6c3d5d3",
"status": {
"color": "#0066ff",
"name": "Open",
"id": "2"
},
"template": {
"is_service_template": false,
"service_category": null,
"name": "Default Request",
"id": "1"
},
"primary_asset": null,
"request_type": null,
"cancel_requested_time": null,
"chat_type": 0,
"is_service_request": false,
"cancel_requested": false,
"has_request_initiated_change": false,
"has_attachments": false,
"has_linked_requests": false,
"has_request_caused_by_change": false,
"has_problem": false,
"subject": "Unable to fetch mails",
"linked_to_request": null,
"mode": null,
"is_read": false,
"lifecycle": null,
"reason_for_cancel": null,
"assets": [],
"group": null,
"email_to": [],
"created_time": {
"display_value": "Mar 18, 2024 10:17 AM",
"value": "1710757038415"
},
"level": null,
"approval_status": null,
"service_category": null,
"created_by": {
"email_id": null,
"phone": "1234455",
"name": "administrator",
"mobile": "1234567890",
"profile_pic": {
"content-url": "/images/default-profile-pic2.svg"
},
"is_vipuser": false,
"id": "5",
"department": null
},
"scheduled_end_time": null,
"first_response_due_by_time": null,
"last_updated_time": null,
"impact_details": "Tasks are pending",
"subcategory": null,
"email_cc": [],
"scheduled_start_time": null,
"email_ids_to_notify": [],
"notification_status": null,
"description": "Unable to fetch mails from the mail server",
"has_dependency": false,
"has_conversation": false,
"fr_sla_violated_technician": null,
"callback_url": null,
"urgency": null,
"is_shared": false,
"request_template_task_ids": [],
"department": null,
"is_reopened": false,
"has_draft": false,
"is_overdue": false,
"technician": null,
"due_by_time": null,
"has_project": false,
"is_first_response_overdue": false,
"cancel_requested_is_pending": false,
"recommend_template": null,
"unreplied_count": null,
"category": null,
"maintenance": null
},
"response_status": {
"status_code": 2000,
"status": "success"
}
}
To map ManageEngine ServiceDesk Plus ticket ID with OpsRamp,
select EXT_ENTITY_ID from Response drop-down and enter the
$request.id value.
Update incident
| Field | Value | ||||
|---|---|---|---|---|---|
| Endpoint URL | http://<servername>:<port number>/api/v3/requests/$utils.extEntityId($incident.id,$installedAppId,$entity) | ||||
| Notification Type | REST API | ||||
| Authentication | NONE | ||||
| Web Method | PUT | ||||
| Headers |
| ||||
| Payload |
|
Request payload
{
"request": {
"subject": "$incident.subject",
"description": "$incident.impact",
"request_type": {
"name": "Incident"
},
"priority": {
"name": "[@$incident.priority.name@]"
},
"status": {
"name": "[@$incident.status.name@]"
},
"impact_details": "$incident.impact",
"udf_fields": {
"udf_sline_301": "$incident.uniqueId"
}
}
}
Provide additional API field name in place of udf_sline_301
Response
{
"request": {
"ola_due_by_time": null,
"resolution": {
"resolution_attachments": [],
"content": null
},
"onhold_time": null,
"is_trashed": false,
"fr_sla_violated_group": null,
"id": "18",
"assigned_time": null,
"requester": {
"email_id": null,
"phone": "1234455",
"name": "administrator",
"mobile": "1234567890",
"profile_pic": {
"content-url": "/images/default-profile-pic2.svg"
},
"is_vipuser": false,
"id": "5",
"department": null
},
"cancel_requested_by": null,
"sla_violated_technician": null,
"item": null,
"has_resolution_attachments": false,
"impact": null,
"sla": {
"name": "High SLA",
"id": "4"
},
"priority": {
"color": "#ff0000",
"name": "High",
"id": "4"
},
"sla_violated_group": null,
"tags": [],
"has_notes": false,
"is_current_ola_violated": null,
"image_token": "1fd69830b17420ba341af26161af2c45f6b915d3a97e00beb0095416f72164ffa8bd25c229dbb1f15029dd3c37cc598fcfbaef6c",
"status": {
"color": "#0066ff",
"name": "Open",
"id": "2"
},
"template": {
"is_service_template": false,
"service_category": null,
"name": "Default Request",
"id": "1"
},
"primary_asset": null,
"request_type": null,
"cancel_requested_time": null,
"chat_type": 0,
"is_service_request": false,
"cancel_requested": false,
"has_request_initiated_change": false,
"has_attachments": false,
"has_linked_requests": false,
"has_request_caused_by_change": false,
"has_problem": false,
"subject": "Need an External Monitor",
"linked_to_request": null,
"mode": null,
"is_read": false,
"lifecycle": null,
"reason_for_cancel": null,
"assets": [],
"group": null,
"email_to": [],
"created_time": {
"display_value": "Mar 18, 2024 10:17 AM",
"value": "1710757038415"
},
"level": null,
"approval_status": null,
"service_category": null,
"created_by": {
"email_id": null,
"phone": "1234455",
"name": "administrator",
"mobile": "1234567890",
"profile_pic": {
"content-url": "/images/default-profile-pic2.svg"
},
"is_vipuser": false,
"id": "5",
"department": null
},
"scheduled_end_time": null,
"first_response_due_by_time": null,
"last_updated_time": {
"display_value": "Mar 18, 2024 10:23 AM",
"value": "1710757434369"
},
"impact_details": "Details of the impact",
"subcategory": null,
"email_cc": [],
"scheduled_start_time": null,
"email_ids_to_notify": [],
"notification_status": null,
"description": "Provide me an External Monitor",
"has_dependency": false,
"has_conversation": false,
"fr_sla_violated_technician": null,
"callback_url": null,
"urgency": null,
"is_shared": false,
"request_template_task_ids": [],
"department": null,
"is_reopened": false,
"has_draft": false,
"is_overdue": false,
"technician": null,
"due_by_time": {
"display_value": "Mar 18, 2024 11:17 AM",
"value": "1710760638415"
},
"has_project": false,
"is_first_response_overdue": false,
"cancel_requested_is_pending": false,
"recommend_template": null,
"unreplied_count": null,
"category": null,
"maintenance": null
},
"response_status": {
"status_code": 2000,
"status": "success"
}
}
To map the ManageEngine ServiceDesk Plus status property with OpsRamp,
select STATUS_MSG from the Response drop-down and enter the $response_status.status value.
Add response to incident
| Field | Value | ||||
|---|---|---|---|---|---|
| Endpoint URL | http://<servername>:<port number>/api/v3/requests/$utils.extEntityId($incident.id,$installedAppId,$entity)/notes | ||||
| Notification Type | REST API | ||||
| Authentication | NONE | ||||
| Web Method | POST | ||||
| Headers |
| ||||
| Payload |
|
Request payload
{
"note": {
"description": "Need info on this topic.",
"show_to_requester": true,
"mark_first_response": false,
"add_to_linked_requests": true
}
}
Response
{
"note": {
"request": {
"subject": "Need an External Monitor",
"id": "18"
},
"last_updated_by": null,
"added_time": {
"display_value": "Mar 18, 2024 10:59 AM",
"value": "1710759585717"
},
"has_attachments": false,
"attachments": [],
"last_updated_time": null,
"added_by": {
"email_id": null,
"phone": "1234455",
"name": "administrator",
"mobile": "1234567890",
"profile_pic": {
"content-url": "/images/default-profile-pic2.svg"
},
"is_vipuser": false,
"id": "5",
"department": null
},
"image_token": "a55d58adbd4cddc167a3f0f7dd046ce1e1367e4d83c2a3399e6d163d3a3a3dabde1d51bb60f05737146153ab6420072a5c8c8f33",
"show_to_requester": true,
"description": "Need info on this topic.",
"id": "3"
},
"response_status": {
"status_code": 2000,
"status": "success"
}
}
To manage ManageEngine ServiceDesk Plus status property with OpsRamp,
select STATUS_MSG from Response drop-down and enter the $response_status.status value.
ManageEngine ServiceDesk Plus Configuration
Configuration involves generating an authentication key. The authentication key (technician key) is required to post OpsRamp events as ServiceDesk Plus Incidents using ServiceDesk Plus APIs.
To generate an authentication key in ServiceDesk Plus:
- Log into ServiceDesk Plus with administrator privileges.
- Navigate to Admin > Developers Space > Integration key.
- Click Add New to add a new technician and configure the following:
- Enter name.
- Enter a description and specify the privileges for the technician.
- Select Enable login for this technician and enter information for the technician.
- Select Enable Administrator Privileges (SDAdmin).
- In API key details, click Generate/Regenerate and select Never Expires to generate the authentication key.
- Copy the authentication key. The key is used while configuring an integration event in OpsRamp.
Or, you can generate an authentication token for an existing user by editing the technician details using API key details > Generate.
Configure Inbound Integration
Click here to learn how to configure Inbound Integration
Follow these steps to configure Inbound integration:
(From ManageEngine ServiceDesk Plus to OpsRamp)
Create Additional Field
Create an additional field in Manage Engine Service Desk Plus to keep track of OpsRamp Incident Id for proper handling of create and update incidents.
Follow these steps to create an additional field:
- Click Admin (gear icon) at the top-right corner of the screen.
- Under Customization click Additional Field. The Customization - Additional Field - Incident screen is displayed.
- Under Incident, click +New Field. The Incident - Additional Fields window is displayed.
- Enter the following details:
- Label Name: Enter the label name.
Example: EXT_REQ_ID. - Description: Enter a description.
- Label Name: Enter the label name.
- Click Save.
Modify Incident Template
Modify the Incident template to display the OpsRamp Incident ID in incidents.
Click Admin (gear icon) at the top-right corner of the screen.
Under Templates & Forms, click Incident Template. The Templates & Forms - Incident Template screen is displayed.
Click the Default Request template to edit.
Drag and drop the label (created in the previous step - EXT_REQ_ID) from Custom Fields to the right side.
Click Save.
Configure Custom Triggers
The Custom Triggers feature, as the name indicates, helps customize automatic workflows for different types of user requests. An action is triggered for new requests that match the conditions you specify. These conditions refer to the values that certain fields in the request must hold, and are checked when a request is created, updated, or created and updated.
Follow these steps to configure custom triggers:
Click Admin (gear icon) at the top-right corner of the screen.
Under Automation, click Custom Triggers. The Automation - Custom Triggers - Request screen is displayed.
Under Request, click Trigger Group. The New Trigger Group dialog box is displayed.
Enter the following information:
- Trigger Name: Name of the action (Example: OpsRamp Create and Edit incident Action)
- Description: Description of the action (Example: Send request create and edit notifications to OpsRamp via REST API.)
Click Save.
Move the mouse pointer over OpsRamp Create and Edit incident Action and click Add Trigger. The Automation - Custom Triggers - Request screen is displayed.
Enter the information as per your requirement:
Field Name Field Type Description Trigger Name String Name of the trigger (Example: OpsRamp Create and Edit incident Action) Description String Description of the trigger (Example: Send request create and edit notifications to OpsRamp via REST API.) Execute on actions Dropdown Select When a Request is created and edited. Execute during Radio button Any Time. Cascade Execution Radio button Execute next rule. When Request arrives Radio button Select a condition on when to trigger this action. Actions Dropdown Select Action Type as Execute Class and Class File to Run as com.vistara.integrations.ManageEngineSDeskPlusSDKClick Save.
Configure External Action Plugin
This section provides procedural information for developers to create a plugin and establish integration between ServiceDesk Plus and OpsRamp.
Configurations
WINDOWS
Follow these steps to configure files in Windows OS:
Step 1: Copy configuration files into your On-Premise server where ManageEngine Service Desk Plus is running.
- Copy the
sdeskplus-opsramp-integration-sdk.jarfile to “[SCP_Home]/integration/lib” directory. - Copy the
OpsRamp.ymlfile to “[SCP_Home]/integration/conf” directory. Edit this file with actual API credentials and mappings. - Restart the ServiceDesk Plus.
LINUX
Follow these steps to configure files in Linux OS:
Step 1: Copy configuration files into your On-Premise server where ManageEngine Service Desk Plus is running.
- Copy the
sdeskplus-opsramp-integration-sdk.jarfile to “[SCP_Home]/integration/lib” directory.
Example:
root@sdp:/home/sdp/ManageEngine/ServiceDesk/integration/lib# ll
total 17656
drwxrwxr-x 2 sdp sdp 4096 Jun 12 06:20 ./
drwxrwxr-x 8 sdp sdp 4096 Jun 11 18:27 ../
-rwxr-xr-x 1 sdp sdp 18070970 Jun 19 09:07 sdeskplus-opsramp-integration-sdk.jar*
root@sdp:/home/sdp/ManageEngine/ServiceDesk/integration/lib#
</code>
- Copy the ‘OpsRamp.yml’ file to “[SCP_Home]/integration/conf” directory.
Example:
root@sdp:/home/sdp/ManageEngine/ServiceDesk/integration/conf# ll
total 28
drwxrwxr-x 2 sdp sdp 4096 Jun 12 06:20 ./
drwxrwxr-x 8 sdp sdp 4096 Jun 11 18:27 ../
-rwxrwxr-x 1 sdp sdp 632 May 27 21:29 AppIntegrations_Handler.xml*
-rwxrwxr-x 1 sdp sdp 10789 May 27 21:29 ConnectorCard.json*
-rwxr-xr-x 1 sdp sdp 694 Jun 19 09:07 OpsRamp.yml*
root@sdp:/home/sdp/ManageEngine/ServiceDesk/integration/conf
- Restart the ServiceDesk Plus
Files
- OpsRamp.yml:
# OpsRamp API details
opsramp:
opsramp.api.url : "https://{server name}"
opsramp.api.key : "{key}"
opsramp.api.secret : "{secret}"
opsramp.partner.id : "{partnerId}"
opsramp.client.id : "{clientId}"
# properties mapping
status:
Open : Open
Onhold : On Hold
Resolved : Resolved
Closed : Closed
priority:
Low : Low
Medium : Normal
Normal : High
High : Urgent
sdp:
filed.name : "udf_fields"
incident.field.mapping : "udf_sline_301"
operation.name : "UPDATE"
format.version : "V3"
Update the values for below keys in opsramp.yml file before pushing to the ManageEngine On-Premise Server.
- opsramp.api.url
- opsramp.api.key
- opsramp.api.secret
- opsramp.partner.id
- opsramp.client.id
- incident.field.mapping: Provide the additional API field name that you created previously.
https://www.dropbox.com/scl/fi/cpmbjwz7su6spj2f8u6i6/sdeskplus-opsramp-integration-sdk.jar
Check logs in On-Prem Server
Below are the details to check the server logs in On-Prem Server to send the create/update incidents from ManageEngine to OpsRamp:
root@test:/home/opsramp/ManageEngine/ServiceDesk/logs# tail -f serverout0.txt | grep "vistara"