About¶

aiosnow is a Python asyncio library for interacting with ServiceNow programmatically. It hopes to be:

Convenient: A good deal of work is put into making the library flexible and easy to use.
Performant: Remote API calls uses non-blocking sockets tracked by an event loop, allowing large amounts of lightweight request tasks to run concurrently.
Modular: Core functionality is componentized into modules that are built with composability and extensibility in mind.

For usage examples, visit github.com/rbw/aiosnow/examples.

Requirements¶

Python 3.7+

Installation¶

The library is available on PyPI and can be installed using pip.

$ pip install aiosnow

Dependencies¶

The aiosnow library depends on a small set of stable and permissively licensed libraries.

aiohttp: Communication
marshmallow: Schema system

Table of Contents¶

Funding¶

The aiosnow code is permissively licensed, and can be incorporated into any type of application–commercial or otherwise–without costs or limitations. Its author believes it’s in the commercial best-interest for users of the project to invest in its ongoing development.

Consider leaving a donation if you like this software.

Client¶

The Client is typically invoked via Models and provides means to communicate with ServiceNow.

API¶

class aiosnow.Client(address: Union[str, bytes], basic_auth: tuple = None, use_ssl: bool = True, verify_ssl: bool = None, pool_size: int = 100, response_cls: Type[aiosnow.request.response.Response] = None, session_cls: Type[aiohttp.client.ClientSession] = None)[source]¶

Client for communicating with ServiceNow

Parses client config and provides a ClientSession factory.

Parameters:	address – Instance TCP address, example: my-instance.service-now.com basic_auth – Tuple of (username, password) use_ssl – Whether to use SSL verify_ssl – Whether to verify SSL certificates pool_size – Connection pool size response_cls – Custom Response class

config¶: Client configuration object

Models¶

A model in aiosnow must be declared a type and one or more fields. Once instantiated, an interface for reading and altering data in ServiceNow is provided.

Types¶

Table¶

The TableModel defines items of, and provides means for working with, ServiceNow Table API resources.

Reference

API¶

class aiosnow.models.table.TableModel(client: aiosnow.client.Client, attachment: bool = True, **kwargs)[source]¶

create(payload: dict) → aiosnow.request.response.Response¶

Create a new record

Parameters:	payload – New record payload
Returns:	Response

delete(selection: Union[aiosnow.query.condition.Condition, str]) → aiosnow.request.response.Response¶

Delete matching record

Parameters:	selection – Condition or ID
Returns:	Response

download_file(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str], dst_dir: str = '.') → aiosnow.models.attachment.file.FileHandler[source]¶

Download incident attachment

Parameters:	selection – Attachment selection dst_dir – Destination directory
Returns:	FileHandler object

get(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response¶

Buffered many

Fetch and store the entire result in memory.

Note: It’s recommended to use the stream method when dealing with a large number of records.

Keyword Arguments:
	selection – Aiosnow-compatible query limit (int) – Maximum number of records to return offset (int) – Starting record index
Returns:	Response

get_attachment(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response[source]¶

Returns Response if the given condition yielded exactly one attachment

Parameters:	selection – Attachment selection **kwargs – arguments to pass along to AttachmentModel
Returns:	Response object

get_attachments(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response[source]¶

Returns list of attachments for this table

Parameters:	selection – Attachment selection **kwargs – arguments to pass along to AttachmentModel
Returns:	Response object

get_object_id(value: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str]) → str¶

Get object id by str or Condition

Immediately return if value is of str type.

Parameters:	value – Condition or str
Returns:	Object id

get_one(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response¶

Get one record

Parameters:	selection – aiosnow-compatible query
Returns:	Response

stream(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → AsyncGenerator[T_co, T_contra]¶

Stream-like async generator

Chunk size determines the number of records to fetch in one go. Setting a lower chunk size decreases memory usage, but increases the number of requests sent to the server.

Keyword Arguments:
	selection – aiosnow-compatible query limit (int) – Maximum number of records to return offset (int) – Starting record index page_size (int) – Number of records to fetch in one go
Yields:	Chunk of records

update(selection: Union[aiosnow.query.condition.Condition, str], payload: dict) → aiosnow.request.response.Response¶

Update matching record

Parameters:	selection – Condition or ID of object to update payload – Update payload
Returns:	Response

upload_file(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str], path: str) → aiosnow.request.response.Response[source]¶

Upload incident attachment

Parameters:	selection – Attachment selection path – Source file path
Returns:	Response

Schemas¶

A growing collection of declared TableModel classes is included with the library in aiosnow.models.table.declared, these classes are typically subclassed and adjusted to reflect the ServiceNow instance at hand, but can be instantiated and used directly as well.

Incident¶

ServiceNow default Incident definition. Used by aiosnow.models.table.declared.incident.IncidentModel.

class aiosnow.models.table.declared.incident.IncidentModelSchema[source]¶

active = <Boolean [maps_to=Pluck.VALUE, primary=False]>¶

activity_due = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

additional_assignee_list = <String [maps_to=Pluck.VALUE, primary=False]>¶

approval = <String [maps_to=Pluck.VALUE, primary=False]>¶

approval_history = <String [maps_to=Pluck.VALUE, primary=False]>¶

approval_set = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

assigned_to = <String [maps_to=Pluck.VALUE, primary=False]>¶

assignment_group = <String [maps_to=Pluck.VALUE, primary=False]>¶

business_duration = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

business_service = <String [maps_to=Pluck.VALUE, primary=False]>¶

business_stc = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

calendar_duration = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

calendar_stc = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

caller_id = <String [maps_to=Pluck.VALUE, primary=False]>¶

category = <String [maps_to=Pluck.VALUE, primary=False]>¶

caused_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

child_incidents = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

close_code = <String [maps_to=Pluck.VALUE, primary=False]>¶

close_notes = <String [maps_to=Pluck.VALUE, primary=False]>¶

closed_at = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

closed_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

cmdb_ci = <String [maps_to=Pluck.VALUE, primary=False]>¶

comments = <String [maps_to=Pluck.VALUE, primary=False]>¶

comments_and_work_notes = <String [maps_to=Pluck.VALUE, primary=False]>¶

company = <String [maps_to=Pluck.VALUE, primary=False]>¶

contact_type = <String [maps_to=Pluck.VALUE, primary=False]>¶

correlation_display = <String [maps_to=Pluck.VALUE, primary=False]>¶

correlation_id = <String [maps_to=Pluck.VALUE, primary=False]>¶

delivery_plan = <String [maps_to=Pluck.VALUE, primary=False]>¶

delivery_task = <String [maps_to=Pluck.VALUE, primary=False]>¶

description = <String [maps_to=Pluck.VALUE, primary=False]>¶

due_date = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

escalation = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

expected_start = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

follow_up = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

group_list = <String [maps_to=Pluck.VALUE, primary=False]>¶

hold_reason = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

impact = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

incident_state = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

knowledge = <Boolean [maps_to=Pluck.VALUE, primary=False]>¶

location = <String [maps_to=Pluck.VALUE, primary=False]>¶

made_sla = <Boolean [maps_to=Pluck.VALUE, primary=False]>¶

notify = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

number = <String [maps_to=Pluck.VALUE, primary=False]>¶

opened_at = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

opened_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

order = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

parent = <String [maps_to=Pluck.VALUE, primary=False]>¶

parent_incident = <String [maps_to=Pluck.VALUE, primary=False]>¶

priority = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

problem_id = <String [maps_to=Pluck.VALUE, primary=False]>¶

reassignment_count = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

reopen_count = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

reopened_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

reopened_time = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

resolved_at = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

resolved_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

rfc = <String [maps_to=Pluck.VALUE, primary=False]>¶

severity = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

short_description = <String [maps_to=Pluck.VALUE, primary=False]>¶

sla_due = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

state = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

subcategory = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_class_name = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_on = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

sys_domain = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_domain_path = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_id = <String [maps_to=Pluck.VALUE, primary=True]>¶

sys_mod_count = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

sys_tags = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_updated_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_updated_on = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

time_worked = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

upon_approval = <String [maps_to=Pluck.VALUE, primary=False]>¶

upon_reject = <String [maps_to=Pluck.VALUE, primary=False]>¶

urgency = <IntegerMap [maps_to=Pluck.VALUE, primary=False]>¶

user_input = <String [maps_to=Pluck.VALUE, primary=False]>¶

watch_list = <String [maps_to=Pluck.VALUE, primary=False]>¶

work_end = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

work_notes = <String [maps_to=Pluck.VALUE, primary=False]>¶

work_notes_list = <String [maps_to=Pluck.VALUE, primary=False]>¶

work_start = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

Journal¶

ServiceNow default Journal definition, used for working with collections of work_notes, comments, etc. Used by aiosnow.models.table.declared.journal.JournalModel.

class aiosnow.models.table.declared.JournalModelSchema[source]¶

element = <String [maps_to=Pluck.VALUE, primary=False]>¶

element_id = <String [maps_to=Pluck.VALUE, primary=False]>¶

name = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_on = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

sys_id = <String [maps_to=Pluck.VALUE, primary=True]>¶

sys_tags = <String [maps_to=Pluck.VALUE, primary=False]>¶

value = <String [maps_to=Pluck.VALUE, primary=False]>¶

Attachment¶

The AttachmentModel is typically used in context of another API, e.g. via a TableModel type, but can be used directly in a global context as well.

Reference

API¶

class aiosnow.models.attachment.model.AttachmentModel(*args, **kwargs)[source]¶

Attachment API Model

delete(selection: Union[aiosnow.query.condition.Condition, str]) → aiosnow.request.response.Response¶

Delete matching record

Parameters:	selection – Condition or ID
Returns:	Response

download(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str], dst_dir: str = '.') → aiosnow.models.attachment.file.FileHandler[source]¶

Download file

Parameters:	selection – Attachment selection dst_dir – Destination directory

Returns: FileWriter

get(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response¶

Buffered many

Fetch and store the entire result in memory.

Note: It’s recommended to use the stream method when dealing with a large number of records.

Keyword Arguments:
	selection – Aiosnow-compatible query limit (int) – Maximum number of records to return offset (int) – Starting record index
Returns:	Response

get_object_id(value: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str]) → str¶

Get object id by str or Condition

Immediately return if value is of str type.

Parameters:	value – Condition or str
Returns:	Object id

get_one(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → aiosnow.request.response.Response¶

Get one record

Parameters:	selection – aiosnow-compatible query
Returns:	Response

stream(selection: Union[aiosnow.query.selector.Selector, aiosnow.query.condition.Condition, str] = None, **kwargs) → AsyncGenerator[T_co, T_contra]¶

Stream-like async generator

Chunk size determines the number of records to fetch in one go. Setting a lower chunk size decreases memory usage, but increases the number of requests sent to the server.

Keyword Arguments:
	selection – aiosnow-compatible query limit (int) – Maximum number of records to return offset (int) – Starting record index page_size (int) – Number of records to fetch in one go
Yields:	Chunk of records

upload(table_name: str, record_sys_id: str, file_name: str, dir_name: str) → aiosnow.request.response.Response[source]¶

Upload file

Parameters:	table_name – Table name, e.g. incident record_sys_id – Sys id of the record to attach to file_name – Source file name dir_name – Source directory name

Returns: ClientResponse

Schema¶

class aiosnow.models.attachment.model.AttachmentModelSchema[source]¶

Attachment API model schema

average_image_color = <String [maps_to=Pluck.VALUE, primary=False]>¶

chunk_size_bytes = <String [maps_to=Pluck.VALUE, primary=False]>¶

compressed = <Boolean [maps_to=Pluck.VALUE, primary=False]>¶

content_type = <String [maps_to=Pluck.VALUE, primary=False]>¶

download_link = <String [maps_to=Pluck.VALUE, primary=False]>¶

file_name = <String [maps_to=Pluck.VALUE, primary=False]>¶

hash = <String [maps_to=Pluck.VALUE, primary=False]>¶

image_height = <String [maps_to=Pluck.VALUE, primary=False]>¶

image_width = <String [maps_to=Pluck.VALUE, primary=False]>¶

size_bytes = <Integer [maps_to=Pluck.VALUE, primary=False]>¶

size_compressed = <String [maps_to=Pluck.VALUE, primary=False]>¶

state = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_created_on = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

sys_id = <String [maps_to=Pluck.VALUE, primary=True]>¶

sys_mod_count = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_tags = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_updated_by = <String [maps_to=Pluck.VALUE, primary=False]>¶

sys_updated_on = <DateTime [maps_to=Pluck.VALUE, primary=False]>¶

table_name = <String [maps_to=Pluck.VALUE, primary=False]>¶

table_sys_id = <String [maps_to=Pluck.VALUE, primary=False]>¶

Aggregate¶

TBC

Importset¶

TBC

Fields¶

The aiosnow.fields module is a collection of typed field classes for:

Declaring Models

Building queries

Serializing data

Classes

String¶

class aiosnow.fields.string.StringQueryable¶

between(value1: str, value2: str) → aiosnow.query.condition.Condition¶

Example: short_description.between(“q”, “t”)

All records in which the first letter in the Short description field is “q,” “r,” “s,” or “t.”

contains(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.contains(“SAP”)

All records in which the characters “SAP” appear anywhere in the value for the Short description field.

ends_with(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.ends_with(“outage”)

All records in which the string “outage” appears at the end of the value for the Short description field.

equals(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.equals(“Network storage is unavailable”)

All records in which the Short description says nothing else but “Network storage is unavailable.”

greater_or_equals(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.greater_or_equals(“s”)

All records in which the string in the Short description field is one of the following:

the first letter is any letter between “s” and “z”
the exact value is “s”

less_or_equals(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.less_or_equals(“s”)

All records in which the string in the Short description field is one of the following:

the first letter is any letter between “a” and “s”
the exact value is “s”

not_contains(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.not_contains(“SAP”)

All records in which the characters “SAP” do not appear anywhere in the value for the Short description field.

not_equals(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.not_equals(“Network storage is unavailable”)

All records in which the value for the Short description field says anything but “Network storage is unavailable.”

starts_with(value: str) → aiosnow.query.condition.Condition¶

Example: short_description.starts_with(“SAP”)

All records in which the characters “SAP” appear at the beginning of the value for the Short description field.

class aiosnow.fields.string.String(*args, pluck: aiosnow.models._schema.helpers.pluck.Pluck = <Pluck.VALUE: 'value'>, is_primary: bool = False, **kwargs)¶

Integer¶

class aiosnow.fields.integer.IntegerQueryable¶

between(value1: int, value2: int) → aiosnow.query.condition.Condition¶

Example: impact.between([1, 3])

All records in which the Impact field has one of the following values: 1 - High 2 - Medium 3 - Low

equals(value: int) → aiosnow.query.condition.Condition¶

Example: reassignment_count.equals(0)

All records in which the Reassignment count is nothing else but 0.

greater_or_equals(value: int) → aiosnow.query.condition.Condition¶

Example: impact.greater_or_equals(2)

All records in which the Impact field has a value of 2 - Medium or 3 - Low.

greater_than(value: int) → aiosnow.query.condition.Condition¶

Example: impact.greater_than(2)

All records in which the Impact field has a value of 3 - Low

less_or_equals(value: int) → aiosnow.query.condition.Condition¶

Example: impact.less_or_equals(2)

All records in which the Impact field has a value of 1 - High or 2 - Medium.

less_than(value: int) → aiosnow.query.condition.Condition¶

Example: impact.less_than(2)

All records in which the Impact field has a value of 1 - High.

not_equals(value: int) → aiosnow.query.condition.Condition¶

Example: reassignment_count.not_equals(0)

All records in which the value for the Reassignment count is any number but 0.

class aiosnow.fields.integer.Integer(*, strict: bool = False, **kwargs)¶

DateTime¶

class aiosnow.fields.datetime.DateTimeQueryable¶

after(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.after(“2019-12-24 02:03:04”)

All records in which the value for the SLA due field is any date after the given date.

as_of(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.as_of(“2019-12-24 02:03:04”)

All records in which the date value for the SLA due field is one of the following:

today
any date after today

before(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.before(“2019-12-24 02:03:04”)

All records in which the value for the SLA due field is any date previous to the given date.

between(value1: str, value2: str) → aiosnow.query.condition.Condition¶

Example:

All records in which the value for the SLA due field is between the given dates

not_on(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.not_on(“2019-12-24 02:03:04”)

All records in which the value for the SLA due field is any other but the given date

on(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.on(“2019-12-24 02:03:04”)

All records in which the value for the SLA due field matches the given date

until(value: str) → aiosnow.query.condition.Condition¶

Example: sla_due.until(“2019-12-24 02:03:04”)

All records in which the value for the SLA due field is one of the following:

any date previous to today
today

class aiosnow.fields.datetime.DateTime(format: Optional[str] = None, **kwargs)¶

Boolean¶

class aiosnow.fields.boolean.BooleanQueryable¶

is_falsy() → aiosnow.query.condition.Condition¶

Example: active.is_falsy()

All records in which the Active field is False, empty, or NULL.

is_true() → aiosnow.query.condition.Condition¶

Example: active.is_true()

All records in which the Active field is True.

class aiosnow.fields.boolean.Boolean(*, truthy: Optional[Set[T]] = None, falsy: Optional[Set[T]] = None, **kwargs)¶

IntegerMap¶

Converts nested mapping to a named tuple.

Response content of:

{
   "impact":{
      "value":2,
      "display_value":"2 - Medium"
   }
}

Gets deserialized into:

Mapping(key=2, value="2 - Medium")

StringMap¶

Converts nested mapping to a named tuple.

Response content of:

{
   "impact":{
      "value":2,
      "display_value":"2 - Medium"
   }
}

Gets deserialized into:

Mapping(key="2", value="2 - Medium")

Condition¶

The Condition class is mainly for creating queries, see query usage for examples.

class aiosnow.query.condition.Condition(key: str, operator: str, value: Union[str, int, None])[source]¶

Bases: object

__and__(next_cond: aiosnow.query.condition.Condition) → aiosnow.query.condition.Condition[source]¶: Appends ^ Condition to chain

__or__(next_cond: aiosnow.query.condition.Condition) → aiosnow.query.condition.Condition[source]¶: Appends ^OR Condition to chain

__str__() → str[source]¶: Return str(self).

__xor__(next_cond: aiosnow.query.condition.Condition) → aiosnow.query.condition.Condition[source]¶: Appends ^NQ Condition to chain

serialize(cond: Optional[aiosnow.query.condition.Condition] = None) → str[source]¶

Serializes this Condition into a sysparm query condition

Returns: sysparm query string

serialize_registry() → str[source]¶

Condition string representation

Returns: sysparm query

Response¶

ServiceNow API operations performed by aiosnow returns an instance of Response.

API¶

class aiosnow.request.response.Response(*args, **kwargs)[source]¶

Aiosnow Response class

The Response object holds information about the ServiceNow HTTP response.

Subclass of aiohttp.ClientResponse, its base reference documentation can be found here: https://docs.aiohttp.org/en/latest/client_reference.html#aiohttp.ClientResponse

- data: Deserialized (ContentSchema) response content

- status: HTTP status code of response (int), e.g. 200

- reason: HTTP status reason of response (str), e.g. “OK”

- url: Request URL

load_document() → None[source]¶

Deserialize and set response content

Raises:	`RequestError` – If there was an error in the request-response content

Exceptions¶

exception aiosnow.exceptions.AiosnowException[source]¶: Bases: Exception

exception aiosnow.exceptions.AmbiguousClientAuthentication[source]¶

Bases: aiosnow.exceptions.AiosnowException

Multiple authentication methods provided

exception aiosnow.exceptions.ClientConnectionError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised when there was a problem connecting to the server

exception aiosnow.exceptions.ConfigurationError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Configuration error

exception aiosnow.exceptions.DeleteError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised if there was an error deleting a record

exception aiosnow.exceptions.DeserializationError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised when there was an issue with deserialization

exception aiosnow.exceptions.ErrorResponse(message: str, status: int)[source]¶

Bases: aiosnow.exceptions.RequestError

The server returned an error in the response

exception aiosnow.exceptions.IncompatiblePayloadField[source]¶

Bases: aiosnow.exceptions.AiosnowException

An incompatible field was found in the payload

exception aiosnow.exceptions.InvalidContentMethod[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised if the response content was incorrectly accessed

exception aiosnow.exceptions.InvalidFieldName[source]¶

Bases: aiosnow.exceptions.AiosnowException

Usually raised if an attempt is made to override a base member with a Field

exception aiosnow.exceptions.MissingClientAuthentication[source]¶

Bases: aiosnow.exceptions.AiosnowException

No authentication method provided

exception aiosnow.exceptions.NoItems[source]¶

Bases: aiosnow.exceptions.AiosnowException

The request yielded no results

exception aiosnow.exceptions.PayloadValidationError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Local payload validation against a Resource Schema failed

exception aiosnow.exceptions.RequestError(message: str, status: int)[source]¶

Bases: aiosnow.exceptions.AiosnowException

The application returned a parsable error in the response

exception aiosnow.exceptions.SchemaError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Generic exception raised on schema issues, e.g. integrity errors

exception aiosnow.exceptions.SelectError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised on query builder issues

exception aiosnow.exceptions.SerializationError[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised when there was an issue with serialization

exception aiosnow.exceptions.TooManyItems[source]¶

Bases: aiosnow.exceptions.AiosnowException

The request yielded too many results

exception aiosnow.exceptions.UnexpectedContentType[source]¶

Bases: aiosnow.exceptions.AiosnowException

Unexpected content type from server

exception aiosnow.exceptions.UnexpectedPayloadType[source]¶

Bases: aiosnow.exceptions.AiosnowException

Raised when the request payload was of an unexpected type

exception aiosnow.exceptions.UnexpectedResponseContent(message: str, status: int)[source]¶

Bases: aiosnow.exceptions.RequestError

Unexpected content in response from server

exception aiosnow.exceptions.UnexpectedValue[source]¶

Bases: aiosnow.exceptions.AiosnowException

Typically raised when a method receives unexpected input

exception aiosnow.exceptions.UnknownPayloadField[source]¶

Bases: aiosnow.exceptions.AiosnowException

A field unknown to the schema was found in the payload

Connect¶

To connect to ServiceNow, a Client must be created.

import aiosnow

client = aiosnow.Client(
    address="<instance-name>.service-now.com",
    basic_auth=("<username>", "<password>")
)

Model¶

The Model object provides an interface for reading and altering data in ServiceNow.

Usage

Declare¶

The Model Declaration is done by making one or more aiosnow.fields members of the Model.

Model¶

Assign fields directly on the BaseModel derived class.

from aiosnow import TableModel, fields

class IncidentModel(TableModel):
    sys_id = fields.String(is_primary=True)
    number = fields.String()
    impact = fields.IntegerMap()
    priority = fields.Integer()
    assignment_group = fields.StringMap()
    sys_created_on = fields.DateTime()
    made_sla = fields.Boolean()

ModelSchema¶

Assign fields in separate class, which is then subclassed.

from aiosnow import TableModel, fields

class IncidentModelSchema:
    sys_id = fields.String(is_primary=True)
    number = fields.String()
    impact = fields.IntegerMap()
    priority = fields.Integer()
    assignment_group = fields.StringMap()
    sys_created_on = fields.DateTime()
    made_sla = fields.Boolean()


class IncidentModel(TableModel, IncidentModelSchema):
    """Incident API Model"""

Use¶

A declared Model can be instantiated for reading and altering data in ServiceNow.

Example

async with Incident(client, table_name="incident") as inc:
    response = await inc.get_one(Incident.number == "INC0000001")
    print(response.data)

Query¶

The aiosnow.fields classes provides a set of type-specific methods for creating queries. Calling such a method returns a Condition with the string representation of a ServiceNow sysparm.

Conditions can be chained using bitwise operators for AND, OR and XOR.

Usage

Single¶

Single conditions are typically used when updating, deleting or fetching a specific item by a unique identifier.

Example

async with Incident(client, table_name="incident") as inc:
    response = await inc.update(
        Incident.number == "INC0000001",
        dict(
            description="Hello!"
        )
    )
    print("Updated description: {}".format(response["description"]))

List¶

When querying for a list of items, aiosnow.select() with chained conditions can be used.

Example

query = aiosnow.select(
    Incident.number.starts_with("INC123")
    &
    Incident.impact.less_than(3)
    ^
    Incident.assignment_group.name.equals("Hardware")
).order_desc(Incident.number)

async with Incident(client, table_name="incident") as inc:
    response = await inc.get(query, limit=10)
    print("The query yielded {} items.".format(len(response.data)))

Raw¶

Shows how a sysparm query string can be passed directly to a query method. See the Condition equivalent here.

async with Incident(client, table_name="incident") as inc:
    response = await inc.get(
        "numberSTARTSWITHINC123^impact<3^NQassignment_group.name=Hardware^ORDERBYDESCnumber"
    )
    print("The query yielded {} items.".format(len(response.data)))