Blog

Background Scripts

What is a Background Script?  It is an utility in ServiceNow to run scripts in the background, which is useful for mass creations, updates, and deletions of records.  It is also greatly helpful in troubleshooting records and running complex scripts to find information.  Background scripts are very powerful and can do complex operations in a short amount of time.

The need for Background Scripts

In ServiceNow, you can get around using background scripts by using these other methods

However, that is not the most efficient way to update data in cases.  It might not be feasible to use the list editor to update 200K records or make a csv file to update the records.  Sometimes a background script can be created in minutes that solves the issue.

How to find the Scripts - Background Utility

1. Login as an Admin User
2. Elevate your security privileges to security_admin. Click the Lock icon next your name on the title bar
3. Click the security_admin checkbox and click ok. The Lock icon is now unlocked
4. Go to System Defintion > Scripts - Background.  The Scripts - Background Utility appears.

WARNING #1: Background Scripts are powerful

With great power comes great responsibility.

Background Scripts are so powerful you can wreck your ServiceNow system with the right script.  You need to be extra careful in running background scripts.

Background Script Utility

I think this the reason there is not much information on the ServiceNow wiki for Background scripts, ServiceNow doesn't really want you to run Background Scripts if you are not experienced with them. How do you get experience if you don't try them right?  Well, there are demo ServiceNow instances and your development ServiceNow instances.  Be sure to try your Background scripts carefully before attempting on a Production ServiceNow instance.

WARNING #2: How to avoid disaster

Remember how I told you a few paragraphs back about how powerful background scripts are?  I really mean this, I have seen data destroyed, access revoked, and system shutdown from background scripts. 

Here are a couple points to help you avoid unknown disasters with Background Scripts

1. Bad Syntax

If you are doing a glide record query and your query is not designed correctly, ServiceNow javascript will ignore the query and not produce an error.  Here is an example: 

Working Script: Find a CI

findCI();
function findCI(){
grCI = new GlideRecord('cmdb_ci');
grCI.addQuery('name','=','SAP WEB03');
grCI.query();
while (grCI.next()){
gs.print('CI Found: '+grCI.name);
}
}

Bad Script: Accidentally Finds all CIs

findCI();
function findCI(){
grCI = new GlideRecord('cmdb_ci');
grCI.addQuery('sys_name','=','SAP WEB03');
grCI.query();
while (grCI.next()){
gs.print('CI Found: '+grCI.name);
}
}

In the bad script the column name in the cmdb_ci is not sys_name, it is name. This is an honest mistake, but since that column doesn't exist ServiceNow will ignore the query and return all records.  If I was doing a delete or update statement in the background script, this would not be good.

2.  RowCount and Comment Out Update Statement

If you are doing an update statement in your background script.  Comment out your update statement and add a RowCount statement until you are sure it is ok.  Here is an example:

Update CI Script

updateCI();
function updateCI(){
grCI = new GlideRecord('cmdb_ci');
grCI.addQuery('name','=','SAP WEB03');
grCI.query();
gs.print('grCI Query: ' + grCI.getEncodedQuery() + ' = ' + grCI.getRowCount());
while (grCI.next()){
grCI.asset_tag='ServiceNowELITE.com';
//grCI.update;
}
}

With this example, it will return how many rows are going to be updated before you update.

Script Results:

[0:00:00.005] Script completed: script
*** Script: grCI Query: name=SAP WEB03 = 1

When you ready to run that script and it is going to update the right number of rows, uncomment out the update line and run again.

3. Use the gs.print or gs.log statements.

In #2 above, I used a gs.print statement to print the rowcount of the query.  However you can also use gs.log to print the results to the Script Log.  gs.log is kind of nice if you have a log-running query.  However either one you pick, they are both helpful to troubleshoot issues with your script or with just general troubleshooting

4. Use setWorkflow(false) and autoSysFields(false)

When you are mass updating records with a background script, sometimes you don't want to run the business rules/workflow on every record you updated or have your name and the last updated time be when you updated it.  Here is an example on how to avoid this:

updateCI();
function updateCI(){
grCI = new GlideRecord('cmdb_ci');
grCI.addQuery('name','=','SAP WEB03');
grCI.query();
gs.print('grCI Query: ' + grCI.getEncodedQuery() + ' = ' + grCI.getRowCount());
while (grCI.next()){
grCI.asset_tag='ServiceNowELITE.com';
grCI.setWorkflow(false); //Do not run business rules
grCI.autoSysFields(false); //Do not update system fields
grCI.update;
}
}

In the example above the setWorkflow and autoSysFields statements avoid those workflow and autoSysFields from being run or updated.  This is really needed in cases when you are updating tasks and the last updated time affects an sla or the tasks that have a lot of business rules on them you want to ignore.

5. Stop Transaction

In Greek mythology, Icarus is the son of the master craftsman Daedalus. The main story told about Icarus is his attempt to escape from Crete by means of wings that his father constructed from feathers and wax. He ignored instructions not to fly too close to the sun, and the melting wax caused him to fall into the sea where he drowned.

Sometimes we get a little too confident with our work and are similar to Icarus.  You started a background script, and realized it is not working correctly.  You can kill the job fortunately, just don't rely on this feature too much.

Viewing and Killing Active Transactions

Background Script Ideas

Now that we know what not to do, here are some background script ideas that you might run:

How to save your Background Scripts

Good luck with your background scripting!  If you skimmed over the previous warnings, remember to run background scripts in development or sandbox system first and always be careful.

Mike