MuleSoft Integrate With ServiceNow

gowebing

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.

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.

XML
  
<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. 

YAML
  
/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:

XML
  
<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.

XML
  
<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.

JSON
  
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:

JSON
  
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.

XML
  
<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.

JSON
  
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:

JSON
  
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.

XML
  
<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.

JSON
  
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:

JSON
  
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.

XML
  
<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.

JSON
  
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).

JSON
  
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.

XML
  
<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.

JSON
  
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:

JSON
  
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.

 

 

 

 

Top