MuleSoft Integrate With ServiceNow
This article explains how to define a robust API that serves the E2E feature of a ServiceNow incident management lifecycle using the MuleSoft ServiceNow connector.
Join the DZone community and get the full member experience.
Join For FreeThis article explains how to define a robust API that serves the E2E feature of a ServiceNow incident management lifecycle using the MuleSoft ServiceNow connector.
Here, the basic CRUD operations are covered; we can extend it with additional features like uploading/downloading incident files, getting the incident assigned group/people, keeping track of each incident, etc.
Dependency Snippet
To use the features of ServiceNow operations, we have to use the provided connector plugin as a dependency first.
<dependency>
<groupId>com.mulesoft.connectors</groupId>
<artifactId>mule-servicenow-connector</artifactId>
<version>6.14.0</version>
<classifier>mule-plugin</classifier>
</dependency>
RAML Definition
Define an API spec to expose the features of MuleSoft + ServiceNow integration.
/incident:
usage: Use this resource to interact with ITSM system
get:
is: [client-id-required,get-incident,error-400,error-404,error-500]
description: Operation for getting existing incidents information from the ITSM system.
responses:
200:
body:
application/json:
post:
is: [client-id-required,error-400,error-404,error-500]
description: Operation for create incident in the ITSM system.
responses:
201:
body:
application/json:
put:
is: [client-id-required,error-400,error-404,error-500]
description: Operation for update incident in the ITSM system.
responses:
201:
body:
application/json:
/upload-file/{sys_id}:
post:
is: [client-id-required,error-400,error-404,error-500]
description: Operation for upload file related to incident
responses:
201:
body:
application/json:
/incidents:
usage: Use this resource to interact with ITSM system
get:
is: [client-id-required,error-400,error-404,error-500]
description: Operation for getting existing incidents information from the ITSM system.
responses:
200:
body:
application/json:
Global Configuration
Before using the operations, create the global configuration for the connector as shown below:
<servicenow:config name="ServiceNow_Config" doc:name="ServiceNow Config" doc:id="1af0e739-d0d5-4a35-a71a-3125151b564d" >
<servicenow:basic-connection username="${secure::service.username}" password="${secure::service.password}" serviceAddress="${secure::service.address}" />
</servicenow:config>
Create an Incident
We have to use the operation name as insert under servicenow:invoke
operation, which does SOAP invocations.
<servicenow:invoke doc:name="Create Incident" doc:id="43d8602a-5558-4c45-8f66-98a8e800678a" config-ref="ServiceNow_Config" service="incident" operation="insert"/>
A sample API request to create an incident under the ServiceNow portal.
curl --location --request POST 'http://0.0.0.0:8081/incident-app/v1/incident' \
--header 'client_id: test' \
--header 'client_secret: test' \
--header 'Content-Type: application/json' \
--data-raw '{
"short_description": "Mulesoft Test Incident 1",
"urgency" : "3"
}'
Once the incident gets created successfully, the API response will be as shown below:
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Content-Length: 76
Date: Wed, 3 Jan 2024 22:02:21 GMT
{
"sys_id": "db92356ddbe17d5008d241b91396197a",
"number": "INC0010049"
}
Update an Incident
We have to use the operation name as an update under the servicenow:invoke
operation.
<servicenow:invoke doc:name="Update Incident" doc:id="23d63298-c163-4ff8-bb58-106315a4a4c8" config-ref="ServiceNow_Config" service="incident" operation="update"/>
A sample API request to update an incident under the ServiceNow portal.
curl --location --request PUT 'http://0.0.0.0:8081/incident-app/v1/incident' \
--header 'client_id: test' \
--header 'client_secret: test' \
--header 'Content-Type: application/json' \
--data-raw '{
"sys_id": "db92356ddbe17d5008d241b91396197a",
"urgency" : "2"
}'
Once the incident gets updated successfully, the API response will be as shown below:
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Content-Length: 76
Date: Wed, 3 Jan 2024 22:02:21 GMT
{
"sys_id": "db92356ddbe17d5008d241b91396197a"
}
Retrieve an Incident
We have to use the operation name to get under the servicenow:invoke
operation.
<servicenow:invoke doc:name="Get Incident" doc:id="3863adc2-87c1-447c-920c-bce3b6f7a1c4" config-ref="ServiceNow_Config" service="incident" operation="get"/>
A sample API request to get an incident from the ServiceNow
portal.
curl --location 'http://0.0.0.0:8081/incident-app/v1/incident?sys_id=db92356ddbe17d5008d241b91396197a&api_type=SOAP' \
--header 'client_id: test' \
--header 'client_secret: test'
A sample incident details retrieved from the ServiceNow portal is as shown below:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 8053
Date: Wed, 3 Jan 2024 22:01:06 GMT
{
"active": "1",
"activity_due": "2023-10-04 06:17:08",
"additional_assignee_list": null,
"approval": "not requested",
"approval_set": null,
"assigned_to": null,
"assignment_group": null,
"business_duration": null,
"business_impact": null,
"business_service": null,
"business_stc": "0",
"calendar_duration": null,
"calendar_stc": "0",
"caller_id": "c95409a9db19f510469fab1c1396197e",
"category": "inquiry",
"cause": null,
"caused_by": null,
"child_incidents": "0",
"close_code": null,
"close_notes": null,
"closed_at": null,
"closed_by": null,
"cmdb_ci": null,
"comments_and_work_notes": null,
"company": null,
"contact_type": null,
"contract": null,
"correlation_display": null,
"correlation_id": null,
"delivery_plan": null,
"delivery_task": null,
"description": "dsdsdsdsdsds 1234",
"due_date": null,
"escalation": "0",
"expected_start": null,
"follow_up": null,
"group_list": null,
"hold_reason": "0",
"impact": "3",
"incident_state": "2",
"knowledge": "0",
"location": null,
"made_sla": "1",
"notify": "1",
"number": "INC0010049",
"opened_at": "2023-09-27 22:02:21",
"opened_by": "c95409a9db19f510469fab1c1396197e",
"order": "0",
"origin_id": null,
"origin_table": null,
"parent": null,
"parent_incident": null,
"priority": "5",
"problem_id": null,
"reassignment_count": "0",
"reopen_count": "0",
"reopened_by": null,
"reopened_time": null,
"resolved_at": null,
"resolved_by": null,
"rfc": null,
"route_reason": "0",
"service_offering": null,
"severity": "3",
"short_description": "Mulesoft Test Incident 1",
"skills": null,
"sla_due": null,
"state": "2",
"subcategory": null,
"sys_class_name": "incident",
"sys_created_by": "mulesoft.int",
"sys_created_on": "2023-09-27 22:02:21",
"sys_domain": "global",
"sys_domain_path": "/",
"sys_id": "db92356ddbe17d5008d241b91396197a",
"sys_mod_count": "13",
"sys_updated_by": "mulesoft.int",
"sys_updated_on": "2023-10-06 02:48:09",
"task_effective_number": "INC0010049",
"time_worked": null,
"universal_request": null,
"upon_approval": "proceed",
"upon_reject": "cancel",
"urgency": "3",
"user_input": null,
"watch_list": null,
"work_end": null,
"work_notes_list": null,
"work_start": null
}
Retrieve an Incident (REST)
We can use REST call to get incident details, also.
<http:request method="GET" doc:name="Get Incident" doc:id="283c6297-ae56-4ce9-94f0-facf5e603d06" config-ref="Servicenow_HTTP_Request_configuration" path="#[Mule::p('secure::http.requester.servicenow.path.incident') ++ '/' ++ attributes.queryParams.sys_id]" target="incidentResponse">
<http:query-params ><![CDATA[#[output application/java
---
{
"sysparm_display_value" : Mule::p('secure::http.requester.servicenow.params.sysparm_display_value'),
"sysparm_limit" : Mule::p('secure::http.requester.servicenow.params.sysparm_limit')
}]]]></http:query-params>
</http:request>
A sample API request to get an incident from the ServiceNow portal using a REST call.
curl --location 'http://0.0.0.0:8081/v1/incident?sys_id=db92356ddbe17d5008d241b91396197a' \
--header 'client_id: test' \
--header 'client_secret: test'
With a REST call to ServiceNow API for the same incident, we can retrieve more information than a ServiceNow:invoke
operation (SOAP call).
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 8053
Date: Wed, 3 Jan 2024 22:01:06 GMT
{
"incident": {
"parent": "",
"made_sla": "true",
"caused_by": "",
"watch_list": "",
"upon_reject": "Cancel all future Tasks",
"sys_updated_on": "2023-10-06 11:48:09",
"child_incidents": "0",
"hold_reason": "",
"origin_table": "",
"task_effective_number": "INC0010049",
"approval_history": "",
"skills": "",
"number": "INC0010049",
"resolved_by": "",
"sys_updated_by": "mulesoft.int",
"opened_by": {
"display_value": "Mulesoft Integration",
"link": "https://demo4.service-now.com/api/now/table/sys_user/c95409a9db19f510469fab1c1396197e"
},
"user_input": "",
"sys_created_on": "2023-09-28 07:02:21",
"sys_domain": {
"display_value": "global",
"link": "https://demo4.service-now.com/api/now/table/sys_user_group/global"
},
"state": "In Progress",
"route_reason": "",
"sys_created_by": "mulesoft.int",
"knowledge": "false",
"order": "",
"calendar_stc": "",
"closed_at": "",
"cmdb_ci": "",
"delivery_plan": "",
"contract": "",
"impact": "3 - Low",
"active": "true",
"work_notes_list": "",
"business_service": "",
"business_impact": "",
"priority": "5 - Planning",
"sys_domain_path": "/",
"rfc": "",
"time_worked": "",
"expected_start": "",
"opened_at": "2023-09-28 07:02:21",
"business_duration": "",
"group_list": "",
"work_end": "",
"caller_id": {
"display_value": "Mulesoft Integration",
"link": "https://demo4.service-now.com/api/now/table/sys_user/c95409a9db19f510469fab1c1396197e"
},
"reopened_time": "",
"resolved_at": "",
"approval_set": "",
"subcategory": null,
"work_notes": "",
"universal_request": "",
"short_description": "Mulesoft Test Incident 1",
"close_code": null,
"correlation_display": "",
"delivery_task": "",
"work_start": "",
"assignment_group": "",
"additional_assignee_list": "",
"business_stc": "",
"cause": "",
"description": "dsdsdsdsdsds 1234",
"origin_id": "",
"calendar_duration": "",
"close_notes": "",
"notify": "Do Not Notify",
"service_offering": "",
"sys_class_name": "Incident",
"closed_by": "",
"follow_up": "",
"parent_incident": "",
"sys_id": "db92356ddbe17d5008d241b91396197a",
"contact_type": null,
"reopened_by": "",
"incident_state": "In Progress",
"urgency": "3 - Low",
"problem_id": "",
"company": "",
"reassignment_count": "0",
"activity_due": "2023-10-04 15:17:08",
"assigned_to": "",
"severity": "3 - Low",
"comments": "2023-10-04 13:20:28 - Mulesoft Integration (Additional comments)\n123456test123456\n\n2023-10-04 13:11:46 - Mulesoft Integration (Additional comments)\n12345test12345\n\n2023-10-04 12:15:57 - Mulesoft Integration (Additional comments)\ntttttttttttttttttttttt1\n\n2023-10-04 12:11:07 - Mulesoft Integration (Additional comments)\ndsdsdsdsdsds 1234\n\n2023-10-04 12:06:02 - Mulesoft Integration (Additional comments)\ndsdsdsdsdsds 123\n\n2023-09-29 12:59:56 - Mulesoft Integration (Additional comments)\nsssssssssss\n\n",
"approval": "Not Yet Requested",
"sla_due": "UNKNOWN",
"comments_and_work_notes": "2023-10-04 13:20:28 - Mulesoft Integration (Additional comments)\n123456test123456\n\n2023-10-04 13:11:46 - Mulesoft Integration (Additional comments)\n12345test12345\n\n2023-10-04 12:15:57 - Mulesoft Integration (Additional comments)\ntttttttttttttttttttttt1\n\n2023-10-04 12:11:07 - Mulesoft Integration (Additional comments)\ndsdsdsdsdsds 1234\n\n2023-10-04 12:06:02 - Mulesoft Integration (Additional comments)\ndsdsdsdsdsds 123\n\n2023-09-29 12:59:56 - Mulesoft Integration (Additional comments)\nsssssssssss\n\n",
"due_date": "",
"sys_mod_count": "13",
"reopen_count": "0",
"sys_tags": "",
"escalation": "Normal",
"upon_approval": "Proceed to Next Task",
"correlation_id": "",
"location": "",
"category": "Inquiry / Help"
},
"all_comments": [
{
"sys_id": "a8b20a63db65f59008d241b91396190c",
"sys_created_on": "2023-10-04T04:20:28Z",
"name": "incident",
"element_id": "db92356ddbe17d5008d241b91396197a",
"sys_tags": "",
"value": "123456test123456",
"sys_created_by": "mulesoft.int",
"element": "comments"
}
]
}
Retrieve All Incidents
As part of the admin team, the user may want to retrieve all the incidents related to an incident management group.
We have to use the operation name as getRecords
under the servicenow:invoke
operation.
<servicenow:invoke doc:name="Get Incidents" doc:id="42b90aa4-f064-4920-966a-e9c584479001" config-ref="ServiceNow_Config" service="incident" operation="getRecords"/>
A sample request to get all incidents from MuleSoft API.
curl --location 'http://0.0.0.0:8081/incident-app/v1/incidents?sys_created_by=mulesoft.int' \
--header 'client_id: test' \
--header 'client_secret: test'
A sample response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 15238
Date: Wed, 27 Sep 2023 22:51:11 GMT
[
{
"active": "0",
"activity_due": null,
"additional_assignee_list": null,
"approval": "not requested",
"approval_set": null,
"assigned_to": "008b3adc1dsdsdwdwdwdssdcb39",
"assignment_group": null,
"business_duration": "1970-01-02 02:22:44",
"business_impact": null,
"business_service": null,
"business_stc": "94964",
"calendar_duration": "1970-01-02 02:22:44",
"calendar_stc": "94964",
"caller_id": "c95409asdsdwewssd197e",
"category": "inquiry",
"cause": null,
"caused_by": null,
"child_incidents": "0",
"close_code": null,
"close_notes": null,
"closed_at": "2023-09-21 06:20:34",
"closed_by": "008b3adsdsddewdsdsdcb39",
"cmdb_ci": null,
"comments_and_work_notes": null,
"company": null,
"contact_type": "self-service",
"contract": null,
"correlation_display": null,
"correlation_id": null,
"delivery_plan": null,
"delivery_task": null,
"description": "Test Mule integration",
"due_date": null,
"escalation": "0",
"expected_start": null,
"follow_up": null,
"group_list": null,
"hold_reason": "0",
"impact": "3",
"incident_state": "8",
"knowledge": "0",
"location": null,
"made_sla": "1",
"notify": "1",
"number": "INC0010041",
"opened_at": "2023-09-20 03:57:50",
"opened_by": "c95409awewddsddsds96197e",
"order": "0",
"origin_id": null,
"origin_table": null,
"parent": null,
"parent_incident": null,
"priority": "5",
"problem_id": null,
"reassignment_count": "0",
"reopen_count": "0",
"reopened_by": null,
"reopened_time": null,
"resolved_at": null,
"resolved_by": null,
"rfc": null,
"route_reason": "0",
"service_offering": null,
"severity": "3",
"short_description": "Test Mule integration",
"skills": null,
"sla_due": null,
"state": "8",
"subcategory": null,
"sys_class_name": "incident",
"sys_created_by": "mulesoft.int",
"sys_created_on": "2023-09-20 03:57:53",
"sys_domain": "global",
"sys_domain_path": "/",
"sys_id": "4b27f9cdsdsdsdsdsd19ca",
"sys_mod_count": "3",
"sys_updated_by": "Ankur.Bhuyan",
"sys_updated_on": "2023-09-21 06:20:34",
"task_effective_number": "INC0010041",
"time_worked": null,
"universal_request": null,
"upon_approval": "proceed",
"upon_reject": "cancel",
"urgency": "3",
"user_input": null,
"watch_list": null,
"work_end": null,
"work_notes_list": null,
"work_start": null
}
]
Code Reference and Postman Collection
You can follow the GitHub URL to understand more about MuleSoft + ServiceNow integration.
Opinions expressed by DZone contributors are their own.
Comments