# snow_record – Manage records in ServiceNow

New in version 2.5.

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## 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)

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
attachment string |  | Attach a file to the record.
client_id string added in 2.9 |  | Client ID generated by ServiceNow.
client_secret string added in 2.9 |  | Client Secret associated with client id.
data dictionary |  | key, value pairs of data to load into the record. See Examples. Required for `state:present`.
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. Environment variable support added in Ansible 2.9.
lookup_field string | Default: "number" | Changes the field that `number` uses to find records.
number string |  | Record number to update. Required for `state:absent`.
password string |  | Password for username. Required whether using Basic or OAuth authentication. If the value is not specified in the task, the value of environment variable `SN_PASSWORD` will be used instead. Environment variable support added in Ansible 2.9.

state
string / required

Choices:
- present
- absent

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.

table string | Default: "incident" | Table to query for records.
username string |  | Name of user for connection to ServiceNow. Required whether using Basic or OAuth authentication. If the value is not specified in the task, the value of environment variable `SN_USERNAME` will be used instead. Environment variable support added in Ansible 2.9.

## Examples

    - name: Grab a user record
      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 using OAuth
      snow_record:
        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: Create an incident
      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: Delete the record we just made
      snow_record:
        username: admin
        password: xxxxxxx
        instance: dev99999
        state: absent
        number: "{{new_incident['record']['number']}}"

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

    - name: Update an incident
      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
      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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Tim Rightnour (@garbled1)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.