Creating Webhooks
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.
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
- Under System Web Services, select Scripted Rest APIsA 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
- Login to the Zapier web interface by clicking https://zapier.com/shared/0ec3d66a9a6889681fdb83248838d6ca161c90c6.
- Click Try this Zap.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.
- 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.
- 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
- Setup incident update by clicking https://zapier.com/shared/6bb3dc515e23d86796c3c70bfcc4121f0d41ae59
- Repeat Step 2 to Step 23 from the Create a New Salesforce Case for RUCKUS Analytics Incident using Zapier Application section