Skip to content

Latest commit

 

History

History
727 lines (437 loc) · 21.3 KB

REFERENCE.md

File metadata and controls

727 lines (437 loc) · 21.3 KB

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • servicenow_reporting_integration: This class contains the common setup code for incident_management and event_management.

Functions

Data types

Tasks

  • add_ignore_ok_events_rule: Add an event rule that will ignore Puppet events with OK status to prevent creating alerts for them.

Plans

Classes

servicenow_reporting_integration::event_management

Configures the report processor to send events to servicenow

Examples

include servicenow_reporting_integration::event_management

Parameters

The following parameters are available in the servicenow_reporting_integration::event_management class:

instance

Data type: String[1]

The FQDN of the ServiceNow instance.

user

Data type: Optional[String[1]]

A user that has permission to send events

Default value: undef

password

Data type: Optional[Sensitive[String[1]]]

The password for the user

Default value: undef

oauth_token

Data type: Optional[Sensitive[String[1]]]

You can use an oauth token instead of username and password if you choose

Default value: undef

pe_console_url

Data type: Optional[String[1]]

The url to access the PE console. Used to link users back to the console

Default value: undef

servicenow_credentials_validation_table

Data type: String

The name of a table to query that can be used to validate that the credentials provided will work to send events.

Default value: 'em_event'

failures_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains errors

Default value: 'Minor'

corrective_changes_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains corrective changes

Default value: 'Warning'

intentional_changes_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains intentional changes

Default value: 'OK'

pending_corrective_changes_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains pending corrective changes

Default value: 'Warning'

pending_intentional_changes_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains pending intentional changes

Default value: 'OK'

no_changes_event_severity

Data type: Optional[Servicenow_reporting_integration::Severity_levels]

The severity to assign to events when the report contains no events

Default value: 'OK'

include_facts

Data type: Optional[Array[String[1]]]

An array of fact queries to send with each event. The query can be the simple name of a top level fact like 'id', or it can be a dot notation query for nested facts like 'os.distro'

Default value: ['aio_agent_version', 'id', 'memorysize', 'memoryfree', 'ipaddress', 'ipaddress6', 'os.distro', 'os.windows', 'path', 'uptime', 'rubyversion']

allow_list

Data type: Optional[Array[String[1]]]

An array of the name of environments that the user wants to allow data to be sent

Default value: ['all']

block_list

Data type: Optional[Array[String[1]]]

An array of the name of environments that the user does not want data to be sent

Default value: ['none']

facts_format

Data type: Enum['yaml', 'pretty_json', 'json']

The format of the facts that are included in the event description

Default value: 'yaml'

disabled

Data type: Optional[Boolean]

Turn off sending events from the report processor. This is an easier way to disable the module temporarily instead of uninstalling the module and removing the setting from puppet.conf.

Default value: false

skip_certificate_validation

Data type: Optional[Boolean]

If your Servicenow instance uses a certificate that is not trusted by the Puppet server, you can set this parameter to 'true'. The connection will still use SSL, but the module will not perform certificate validation, which is a risk for man in the middle attacks.

Default value: false

http_read_timeout

Data type: Optional[Variant[Integer[0], Float[0]]]

The read timeout parameter sets an upper limit on how long HTTP read read operations should take. For the sake simplicity, this paramter sets three different arguments to the Net::HTTP.start method: read_timeout, connect_timeout, ssl_timeout. This type is a Float because those argumants can all accept fractional seconds values. The default value of 60 seconds is also the default value for that Ruby class if no argument is passed

Default value: 60

http_write_timeout

Data type: Optional[Variant[Integer[0], Float[0]]]

Sets the write_timeout argument to the Net::HTTP.start method. The datatype is a float because it accepts fractions seconds values. The default value of 60 seconds is also the default value for that Ruby class if no argument is passed

Default value: 60

pe_console_cert_validation

Data type: Enum['selfsigned', 'truststore', 'none']

Sets the method the settings validation script will use to validate the PE Console certificate. The default is selfsigned meaning the script expects the certificate generated by the PE private CA and will validate against that cert. If you have generated your own cert using an alternate CA, and you have imported the CA for that cert into the OS Trust Store, then use truststore. If you would like to skip certificate validation use none.

Default value: 'selfsigned'

event_creation_conditions

Data type: Servicenow_reporting_integration::ReportCategories

Default value: ['always']

servicenow_reporting_integration::incident_management

parameter to the empty string ''.

Examples

include servicenow_reporting_integration::incident_management

Parameters

The following parameters are available in the servicenow_reporting_integration::incident_management class:

instance

Data type: String[1]

The FQDN of the ServiceNow instance

caller_id

Data type: String[1]

The sys_id of the incident's caller as specified in the sys_user table

user

Data type: Optional[String[1]]

The username of the account with permission to query data

Default value: undef

password

Data type: Optional[Sensitive[String[1]]]

The password of the account used to query data from Servicenow

Default value: undef

oauth_token

Data type: Optional[Sensitive[String[1]]]

An OAuth access token created in Servicenow that can be used in place of a

Default value: undef

pe_console_url

Data type: Optional[String[1]]

The PE console url username and password.

Default value: undef

category

Data type: Optional[String[1]]

The incident's category

Default value: undef

subcategory

Data type: Optional[String[1]]

The incident's subcategory

Default value: undef

contact_type

Data type: Optional[String[1]]

The incident's contact type

Default value: undef

state

Data type: Optional[Integer]

The incident's state

Default value: undef

impact

Data type: Optional[Integer]

The incident's impact

Default value: undef

urgency

Data type: Optional[Integer]

The incident's urgency

Default value: undef

assignment_group

Data type: Optional[String[1]]

The sys_id of the incident's assignment group as specified in the sys_user_group table

Default value: undef

assigned_to

Data type: Optional[String[1]]

The sys_id of the user assigned to the incident as specified in the sys_user table. Note that if assignment_group is also specified, then this must correspond to a user who is a member of the assignment_group.

Default value: undef

allow_list

Data type: Optional[Array[String[1]]]

An array of the name of environments that the user wants to allow data to be sent

Default value: ['all']

block_list

Data type: Optional[Array[String[1]]]

An array of the name of environments that the user does not want data to be sent

Default value: ['none']

incident_creation_conditions

Data type: Servicenow_reporting_integration::ReportCategories

The incident creation conditions. The report processor will create incidents for reports that satisfy at least one of the specified conditions. For example, if you use the default value (['failures', 'corrective_changes']), then the report processor will create an incident if the report had any failures or corrective changes. Note: Set this parameter to ['never'] if you want to completely turn off incident creation. If set to ['never'], then this module will not create any incidents at all.

Default value: ['failures', 'corrective_changes']

servicenow_credentials_validation_table

Data type: String

The table to read for validating the provided ServiceNow credentials. You should set this to another table if the current set of credentials don't have READ access to the default 'incident' table. Note that you can turn the ServiceNow credentials validation off by setting this

Default value: 'incident'

include_facts

Data type: Optional[Array[String[1]]]

An array of fact queries to send with each event. The query can be the simple name of a top level fact like 'id', or it can be a dot notation query for nested facts like 'os.distro'

Default value: ['aio_agent_version', 'id', 'memorysize', 'memoryfree', 'ipaddress', 'ipaddress6', 'os.distro', 'os.windows', 'path', 'uptime', 'rubyversion']

facts_format

Data type: Enum['yaml', 'pretty_json', 'json']

The format of the facts that are included in the event description

Default value: 'yaml'

skip_certificate_validation

Data type: Optional[Boolean]

If your Servicenow instance uses a certificate that is not trusted by the Puppet server, you can set this parameter to 'true'. The connection will still use SSL, but the module will not perform certificate validation, which is a risk for man in the middle attacks.

Default value: false

http_read_timeout

Data type: Optional[Variant[Integer[0], Float[0]]]

The read timeout parameter sets an upper limit on how long HTTP read read operations should take. For the sake simplicity, this paramter sets three different arguments to the Net::HTTP.start method: read_timeout, connect_timeout, ssl_timeout. This type is a Float because those argumants can all accept fractional seconds values. The default value of 60 seconds is also the default value for that Ruby class if no argument is passed

Default value: 60

http_write_timeout

Data type: Optional[Variant[Integer[0], Float[0]]]

Sets the write_timeout argument to the Net::HTTP.start method. The datatype is a float because it accepts fractions seconds values. The default value of 60 seconds is also the default value for that Ruby class if no argument is passed

Default value: 60

pe_console_cert_validation

Data type: Enum['selfsigned', 'truststore', 'none']

Sets the method the settings validation script will use to validate the PE Console certificate. The default is selfsigned meaning the script expects the certificate generated by the PE private CA and will validate against that cert. If you have generated your own cert using an alternate CA, and you have imported the CA for that cert into the OS Trust Store, then use truststore. If you would like to skip certificate validation use none.

Default value: 'selfsigned'

Functions

servicenow_reporting_integration::check_report_processor

Type: Ruby 4.x API

This function gets the report processor version and stores in the settings_file hash

servicenow_reporting_integration::check_report_processor(String $settings_file_path)

This function gets the report processor version and stores in the settings_file hash

Returns: Array Returns an array of boolean (if the stored ver is same as current ver) and string (current version)

settings_file_path

Data type: String

The path to the settings file

Data types

Servicenow_reporting_integration::ReportCategories

The possible incident creation conditions. Here's what each condition means: 'always' Always create an incident for all reports 'never' Never create an incident for any report 'failures' Create an incident if the report has failures 'corrective_changes' Create an incident if the report contains at least one corrective change 'intentional_changes' Create an incident if the report contains at least one intentional change 'pending_corrective_changes' Create an incident if the report contains at least one corrective change that wasn't applied because of noop 'pending_intentional_changes' Create an incident if the report contains at least one intentional change that wasn't applied because of noop

Alias of

Array[Enum[
  'always',
  'never',
  'failures',
  'corrective_changes',
  'intentional_changes',
  'pending_corrective_changes',
  'pending_intentional_changes',
]]

Servicenow_reporting_integration::Severity_levels

The valid Servicenow event severity levels. Here's what each level means: 'Clear' The alert no longer needs action. 'Critical' The resource is either not functional or critical problems are imminent. 'Major' Major functionality is severely impaired or performance has degraded. 'Minor' Partial, non-critical loss of functionality or performance degradation occurred. 'Warning' Attention is required, even though the resource is still functional. 'OK' No severity. An alert is created. The resource is still functional. https://docs.servicenow.com/bundle/paris-it-operations-management/page/product/event-management-operator/concept/operator-events-alerts.html

Alias of

Enum['Clear', 'Critical', 'Major', 'Minor', 'Warning', 'OK']

Tasks

add_ignore_ok_events_rule

Add an event rule that will ignore Puppet events with OK status to prevent creating alerts for them.

Supports noop? false

Parameters

name

Data type: Optional[String]

The name of the rule to create. Defaults to 'Puppet Node Report - Info'

description

Data type: Optional[String]

Description to add to the rule.

order

Data type: Optional[Integer]

Order of rule application. Defaults to 100.

user

Data type: Optional[String]

Username authorized to insert event rules.

password

Data type: Optional[String]

ServiceNow password

instance

Data type: Optional[String]

ServiceNow instance. For example, dev84270.service-now.com.

oauth_token

Data type: Optional[String]

ServiceNow OAuth token

Plans

servicenow_reporting_integration::acceptance::pe_server_setup

Install PE Server

Examples

pe_event_forwarding::acceptance::pe_server

Parameters

The following parameters are available in the servicenow_reporting_integration::acceptance::pe_server_setup plan:

version

Data type: Optional[String]

PE version

Default value: '2019.8.7'

pe_settings

Data type: Optional[Hash]

Hash with key password and value of PE console password for admin user

Default value: {password => 'puppetlabs'}

servicenow_reporting_integration::acceptance::provision_machines

Provisions machines

Parameters

The following parameters are available in the servicenow_reporting_integration::acceptance::provision_machines plan:

using

Data type: Optional[String]

provision service

Default value: 'abs'

image

Data type: Optional[String]

os image

Default value: 'centos-7-x86_64'