This post was originally published on the
Ansible blog.
It has been almost half a year since the XLAB Steampunk and Red Hat Ansible Automation Platform teams developed the first version of the Red Hat Ansible Certified Content Collection for ServiceNow IT Service Management (ITSM). You may also want to read our ServiceNow introduction if you are not familiar with this already. So, let’s take a look at what is new since the last release.
We will skip most of the technical details in this post because, let us face it, talking about interactions between API pagination and filtering is not something many people enjoy. Instead, we will focus on the new things users can do using the current 1.2.0 version of this collection.
Attachment management
ServiceNow records (incidents, problems, change requests, etc.) may contain attachments, but the first version of the ServiceNow Collection did not expose this capability to Ansible Automation Platform users. We changed this in version 1.2.0 when we added the attachments parameter to all non-info modules.
Ansible users can now upload error logs and other artifacts when creating new incidents and other ServiceNow records. They can also add them later to existing ServiceNow records. For example, users might want to attach root cause analysis results when changing the state of the problem.
In the simplest case, attaching files to a record means listing them under the attachments parameter. The following example contains one such playbook task:
- name: Attach a file to a problem
servicenow.itsm.problem:
number: INC0123456
attachments:
- path: /path/to/screenshot.png
- path: /path/to/log.txt
We have also checked to ensure that change detection still works. If a file with a matching name is not yet attached to the record, we upload it. If the attachment already exists in ServiceNow, we only update it if the local and remote files differ.
It is also possible to rename the file during the upload by specifying the name of the remote file. And in cases where Ansible cannot detect the file type from the extension, we can also supply that information manually:
- name: Attach a file to a problem
servicenow.itsm.problem:
number: INC0123456
attachments:
- path: /path/to/error.log
type: text/plain
name: specific-error.log
Filtering records
Until now, info modules from this ServiceNow collection operated in an all-or-nothing fashion. For example, users could retrieve a single record or list all records. And so, in this 1.2.0 release, we have made things more flexible.
All info modules gained a new query parameter that allows users to retrieve a subset of records. Users write the query expression using a domain-specific language (DSL) that exposes advanced filtering capabilities in a user-friendly way. The query DSL supports all operators listed in the ServiceNow documentation.
For example, the next task will retrieve all incidents that contain SAP in their short description:
- servicenow.itsm.incident_info:
query:
- short_description: LIKE SAP
It is also possible to combine multiple conditions. The following sample shows how users could fetch only SAP incidents that the admins are already working on:
- servicenow.itsm.incident_info:
query:
- short_description: LIKE SAP
state: = in_progress
Query DSL also supports combining multiple filters into one. So, for example, if users would like to retrieve resolved problems reported by two different people, we can do it in one task:
- servicenow.itsm.incident_info:
query:
- caller: = person.one
state: = resolved
- caller: = person.two
state: = resolved
Constructed inventory features
The first version of the inventory plugin offered quite a few options for filtering and grouping, but there were two areas it did not address:
- It did not allow us to construct custom variables from the data in the Configuration Management Database (CMDB).
- Its configuration options were slightly different from those that the majority of other inventory plugins use.
So we adopted the standard options while adding one ServiceNow-specific additional option. This additional option allows Ansible users to filter CMDB items using the same query DSL we discussed previously.
This is a relatively short example that demonstrates most of the options would look like:
---
plugin: servicenow.itsm.now
table: cmdb_ci_ec2_instance
columns:
- ip_address
- name
- vm_inst_id
query:
- operational_status: = 1
fqdn: ISNOTEMPTY
manufacturer: STARTSWITH Cisco
keyed_groups:
- key: environment
prefix: env_
separator: ""
groups:
development: "'devel' in environment"
compose:
ansible_host: fqdn
For more information about available options, you can consult the constructed reference documentation.
Updating multiple CMDB items at once
The newly introduced batch module does not add new capabilities. Users can update as many CMDB items as they want using the existing servicenow.itsm.configuration_item module and Ansible looping. Considering that looping in Ansible can be slower and that each loop iteration needs to establish a new ServiceNow connection, we made some optimizations.
For example, this is the “old” way of updating a specific configuration item:
---
- name: Update a single CMDB item
hosts: localhost
gather_facts: false
vars:
dataset:
- id: i-0af01c0123456789a
address_ipv4: 1.2.3.4
mac: aa:bb:cc:dd:ee:ff
tasks:
- name: Retrieve specific CMDB item
servicenow.itsm.configuration_item_info:
sys_class_name: cmdb_ci_ec2_instance
query:
- vm_inst_id: = {{ dataset.0.id }}
register: vm
- name: Make sure we only grabbed one instance
ansible.builtin.assert:
that:
- vm.records | length == 1
- name: Update CMDB item with fresh data
servicenow.itsm.configuration_item:
sys_class_name: cmdb_ci_ec2_instance
sys_id: "{{ vm.records.0.sys_id }}"
ip_address: "{{ dataset.0.address_ipv4 }}"
mac_address: "{{ dataset.0.mac }}"
With the new batch module, users can write this using a single task:
---
- name: Update a single CMDB item
hosts: localhost
gather_facts: false
vars:
dataset:
- id: i-0af01c0123456789a
address_ipv4: 1.2.3.4
mac: aa:bb:cc:dd:ee:ff
tasks:
- name: Update data in CMDB
servicenow.itsm.configuration_item_batch:
sys_class_name: cmdb_ci_ec2_instance
id_column_set: vm_inst_id
dataset: "{{ dataset }}"
map:
vm_inst_id: id
ip_address: address_ipv4
mac_address: mac
Updating multiple items using the “old” method will most likely need some
clever tricks like looping over the include_tasks invocation. However, users
do not require such tricks when using the batch module. They can add as many
items they need to the dataset and call it a day.
Combining things for the win
Filtering support in info modules is useful on its own, and working with transformations in the batch module can be surprisingly effective. But this is not the primary reason why we added those individual features. The real power is realized when we start combining them.
For example, let us have a look at the following playbook that will refresh information about the AWS EC2 instances stored in the ServiceNow CMDB that do not have IP address stored:
---
- name: Update CMDB data
hosts: localhost
gather_facts: false
tasks:
- name: Get all EC2 instances with no IP address
servicenow.itsm.configuration_item_info:
sys_class_name: cmdb_ci_ec2_instance
query:
- ip_address: ISEMPTY
register: snow_instances
- name: Fetch information about instances from AWS
amazon.aws.ec2_instance_info:
instance_ids: "{{ snow_instances | map(attribute='vm_inst_id') | list }}"
register: ec2_instances
- name: Update CMDB with data from AWS
servicenow.itsm.configuration_item_batch:
sys_class_name: cmdb_ci_ec2_instance
id_column_set: vm_inst_id
dataset: "{{ ec2_instances.instances }}"
map:
vm_inst_id: instance_id
ip_address: public_ip_adress
name: tags.Name
And so, now you are aware of the newest capabilities in this collection. Give them a try. You can download this new certified collection in the automation hub if you subscribe to Ansible Automation Platform.
Want to learn more? We presented these features and explained how you can drive your automation by integrating Ansible Automation Platform into your existing ServiceNow environment in a webinar we co-hosted with Devoteam. If you missed it, you can watch it on demand.
