Methods

• AltServiceNow::Instance Methods
  • new
  • table
  • setTrace [Instance]
  • saveSession
  • loadSession
• AltServiceNow::Table Methods
  • enableCache
  • loadCache
  • setChunk
  • setDV
  • setTrace [Table]
  • setValidate
  • get
  • getKeys
  • getRecords
  • setQuery
  • fetch
  • insert
  • update
  • attachFile

AltServiceNow::Instance Methods

new

To obtain a reference to an AltServiceNow::Instance object. The first argument is the URL of the instance. The second argument is the SOAP user name. The third argument is the SOAP password. The fourth argument (optional) is the trace level. Set the trace level to 1 to enable tracing messages for SOAP calls.

Example

The following code returns a reference to an instance.

my $url = "https://demoxxx.service-now.com";
my $user = "******";
my $pass = "******";
my $instance = new AltServiceNow::Instance($url, $user, $pass);

The following code returns a reference to an instance with tracing enabled.

my $instance = new AltServiceNow::Instance($url, $user, $pass, 1);

table

Obtain a reference to an AltServiceNow::Table object for use in Table methods described below.

Arguments

Table name.

Returns

A reference to a table object.

Example

my $ci_tbl = $instance->table("cmdb_ci_server");

setTrace [Instance]

Used to activate trace messages for all subsequent table references.

Example

$instance->setTrace(1);

saveSession

Write the jsession cookie to a file.

Example

$instance->saveSession($filename);

loadSession

Read the jsession cookie from a file.

Example

$instance->loadSession($filename);

AltServiceNow::Table Methods

enableCache

Causes the result from calls to get to be locally cached. For any subsequent call to get with the same arguments the result will be read from the local cache, avoiding a Web Service call.

my $location = $instance->table("cmn_location")->enableCache();

loadCache

Pre-loads the table cache.

Arguments

The first argument is an encoded query. If omitted or an empty string then the entire table will be read into the cache.

The second argument is a field name which will be used for lookups. If omitted it assumed that lookups will be performed using sys_id.

Returns

In a list context this method returns a list of the cached records (list of hash references).
In a scalar context this method returns a reference to the table object.

Example

This example pre-loads the cache with all non-retired production applications having a non-blank APP_ID.

$application->loadCache(
    "used_for=Production^operational_status!=5^u_app_id!=", 
    "u_app_id");

setChunk

Sets the chunk size, which is the number of records retrieved at a time for getRecords and fetch calls. The chunk size cannot be less than 1 or greater than 250. The default chunk size is 250.

Returns a reference to the table object.

Example
The following example reads production servers into an array 200 at a time.

my $ci_tbl = $instance->table("cmdb_ci_server")->setChunk(200);
my @serverData = $ci_tbl->getRecords(used_for => "Production", operational_status => 1);

setDV

Activates or deactivates the inclusion of display values in get calls. These elements have a prefix of "dv_". Use 1 to activate, 0 to deactivate.

The default is controlled by the global variable $AltServiceNow::DEFAULT_DV.

setTrace [Table]

Activates or deactivates trace messages for Web Services calls. Use 1 to activate, 0 to deactivate.

Returns a reference to the table object.

my $location = $instance->table("cmn_location")->setTrace(1);

setValidate

Activates or deactivates validation functions. Use 1 to activate, 0 to deactivate.

Returns a reference to the table object.

If validation is active:

• Following an insert or an update, the package will re-read the record and compare each field to ensure that it was updated as expected. Although there is some overhead in this operation, it is quite useful for detecting misspelled field names.
• Following getRecords, the package will compare the number of records retrieved with the number of sys_ids in the argument list. If there is a mismatch an error will be generated.

get

Used to retrieve a single record.

Arguments

Either a sys_id, or a set of name => value pairs. An error will be generated if multiple records are selected.

Returns

• Returns false if no matching record found.
• Otherwise returns a reference to a hash.

Example

my $rec = $change_request->get(number => "CHG39985");
print "sys_id=",$rec->{sys_id},"\n";

getKeys

Returns a list of sys_ids.

Arguments

This method accepts as arguments any of the following:

• A list of name => value pairs
• An encoded query
• '*' or no argument - Returns a list of all keys in the table

Example

Get a list of sys_ids for all non-virtual production servers with a status of "Operational".

my @keys = $ci_tbl->getKeys(
    used_for => "Production", operational_status => 1, virtual => "false");

getRecords

Used to retrieve multiple records using a list of sys_ids. If the list contains more sys_ids than the chunk size then this function will loop internally, making multiple Web Services calls.

Arguments

This method accepts as arguments any of the following:

• A list of sys_ids.
• A list of name => value pairs
• An encoded query
• '*' - Causes the entire table to be returned as a list of records

If getRecords() is called with no arguments, then it assumes it is being passed an empty list of sys_ids, and it returns a empty list of records.

Returns

A list of hash references.

Example

The following two examples are equivalent:

@ciKeys = $ci_tbl->getKeys(used_for => "Production", operational_status => 1);
@ciData = $ci_tbl->getRecords(@ciKeys);

@ciData = $ci_tbl->getRecords(used_for => "Production", operational_status => 1);

Notes

If getRecords is passed an encoded query or a list of name => value pairs, it will internally call getKeys to generate a list of sys_ids, and then retrieve the records in chunks. In this manner getRecords is able to circumvent ServiceNow's built in limitation of 250 records per SOAP call.

Warning

If getRecords is passed no arguments, it will assume that it has been passed an empty list of keys and it will return an empty list of records. To read the entire table you must pass in an argument of '*'.

setQuery

Sets an encoded query to be used for subsequent calls to fetch. Use "^" (AND operator) to separate expressions. The following expressions may be used

• fieldname=value
• fieldname!=value
• fieldname<value
• fieldname>value
• fieldname<=value
• fieldname>=value
• fieldnameSTARTSWITHvalue
• fieldnameLIKEvalue
• fieldnameINvalue,value,value...

Example

$ci_tbl->setQuery("used_for=Production^operational_status=1^virtual=false");

fetch

Used to retrieve records following a setQuery.

Argument

The maximum number of records to be retrieved. This is an optional argument. The default is the current chunk size. The value cannot exceed 250.

Returns

A list of references to records. If there are no more records available then an empty list is returned.

Notes

setQuery and fetch were implemented as an alternate to the getRecords function. If getRecords is passed an encoded query or a set of name => value pairs, it will call getKeys internally. However, if the number of keys is too large, the function may never return. The fetch function uses "__first_row" and "__last_row" to window through the results. Performance testing has shown that the getKeys approach performs better, and the use of getKeys and/or getRecords should be preferred over setQuery/fetch. However, setQuery/fetch may be appropriate if the intent is to abandon the query after a certain number of rows have been retrieved.

insert

Arguments

Either a reference to a hash or a list of name => value pairs.

Returns

A list containing two elements. The first element is the sys_id and the second element is the number.

Example

my ($sysid, $number) = $incident->insert(
    short_description => $description,
    category => 'software',
    assignment_group => $group,
    cmdb_ci => $server
    );

update

Arguments

Either a reference to a hash or a list of name => value pairs. An error will occur if sys_id is not specified.

Example

$incident->update(sys_id => $sysid, u_noc_flag => 1);

attachFile

Used to attach a file to an Incident, Problem or Change Request.

Arguments

This method takes the following four arguments

1. sys_id of the record to receive the attachment
2. file name - this file will be read and attached to the corresponding record
3. attachment name (optional) - if omitted this will default to file name
4. mime type (optional) - if omitted this will default to "text/plain"

For a list of mime types refer to http://en.wikipedia.org/wiki/Internet_media_type

Example

$incident->attachFile($sysid, "C:/temp/sample.htm", "sample.htm", "text/html");