servicenow.servicenow.snow_record – Manage records in ServiceNow
Note
This plugin 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
- 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 | Choices/Defaults | 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. |
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 |
exclude_reference_link boolean |
| sysparm_exclude_reference_link |
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 |
lookup_field string | Default: "number" | Changes the field that number uses to find records. |
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 | Default: ["openid"] | 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. |
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. |
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. |
suppress_pagination_header boolean |
| sysparm_suppress_pagination_header |
table string | Default: "incident" | Table to query for records. |
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 | Returned | Description |
---|---|---|
attached_file dictionary | when supported | Details of the file that was attached via attachment
|
record dictionary | when supported | Record data from Service Now |
Authors
- Tim Rightnour (@garbled1)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/servicenow/servicenow/snow_record_module.html