Getting started with PE and the ServiceNow Reporting integration
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.
Before you begin
- Install Puppet Enterprise version 2019.8.1 (LTS) or newer
- Make sure you have access to a ServiceNow instance (dev or enterprise)
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.
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:
Node: The node the agent ran on.
Type: The type of event. Can be one of:
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_severityclass parameters, including the severity of no_changes reports via
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
auditevents, 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_factsparameter. The default format is yaml, but can be changed via the
- 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:
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
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.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:
- pretty_json (json with readability line breaks and indentation)
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.
password(Alternatively, you can bypass username/password authentication and use an oauth token using the
sys_idof the user you would like to use as the
Callerfor each ticket. See the
How Tosection below for more information on how to get a user
servicenow_reporting_integration::incident_managementclass requires the
caller_idbecause that is a required incident field on ServiceNow’s end.
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
['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
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
incident_mangement class also lets you specify additional (but optional) incident fields such as
assigned_to fields via the corresponding
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_idgiven to the
caller_idparameter of the
incident_managementclass. 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
Short Description: Contains the following information:
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.
For both incidents and events, you can filter sending reports on the environment using an
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.
To verify that everything has worked:
- Trigger a Puppet run on one of the nodes in the
PE Masternode group then log into the node.
- 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
- In the Application Navigator (left sidebar navigation menu) navigate to System Security > Users and Groups > Users.
- Use the search box to search for the user you want.
- In the user listing, select a user.
- On the user properties screen, click the ☰ icon to the right of the left arrow in the upper left corner of the screen.
Copy sys_idto copy the
sys_iddirectly to the clipboard. Alternatively, click Show XML to see the
sys_idin 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 email@example.com!