The ServiceNow reporting integration module ships with a servicenow report processor that can send one of two kinds of information back to ServiceNow. It can send events that are handled by ServiceNow to create Alerts and Incidents, or you can create Incidents directly.

Setup

First, install the puppetlabs-servicenow_reporting_integration module on your Puppet server.

The module can send events or it can create incidents, but attempting to do both will cause a catalog compilation failure. Please choose which of the two you would like to do and only classify your Puppet server nodes with one of those classes, either event management, or incident management.

Sending Events

To send events, classify your Puppet servers with the servicenow_reporting_integration::event_management class. The minimum parameters you need to configure for the class to work are:

• instance (the fqdn of the ServiceNow instance)
• user and password (you can bypass username/password authentication and use an oauth token using the oauth_token parameter.)

When configured properly an event sent to ServiceNow looks similar to the following:

By default each event will include the following information:

• Source: Puppet
• Node: The node the agent ran on.
• Type: The type of event. Can be one of:
  • node_report_changed
  • node_report_unchanged
  • node_report_failed
• Source instance: The name of the Puppet server that generated the report.
• Message Key: A hash of all of the relevant report properties to ensure that future events are grouped together properly.
• Severity: The highest severity rating of all of the events that occurred in a given run. These severity levels can be configured via the <change_type>_event_severity class parameters, including the severity of no_changes reports via no_changes_events_severity.
• Description: Contains the following:
  • Report Labels - The different kinds of events that were in the Puppet run that generated this event. While severity is only the single highest severity, these labels tell you all of the kinds of events that occurred.
  • Environment - The Puppet environment the node is assigned to.
  • Resource Statuses - The full name of the resource, the name of the property and the event message, and the file and line where the resource was defined, for each resource event that was in the report. All resource events are included except for audit events, which are resources for which nothing interesting happened; Puppet simply verified that they are currently still in the correct state.
  • Facts - All of the facts that were requested via the include_facts parameter. The default format is yaml, but can be changed via the facts_format parameter.
• Additional Information: The additional information field contains data about the event in JSON format to make it easy to target that information for rules and workflows. It contains the following keys
  • Facts: A json format representation of all of the facts from the node where Puppet ran.
  • Node Environment: The environment the node is assigned to.

By default, the event_creation_conditions is set to ['always']. This means the module will send a single event for every Puppet run on every node. If you would like to filter on the types of reports being sent, the other available types are: corrective_changes, intentional_changes, pending_corrective_changes, pending_intentional_changes, and failures. You can set the filter in the module's parameters. If nothing interesting such as changes or a failure happened in a given Puppet run then the event type will be node_report_unchanged, there will be no resources listed in the description, and the report severity default value will be OK.

If a change happens then the event type and severity is updated, and any resources that changed are listed in the description.

If multiple events happen (e.g. two resources make corrective changes, but a third resource fails), then the report type will be node_report_failure, the severity by default will be Minor. But all three resources, the resource message that describes what happened, and the file and line where the resource can be found, are included in the event description.

Event severities can be configured via the <change_type>_event_severity class parameters.

You can specify the set of facts included in the event description via the include_facts parameter. It takes an array of strings that each represent a fact to retrieve from the available node facts set. Nested facts can be queried using dot notation such as os.distro, or os.windows to get the Windows version. Queries for nested facts must start at the top level fact name, and any fact that is not present on a node, such as os.windows on a Linux box, is simply ignored without error.

Facts in the description by default are in yaml format for readability, but this can be changed via the facts_format parameter to one of:

• yaml
• pretty_json (json with readability line breaks and indentation)
• json

Sending Incidents

When configured properly, an incident sent to ServiceNow resembles the following:

To send incidents, classify your Puppet server nodes with the servicenow_reporting_integration::incident_mangement class. The minimum parameters you need to configure for the class to work are:

• instance (the fqdn of the servicenow instance, not including the protocol, e.g. https://)
• user and password (Alternatively, you can bypass username/password authentication and use an oauth token using the oauth_token parameter.)
• sys_id of the user you would like to use as the Caller for each ticket. See the How To section below for more information on how to get a user sys_id. The servicenow_reporting_integration::incident_management class requires the caller_id because that is a required incident field on ServiceNow’s end.

The servicenow report processor creates a ServiceNow incident based on that report if at least one of the incident creation conditions are met.

By default the incident_creation_conditions are ['failures', 'corrective_changes']. This means an incident is created if there is a resource failure, a catalog compilation failure, or if a corrective change is made to a managed resource during a Puppet run. With these default parameters intentional changes such as adding a new resource to the catalog and Puppet bringing it into compliance for the first time, and pending changes, like running an agent in noop mode and the agent reporting changes would have occurred, do not result in an incident in ServiceNow.

If you would like to report on those types of changes please note that intentional_changes, pending_corrective_changes, and pending_intentional_changes are also available as values for this parameter.

As a shortcut you can also specify always. To temporarily stop the module from creating any incidents at all, set the incident_creation_conditions parameter to never.

The incident_mangement class also lets you specify additional (but optional) incident fields such as category, subcategory and assigned_to fields via the corresponding category, subcategory, and assigned_to parameters, respectively. See REFERENCE.md for the full details.

Each incident will include the following information provided by Puppet:

• Caller: The user specified by the sys_id given to the caller_id parameter of the incident_management class. This can be any user in ServiceNow and doesn’t need to be the same as the user that creates the incident via the username/password or oauth_token parameters.
• Urgency: Defaults to 3 - Low. Configurable.
• Impact: Defaults to 3 - Low. Configurable.
• State: Defaults to New. Configurable.
• Short Description: Contains the following information:
  • Status: changed, unchanged, failed, pending changes.
  • Node: fqdn of the node the agent ran on.
  • Report Time: timestamp of the report to help find the report in the console.
• Description: See the description section from event management above. Incidents get the same description.

Filtering Environments

For both incidents and events, you can filter sending reports on the environment using an allow_list and block_list. You can set these lists in the module's parameters. The allow_list is defaulted to ['all'] and the block_list is defaulted to ['none']. If you have specific environment filters, you can add them to the list.

You can also use wildcards (i.e. ['*env_filter'], ['env_filter*'], ['*env_filter*']).

Troubleshooting

To verify that everything has worked:

1. Trigger a Puppet run on one of the nodes in the PE Master node group then log into the node.
2. Once logged in, run sudo tail -n 60 /var/log/puppetlabs/puppetserver/puppetserver.log | grep servicenow. This produces some output. If not, then the class is probably not being classified properly. Either the class is not being assigned to the Puppet server nodes at all, or there may be catalog compilation errors on those nodes with the provided parameter values. Please use GitHub issues to file any bugs you find during your troubleshooting.

How To Get the Servicenow User Sys_id

1. In the Application Navigator (left sidebar navigation menu) navigate to System Security > Users and Groups > Users.
2. Use the search box to search for the user you want.
3. In the user listing, select a user.
4. On the user properties screen, click the ☰ icon to the right of the left arrow in the upper left corner of the screen.
5. Click Copy sys_id to copy the sys_id directly to the clipboard. Alternatively, click Show XML to see the sys_id in a new window along with the rest of the user’s properties.

Have feedback? Let us know what you think!

Try out the servicenow_reporting_integration module and let us know what you think at team-pie@puppet.com!