pysnow

Python library for the ServiceNow REST API

pysnow.Client — Creates a new client

class pysnow.Client(instance=None, host=None, user=None, password=None, raise_on_empty=True, request_params=None, use_ssl=True, session=None)

Creates a client ready to handle requests

Parameters:

• instance – instance name, used to construct host
• host – host can be passed as an alternative to instance
• user – username
• password – password
• raise_on_empty – whether or not to raise an exception on 404 (no matching records)
• request_params – request params to send with requests
• use_ssl – Enable or disable SSL
• session – a requests session object

query(table, **kwargs)

Query (GET) request wrapper.

Parameters:

• table – table to perform query on
• kwargs – Keyword arguments passed along to Request

Returns:

Request object

insert(table, payload, **kwargs)

Insert (POST) request wrapper

Parameters:

• table – table to insert on
• payload – update payload (dict)
• kwargs – Keyword arguments passed along to Request

Returns:

New record content

pysnow.OAuthClient — Creates a new client with OAuth extras

class pysnow.OAuthClient(client_id=None, client_secret=None, token_updater=None, *args, **kwargs)

Pysnow Client with extras for oauth session and token handling.

This API exposes two extra public methods:

• generate_token(user, pass)

  • This method takes user and password credentials to generate a new OAuth token that can be stored outside the context of pysnow, e.g. in a session or database.

• set_token(token)

  • Takes an OAuth token (dict) and internally creates a new pysnow-compatible session, enabling pysnow.OAuthClient to create requests.

Parameters:

• client_id – client_id from ServiceNow
• client_secret – client_secret from ServiceNow
• token_updater – callback function called when a token has been refreshed
• instance – instance name, used to construct host
• host – host can be passed as an alternative to instance
• raise_on_empty – whether or not to raise an exception on 404 (no matching records)
• request_params – request params to send with requests
• use_ssl – Enable or disable SSL

set_token(token)

Validates token and creates a pysnow compatible session

Parameters:token – dict containing the information required to create an OAuth2Session

generate_token(user, password)

Takes user and password credentials and generates a new token

Parameters:

• user – user
• password – password

Returns:

dictionary containing token data

pysnow.QueryBuilder — Creates a new QueryBuilder object

class pysnow.QueryBuilder

Query builder - used for building complex queries

AND()

And operator

OR()

OR operator

NQ()

NQ (new query) operator

field(field)

Sets the field to operate on

Parameters:field – field (str) to operate on Returns:self

starts_with(value)

Query records with the given field starting with the value specified

ends_with(value)

Query records with the given field ending with the value specified

contains(value)

Query records with the given field containing the value specified

not_contains(value)

Query records with the given field not containing the value specified

is_empty()

Query records with the given field empty

equals(data)

Query records with the given field equalling either: - the value passed (str) - any of the values passed (list)

not_equals(value)

Query records with the given field not equalling: - the value specified - any of the values specified (list)

greater_than(value)

Query records with the given field greater than the value specified

less_than(value)

Query records with the given field less than the value specified

between(start, end)

Query records in a start and end range

Parameters:

• start – int or datetime object
• end – int or datetime object

Raise:

QueryTypeError:if start or end arguments is of an invalid type

Returns:

self

pysnow.Request — Creates a new request object

class pysnow.Request(method, table, **kwargs)

Takes arguments used to perform a HTTP request

Parameters:

• method – HTTP request method
• table – table to operate on

last_response

Return _last_response after making sure an inner requests.request has been performed

Raise:

NoRequestExecuted:  If no request has been executed

Returns:

last response

count

Returns the number of records the query would yield

status_code

Return last_response.status_code after making sure an inner requests.request has been performed

Returns:status_code of last_response

get_all(fields=[], limit=None, order_by=[], offset=None)

DEPRECATED - see get_multiple()

get_multiple(fields=[], limit=None, order_by=[], offset=None)

Wrapper method that takes whatever was returned by the _all_inner() generators and chains it in one result

The response can be sorted by passing a list of fields to order_by.

Example: get_multiple(order_by=[‘category’, ‘-created_on’]) would sort the category field in ascending order, with a secondary sort by created_on in descending order.

Parameters:

• fields – List of fields to return in the result
• limit – Limits the number of records returned
• order_by – Sort response based on certain fields
• offset – A number of records to skip before returning records (for pagination)

Returns:

Iterable chain object

get_one(fields=[])

Convenience function for queries returning only one result. Validates response before returning.

Parameters:

fields – List of fields to return in the result

Raise:

MultipleResults:  if more than one match is found

Returns:

Record content

insert(payload)

Inserts a new record with the payload passed as an argument

Parameters:payload – The record to create (dict) Returns:Created record

delete()

Deletes the queried record and returns response content after response validation

Raise:

NoResults:if query returned no results NotImplementedError:  if query returned more than one result (currently not supported)

Returns:

Delete response content (Generally always {‘Success’: True})

update(payload)

Updates the queried record with payload and returns the updated record after validating the response

Parameters:

payload – Payload to update the record with

Raise:

NoResults:if query returned no results MultipleResults:  if query returned more than one result (currently not supported)

Returns:

The updated record

clone(reset_fields=[])

Clones the queried record

Parameters:

reset_fields – Fields to reset

Raise:

NoResults:if query returned no results MultipleResults:  if query returned more than one result (currently not supported) UnexpectedResponse:  informs the user about what likely went wrong

Returns:

The cloned record

attach(file)

Attaches the queried record with file and returns the response after validating the response

Parameters:

file – File to attach to the record

Raise:

NoResults:if query returned no results MultipleResults:  if query returned more than one result (currently not supported)

Returns:

The attachment record metadata

exception pysnow.exceptions.UnexpectedResponse(code_expected, code_actual, http_method, error_summary, error_details)

Informs the user about what went wrong when interfacing with the API

Parameters:

• code_expected – Expected HTTP status code
• code_actual – Actual HTTP status code
• http_method – HTTP method used
• error_summary – Summary of what went wrong
• error_details – Details about the error

Usage

Go here for usage examples.

Installation

$ pip install pysnow

Compatibility

Python 2 and 3. Tested: Python 2.6+ and Python 3.3+