You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

servicenow.servicenow.snow_record module – Manage records in ServiceNow

Note

This module is part of the servicenow.servicenow collection (version 1.0.6).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install servicenow.servicenow.

To use it in a playbook, specify: servicenow.servicenow.snow_record.

Synopsis
Requirements
Parameters
Examples
Return Values

Synopsis 

Creates, deletes and updates a single record in ServiceNow.

Requirements 

The below requirements are needed on the host that executes this module.

python pysnow (pysnow)
python requests (requests)

Parameters 

Parameter	Comments
attachment string	Attach a file to the record.
auth string	The method used to authenticate with the Service Now instance. Basic authentication uses user name and password. OAuth authentication uses a client id and secret in addition to Basic authentication. Token authentication uses a bearer token in addition to OAuth authentication. OpenID Connect authentication, an extension of OAuth 2.0, uses a provider, like Okta, to obtain a bearer token. If the vaule is not specified in the task, the value of environment variable `SN_AUTH` will be used instead. Choices: basic ← (default) oauth token openid
client_id string	Client ID generated by ServiceNow. Required when using OAuth or OpenID authentication, unless token is specified. If the value is not specified in the task, the value of environment variable `SN_CLIENTID` will be used instead.
client_secret string	Client Secret associated with client id. Required when using OAuth or OpenID authentication, unless token is specified. If the value is not specified in the task, the value of environment variable `SN_CLIENTSECRET` will be used instead.
data dictionary	key, value pairs of data to load into the record. See Examples. Required for `state:present`.
display_value boolean	sysparm_display_value Choices: no ← (default) yes
exclude_reference_link boolean	sysparm_exclude_reference_link Choices: no ← (default) yes
host string	The ServiceNow hostname. This value is FQDN for ServiceNow host. If the value is not specified in the task, the value of environment variable `SN_HOST` will be used instead. Mutually exclusive with `instance`.
instance string	The ServiceNow instance name, without the domain, service-now.com. If the value is not specified in the task, the value of environment variable `SN_INSTANCE` will be used instead.
log_level string	Set the logging level of the module Choices: debug info normal ← (default)
lookup_field string	Changes the field that `number` uses to find records. Default: “number”
number string	Record number to update. Required for `state:absent`.
openid dictionary	If the result of a previous SNOW method, using OpenID, was registered, supply the `openid` key, from the result. The `openid` key contains a dictionary with the bearer token, which, if still valid, can be reused. If the bearer token is no longer valid, the dictionary includes all of the previously supplied `openid_` fields needed to make a new token request. Any other credentials previously supplied, must be provided again.
openid_issuer string	The URL for your organization’s OpenID Connect provider. Okta, an OpenID provider, supports Single Sign-On with a url like ‘https://yourorg.oktapreview.com/oauth2’. Okta supports application-level authentication using a url like ‘https://yourorg.oktapreview.com/oauth2/TH151s50m3L0ngSTr1NG’. If the value is not specified in the task, the value of environment variable `OPENID_ISSUER` will be used instead.
openid_scope list / elements=string	A list of scopes to be included in the access token. Supported scopes for this application are address, email, groups, openid, phone, profile, of which, openid must be one. If the value is not specified in the task, the value of environment variable `OPENID_SCOPE` will be used instead. Default: [“openid”]
password string	Password for username. Required whether using Basic, OAuth or OpenID authentication. If the value is not specified in the task, the value of environment variable `SN_PASSWORD` will be used instead.
raise_on_empty boolean	If set to false, will not cause a SNOW method to raise an exception should it return no records. This is particurlarly useful in snow_record_find, when not sure if any record exists. Choices: no yes ← (default)
state string / required	If `present` is supplied with a `number` argument, the module will attempt to update the record with the supplied data. If no such record exists, a new one will be created. `absent` will delete a record. Choices: present absent
suppress_pagination_header boolean	sysparm_suppress_pagination_header Choices: no ← (default) yes
table string	Table to query for records. Default: “incident”
token string	Bearer token associated with client id and secret. Can be used in place of client id and secret for OpenID authentication. If the value is not specified in the task, the value of environment variable `SN_TOKEN` will be used instead.
username string	Name of user for connection to ServiceNow. Required whether using Basic, OAuth or OpenID authentication. If the value is not specified in the task, the value of environment variable `SN_USERNAME` will be used instead.

Examples 

- name: Grab a user record
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8bcbe5df1
    table: sys_user
    lookup_field: sys_id

- name: Grab a user record, explicitly using basic authentication and suppress exceptions if not found
  servicenow.servicenow.snow_record:
    auth: basic
    raise_on_empty: False
    username: ansible_test
    password: my_password
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8bcbe5df1
    table: sys_user
    lookup_field: sys_id

- name: Grab a user record using OAuth
  servicenow.servicenow.snow_record:
    auth: oauth
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8bcbe5df1
    table: sys_user
    lookup_field: sys_id

- name: Grab a user record using a bearer token
  servicenow.servicenow.snow_record:
    auth: token
    username: ansible_test
    password: my_password
    token: "y0urHorrend0u51yL0ngT0kenG0esH3r3..."
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8bcbe5df1
    table: sys_user
    lookup_field: sys_id

- name: Grab a user record using OpenID
  servicenow.servicenow.snow_record:
    auth: openid
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    openid_issuer: "https://yourorg.oktapreview.com/TH151s50meL0ngSTr1NG"
    openid_scope: "openid email"
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8bcbe5df1
    table: sys_user
    lookup_field: sys_id
  register: response

- name: Grab another user record using previous OpenID response
  servicenow.servicenow.snow_record:
    auth: openid
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    openid: "{{ response['openid'] }}"
    instance: dev99999
    state: present
    number: 62826bf03710200044e0bfc8deadbeef
    table: sys_user
    lookup_field: sys_id
  register: response

- name: Create an incident
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    instance: dev99999
    state: present
    data:
      short_description: "This is a test incident opened by Ansible"
      severity: 3
      priority: 2
  register: new_incident

- name: Create an incident using host instead of instance
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    host: dev99999.mycustom.domain.com
    state: present
    data:
      short_description: "This is a test incident opened by Ansible"
      priority: 2

- name: Delete the record we just made
  servicenow.servicenow.snow_record:
    username: admin
    password: xxxxxxx
    instance: dev99999
    state: absent
    number: "{{new_incident['record']['number']}}"

- name: Delete a non-existant record
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    instance: dev99999
    state: absent
    number: 9872354
  failed_when: false

- name: Update an incident
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    instance: dev99999
    state: present
    number: INC0000055
    data:
      work_notes : "Been working all day on this thing."

- name: Attach a file to an incident
  servicenow.servicenow.snow_record:
    username: ansible_test
    password: my_password
    instance: dev99999
    state: present
    number: INC0000055
    attachment: README.md
  tags: attach

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
attached_file dictionary	Details of the file that was attached via `attachment` Returned: when supported
record dictionary	Record data from Service Now Returned: when supported

Authors

Tim Rightnour (@garbled1)

Collection links

Issue Tracker Repository (Sources)

servicenow.servicenow.snow_record module – Manage records in ServiceNow

Synopsis

Requirements

Parameters

Examples

Return Values