Skip to content

Latest commit

 

History

History
541 lines (481 loc) · 25.2 KB

servicenow.itsm.api_info_module.rst

File metadata and controls

541 lines (481 loc) · 25.2 KB
Raw

servicenow.itsm.api_info module -- Manage ServiceNow GET requests

This module is part of the servicenow.itsm collection (version 2.6.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.api_info.

New in servicenow.itsm 2.0.0

Synopsis

Parameters

Parameter

Comments

api_path

string

added in servicenow.itsm 2.5.0

The path of the service which a record is to be created, updated or deleted from.

Mutually exclusive with resource.

Require one of resource or api_path.

columns

list / elements=string

List of fields/columns to return in the response.

Default: []

display_value

string

Return field display values true, actual values false, or both all.

Default value is set to false.

Choices:

  • "true"

  • "false" ← (default)

  • "all"

exclude_reference_link

boolean

true to exclude Table API links for reference fields.

The default is false.

Choices:

  • false ← (default)

  • true

instance

dictionary

ServiceNow instance information.

access_token

string

added in servicenow.itsm 2.3.0

Access token obtained via OAuth authentication.

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

api_path

string

added in servicenow.itsm 2.4.0

Change the API endpoint of SNOW instance from default 'api/now'.

Default: "api/now"

client_id

string

ID of the client application used for OAuth authentication.

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

If provided, it requires client_secret.

client_secret

string

Secret associated with client_id. Used for OAuth authentication.

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

If provided, it requires client_id.

custom_headers

dictionary

added in servicenow.itsm 2.4.0

A dictionary containing any extra headers which will be passed with the request.

grant_type

string

added in servicenow.itsm 1.1.0

Grant type used for OAuth authentication.

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

Since version 2.3.0, it no longer has a default value in the argument specifications.

If not set by any means, the default value (that is, password) will be set internally to preserve backwards compatibility.

Choices:

  • "password"

  • "refresh_token"

host

string / required

The ServiceNow host name.

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

password

string

Password used for authentication.

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

Required when using basic authentication or when grant_type=password.

refresh_token

string

added in servicenow.itsm 1.1.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.

timeout

float

Timeout in seconds for the connection with the ServiceNow instance.

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

username

string

Username used for authentication.

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

Required when using basic authentication or when grant_type=password.

validate_certs

boolean

added in servicenow.itsm 2.3.0

If host's certificate is validated or not.

Choices:

  • false

  • true ← (default)

no_count

boolean

Do not execute a select count(*) on table.

Default is set to false.

Choices:

  • false ← (default)

  • true

query_category

string

Name of the query category to use for queries.

query_no_domain

boolean

If set to true to access data across domains if authorized.

Default is set to false.

Choices:

  • false ← (default)

  • true

resource

string

The name of the table in which a record is to be created, updated or deleted from.

Mutually exclusive with api_path.

Require one of resource or api_path.

sys_id

string

Unique identifier of the record to retrieve.

sysparm_query

string

An encoded query string used to filter the results.

List of all possible operators and a guide on how to map them to form a query may be found at https://docs.servicenow.com/bundle/tokyo-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html. and https://developer.servicenow.com/dev.do#!/reference/api/tokyo/rest/c_TableAPI under 'sysparm_query'.

See Also

Examples

- name: Retrieve all records from table incident
  servicenow.itsm.api_info:
    resource: incident
  register: result

- name: Retrieve a record with specified sys_id from the resource incident
  servicenow.itsm.api_info:
    resource: incident
    sys_id: 471bfbc7a9fe198101e77a3e10e5d47f
  register: result

- name: Retrieve all incidents with properties specified in a query
  servicenow.itsm.api_info:
    resource: incident
    sysparm_query: numberSTARTSWITHINC^ORnumberSTARTSWITHABC^state!=7^stateBETWEEN1@4^short_descriptionISNOTEMPTY
  register: result

- name: Retrieve all incidents with properties specified in a query, filtered by a few other parameters
  servicenow.itsm.api_info:
    resource: incident
    sysparm_query: numberSTARTSWITHINC^ORnumberSTARTSWITHABC^state!=7^stateBETWEEN1@4^short_descriptionISNOTEMPTY
    display_value: "true"
    exclude_reference_link: true
    columns:
      - state
      - number
      - sys_id
    query_no_domain: true
    no_count: false
  register: result

- name: Retrieve all linux servers
  servicenow.itsm.api_info:
    api_path: api/now/cmdb/instance/cmdb_ci_linux_server

Return Values

The following are the fields unique to this module:

Key

Description

records

list / elements=string

A list of records from the specified table.

Returned: success

Sample: [{"active": "false", "activity_due": "", "additional_assignee_list": "", "approval": "not requested", "approval_history": "", "approval_set": "", "assigned_to": "5137153cc611227c000bbd1bd8cd2007", "assignment_group": "8a4dde73c6112278017a6a4baf547aa7", "business_duration": "1970-01-20 05:38:50", "business_service": "", "business_stc": "1661930", "calendar_duration": "1970-03-21 20:38:50", "calendar_stc": "6899930", "caller_id": "681ccaf9c0a8016400b98a06818d57c7", "category": "inquiry", "caused_by": "", "child_incidents": "", "close_code": "Solved (Work Around)", "close_notes": "Gave workaround", "closed_at": "2020-07-07 23:18:40", "closed_by": "9ee1b13dc6112271007f9d0efdb69cd0", "cmdb_ci": "", "comments": "", "comments_and_work_notes": "", "company": "31bea3d53790200044e0bfc8bcbe5dec", "contact_type": "phone", "contract": "", "correlation_display": "", "correlation_id": "", "delivery_plan": "", "delivery_task": "", "description": "Noticing today that any time I send an email with an attachment, it takes at least 20 seconds to send.", "due_date": "", "escalation": "0", "expected_start": "", "follow_up": "", "group_list": "", "hold_reason": "", "impact": "1", "incident_state": "7", "knowledge": "false", "location": "", "made_sla": "false", "notify": "1", "number": "INC0000013", "opened_at": "2020-07-06 23:15:58", "opened_by": "9ee1b13dc6112271007f9d0efdb69cd0", "order": "", "parent": "", "parent_incident": "", "priority": "1", "problem_id": "", "reassignment_count": "2", "reopen_count": "", "reopened_by": "", "reopened_time": "", "resolved_at": "2020-09-24 19:54:48", "resolved_by": "6816f79cc0a8016401c5a33be04be441", "rfc": "", "route_reason": "", "service_offering": "", "severity": "3", "short_description": "EMAIL is slow when an attachment is involved", "sla_due": "", "state": "7", "subcategory": "", "sys_class_name": "incident", "sys_created_by": "don.goodliffe", "sys_created_on": "2020-07-07 23:18:07", "sys_domain": "global", "sys_domain_path": "/", "sys_id": "46cebb88a9fe198101aee93734f9768b", "sys_mod_count": "5", "sys_tags": "", "sys_updated_by": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER", "sys_updated_on": "2020-09-24 19:54:48", "task_effective_number": "INC0000013", "time_worked": "", "universal_request": "", "upon_approval": "", "upon_reject": "", "urgency": "1", "user_input": "", "watch_list": "", "work_end": "", "work_notes": "", "work_notes_list": "", "work_start": ""}]

Authors

  • Tjaž Eržen (@tjazsch)

Collection links