Recently I worked on a project for one of our clients surrounding the subject of ITSM and was asked to integrate ServiceNow via its REST API with an external system.
For those of you who don’t know ServiceNow, I recommend checking out their website. In short, ServiceNow is a very broad technology platform you can use to create digital workflows for almost any part of your company. In my case I was integrating the incident (ticketing) system with an external party to provide a better workflow for both parties.
Now you might ask, how would you go about this using the range of existing WSO2 products? To do this securely we take the WSO2 API Manager (APIM) to manage traffic and security, WSO2 Identity Server (IS) to handle the authentication (or authorization) and the WSO2 Enterprise Integrator (EI) to handle all the different mediation scenarios to the different endpoints.
In our case there’s information flowing both from ServiceNow to the external system and the other way around. I will describe these separately as they work slightly different in terms of authentication with ServiceNow.
ServiceNow integration to an external system
Inside ServiceNow you can write scripts that fit your use case, in ours we wanted to trigger the Integration platform when a new incident is created. For this to work it needed to be configured in a way that the authentication between the two is seamless. This authentication can be done in ServiceNow in two ways, it allows basic authentication (with the option of mutual authentication via specific profiles in ServiceNow) and OAuth2.0 in various configurations.
For this outbound traffic you can set up an OAuth2.0 provider inside ServiceNow which can be used to authenticate with the WSO2 APIM via WSO2 IS. This provider is connected to WSO2 IS where it retrieves the tokens used for authenticating the request coming into the WSO2 APIM. Once the connection has been established and token validated on the APIM the message payload can be forwarded to the WSO2 EI through the respective API that is being called by ServiceNow.
Inside the WSO2 EI product you can use the Enterprise Service Bus for the message mediation to construct the necessary payloads to the external system of your choice, transforming the message from JSON to XML or something else as you go. And to make sure these messages arrive it’s possible to set up guaranteed delivery with a messaging component like Apache ActiveMQ.
External system integration to ServiceNow
For sending data to ServiceNow the flow works in a similar way but there are some changes. In our use case we polled the external system for new data, but this same integration is also possible with an external party that actively invokes the integration platform. The only difference being that you might decide to add an extra API operation for the external party to call.
In this case I’ll just assume the WSO2 EI has already retrieved the data as the connection the external party is out of the scope for this blog and could be almost any system in the world. Let’s say you receive a message payload containing a username, a title and a description from the external system, which you want to use to create an incident in ServiceNow assigned to the specific username.
This flow requires two separate invocations of the ServiceNow REST API:
- A GET request to the ServiceNow user table to retrieve the user id
- A POST request to the ServiceNow incident table
But before you can invoke the API an access token is needed. This can also be retrieved via the REST API but instead of setting up an oAuth2.0 provider, you need to set up an OAuth2.0 client and use the Client Secret/Client Id combination provided by the client for retrieving a token via the EI. After the authentication has been set up you can start using the REST API. The ServiceNow REST API has expansive functionality and is (in my opinion) very nice to work with in combination with the WSO2 products, as it’s easy to mediate the message formats and set up the correct calls to the API to retrieve the data you want. All it takes is some research into which data is in which table. With the large selection of ServiceNow documentation and their REST API Explorer, this isn’t hard to find.
To finish the example, we need to retrieve the user ID of a user while we only have the username. The GET request URL would look something like this:
GET https://{ServiceNowHost}/api/now/table/sys_user?sysparm_query=user_name={the username}
This will return a JSON payload with various details of the user including the ID.
After extracting the ID from the response payload you can start putting together your incident creation payload.
This would look something like this:
{
"caller_id":"The user id",
"short_description":"The Title",
"description":"The description"
}
With the corresponding endpoint:
POST https://{ServiceNowHost}/api/now/table/incident
After sending the correct payload to the endpoint, ServiceNow will return an incident payload including an incident number and incident ID to confirm that the incident has been created successfully.
This concludes the example, there are many more possibilities with this setup of course, during both described flows. It doesn’t have to stop at only one invocation for information, if more are necessary this is also possible. If this blog sparks any questions for you don’t hesitate to ask in the comments or contact us via any of our other channels.
