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 Pipeline that provides deep integration between Sensu and ServiceNow, including:

  • CMDB Registration — keep the ServiceNow CMDB up-to-date with your Sensu entity inventory
  • CMDB Discovery — keep Sensu Entities up-to-date with ServiceNow CMDB properties
  • Incident Management — create and resolve ServiceNow Incidents for Sensu monitoring events
  • Event Management — send Sence monitoring event data to ServiceNow for reporting and analysis

Usage

Sensu Go integraiton for ServiceNow CMDB, Incident Management, and Event Management

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, --help                                  help for sensu-servicenow-handler
  -U, --url string                            ServiceNow URL (e.g. https://yourcompany.service-now.com:443)
  -u, --username string                       ServiceNow username
  -p, --password string                       ServiceNow password
      --timeout string                        ServiceNow timeout (default "10s")
      --api-key string                        Sensu API Key (only used when --cmdb-discovery is enabled)
      --api-url string                        Sensu API URL (only used when --cmdb-discovery is enabled) (default "http://127.0.0.1:8080")
      --cmdb-registration                     Enable ServiceNow CMDB registration
      --cmdb-table string                     ServiceNow CMDB table name (default "cmdb_ci")
      --cmdb-key string                       ServiceNow CMDB key field name (used for looking up & updating existing CMDB records) (default "name")
      --cmdb-name string                      ServiceNow CMDB CI name used for looking up & updating existing CMDB records (supports handler templating) (default "{{ .Entity.Name }}")
      --cmdb-asset-tag string                 ServiceNow CMDB CI asset tag (supports handler templating) (default "sensu/{{ .Entity.Namespace }}/{{ .Entity.Name }}")
      --cmdb-properties string                Comma-separated list of ServiceNow CMDB table properties to manage
      --cmdb-discovery                        Enable ServiceNow CMDB discovery (Sensu entity enrichment)
      --cmdb-discovery-subscriptions string   Comma-separated list of fieldnames; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled)
      --cmdb-discovery-labels string          Comma-separated list of label=fieldname pairs; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled) (default "servicenow_sys_id=sys_id,servicenow_sys_class_name=sys_class_name")
      --cmdb-discovery-annotations string     Comma-separated list of annotation=fieldname pairs; for use with ServiceNow CMDB discovery (only used when --cmdb-discovery is enabled)
      --incident-management                   Enable ServiceNow Incident Management
      --incident-table string                 ServiceNow Incident table name (default "incident")
      --incident-key string                   ServiceNow Incident key field name used for looking up & updating existing incidents (default "short_description")
      --incident-description string           ServiceNow Incident description (supports handler templating) (default "{{ .Check.State }}")
      --incident-work-notes string            ServiceNow Incident Work Notes (supports handler templating) (default "{{ .Check.Output }}")
      --incident-comments string              ServiceNow Incident Additional Comments (supports handler templating)
      --incident-properties string            Comma-separated list of ServiceNow Incident table properties to manage
      --event-management                      Enable ServiceNow Event Management
      --event-table string                    ServiceNow Event table name (default "em_event")
      --event-additional-info string          ServiceNow Event Additional Info (supports handler templating)
      --event-properties string               Comma-separated list of ServiceNow Event table properties to manage

      --property-annotation-prefix string     Sensu annotation prefix for custom ServiceNow Table properties (default "servicenow/table")

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

ServiceNow CMDB Registration

Servicenow CMDB registration is enabled with the --cmdb-registration argument.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

The available configuration parameters for CMDB registration are:

  • --cmdb-table

    Configures which ServiceNow table to use for managing Configuration Items.

    Default: cmdb_ci

  • --cmdb-key

    Configures which fieldname Sensu should use to lookup Configuration Items; effectively used as a "primary key".

    Default: name

  • --cmdb-name

    Configures the Configuration Item name to be created or updated.
    The --cmdb-name flag supports Sensu handler templates.

    Default: {{ .Entity.Name }}

  • --cmdb-asset-tag

    Configures the Configuration Item "Asset Tag".
    The --cmdb-asset-tag flag supports Sensu handler templates.

    Default: sensu/{{ .Entity.Namespace }}/{{ .Entity.Name }}

  • --cmdb-properties

    Configures a list of custom ServiceNow CMDB table properties to populate (if provided via custom property annotations).

    Custom CMDB properties can be populated via custom property annotations following the <property-annotation-prefix>/cmdb/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

    If the "--cmdb-properties asset_tag,store_id" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow CMDB CI table.
    The --cmdb-properties flag is best used with Sensu Entity annotations (e.g. setting annotations in agent.yml):

    annotations:
      servicenow/table/cmdb/asset_tag: i-42424242
      servicenow/table/cmdb/store_id: 1234
    

ServiceNow CMDB Discovery

ServiceNow CMDB discovery is enabled with the --cmdb-discovery argument.

NOTE: valid Sensu --api-url and --api-key configuration is required for CMDB Discovery (see below for more information on setting these as environment variables).
The Sensu ServiceNow Handler uses this configuration to authenticate with the Sensu API and update Sensu Entity properties (e.g. labels, annotations, and/or subscriptions).
ServiceNow CMDB discovery is incompatible with Sensu Agents that are configured with --agent-managed-entity=true, as any Sensu Entity API updates will be overwritten by the agent.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-discovery
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10

CMDB discovery can also be used with CMDB registration:

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10

The available configuration parameters for CMDB discovery are:

  • --cmdb-table

    Configures which ServiceNow table to use for managing Configuration Items.

    Default: cmdb_ci

  • --cmdb-key

    Configures which fieldname Sensu should use to lookup Configuration Items; effectively used as a "primary key".

    Default: name

  • --cmdb-discovery-labels

    Configures which Configuration Item fields should be synchronized as Sensu Labels, defined as a comma-separated list of label=fieldname pairs.

    Default: servicenow_sys_id=sys_id,servicenow_sys_class_name=sys_class_name

  • --cmdb-discovery-annotations

    Configures which Configuration Item fields should be synchronized as Sensu Annotations, defined as a comma-separated list of annotation=fieldname pairs (e.g. a custom ServiceNow CMDB CI field named store_id could be syncrhonized via --cmdb-discovery-annotations servicenow_store_id=store_id).

  • --cmdb-discovery-subscriptions

    Configures which Configuration Item fields should be syncrhonized as Sensu Subscriptions, defined as a comma-separated list of fieldnames (e.g. a custom ServiceNow CMDB CI field named store_id could be synchronized via --cmdb-discovery-subscriptions=store_id).

ServiceNow Incident Management

ServiceNow Incident Management integration is enabled with the --incident-management argument.

Example

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

Incident Management can also be used with CMDB registration (and even CMDB discovery):

---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10

The available configuration parameters for Incident Management are:

  • --incident-table

    Configures which ServiceNow table to use for managing Incidents.

    Default: incident

  • --incident-key

    Configures which fieldname Sensu should use to lookup Incidents; effectively used as a "primary key".

    Default: short_description

  • --incident-description

    Configures the ServiceNow Incident "short description" suffix.
    The --incident-description flag supports Sensu handler templates.

    Default: {{ .Check.State }}

    NOTE: All ServiceNow Incident short descriptions are prefixed with the Sensu namespace and entity name (i.e. {{ .Entity.Name }}/{{ .Check.Name }}: ).
    In practice the default value for ServiceNow Incident short descriptions is:

    {{ .Entity.Name }}/{{ .Check.Name }}: {{ .Check.State }}
    

    Setting --incident-description provides the ability to replace {{ .Check.State }} with some other value.

  • --incident-work-notes

    Configures the ServiceNow Incident work notes (incident content).
    The --incident-work-notes flag supports Sensu handler templates.

    Default: {{ .Check.Output }}

  • --incident-comments

    Appends additional comments to the ServiceNow Incident.
    The --incident-comments flag supports Sensu handler templates.

  • --incident-properties

    Configures a list of custom ServiceNow Incident table properties to populate (if provided via custom property annotations).

    Custom Incident properties can be populated via custom property annotations following the <property-annotation-prefix>/incident/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

    If the "--incident-properties category,example" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow Incident table.
    The --incident-properties flag is best used with Sensu Check annotations (e.g. setting annotations in your check definitions).

    Example:

    annotations:
      servicenow/table/incident/category: software
      servicenow/table/incident/example: hello, world
    

ServiceNow Event Management

ServiceNow Event Management is enabled with the --event-management argument.

Example

coming soon

The available configuration parameters for Event Management are:

  • --event-table

    Configures which ServiceNow table to use for managing Events.

    Default: em_event

  • --event-additional-info

    Configures the ServiceNow Event "additional info" content.

  • --event-properties

    Configures a list of custom ServiceNow Event table properties to populate (if provided via custom property annotations).

    Custom Incident properties can be populated via custom property annotations following the <property-annotation-prefix>/event/<property-name> syntax (NOTE: the default --property-annotation-prefix is servicenow/table/).

    If the "--event-properties foo,bar" flag was set, Sensu would check for matching annotations and populate the corresponding fields in the ServiceNow Incident table.
    The --event-properties flag is best used with Sensu Check annotations (e.g. setting annotations in your check definitions).

    Example:

    annotations:
      servicenow/table/incident/foo: hello
      servicenow/table/incident/bar: world
    

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.

Pipeline definition

---
type: Pipeline
api_version: core/v2
metadata:
  name: servicenow
spec:
  workflows:
    - name: servicenow-incidents
      filters:
        - api_version: core/v2
          type: EventFilter
          name: is_incident
      handler:
        api_version: core/v2
        type: Handler
        name: servicenow-incidents
    - name: servicenow-cmdb
      filters:
        - api_version: core/v2
          type: EventFilter
          name: is_registration
      handler:
        api_version: core/v2
        type: Handler
        name: servicenow-cmdb
---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-incidents
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --incident-management
    --incident-properties category
    --cmdb-registration
    --cmdb-properties asset_tag
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
  timeout: 10
---
type: Handler
api_version: core/v2
metadata:
  name: servicenow-cmdb
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow_username
    - name: SERVICENOW_PASSWORD
      secret: servicenow_password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10
---
type: Handler
api_version: core/v2
metadata:
  name: registration
spec:
  type: pipe
  command: >-
    sensu-servicenow-handler
    --cmdb-registration
    --cmdb-properties asset_tag
    --cmdb-discovery
    --cmdb-discovery-labels servicenow_sys_id=sys_id
    --cmdb-discovery-annotations servicenow_sys_class_name=sys_class_name
  runtime_assets:
    - sensu/sensu-servicenow-handler:3.0.0
  env_vars:
    - SERVICENOW_URL=https://example.servicenow.com
    - SENSU_API_URL=http://127.0.0.1:8080
  secrets:
    - name: SERVICENOW_USERNAME
      secret: servicenow-username
    - name: SERVICENOW_PASSWORD
      secret: servicenow-password
    - name: SENSU_API_KEY
      secret: sensu-api-key
  timeout: 10
---
type: EventFilter
api_version: core/v2
metadata:
  name: is_registration
spec:
  action: allow
  expressions:
    - event.check.name == "keepalive"
    - event.check.status == 0
    - event.check.occurrences == 1
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-username
spec:
  provider: env
  id: SENSU_SERVICENOW_USERNAME
---
type: Secret
api_version: secrets/v1
metadata:
  name: servicenow-password
spec:
  provider: env
  id: SENSU_SERVICENOW_PASSWORD
---
type: Secret
api_version: secrets/v1
metadata:
  name: sensu-api-key
spec:
  provider: env
  id: SENSU_ENTITY_MANAGER_API_KEY

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
--url SERVICENOW_URL
--username SERVICENOW_USERNAME
--password SERVICENOW_PASSWORD
--cmdb-table SERVICENOW_CMDB_TABLE
--incident-table SERVICENOW_INCIDENT_TABLE
--event-table SERVICENOW_EVENT_TABLE
--api-key SENSU_API_KEY

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

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 servicenow/config.
Any such annotations take precedence over environment variables and command line arguments.

Argument Annotation
--url servicenow/config/url
--username servicenow/config/username
--password servicenow/config/password
--api-url servicenow/config/api-url
--api-key servicenow/config/api-key
--property-annotation-prefix servicenow/config/property-annotation-prefix
--cmdb-registration servicenow/config/cmdb-registration
--cmdb-table servicenow/config/cmdb-table
--cmdb-key servicenow/config/cmdb-key
--cmdb-name servicenow/config/cmdb-name
--cmdb-asset-tag servicenow/config/cmdb-asset-tag
--cmdb-properties servicenow/config/cmdb-asset-properties
--cmdb-discovery servicenow/config/cmdb-discovery
--cmdb-discovery-labels servicenow/config/cmdb-discovery-labels
--cmdb-discovery-annotations servicenow/config/cmdb-discovery-annotations
--cmdb-discovery-subscriptions servicenow/config/cmdb-discovery-subscriptions
--incident-management servicenow/config/incident-management
--incident-table servicenow/config/incident-table
--incident-key servicenow/config/incident-key
--incident-description servicenow/config/incident-description
--incident-work-notes servicenow/config/incident-work-notes
--incident-comments servicenow/config/incident-comments
--incident-properties servicenow/config/incident-properties
--event-management servicenow/config/event-management
--event-table servicenow/config/event-table
--event-additional-info servicenow/config/event-additional-info
--event-properties servicenow/config/event-properties

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.

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

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.

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: