Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name


README
Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset

Sensu Go ServiceNow Handler

Table of Contents

Overview

The Sensu Go ServiceNow handler is a Sensu Event Handler that creates or updates a ServiceNow incident and/or event.

Enterprise Plugin

The Sensu Go ServiceNow Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Usage Examples

This handler creates a ServiceNow incident and/or event.

The incident or event can optionally be associated to a configuration item based on the Sensu event's entity.metadata.name attribute.

If a Configuration Item for the Sensu Entity doesn't exist in ServiceNow, this handler will create one automatically.

Help output

The Sensu Go handler for managing ServiceNow Configuration Items, Incidents, and Events

Usage:
  sensu-servicenow-handler [flags]
  sensu-servicenow-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -H, --host string                           The ServiceNow host
  -p, --password string                       The ServiceNow password
  -u, --username string                       The ServiceNow username
  -c, --cmdbCiTable string                    The ServiceNow CMDB CI table
  -C, --configurationItemDescription string   The template for the ServiceNow Configuration Item Description
  -b, --incidentBodyNotes string              The template for the ServiceNow Incident Body Notes
  -i, --incidentTable string                  The ServiceNow Incident table
  -a, --eventAdditionalInfo string            The template for the ServiceNow Event's Additional Info
  -e, --eventTable string                     The ServiceNow Event table
  -h, --help                                  help for sensu-servicenow-handler

Use "sensu-servicenow-handler [command] --help" for more information about a command.

Environment variables

All arguments for this handler are available to be set via environment variables. However, any
arguments specified directly on the command line override the corresponding environment variable.

Argument Environment Variable
--cmdbCiTable SERVICENOW_CMDB_CI_TABLE
--configurationItemDescription SERVICENOW_CONFIGURATION_ITEM_DESCRIPTION
--eventAdditionalInfo SERVICENOW_EVENT_ADDITIONAL_INFO
--eventTable SERVICENOW_EVENT_TABLE
--host SERVICENOW_HOST
--incidentBodyNotes SERVICENOW_INCIDENT_BODY_NOTES
--incidentTable SERVICENOW_INCIDENT_TABLE
--password SERVICENOW_PASSWORD
--username SERVICENOW_USERNAME

Security Note: Care should be taken to not expose the username/password for this handler by specifying them
on the command line. It is suggested to make use of secrets management to surface them as environment
variables. The handler definition above references them as secrets. Below are example secrets definitions
that make use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow_username
spec:
  provider: env
  id: SERVICENOW_USERNAME
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow_password
spec:
  provider: env
  id: SERVICENOW_PASSWORD

Templates

This handler provides options for using templates to populate the values
provided by the event in the event or incident records created in ServiceNow.
More information on template syntax and format can be found in the documentation

Example scenarios:

The records created/updated in ServiceNow are dependent on which arguments are provided to this handler,
whether via the command line specifications above, environment variables, or
annotations. If the appropriate table is not specified then records are not created there.

Note: In the examples below, the command given is a snippet of what would be defined for the handler
for the given scenario, in yaml multiline format. Also, the ServiceNow username and password are assumed
to be set as environment variables.

Annotations

All arguments for this handler are tunable on a per entity or check basis based on annotations. The
annotations keyspace for this handler is sensu.io/plugins/sensu-servicenow-handler/config. Any such
annotations take precedence over environment variables and command line arguments.

NOTE: Due to check token substituion, supplying a template value such
as for description-template as a check annotation requires that you place the
desired template as a golang string literal (enlcosed in backticks)
within another template definition. This does not apply to entity annotations.

Examples

To change the ServiceNow host for a particular entity, in that agent's agent.yml file add the following:

annotations:
  sensu.io/plugins/sensu-servicenow-handler/config/host: "mycompany-nonprod.service-now.com"

To change the incident body notes template for a particular check, for that checks's metadata add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/sensu-servicenow-handler/config/incidentBodyNotes: "{{`Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}`}}"
[...]

ServiceNow Incident Management

  1. Specifying only the Incident table (--incidentTable) will create a ServiceNow incident not associated with
    a CMDB configuration item.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-instance.service-now.com
        --incidentTable incident
    
  2. Specifying both the Incident table (--incidentTable) and CMDB CI table (--cmdbCiTable) will create a
    ServiceNow incident associated with a CMDB configuration item (and create the CMDB configuration item
    if it does not already exist).

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-instance.service-now.com
        --cmdbCiTable cmdb_ci
        --incidentTable incident
    
  3. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow
    Incident Body Notes.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-instance.service-now.com
        --cmdbCiTable cmdb_ci
        --incidentTable incident
        --incidentBodyNotes "Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}"
    

ServiceNow Event Management

  1. Specifying only the Event table (--eventTable) will create a ServiceNow event not associated with a
    CMDB configuration item.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-events.service-now.com
        --eventTable em_events
    
  2. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow Event
    Additional Info field.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-events.service-now.com
        --eventTable em_events
        --eventAdditionalInfo "Check: {{ .Check.Name }}\nEntity: {{ .Entity.Name }}\n\nDescription: {{ .Check.Output }}\n\nSensu URL: https://sensu.mycompany.com:3000/{{ .Check.Namespace }}/events/{{ .Entity.Name }}/{{ .Check.Name }}"
    
  3. Specifying both the Event table (--eventTable) and CMDB CI table (--cmdbCiTable) will create a
    ServiceNow event associated with a CMDB configuration item (and create the CMDB configuration item
    if it does not already exist).

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-events.service-now.com
        --eventTable em_events
        --cmdbCiTable cmdb_ci
    

ServiceNow Inventory Management

When used in a registration handler, you can have Sensu create ServiceNow CMDB configuration items.

  1. Specifying the CMDB CI table (--cmdbCiTable) will create a CMDB configuration for the entity.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-events.service-now.com
        --cmdbCiTable cmdb_ci
    
  2. Same as above, but also specifying what Sensu event fields are used to populate the ServiceNow
    Configuration Item Description.

    spec:
      command: >-
        sensu-servicenow-handler
        --host sn-events.service-now.com
        --cmdbCiTable cmdb_ci
        --configurationItemDescription "Entity: {{ .Entity.Name }}\nOS: {{ .Entity.System.OS }}"
    

Configuration

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not using an asset, please
consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the
following command to add the asset:

sensuctl asset add sensu/sensu-servicenow-handler

If you're using an earlier version of sensuctl, you can find the asset on the Bonsai Asset Index.

Handler definition

---
type: Handler
api_version: core/v2
metadata:
  name: sensu-servicenow-handler
  namespace: default
spec:
  command: sensu-servicenow-handler
  type: pipe
  runtime_assets:
  - sensu/sensu-servicenow-handler
  filters:
  - is_incident
  secrets:
  - name: SERVICENOW_USERNAME
    secret: servicenow_username
  - name: SERVICENOW_PASSWORD
    secret: servicenow_password

Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.

Installation from source

The preferred way of installing and deploying this plugin is to use it as an Asset. If you would
like to compile and install the plugin from source or contribute to it, download the latest version
or create an executable from this source.

From the local path of the sensu-servicenow-handler repository:

go build

Contributing

See https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.

×

You must be signed in to report this asset.

Sign In with Github

Download

×

Either download the source code:

Download Source

Or download the asset definition: