Advanced customization options are available in the ServiceNow Incidents integration.

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 transformation of data. If changes occur to the alerts on open incidents, BigPanda updates the corresponding incidents in ServiceNow. Updates are checked every 15 seconds, by default.

ServiceNow Field Default Values

Field	Default Value
`description`	`{X} Critical, {Y} Warning, {Z} Resolved[, {U} Unknown]` `Incident Link: {incident-link-url}` `Incident Timeline Link: {timeline-link-url}` `Incident Preview Link: {preview-link-url}`
`short_description`	`BigPanda Incident: {Primary tag of Primary Alert}`
`opened_at`	BigPanda incident `startedOn` time
`resolved_at`	BigPanda incident `endedOn` time
`comments`	BigPanda comments, by default this value is mapped to the `work_notes` column in ServiceNow.

👍
Custom short_description
Custom short descriptions for ServiceNow Incidents can be created without modifying the transform script for the short_description field in the field map.
Create a composition tag with the alert tag values needed by defining bp_short_description. If this field exists, the short_description will follow the same format and add a status or priority value to the end.

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. Refer to the x_bip_panda_shareincident import set table for viewing the mapped values from a shared incident.

Field	Description
`u_bp_incident_id`	BigPanda Incident ID
`u_bp_incident_status`	BigPanda Incident status
`u_bp_alerts_statuses`	Text printout of statuses of all alerts in an incident
`u_bp_alerts_count`	The count of all the alerts in the incident
`u_bp_active_alerts_count`	The count of all non-resolved alerts in the incident
`u_bp_environment`	The BigPanda Environment from which the share originated
`u_bp_environment_id`	The BigPanda Environment ID
`u_bp_sender_email`	The email address of the user who performed the share If this was an auto-share, the address will be [email protected]
`u_bp_raw_incident`^*	A string representation of the entire BigPanda Incident JSON Object
`u_bp_incident_url`	A link to the BigPanda incident
`u_bp_timeline_url`	A link to the BigPanda incident timeline
`u_bp_preview_url`	A link to the preview of a BigPanda Incident
`u_bp_cmdb_ci`	This defined the property to lookup on the defined primary alert tags for attempting to populate the ServiceNow Configuration Item field Default: `hostname`
`u_bp_config`	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

  {
   "incident":{
      "id":"5f73d0f2xxxe10757e4xxxxx",
      "status":"Critical",
      "active":true,
      "severity":"Critical",
      "flapping":false,
      "resolved":false,
      "snooze":{
         "snoozed":false,
         "wake":null,
         "autoCancel":false
      },
      "startedOn":1601425650,
      "changedOn":1601425650,
      "updatedOn":1674881061,
      "endedOn":null,
      "alerts":[
         {
            "id":"5f73d0f2xxxe10757e4xxxxx",
            "status":"Critical",
            "startedOn":1601425650,
            "endedOn":null,
            "changedOn":1601425650,
            "updatedOn":1601425650,
            "active":true,
            "primaryProperty":"host",
            "secondaryProperty":"ip_address",
            "sourceSystem":"api.testemailparser",
            "description":null,
            "tags":[
               {
                  "name":"ip_address",
                  "value":"10.xxx.134.xxx"
               },
               {
                  "name":"system_name",
                  "value":"Test system"
               },
               {
                  "name":"product_version_endpoint_security_platform",
                  "value":"10.x.1.xxxx"
               },
               {
                  "name":"product_version_endpoint_security_threat_prevention",
                  "value":"10.x.1.xxxx"
               },
               {
                  "name":"last_communication",
                  "value":"9/2/20 7:39:01 AM CDT"
               },
               {
                  "name":"agent_version",
                  "value":"5.x.5.xxx"
               },
               {
                  "name":"host",
                  "value":"Test system"
               },
               {
                  "name":"amcore_content_version",
                  "value":"0.5"
               }
            ]
         }
      ]
   },
   "links":{
      "landingPage":"http://bigp.io/xxx6e2c58xxxxxxx"
   },
   "metadata":{
      "sender":{
         "name":"Test User",
         "email":"[email protected]"
      },
      "environment":"All",
      "environment_id":"xxx6dde2bcxxxdaf7318xxxx",
      "event_types":[
         {
            "event":"incident#new",
            "time":1674571309
         },
         {
            "event":"incident-tag#upserted",
            "time":1674571309
         },
         {
            "event":"incident-tag#upserted",
            "time":1674571309
         }
      ]
   },
   "config":{
      
   }
}

Custom Headers

BigPanda allows you to create Custom Headers to specify customized information with your integration. If you have not been granted Administrator access to the integration system, you can modify the integration through custom headers.

📘
Note
Custom headers take priority over the fields you configure on the Integration page.

See the Custom Headers documentation for more details. Below are some of the advanced features supported by custom headers.

OAuth 2.0 Support

BigPanda supports OAuth 2.0 for ServiceNow incident creation. In order to add OAuth provider details within the BigPanda ServiceNow integration, add the following custom headers. Once OAuth details are added, any Basic Auth credentials are ignored when making requests to ServiceNow.

x-bp-config-oauthUrl
x-bp-config-oauthClientId
x-bp-config-oauthClientSecret
x-bp-config-oauthGrantType
(optional; required for oauthGrantType of password) x-bp-config-oauthPassword
(optional; required for oauthGrantType of password) x-bp-config-oauthUser
(optional) x-bp-config-oauthScope

The recommended oauthGrantType is 'password'. The oauth user in ServiceNow needs to have the role of x_bip_panda_user assigned.

We only support grant types of 'password' and 'client_credentials' at present. OAuth support is only available for ticket creation via push mechanism and not when polling from ServiceNow.

Override URL

To support an intermediate custom implementation, add the below custom header to your ServiceNow integration. Such custom implementations are typically needed to support complex security requirements that are not supported by the standard integration.

x-bp-config-servicenowUrlOverride

ShareIncident Transform Map

The ShareIncident Transform map is where customization of fields in the ServiceNow incident is 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.

Customize Transform Fields

Add 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.

1  answer = (function transformEntry(source) {
2	 // Instantiate BigPanda Utility Object with source
3	 var bpUtils = new x_bip_panda.BigPandaUtility(source);
4	 var description = null;
5	
6	 // Validates if this field can be updated on an update action
7	 if (bpUtils.canUpdate(action, 'description')) {
8	  	description = source.description;
9	 }
10	
11	// Example of custom logic
12	// Retrieve the BigPanda Incident Data
13	var incident = bpUtils.getIncident().incident;
14	for (var i = 0; i < incident.alerts.length; i++) {
15		description += '\nAlert ' + (i + 1) + '\nStatus: ' + incident.alerts[i].status + '\nDescription: ' + incident.alerts[i].description;
16	}
17
18	return description;
19  })(source);

Capturing Alert Tag

When multiple alerts correlate to form a single BigPanda incident, a primary alert can be defined which helps to accurately categorize the incident. By default, the oldest, most severe alert serves as the primary alert. However, the criteria can be changed in the configuration section of the app. Once the primary alert is defined, various tags/properties from that alert can be captured to form the ServiceNow incident fields.

The snippet below can be used if attempting to capture a tag from your defined primary alert within the BigPanda Incident.

1   answer = (function transformEntry(source) {
2   // Instantiate BigPanda Utility Object with source
3   var bpUtils = new x_bip_panda.BigPandaUtility(source);
4   var desiredTag;
5
6   // Validates if this field can be updated on an update action
7   // If the TARGET_FIELD_NAME is not added to the update fields 
8   // input within the BigPanda Configuration form, then this
9   // will only work on Incident creations
10	if (bpUtils.canUpdate(action, '<TARGET_FIELD_NAME>')) {
11		desiredTag = bpUtils.getPrimaryAlertTag('<DESIRED_ALERT_TAG>');
12	}
13
14  return desiredTag;
15  })(source);

Capturing Incident Tags

The snippet below can be used to retrieve the Incident Tags of the BigPanda Incident.

1  answer = (function transformEntry(source) {
2  // Instantiate BigPanda Utility Object with source
3  var bpUtils = new x_bip_panda.BigPandaUtility(source);
4
5  // Getting all Incident Tags
6  var incidentTags = bpUtils.getIncidentTags();
7  /* Return Schema for Incident Tags
8    [
9      {
10        id: 'some_id',
11        name: 'Incident Tag Name',
12        value: 'SOME_VALUE'
13        type: 'INCIDENT_TAG_TYPE' ('text', 'multivalue', 'priority')
14      }
15    ]
16  */
17
18  // Getting a single Incident Tag
19  var incidentTag = bpUtils.getIncidentTag('some tag name');
20
21  // Getting the Priority Incident Tag
22  var priority = bpUtils.getPriorityIncidentTag();
23
24  var desiredTag;
25
26  // Validates if this field can be updated on an update action
27  // If the TARGET_FIELD_NAME is not added to the update fields 
28  // input within the BigPanda Configuration form, then this
29  // will only work on Incident creations
30  if (bpUtils.canUpdate(action, '<TARGET_FIELD_NAME>')) {
31    // CUSTOM LOGIC GOES HERE
32  }
33
34  return desiredTag;
35  })(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)`

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()`

Returns the BigPanda Share payload

`getIncidentTags()`

Returns an array of Incident Tags (See example above for return schema)

`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()`

Returns the value for the provided priority Incident Tag. Returns null if not found

`getPrimaryAlert()`

Returns Primary Alert object as determined by setPrimaryAlert.

`getPrimaryAlertStatus()`

Returns a String representing the Primary Alert status.

`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)`

tag Name of tag to retrieve

Returns the value of specified tag within Primary Alert or null if it does not exist.

`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)`

epochTime epoch time used as fallback source value
property 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)`

userEmail fallback value used for email
property 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()`

Returns list of fields to be updated during an update event

`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.