servicenow.servicenow.snow_record_find module – Search for multiple records from 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. You need further requirements to be able to use this module, see Requirements for details.

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

Synopsis

  • Gets multiple records from a specified table from ServiceNow based on a query dictionary.

Requirements

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

  • python pysnow (pysnow)

  • python requests (requests)

Parameters

Parameter

Comments

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.

display_value

boolean

sysparm_display_value

Choices:

  • false ← (default)

  • true

boolean

sysparm_exclude_reference_link

Choices:

  • false ← (default)

  • true

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)

max_records

integer

Maximum number of records to return.

Default: 20

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"]

order_by

string

Field to sort the results on.

Can prefix with “-” or “+” to change descending or ascending sort order.

Default: "-created_on"

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.

query

dictionary / required

Dict to query for records.

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:

  • false

  • true ← (default)

return_fields

list / elements=string

Fields of the record to return in the json.

By default, all fields will be returned.

suppress_pagination_header

boolean

sysparm_suppress_pagination_header

Choices:

  • false ← (default)

  • true

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: Search for incident assigned to group, return specific fields
  servicenow.servicenow.snow_record_find:
    username: ansible_test
    password: my_password
    instance: dev99999
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Search for incident assigned to group, explicitly using basic authentication, return specific fields, and suppress exception if not found
  servicenow.servicenow.snow_record_find:
    auth: basic
    username: ansible_test
    password: my_password
    instance: dev99999
    raise_on_empty: False
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Search for incident using host instead of instance
  servicenow.servicenow.snow_record_find:
    username: ansible_test
    password: my_password
    host: dev99999.mycustom.domain.com
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Using OAuth, search for incident assigned to group, return specific fields
  servicenow.servicenow.snow_record_find:
    auth: oauth
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    instance: dev99999
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Using a bearer token, search for incident assigned to group, return specific fields
  servicenow.servicenow.snow_record_find:
    auth: token
    username: ansible_test
    password: my_password
    token: "y0urHorrend0u51yL0ngT0kenG0esH3r3..."
    instance: dev99999
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Using OpenID, search for incident assigned to group, return specific fields
  servicenow.servicenow.snow_record_find:
    auth: openid
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    openid_issuer: "https://yourorg.oktapreview.com/oauth2/TH151s50M3L0ngStr1NG"
    openid_scope: "openid email"
    instance: dev99999
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at
  register: response

- name: Using previous OpenID response, search for incident assigned to group, return specific fields
  servicenow.servicenow.snow_record_find:
    auth: openid
    username: ansible_test
    password: my_password
    client_id: "1234567890abcdef1234567890abcdef"
    client_secret: "Password1!"
    openid: "{{ response['openid'] }}"
    instance: dev99999
    table: incident
    query:
      assignment_group: d625dccec0a8016700a222a0f7900d06
    return_fields:
      - number
      - opened_at

- name: Find open standard changes with my template
  servicenow.servicenow.snow_record_find:
    username: ansible_test
    password: my_password
    instance: dev99999
    table: change_request
    query:
      AND:
        equals:
          active: "True"
          type: "standard"
          u_change_stage: "80"
        contains:
          u_template: "MY-Template"
    return_fields:
      - sys_id
      - number
      - sys_created_on
      - sys_updated_on
      - u_template
      - active
      - type
      - u_change_stage
      - sys_created_by
      - description
      - short_description

Return Values

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

Key

Description

record

dictionary

The full contents of the matching ServiceNow records as a list of records.

Returned: always

Authors

  • Tim Rightnour (@garbled1)