Update the BigPanda ServiceNow App

The latest BigPanda ServiceNow integration includes support for recent ServiceNow versions and additional functionality. Upgrading your integration allows you to take advantage of the latest functionality.

Identify the Needed Update Steps

Updating the BigPanda ServiceNow app may involve different steps depending upon the version that you are currently running. Determine which version you are on, and follow the steps below to upgrade.

• If you are installing ServiceNow for the first time, follow the Install the ServiceNow Integration instructions.
• If you are using BigPanda ServiceNow v1, first update to the BigPanda ServiceNow v2 app.
• If you are running the non-customized ServiceNow Store version, update to the Developer Custom App (Update Set) prior to installing the latest version.
• If you are running the version downloaded from the Developer Store, follow the Install the Latest Version instructions below to install the latest version.

📘

BigPanda App Version

To determine your BigPanda ServiceNow application version, navigate to System Applications > My Company Applications within your ServiceNow instance. The BigPanda Application tile will list which version has been installed.

❗️

Controlled Rollout Recommended

Your ServiceNow instance will be customized to the unique needs and processes of your organization. When working through the upgrade process, please utilize the standard servicenow Update-Set practice that applies to your organization. We always recommend you apply your BigPanda ServiceNow update sets in a Developement environment and promote them to QA and Production using the standard ServiceNow retrieval processes. We do not recommend applying an update set directly to production as it cannot be vetted out in the lower environments. As you simulate a production rollout by promoting your code from Dev to a QA or Staging environment, take note of the specific changes required for your instance. If unsure, contact your ServiceNow architect to learn about your organization's code promotion process and policy.

(Optional) Exclude Properties from Update Sets

If you want to exclude certain system properties in one instance from overwriting values in another, you’ll need to set those properties to private in ServiceNow. Here’s how:

1. Type sys_properties.list into the search bar to find the desired property.
2. Select and open the property.
3. Select the checkbox marked Private at the bottom of the screen.

This will prevent these properties from being exported when cloning or downloading an Update Set.

📘

Recommended Private Properties

We recommend making the following properties private:

• x_bip_panda.apiKey
• x_bip_panda.bearerToken
• x_bip_panda.changesAppKey
• x_bip_panda.incidentsAppKey

Install the Latest Version

Install the BigPanda app from the ServiceNow Developer Portal.

If installing the BigPanda ServiceNow integration for the first time, you will want to use the download button to retrieve the latest full version.

If upgrading from 2.9.0 or 2.9.1, use the NEW UPDATE AVAILABLE 2.9.2 link in the developer portal or through this update link.

• The 2.9.2 UPGRADE PATCH has only the updates above 2.9.0. Only apply this upgrade patch if you have already upgraded to 2.9.1 or 2.9.0
• Version 2.9.1 includes the ability to use BigPanda Alert Tables. This update set is a secondary Add-on since it requires a table entitlement from ServiceNow in production instances. You are free to load the Alert Tables into Dev/Test Instances to evaluate them, but you will need to check with your ServiceNow administrator to understand production table entitlements.
• The BigPanda Alert Table Add-on Update set is also listed in the developer portal description, or through this add-on link. Apply this only after upgrading to 2.9.1 or higher.

📘

Conflicting Updates

During the Preview Set step, if you made any updates that conflict with BigPanda’s updates, they can be fixed or consolidated.

❗️

Merge Conflicts

During the ServiceNow upgrade process, individual components of the BigPanda ServiceNow Application will be presented as update conflicts if there is an existing version of that component in the app.

To resolve merge conflicts, keep a list of all customizations to compare to the Merge Conflicts table.

Installation Steps

1. Navigate to System Update Sets > Retrieved Update Sets.
2. Under Related Links, select Import Update Set from XML.
3. Under Preview Set, select Fix any errors.
4. Once imported, the application should now be available from the Navigation Pane and Scope.

Migrate from the ServiceNow Store to the Update Set

In order to support future updates of the BigPanda ServiceNow app, existing installations must be migrated from the store-installed version to a custom installation. BigPanda is providing a set of scripts in order to make this process as seamless and easy as possible, while also maintaining any configuration changes that have already been made.

📘

Note

While this migration is required to update to newer versions of BigPanda's ServiceNow application, this guide is only to migrate existing installations from the Store app to the custom developer application after BigPanda's removal from the ServiceNow store in October 2021.

These scripts will not install the latest version or update installations from v1 to v2. To perform either of these functions instead, please refer to the linked documentation.

Scripts

The migration scripts will be provided in the form of a ServiceNow update set containing three fix scripts labeled 1, 2, and 3. The update set is available here.

Migration Steps

To complete the migration, your ServiceNow admin must upload the update set, preview and commit, and then run the scripts in the prescribed order. Detailed instructions for how to do every step are provided below.

Update Sets

1. Admin users may upload the update set by first logging into your ServiceNow instance. Then, using the Sidebar, search for or navigate to System Update Sets > Retrieved Update Sets.

   

2. In there, search for the option labeled “Import Update Set from XML”

   

3. Once you are on the upload screen, click “Choose File” and select the file provided in the Scripts section. Click “Upload”. This will bring you back to the Update Set listing, and three new update sets will appear. Select “BigPanda Migration Script Batch”.

   

4. Once you are in the Update Set screen, select “Preview Update Set Batch”. This will allow you to see, in detail, how your instance will be affected. Under “Customer Updates In Batch” confirm that there are three updates with type “Fix Script” and target name “BigPanda App Migration: (1-3) of 3”. The preview process should only take a couple of seconds.

   

5. Once you’ve confirmed that the updates are correct, apply the updates by selecting “Commit Update Set Batch”.

   

Committing these changes should only take a few seconds. After this commit is applied, you can move to the next step in migration.

Fix Scripts

1. Admin users may execute the newly added fix scripts by, using the Sidebar, searching for or navigating to System Definition > Fix Scripts.

   

2. From this listing, locate the scripts named “BigPanda App Migration: (1-3) of 3”. These scripts are numbered by order in which they should be executed.

   

   > 📘 Important Notes
   > 
   > - Once the first script has been run, it is important to finish running all scripts before attempting to make any changes to your BigPanda SNOW configuration. There should be no data loss at any point during the script execution, but BigPanda configuration changes within SNOW may not be applied.
   > - Each script should be run only once, and in the order prescribed. We have added checks at every step to ensure that no data is changed if we suspect that the scripts are being run again or out of order, but BigPanda cannot ensure data integrity if the scripts are run multiple times or executed out of order.
   > - Although these scripts have been thoroughly tested to ensure that they work correctly and that user data is preserved, these scripts will make modifications to your application tables. If you have any questions or concerns, please reach out to BigPanda before running them.
   

3. Select BigPanda App Migration: 1 of 3. At either the top or bottom of the page, press the green Run Fix Script button.

   If you are operating outside of the Global Scope, you will see a warning at the top of the page informing you that `The record is in the Global application`. This warning is expected, and will not cause any issues executing the script. To prevent accidental script modification, it is advised that you do not change your selected scope or enable editing of the script.
   
   [block:image]
   

   {
   "images": [
   {
   "image": [
   "https://files.readme.io/239b836-Picture8.png",
   "Picture8.png",
   624
   ],
   "caption": "Running the Scripts"
   }
   ]
   }
   [/block]
   v

4. In the dialog box, click Proceed

   

5. After the script has been run, the pop-up will fill with details about the script execution. If executed successfully, you’ll get a message resembling the following: *** Script: could not find the new update set for the new current application: no thrown error. This message is expected and correct, and the problem that it is warning against will be resolved once all the scripts are finished.

   

6. Press Close on the dialog box, then click < in the top-left corner of the ServiceNow menu.

7. Repeat the previous steps for BigPanda App Migration: 2 of 3 and BigPanda App Migration: 3 of 3

   Each of the scripts will show a results dialog box when done.
   
   [block:image]
   

   {
   "images": [
   {
   "image": [
   "https://files.readme.io/e14231a-Picture11.png",
   "Picture11.png",
   624
   ],
   "caption": "Migration Script 2 of 3 Results Message"
   }
   ]
   }
   [/block]
   [block:image]
   {
   "images": [
   {
   "image": [
   "https://files.readme.io/39bf969-Picture12.png",
   "Picture12.png",
   624
   ],
   "caption": "Migration Script 3 of 3 Results Message"
   }
   ]
   }
   [/block]

   Any warnings regarding update set are expected and indicate success.
   

8. Once BigPanda App Migration: 3 of 3 has been executed, you may verify that your migration completed successfully. Refresh the page, and navigate to the Application Selector (Settings Wheel > Developer > Application) and ensure that there is only one BigPanda option available.

   

9. Next, navigate to the BigPanda Configuration screen by using the Sidebar to search for or select BigPanda > Configuration and confirm that all of your settings are intact.

   

Migrate to the BigPanda ServiceNow v2.0 App

NOTE: The following instructions allow you to update the BigPanda ServiceNow App to v2.0. These scripts will not install the latest version or update installations to the custom app (update set). To perform either of these functions instead, please refer to the linked documentation.

Before You Start

• Make sure you have admin access to ServiceNow
• Review the designated migration sections for instructions on how to save data prior to updating the app

App Update Process

To update the app:

1. Download the latest BigPanda App from the ServiceNow Developer Page.
2. If you had previously been using the BigPanda App from the ServiceNow store, please follow the Migrating from the ServiceNow Store to the Update Set instructions.
3. Once the BigPanda App has been fully updated, each module will need to be looked at to compare and merge new files from the update to any defaults that were not overwritten.

📘

Incidents, Changes, and CMDB Modules

If you were on a version of the app that did not include the Changes and/or CMDB module, the next two sections can be skipped as versions will not be available.

If the incidents module was never leveraged, the Incidents Migration can also be skipped.

Incidents Migration

Previously denoted as ticketing, the incidents module has all the relevant files for creating and syncing BigPanda Incidents to ServiceNow Incidents.

Transform Map Updates

The transform map does not get updated automatically if it was modified prior to this update. Please refer below to the various updates required to allow the new logic to work.

Coalesce Field

1. Confirm the Create new record on empty coalesce fields is checked
2. Confirm the following mapping is set to true on the coalesce field

Mapping Updates

The following updates are recommended for the target fields:

• Find the target field defined below and click it
• Check Use source script and provide the script defined for each target field

Assignment_group

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var assignment_group = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'assignment_group')){
		// Attempts to get the assignment group from the source as the primary option
		// Falls back to retrieving the input from the configuration form
		assignment_group = source.assignment_group || gs.getProperty('x_bip_panda.assignmentGroup');
	}
	
	// If additional logic is required
	// Retrieves the BigPanda Incident
	// var bpIncident = bpUtils.getIncident(); // uncomment if needed
	
	// Custom logic goes here
	
	return assignment_group; 

})(source);

Caller_id

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var caller_sys_id = null;

	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'caller_id')){
		// Attempts to retrieve input from the configuration form
		// If no email is retrieved, the default is the email sender from the BigPanda Share 
		var caller_id_email = gs.getProperty('x_bip_panda.callerId', source.u_bp_sender_email);

		// Performs a lookup with the provided email and returns the associated sys id
		caller_sys_id = bpUtils.getUserByProperty(caller_id_email,"caller_id");
	}
	
	return caller_sys_id;

})(source);

CMDB_CI

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var cmdb_ci = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'cmdb_ci')){
		// Capture default cmdb ci field
		var cmdb_ci_field = source.u_bp_cmdb_ci;
		
		// Override the cmdb ci field if a value exists in the configuration form
		if (gs.getProperty('x_bip_panda.cmdbCiField')) {
			cmdb_ci_field = gs.getProperty('x_bip_panda.cmdbCiField');
		}
		
		// If the source provides a value for the cmdb_ci, leverage it
		// Otherwise default to retrieving the value for the field in the primary alert
		cmdb_ci = source.cmdb_ci || bpUtils.getPrimaryAlertTag(cmdb_ci_field);
	}
	
	return cmdb_ci;

})(source);

Description

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();
	// CUSTOM LOGIC HERE
	// description = CUSTOM_LOGIC_RESULT;

	return description;
})(source);

Opened_at

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var opened_at = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'opened_at')){
		// Set default unix time from the BigPanda Incident start time
		var time_to_use = source.opened_at;
		
		// Converts provided unix time to ServiceNow GlideDateTime
		opened_at = bpUtils.getTimeByProperty(time_to_use, 'opened_at');
	}
	
	return opened_at;

})(source);

Opened_by

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var opened_sys_id = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'opened_by')){
		// Attempts to retrieve input from the configuration form
		// If no email is retrieved, the default is the email sender from the BigPanda Share 
		var opened_by_email = gs.getProperty('x_bip_panda.openedBy', source.u_bp_sender_email);
		
		// Performs a lookup with the provided email and returns the associated sys id
		opened_sys_id = bpUtils.getUserByProperty(opened_by_email, 'opened_by');
	}
	
	return opened_sys_id;

})(source);

Resolved_at

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var resolved_at = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'resolved_at')){
		// Set default unix time from the BigPanda Incident start time
		var time_to_use = source.resolved_at;
		
		// Converts provided unix time to ServiceNow GlideDateTime
		resolved_at = bpUtils.getTimeByProperty(time_to_use, 'resolved_at');
	}
	
	return resolved_at;

})(source);

Resolved_by

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	var isResolved = (source.u_bp_incident_status.toLowerCase() === 'ok');
	var resolved_sys_id = null;

	// Validates if this field can be updated on an update action
	// And that the BigPanda Incident Status is resolved
	if (bpUtils.canUpdate(action, 'resolved_by') && isResolved){
		// Attempts to retrieve input from the configuration form
		// If no email is retrieved, the default is the email sender from the BigPanda Share 
		var resolved_by_email = gs.getProperty('x_bip_panda.resolvedBy', source.u_bp_sender_email);
		
		// Performs a lookup with the provided email and returns the associated sys id
		resolved_sys_id = bpUtils.getUserByProperty(resolved_by_email, 'resolved_by');
	}
	
	return resolved_sys_id;
	
})(source);

Short_description

answer = (function transformEntry(source) {
	// Instantiate BigPanda Utility Object with source
	var bpUtils = new x_bip_panda.BigPandaUtility(source);
	
	var short_description = null;
	
	// Validates if this field can be updated on an update action
	if (bpUtils.canUpdate(action, 'short_description')){
		// Sets the default short description
		short_description = source.short_description;
		
		// Sets the short description based on the primary alert definition 
		// in the configuration
		// Retrieve the Primary Property from Primary Alert
		primaryProperty = bpUtils.getPrimaryAlertValue('primaryProperty');

		// Retrieve Value of Primary Property
		primaryValue = bpUtils.getPrimaryAlertTag(primaryProperty);

		// Construct short description string (customize to need)
		short_description = 'BigPanda Incident - ' + primaryValue;
	}

	return short_description;
})(source);

Work_notes

Changes Migration

The Changes module has had some minor changes to the Business Rule that need to be addressed.

Save Existing Data

1. Navigate to BigPanda > Changes.
2. The Changes Business Rule will have a script under the advance tab.
3. Save values within the options object.

// Configuration for the BigPanda Changes Module
var options = {
  "api_key": "API_KEY", // your BigPanda API Key
  "app_key": "APP_KEY", // your BigPanda Integration App Key
  // Mapping of BigPanda change fields => ServiceNow Change Table Columns
  "fieldMapping": {
    "start": "start",
    "end": "end",
    "state": "state", // defaults to "state", can be overridden
    "identifier": "number", // defaults to change "number", can be overridden
    "summary": "short_description" // defaults to "short_description", can be overridden
  },
  // Mapping of BigPanda change states to ServiceNow states
  // these are general defaults but you can customize to align with your instance
  "stateMapping": {
    "Planned": [ "New", "Assess", "Authorize", "Scheduled" ],
    "In Progress": [ "Implement", "Review" ],
    "Done": [ "Closed" ],
    "Canceled": [ "Cancelled" ] 
  },
  // Array of tags which should NOT appear in the BigPanda Changes UI
  "hide": [ "HIDDEN_TAG_1", "HIDDEN_TAG_2" ]
};

Update Configuration UI

1. Update the BigPanda App.
2. Navigate to BigPanda > Configuration.
3. Under the Changes section, enter the data saved from the changes business rule.
4. Mark the section as active to enable this module.
5. Save the form.

Compare and Merge

1. Navigate to BigPanda > Changes > Changes Business Rule.

2. Scroll down to Versions.

3. Two versions should be present. An Update Set: Default and a Store Application: BigPanda source.

   

4. Select both files and click on the Actions dropdown to find the compare option.

5. A side-by-side comparison of the Selected Version (Store Application: BigPanda) and the Current Version (Update Set: Default) will now be in view.

6. Confirm the application scope is BigPanda to be able to view the Revert to Selected Version and Save Merge buttons on the top right of the screen.

7. Click on the Revert to Selected Version button to set the current state to the Store Application: BigPanda source.

CMDB Migration

The CMDB module has had some minor changes to the Scheduled Job that need to be addressed.

Save Existing Data

1. Navigate to BigPanda > CMDB.
2. The CMDB Processing Scheduled Job will have a script section.
3. Make sure to save all tables/views with their respective options.

var tablesAndViews = [
	{
		name: "u_hosts_apps", // Name of transmitted table or view
		query: null, // [optional] A query to filter the table's records
		key: "a_u_app", // The key column (e.g. host). Make sure the key column is indexed in the table
		columns: ["h_u_name", "h_u_host_id"], // String array with all required columns to send
       columnToTagMapping: {"h_u_name": "host"} // Mapping of ServiceNow columns to BigPanda tags
	},
	{
		name: "u_bp_apps",
		query: null,
		key: "u_app",
		columns: ["u_host_id"],
		columnToTagMapping: {"u_app": "app"}
	}
];
var opts = {
   "pageSize": 1000, // Max records per REST request
   "url": "https://integrations.bigpanda.io/servicenow/cmdb/ingest",
   "apiToken": "XXXX", // [optional] Used for authentication for the REST endpoint
   "maxRetries": 3, // Number of retries to try before giving up
   "maxPages": 1000, // Maximum pages to transmit, even if more data is available
   "retrySeconds": 60 // Sleep time between retries
};

Update Configuration UI

1. Update the BigPanda App.
2. Navigate to BigPanda > Configuration.
3. Under the CMDB section, enter the data saved from the CMDB Scheduled Job.
4. Mark the section as active to enable this module.
5. Save the form.

Update the Scheduled Job Script

1. Navigate to BigPanda > CMDB > CMDB Processing Scheduled Job.
2. Confirm the information has already been previously captured and saved to the configuration UI.
3. Copy and paste the code below. Save the file.

/*
 * Configuration for the BigPanda CMDB Module
 *
 * For tablesAndViews please provide an array of configuration objecst for each table or view you wish to send
 *
 * For opts please provide the general configuration for the module
 */

// start with empty table and view data
var tablesAndViews = JSON.parse(gs.getProperty("x_bip_panda.CMDBConfigList"));

var opts = {
	"pageSize": gs.getProperty("x_bip_panda.CMDBPageSize"), // Max records per REST request
	"url": gs.getProperty("x_bip_panda.CMDBEndpoint"),
	"apiToken": gs.getProperty("x_bip_panda.bearerToken"), // Used for authentication for the REST endpoint
	"maxRetries": gs.getProperty("x_bip_panda.CMDBMaxRetries"), // Number of retries to try before giving up
	"maxPages": gs.getProperty("x_bip_panda.CMDBMaxPages"), // Maximum pages to transmit, even if more data is available
	"retrySeconds": gs.getProperty("x_bip_panda.CMDBRetryInterval") // Sleep time between retries
};

gs.info("BigPanda Info: Sending CMDB Data to BigPanda");
var cmdb = new BigPandaCMDB();
cmdb.process(opts, tablesAndViews);