TL;DR

In this article you will learn how to use CloudIQ webhooks to open a ticket in ServiceNow.

• TL;DR
• Webhook ? What webhook ?
• ServiceNow Development resources
• From CloudIQ health issue to ServiceNow incident
  • When is a webhook triggered?
  • Webhook event details
    • Headers
    • Payload
  • ServiceNow Scripted REST API
    • What does this code do ?
  • Configure CloudIQ Webhook
  • Full process in video
  • Testing
• What’s next?

Webhook ? What webhook ?

To paraphrase Wikipedia which paraphrases Atlassian a webhook is a user-defined callback over HTTP.

In other terms, it allows users to add a flow of new behavior or actions via an HTTP call. It is a popular way to have real-time updates with third-party applications.

In the context of CloudIQ, you can use the webhook feature to notify 3rd party application of health issue on monitored systems like storage arrays, virtual machines, etc. At the time of this post publication, only a health issue can trigger a webhook, but it will be extended to other types of events in later releases.

ServiceNow Development resources

ServiceNow offers tons of resources to learn and try ServiceNow features on developer.servicenow.com.

One of the most outstanding features is to spin an on-demand instance with a release of your choice and sample data. It is free to create an account, there is no credit card or personal information requested ; just create an account and you can launch an environment.

The following tutorial has been implemented and tested with on-demand instances.

From CloudIQ health issue to ServiceNow incident

This chapter will present the mechanisms and code to create a ServiceNow incident from CloudIQ health issue notification.

Incident Management is one of the many ITIL processes that can be orchestrated with ServiceNow. The incident table is the natural destination for CloudIQ health issue.

To keep things simple, we are not creating an asset or CI in the CMDB, but it will be subject to a future publication ;-). It means that the incident will have the name of the affected system in the description but that asset won’t be used in other processes like SLA management, CI lifecycle, etc.SLA management, CI lifecycle, etc.

Multiple options have been explored for that prototype (API routing with Sinatra, AWS Lambda) ; the easiest and most relevant solution to create the ServiceNow incident is to use the Scripted REST API feature.

When is a webhook triggered?

At the time of the publication, a notification is triggered on health issue change.

Webhook event details

Useful data is transferred in Headers and Payload. The Headers have control information; the Payload is a JSON data structure with all the useful details for the notification.

Headers

Payload

You can check the health-score-payload schema here.

Below is a sample payload; these fields we will use to create/close the ServiceNow incident with the proposed Scripted REST API example. A new notification will be in the attribute newIssues ; when a notification is cleared it will be in resolvedIssues. resolvedIssues contains the same data as when the issue appeared.

{
  "systemDisplayIdentifier": "APM00000000000",
  "systemName": "APM00000000000",
  "systemModel": "Unity 450F",
  "timestamp": 1594138375970,
  "timestampIso8601": "2020-07-07T16:12Z",
  "currentScore": 94,
  "newIssues": [],
  "resolvedIssues": [
    {
      "impact": -6,
      "description": "Host 'lglxxxx.emc.com' is not logged in to both SPs; this host will lose connectivity in the event of failover.",
      "resolution": "This host does not have logged-in paths to both SPA and SPB.  Review your connectivity to ensure that all hosts have a connection to both SPs to ensure High Availability.",
      "ruleId": "HOST_CONNECTIVITY_RULE",
      "category": "CONFIGURATION",
      "impactedObjects": [
        {
          "id": "APM00000000000__HOST__Host_57"
        }
      ]
    }
  ]
}

ServiceNow Scripted REST API

The reference documentation for Scripted REST API is available here.

To create the scripted REST and handle the webhook there, are few steps :

1. Create a resource
2. Add a request header to pass the header x-ciq-event
3. Add the script to map CloudIQ attributes to ServiceNow ticket fields in the resource.

⚠ In the following example, we are not verifying the signature given by x-ciq-signature header. Indeed CloudIQ signs the payload with an exact string that is posted. Within the Scripted REST we manipulate a JSON Object, not a string.

What does this code do ?

The above example script has the logic to create and close the incident and maps CloudIQ fields to ServiceNow incident parameters.

The urgency level is set using the same threshold as CloudIQ green/orange/red.

There is no identifier for matching a CloudIQ health issue with a ServiceNow incident at the moment of the publication. Therefore to be able to close an incident, we query them on the description and short_description. If it is an exact match, we assume the two events relate to the same incident.

We are not mapping the category to ServiceNow categories as they represent different concepts in each product.

If you want to refine the proposed behavior, you can find more details on CloudIQ Webhook documentation (link to be given) and the GlideRecord API doc to manipulate the incident.

Configure CloudIQ Webhook

Once the Scripted REST API is ready, it is time to configure CloudIQ to trigger the Webhook and call ServiceNow new API.

From the CloudIQ GUI under Admin > Webhooks, you can click on the button ADD WEBHOOK.

In the menu you will have to fill the fields:

• Name ; to name your webhook
• Payload URL ; where an HTTP POST operation will be performed.
• Secret ; which is the pass-phrase that can be used to verify the event’s signature and make sure it comes from CloudIQ.
• List of systems table ; where you can select the systems for which the URL should be invoked when an event is triggered.

At the time of that post, CloudIQ triggers health score changes for storage arrays and Connectrix switches ; not virtual machines.

Full process in video

Testing

It is possible to test the script works according to your needs by using ServiceNow REST API explorer to select the namespace for our new script and pass it, at least, the header x-ciq-event and the Payload.

Another option is to go in CloudIQ and redeliver an existing event like below:

The script below is equivalent to the REDELIVER button and allows you to modify the data you want to try-out. The idea is to copy-paste the Headers from CloudIQ UI in a file, the same thing for the Payload; you can then tweak them at ease.

If you want to trial & error with the webhook feature, another protip is to use https://webhook.site/ as an endpoint. This is a free service, which has straightforward terms & privacy.

Finally, once a Scripted REST API is created, we can call it with REST API Explorer using the same Headers and Payload CloudIQ gives. You can have an IDE-like experience in conjunction with the debugger from the resource code editor, which you can launch by clicking on that icon:

What’s next?

The next article of this series will describe how to use CloudIQ webhooks with Serverless providers like AWS Lambda or Azure function.