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 for every 15 seconds, by default.

ServiceNow field default values

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.

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.

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.

Customize Transform Fields

Add Alert Details to Description

1. Navigate to BigPanda > Incidents > Transform Map
2. Find the row where the target field is description
3. Click on the script
4. 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)

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