RUCKUS Analytics allows you to
configure Webhook URL addresses to receive real-time notifications when incidents are
created or updated in the application – much like e-mail notifications. Webhooks help
applications to communicate with each other in real-time and typically use a message or
payload to communicate between each other. The message or payload contains real-time
information about the incident.
Sample Webhook Message with
Incident Details
For example, RUCKUS Analytics communicates with
ticketing applications in ServiceNow and Salesforce (SFDC) via webhooks. Through
webhooks, the incidents generated in RUCKUS Analytics
appear in the ServiceNow and Salesforce applications, in real-time. Following is a
work-flow to configure Webhooks for ServiceNow and SFDC applications.
Integrating RUCKUS Analytics Incident
Webhook with ServiceNow Application
Login to the ServiceNow instance
Logging into ServiceNow
Under System Web Services, select Scripted Rest APIs
Scripted Rest APIs ConfigurationA new record to configure the Scripted REST Service is displayed.
Configure the following.
Name: enter the name of the service
API ID: enter the API ID
Protection Policy: select the appropriate policy from the menu
Application: enter the scope of the application. In this example
scope is set to Global.
API Namespace: a
system generated value is populated
Click Submit.
The service is created and listed.
Click the service. Under Resources, click
New to provide the endpoint for the
service.
Select the HTTP method as POST
In Script, enter this code for the endpoint to process the
request:
Note: Ensure that the spacing is retained when you copy and paste the
code.
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
// Secret shared between Ruckus Analytics (RA) and ServiceNow
// to ensure the authenticity of data received.
var secret = "<secret>";
// Change value to assign incident to specific group,
// leave as is to not assign to any group
var assignment_group = "<assignment_group>";
// Change value to assign incident to specific person,
// leave as is to not assign to any person
var assigned_to = "<assigned_to>";
// Mapping of RA incident severity to
// ServiceNow incident Impact and Urgency field
var impactAndUrgencyMap = {
P1: { impact: 1 /* High */, urgency: 1 /* High */ },
P2: { impact: 2 /* Medium */, urgency: 1 /* High */ },
P3: { impact: 2 /* Medium */, urgency: 2 /* Medium */ },
P4: { impact: 3 /* Low */, urgency: 3 /* Low */ }
};
// Mapping of RA incident status to
// ServiceNow incident State field
var stateMap = {
'new': 1 /* New */,
'ongoing': 1 /* New */,
'finished': 6 /* Resolved */
};
var data = request.body.data;
// 1. Ensure request uses correct shared secret key
if (data.secret == secret) {
var mode; // insert or update
var event = data.payload;
var inc = new GlideRecord('incident');
// 2. Check if incident exists
inc.addQuery('number', event.id);
inc.query();
if (inc.hasNext()) {
inc.next();
mode = "update";
} else {
inc.initialize();
mode = "insert";
}
// 3. Add/update fields
inc.number = event.id;
inc.state = stateMap[event.status];
inc.impact = impactAndUrgencyMap[event.severity].impact;
inc.urgency = impactAndUrgencyMap[event.severity].urgency;
inc.short_description = event.title;
inc.description = getDescription(event);
// 4. Assign incident to specific group or person
if (assigned_to != "<assigned_to>") {
inc.assigned_to = assigned_to;
}
if (assignment_group != "<assignment_group>") {
inc.assignment_group.setDisplayValue(assignment_group);
}
// 5. Insert/Update the incident
inc[mode]();
var status = mode + (mode == 'insert' ? 'ed' : 'd');
gs.info('incident ' + event.id + ' ' + status);
} else {
gs.warn("Invalid secret to run Ruckus Analytics webhook");
}
// Respond to the Webhook
response.setStatus(200);
/**
* Generate description for incident
*/
function getDescription (event) {
return [
'Incident URL: ' + event.link,
'',
'Details:',
'------------------------------------------------',
'Client Impact Count: ' +
event.impactedClientCount +
' of ' +
event.clientCount +
' (' + event.impactedClientPercentage + ')',
'Incident Category: ' + event.category,
'Incident Sub-Category: ' + event.subCategory,
'Type: ' + event.impactedAreaType,
'Scope: ' + event.impactedAreaName,
'Hierarchy: ' + event.impactedAreaHierarchy,
'Duration: ' + event.duration,
'Event Start Time: ' + event.startTime,
'Event End Time: ' + event.endTime,
'',
'ROOT CAUSE ANALYSIS:',
'------------------------------------------------',
event.rootCauses,
'',
'RECOMMENDED ACTION:',
'------------------------------------------------',
event.recommendations
].join('\n');
}
})(request, response);
In var secret, set the secret value for data
authentication
In var assignment_group, assign the RUCKUS Analytics incident to a specific group
within ServiceNow
In the Security tab, uncheck Required
Authentication
Click Submit.
From the RUCKUS Analytics web interface, go to
Admin > Webhooks.
The Webhooks
page is displayed showing information about the status of the
webhook, name, URL and associated resource group.
Click Create
Webhooks.
The Create
Webhook page is displayed. Configure the following.
Name: enter the name
of the webhook
Webhook URL: enter
the URL by appending the domain URL (for example,
https://dev-123.service-now.com) and the Base API Path from
the ServiceNow record (for example,
/api/93874/ruckus_analytics_incidents)
Resource Group:
select the resource group that you want to associate with the
webhook URL. Any incident created within that resource group will be
notified via the webhook URL to the ServiceNow application
Secret: enter the
secret key generated for authentication from the service record
Enable: If webhook URL is enabled, ServiceNow will receive
notifications about the incidents. If webhook URL is enabled, the
status appears green and appears grey if it is disabled.
Event Types: select the event types from severity P1 to P4.
Click Create. The new webhook is added to the
Webhook page. This URL will establish communication
between ServiceNow and RUCKUS Analytics and
reflect incidents generated within resource groups, in real-time.
You can edit the Webhook URL configuration by clicking the icon. Click Update to
saved edits to the configuration.
Create a New Salesforce Case for
RUCKUS Analytics Incident using Zapier Application
Ensure that you have Zapier account. Also ensure you are
logged into Salesforce and RUCKUS Analytics.
Whenever a new incident is triggered in RUCKUS
Analytics, a new case is created in Salesforce and updated as an when the
incident is updated. Follow these instructions to setup the Zapier application to
create a case in Salesforce.
A page displaying the
webhook URL is displayed. This URL is used to integrate Salesforce cases
with RUCKUS Analytics
incidents, in real-time.
From the RUCKUS Analytics web interface, go
to Admin > Webhooks.
The Webhooks page is displayed showing information
about the status of the webhook, name, URL and associated resource group.
Click Create Webhooks.
The Create Webhook page is displayed. Configure the
following.
Name: enter the name of the webhook
Webhook URL: enter
the webhook URL from the Zapier interface
Resource Group:
select the resource group that you want to associate with the
webhook URL. Any incident created within that resource group will be
notified via the webhook URL to the Salesforce application
Secret: enter secret
key for data authentication between RUCKUS Analytics and Zapier
Enable: If webhook
URL is enabled, Salesforce will receive notifications about the
incidents. If webhook URL is enabled, the status appears green and
appears grey if it is disabled.
Click Send a Sample
Incident to continue integration on the Zapier
application. When the incident sample has reached Zapier, a success
message is relayed on the Create Webhook dialog
box in the RUCKUS
Analytics web interface.
Click Create to
save the configuration.
The new configuration is
listed in the Webhooks page.
In the Zapier web interface,
In Catch Hook, click Test Trigger
.
A request message or
payload from RUCKUS Analytics is
displayed in the Zapier web interface. It contains information about the
incident.Zapier Web Interface
Click Continue.
In Only Continue
if... , go to Filter setup &
testing and enter the same secret key that was included in
the RUCKUS Analytics web interface for data authentication.
Click Continue.
In Utilities, go
to Set up
action and in the lookup table, map the RUCKUS Analytics incidents status with the Case status in
Salesforce.
Click Test & Continue.
In Utilities, go
to Set up
action and in the lookup table, map the RUCKUS Analytics incidents severity with the priority of cases in
Salesforce. For example, P1 incidents will be marked High priority, P2 and
P3 as Medium and P3 as Low priority incidents.
Click Test & Continue.
In Find Record by Query in
Salesforce, go to Choose
account, and select your Salesforce account or login to your
account and authorize Zapier to manage records in Salesforce on your behalf.
This step ensures no new cases are recorded when existing cases are
present.
Click Continue.
Under Setup Action,
select Case as the Salesforce object.
Note: Do not change the WHERE clause field.
Click Skip Test.
Click Close.
Click Continue
Under Only continue if... , go to Filter setup and testing
and click Continue
In Create Record in Salesforce, go to
Choose account and select your Salesforce
account.
Under Setup Action,
select Case as the Salesforce object. Set the other fields
as necessary. Modify the fields as required, such as changing the
description or assigning the Salesforce case to a particular person or
group.
Note: Do not change the "Subject" as it is used when updating a case.
Click Continue.
A Salesforce recorded is now created.
Login to Salesforce Web
interface. A new case is created as shown.
New Record in
Salesforce
In the Zapier web interface, click Turn on
Zap.
Whenever an incident occurs in RUCKUS
Analytics, the changes will reflect in the Salesforce case as
well.
You can also update
existing cases in Salesforce by following the same steps mentioned in the
next section.
Updating an Existing Salesforce Case for RUCKUS Analytics Incident using Zapier
Application