ServiceNow Incidents - Advanced Customization
Data Shared with ServiceNow
When a BigPanda incident is shared with ServiceNow, the integration creates a new record in ServiceNow Incidents Table. The integration also exposes additional data fields that can be used to customize the record in ServiceNow during the transform of data. If changes occur to the alerts on open incidents, BigPanda updates the corresponding incidents in ServiceNow. Updates are checked for every 15 seconds, by default.
ServiceNow field default values
Field | Default Value |
---|---|
|
|
|
|
| BigPanda incident |
| BigPanda incident |
| BigPanda comments, by default this value is mapped to the |
Additional Data Fields from BigPanda
The integration exposes these additional data fields from BigPanda in the default share from BigPanda. ServiceNow administrators can leverage these fields in the transform map to further enrich and customize the incident in ServiceNow.
Field | Description |
---|---|
| BigPanda Incident ID |
| BigPanda Incident status |
| Text printout of statuses of all alerts in incident |
| The count of all the alerts in the incident |
| The count of all non-resolved alerts in the incident |
| The BigPanda Environment from which the share originated |
| The BigPanda Environment ID |
| The email of the user who performed the share If this was an auto-share the email will be [email protected] |
| A string representation of the entire BigPanda Incident JSON Object |
| A link to the BigPanda incident |
| A link to the BigPanda incident timeline |
| A link to the preview of a BigPanda Incident |
| This defined the property to lookup on the defined primary alert tags for attempting to populate the ServiceNow Configuration Item field Default: |
| If any configuration options are passed through the Integration header or by customer success it will override any ServiceNow configurations set in the ServiceNow BigPanda App |
ShareIncident Transform Map
The ShareIncident Transform map is where customization of fields in the ServiceNow incident are performed. Insertion, deletion, or modification of specific columns is achieved by adding, removing, or modifying rows to the map and providing the assigned value, either as a mapped or scripted field. While the same behavior is possible using a Transform Script, modifying the transform map table is clearer and isolates the logic used to generate the field.
Customizing Transform Fields
Adding Alert Details to Description
- Navigate to BigPanda > Incidents > Transform Map
- Find the row where the target field is description
- Click on the script
- You will notice the BigPanda Utility class is already being referenced. Starting on line 13, the BigPanda Incident is being retrieved to traverse each alert and add it to the description field.
answer = (function transformEntry(source) {
// Instantiate BigPanda Utility Object with source
var bpUtils = new x_bip_panda.BigPandaUtility(source);
var description = null;
// Validates if this field can be updated on an update action
if (bpUtils.canUpdate(action, 'description')) {
description = source.description;
}
// Example of custom logic
// Retrieve the BigPanda Incident Data
var incident = bpUtils.getIncident().incident;
for (var i = 0; i < incident.alerts.length; i++) {
description += '\nAlert ' + (i + 1) + '\nStatus: ' + incident.alerts[i].status + '\nDescription: ' + incident.alerts[i].description;
}
return description;
})(source);
Capturing Alert Tag
The snippet below can be used if attempting to capture a tag from your defined primary alert within the BigPanda Incident.
answer = (function transformEntry(source) {
// Instantiate BigPanda Utility Object with source
var bpUtils = new x_bip_panda.BigPandaUtility(source);
var desiredTag;
// Validates if this field can be updated on an update action
// If the TARGET_FIELD_NAME is not added to the update fields
// input within the BigPanda Configuration form, then this
// will only work on Incident creations
if (bpUtils.canUpdate(action, '<TARGET_FIELD_NAME>')) {
desiredTag = bpUtils.getPrimaryAlertTag('<DESIRED_ALERT_TAG>');
}
return desiredTag;
})(source);
Capturing Incident Tags
The snippet below can be used to retrieve the Incident Tags of the BigPanda Incident.
answer = (function transformEntry(source) {
// Instantiate BigPanda Utility Object with source
var bpUtils = new x_bip_panda.BigPandaUtility(source);
// Getting all Incident Tags
var incidentTags = bpUtils.getIncidentTags();
/* Return Schema for Incident Tags
[
{
id: 'some_id',
name: 'Incident Tag Name',
value: 'SOME_VALUE'
type: 'INCIDENT_TAG_TYPE' ('text', 'multivalue', 'priority')
}
]
*/
// Getting a single Incident Tag
var incidentTag = bpUtils.getIncidentTag('some tag name');
// Getting the Priority Incident Tag
var priority = bpUtils.getPriorityIncidentTag();
var desiredTag;
// Validates if this field can be updated on an update action
// If the TARGET_FIELD_NAME is not added to the update fields
// input within the BigPanda Configuration form, then this
// will only work on Incident creations
if (bpUtils.canUpdate(action, '<TARGET_FIELD_NAME>')) {
// CUSTOM LOGIC GOES HERE
}
return desiredTag;
})(source);
Header Needed
For the incident tags to have this enriched schema, confirm the
x-bp-api-key
header is added to the configuration of the integration within the BigPanda Console under the integrations tab.
Class: BigPandaUtility
A Script Include library of functions called BigPandaUtility has been created to make common tasks easier.
new BigPandaUtility(source)
new BigPandaUtility(source)
source
ServiceNow source record (library may only be used when a source is defined)
The initialization function must be called before calling other library functions.
getIncident()
getIncident()
Returns the BigPanda Share payload
getIncidentTags()
getIncidentTags()
Returns an array of Incident Tags (See example above for return schema)
getIncidentTag(tag_name)
getIncidentTag(tag_name)
tag_name
Name of the Incident Tag to retrieve
Returns the value for the provided incident tag. Returns null if no match is found
getPriorityIncidentTag()
getPriorityIncidentTag()
Returns the value for the provided priority Incident Tag. Returns null if not found
getPrimaryAlert()
getPrimaryAlert()
Returns Primary Alert object as determined by setPrimaryAlert
.
getPrimaryAlertStatus()
getPrimaryAlertStatus()
Returns a String
representing the Primary Alert status.
getPrimaryAlertValue(key)
getPrimaryAlertValue(key)
key
Key within Primary Alert to retrieve
Returns the value of specified key within Primary alert or null
if it doesn't exist.
getPrimaryAlertTag(tag)
getPrimaryAlertTag(tag)
tag
Name of tag to retrieve
Returns the value of specified tag within Primary Alert or null
if it does not exist.
getAlertStatusCounts()
getAlertStatusCounts()
Returns String
containing alert counts: X Critical, Y Warning, Z Resolved [U Unknown]
. The unknown value is present only when some alerts have no status.
getTimeByProperty(epochTime, property)
getTimeByProperty(epochTime, property)
epochTime
epoch time used as fallback source valueproperty
field containing epochTime in source record to convert
Returns String
containing ServiceNow formatted time. Generated from field property
if it exists in source, otherwise, epochTime is used.
getUserByProperty(userEmail, property)
getUserByProperty(userEmail, property)
userEmail
fallback value used for emailproperty
field containing user email in source record
Returns the ServiceNow system id for the provided user email. Generated from field property
if it exists in source, otherwise, userEmail is used.
getUpdateFields()
getUpdateFields()
Returns list of fields to be updated during an update event
reopenIncident(incident)
reopenIncident(incident)
incident
source record to determine reopening
Returns Boolean
whether the incident should be reopened. Returns true if Re-open Resolved
is checked in the Configuration UI and the time since the incident was resolved less than Re-open Window
minutes ago.
Updated 6 months ago