Skip to content

Latest commit

 

History

History
1037 lines (906 loc) · 37.3 KB

servicenow.itsm.now_inventory.rst

File metadata and controls

1037 lines (906 loc) · 37.3 KB
Raw

servicenow.itsm.now inventory -- Inventory source for ServiceNow table records.

This inventory plugin is part of the servicenow.itsm collection (version 2.7.0).

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.itsm.

To use it in a playbook, specify: servicenow.itsm.now.

New in servicenow.itsm 1.0.0

Synopsis

  • Builds inventory from ServiceNow table records.
  • Requires a configuration file ending in now.yml or now.yaml.
  • The plugin sets host variables denoted by columns.
  • For variables with dots (for example 'location.country') use lookup('ansible.builtin.vars', 'variable.name') notation. See the example section for more details. This feature is added in version 2.1.0.

Parameters

Parameter

Comments

aggregation

boolean

added in servicenow.itsm 2.7.0

Enable multiple variable values aggregations.

Choices:

  • false ← (default)

  • true

cache

boolean

Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.

Choices:

  • false ← (default)

  • true

Configuration:

  • INI entry

    [inventory]
cache = false

  • Environment variable: ANSIBLE_INVENTORY_CACHE

cache_connection

string

Cache connection data or path, read cache plugin documentation for specifics.

Configuration:

  • INI entries

    [defaults]
fact_caching_connection = VALUE
    [inventory]
cache_connection = VALUE

  • Environment variable: ANSIBLE_CACHE_PLUGIN_CONNECTION

  • Environment variable: ANSIBLE_INVENTORY_CACHE_CONNECTION

cache_plugin

string

Cache plugin to use for the inventory's source data.

Default: "memory"

Configuration:

  • INI entries

    [defaults]
fact_caching = memory
    [inventory]
cache_plugin = memory

  • Environment variable: ANSIBLE_CACHE_PLUGIN

  • Environment variable: ANSIBLE_INVENTORY_CACHE_PLUGIN

cache_prefix

string

Prefix to use for cache plugin files/tables

Default: "ansible_inventory_"

Configuration:

  • INI entries

    [defaults]
fact_caching_prefix = ansible_inventory_
    [inventory]
cache_prefix = ansible_inventory_

  • Environment variable: ANSIBLE_CACHE_PLUGIN_PREFIX

  • Environment variable: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX

cache_timeout

integer

Cache duration in seconds

Default: 3600

Configuration:

  • INI entries

    [defaults]
fact_caching_timeout = 3600
    [inventory]
cache_timeout = 3600

  • Environment variable: ANSIBLE_CACHE_PLUGIN_TIMEOUT

  • Environment variable: ANSIBLE_INVENTORY_CACHE_TIMEOUT

columns

list / elements=string

List of table columns to be included as hostvars.

Default: ["name", "host_name", "fqdn", "ip_address"]

compose

dictionary

Create vars from jinja2 expressions.

Default: {}

enhanced

boolean

added in servicenow.itsm 1.3.0

Enable enhanced inventory which provides relationship information from CMDB.

Choices:

  • false ← (default)

  • true

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

Default: {}

instance

dictionary

ServiceNow instance information.

Default: {}

client_id

string

ID of the client application used for OAuth authentication.

If provided, it requires client_secret.

Configuration:

  • Environment variable: SN_CLIENT_ID

client_secret

string

Secret associated with client_id. Used for OAuth authentication.

If provided, it requires client_id.

Configuration:

  • Environment variable: SN_CLIENT_SECRET

grant_type

string

added in servicenow.itsm 1.4.0

Grant type used for OAuth authentication.

If not set, the value of the SN_GRANT_TYPE environment variable will be used.

Choices:

  • "password" ← (default)

  • "refresh_token"

Configuration:

  • Environment variable: SN_GRANT_TYPE

host

string / required

The ServiceNow host name.

Configuration:

  • Environment variable: SN_HOST

password

string / required

Password used for authentication.

Configuration:

  • Environment variable: SN_PASSWORD

refresh_token

string

added in servicenow.itsm 1.4.0

Refresh token used for OAuth authentication.

If not set, the value of the SN_REFRESH_TOKEN environment variable will be used.

Required when grant_type=refresh_token.

Configuration:

  • Environment variable: SN_REFRESH_TOKEN

timeout

float

Timeout in seconds for the connection with the ServiceNow instance.

Configuration:

  • Environment variable: SN_TIMEOUT

username

string / required

Username used for authentication.

Configuration:

  • Environment variable: SN_USERNAME

inventory_hostname_source

string

The column to use for inventory hostnames.

Default: "name"

keyed_groups

list / elements=dictionary

Add hosts to group based on the values of a variable.

Default: []

default_value

string

added in ansible-core 2.12

The default value when the host variable's value is an empty string.

This option is mutually exclusive with keyed_groups[].trailing_separator.

key

string

The key from input dictionary used to generate groups

parent_group

string

parent group for keyed group

prefix

string

A keyed group name will start with this prefix

Default: ""

separator

string

separator used to build the keyed group name

Default: "_"

trailing_separator

boolean

added in ansible-core 2.12

Set this option to False to omit the keyed_groups[].separator after the host variable when the value is an empty string.

This option is mutually exclusive with keyed_groups[].default_value.

Choices:

  • false

  • true ← (default)

leading_separator

boolean

added in ansible-core 2.11

Use in conjunction with keyed_groups.

By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.

This is because the default prefix is "" and the default separator is "_".

Set this option to False to omit the leading underscore (or other separator) if no prefix is given.

If the group name is derived from a mapping the separator is still used to concatenate the items.

To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.

Choices:

  • false

  • true ← (default)

plugin

string / required

The name of the ServiceNow Inventory Plugin.

This should always be servicenow.itsm.now.

Choices:

  • "servicenow.itsm.now"

query

list / elements=dictionary

Provides a set of operators for use with filters, condition builders, and encoded queries.

The data type of a field determines what operators are available for it. Refer to the ServiceNow Available Filters Queries documentation at https://docs.servicenow.com/bundle/tokyo-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html.

Mutually exclusive with sysparm_query.

strict

boolean

If yes make invalid entries a fatal error, otherwise skip and continue.

Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

Choices:

  • false ← (default)

  • true

sysparm_limit

integer

added in servicenow.itsm 2.5.0

Control the maximum number of records returned in a single query.

Default: 1000

sysparm_query

string

added in servicenow.itsm 2.0.0

An encoded query string used to filter the results as an alternative to query.

Refer to the ServiceNow Available Filters Queries documentation at https://docs.servicenow.com/bundle/tokyo-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html.

If not set, the value of the SN_SYSPARM_QUERY environment, if specified.

Mutually exclusive with query.

Configuration:

  • Environment variable: SN_SYSPARM_QUERY

table

string

The ServiceNow table to use as the inventory source.

Default: "cmdb_ci_server"

use_extra_vars

boolean

added in ansible-core 2.11

Merge extra vars into the available variables for composition (highest precedence).

Choices:

  • false ← (default)

  • true

Configuration:

  • INI entry

    [inventory_plugins]
use_extra_vars = false

  • Environment variable: ANSIBLE_INVENTORY_USE_EXTRA_VARS

Notes

  • Query feature and constructed groups were added in version 1.2.0.
  • Caching feature added in version 2.5.0.

Examples

# A trivial example that creates a host from every record of the
# ServiceNow cmdb_ci_server table. The ip_address column is used for
# for ansible host, and server name for inventory hostname.
# No groups will be created - all the resulting hosts are ungrouped.
plugin: servicenow.itsm.now

# `ansible-inventory -i inventory.now.yaml --graph` output:
# @all:
#  |--@ungrouped:
#  |  |--DatabaseServer1
#  |  |--DatabaseServer2
#  |  |--INSIGHT-NY-03
#  |  |--MailServerUS
#  |  |--VMWARE-SD-04


# Group hosts automatically, according to values of the manufacturer column.
plugin: servicenow.itsm.now
keyed_groups:
  - key: manufacturer
    separator: ""

# `ansible-inventory -i inventory.now.yaml --graph` output:
# @all:
#  |--@Dell Inc.:
#  |  |--DatabaseServer1
#  |  |--DatabaseServer2
#  |  |--INSIGHT-NY-03
#  |--@Lenovo:
#  |  |--FileServerFloor1
#  |  |--FileServerFloor2
#  |--@ungrouped:

# Group hosts automatically, according to values of the os column. Filtering ensures
# that we only see selected operating systems.
plugin: servicenow.itsm.now
query:
  - os: = Linux Red Hat
  - os: = Windows XP
keyed_groups:
  - key: os
    prefix: os

# `ansible-inventory -i inventory.now.yaml --graph` output:
#  |--@os_Linux_Red_Hat:
#  |  |--DatabaseServer1
#  |  |--DatabaseServer2
#  |--@os_Windows_XP:
#  |  |--FileServerFloor1
#  |  |--FileServerFloor2
#  |  |--INSIGHT-NY-03
#  |--@ungrouped:

# Group hosts into named according to the specified criteria. Here, we created a group
# of non-Windows production servers.
plugin: servicenow.itsm.now
groups:
  non_windows_prod_servers: >-
    classification == "Production" and
    os not in ("Windows XP", "Windows 2000", "Windows 2000 Server")

# `ansible-inventory -i inventory.now.yaml --graph` output:
# @all:
#  |--@non_windows_prod_servers:
#  |  |--DatabaseServer2
#  |  |--PS LinuxApp01
#  |  |--PS LinuxApp02
#  |  |--lnux100
#  |  |--lnux101

# Add composed variables to hosts. In the following example, we created a cost variable
# that contains an amount and a currency, and set the ansible_host variable to the fqdn
# listed in the record.
plugin: servicenow.itsm.now
inventory_hostname_source: asset_tag
columns:
  - name
  - classification
  - cpu_type
compose:
    cost: cost ~ " " ~ cost_cc
    ansible_host: fqdn

# `ansible-inventory -i inventory.now.yaml --graph --vars` output:
# @all:
#  |--@ungrouped:
#  |  |--P1000019
#  |  |  |--{ansible_host = my.server.com}
#  |  |  |--{classification = Production}
#  |  |  |--{cost = 100 USD}
#  |  |  |--{cpu_type = Intel}
#  |  |  |--{name = SAP-SD-02}

# Similar to the example above, but use enhanced groups with relationship information instead.
plugin: servicenow.itsm.now
enhanced: true
strict: true
inventory_hostname_source: asset_tag
columns:
  - name
  - classification
  - cpu_type
  - cost
compose:
    cost: cost ~ " " ~ cost_cc
    ansible_host: fqdn

# `ansible-inventory -i inventory.now.yaml --graph --vars` output:
# @all:
# |--@Blackberry_Depends_on:
# |  |--P1000201
# |  |  |--{ansible_host = my.server.com}
# |  |  |--{classification = Production}
# |  |  |--{cost = 2,160 USD}
# |  |  |--{cpu_type = Intel}
# |  |  |--{name = INSIGHT-NY-03}

plugin: servicenow.itsm.now
enhanced: false
strict: true
table: cmdb_ci_server
columns:
  - name
  - ip_address
  - location
  - location.country
compose:
  street: location
  country: lookup('ansible.builtin.vars', 'location.country')

# `ansible-inventory -i inventory.now.yaml --graph --vars` output:
# @all:
# |--@ungrouped:
# |  |--OWA-SD-01
# |  |  |--{country = Italy}
# |  |  |--{ip_address = }
# |  |  |--{location = Via Nomentana 56, Rome}
# |  |  |--{location.country = Italy}
# |  |  |--{name = OWA-SD-01}
# |  |  |--{street = Via Nomentana 56, Rome}

# Use a javascript function defined in ServiceNow under "Script Includes",
# which returns a list of the sys_ids that match a certain criteria
# Example of script:
# function MyFunction(key_entry) {
#   var cis = [];
#   var key_value = new GlideRecord("cmdb_key_value");
#   key_value.addEncodedQuery("keyLIKE"+key_entry);
#   key_value.query();
#   while (key_value.next()) {
#     cis.push(key_value.configuration_item + '');
#   }
#   return cis;
# }
# Other examples in https://docs.servicenow.com/bundle/tokyo-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html
plugin: servicenow.itsm.now
table: cmdb_ci_server
query:
  - sys_id: 'IN javascript:MyFunction("xyz")'
keyed_groups:
  - key: os
    prefix: os

# `ansible-inventory -i inventory.now.yaml --graph` output:
# @all:
# |--@ungrouped:
# |--@os_linux:
# |  |--node2
# |  |--node3
# |  |--node1

Authors

  • Manca Bizjak (@mancabizjak)
  • Miha Dolinar (@mdolin)
  • Tadej Borovsak (@tadeboro)
  • Uros Pascinski (@uscinski)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

Collection links