ServiceNow MetricBase Integration connector - AWS IoT Greengrass
RequirementsParametersInput dataOutput dataUsage ExampleLicensesChangelogSee also

AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

ServiceNow MetricBase Integration connector

Warning

This connector has moved into the extended life phase, and AWS IoT Greengrass won't release updates that provide features, enhancements to existing features, security patches, or bug fixes. For more information, see AWS IoT Greengrass Version 1 maintenance policy.

The ServiceNow MetricBase Integration connector publishes time series metrics from Greengrass devices to ServiceNow MetricBase. This allows you to store, analyze, and visualize time series data from the Greengrass core environment, and act on local events.

This connector receives time series data on an MQTT topic, and publishes the data to the ServiceNow API at regular intervals.

You can use this connector to support scenarios such as:

  • Create threshold-based alerts and alarms based on time series data collected from Greengrass devices.

  • Use time services data from Greengrass devices with custom applications built on the ServiceNow platform.

This connector has the following versions.

Version

ARN

4

arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/4

3

arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/3

2

arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/2

1

arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/1

For information about version changes, see the Changelog.

Requirements

This connector has the following requirements:

Version 3 - 4

  • AWS IoT Greengrass Core software v1.9.3 or later. AWS IoT Greengrass must be configured to support local secrets, as described in Secrets Requirements.

    Note

    This requirement includes allowing access to your Secrets Manager secrets. If you're using the default Greengrass service role, Greengrass has permission to get the values of secrets with names that start with greengrass-.

  • Python version 3.7 or 3.8 installed on the core device and added to the PATH environment variable.

    Note

    To use Python 3.8, run the following command to create a symbolic link from the the default Python 3.7 installation folder to the installed Python 3.8 binaries.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    This configures your device to meet the Python requirement for AWS IoT Greengrass.

  • A ServiceNow account with an activated subscription to MetricBase. In addition, a metric and metric table must be created in the account. For more information, see MetricBase in the ServiceNow documentation.

  • A text type secret in AWS Secrets Manager that stores the user name and password to log in to your ServiceNow instance with basic authentication. The secret must contain "user" and "password" keys with corresponding values. For more information, see Creating a basic secret in the AWS Secrets Manager User Guide.

  • A secret resource in the Greengrass group that references the Secrets Manager secret. For more information, see Deploy secrets to the AWS IoT Greengrass core.

Versions 1 - 2

  • AWS IoT Greengrass Core software v1.7 or later. AWS IoT Greengrass must be configured to support local secrets, as described in Secrets Requirements.

    Note

    This requirement includes allowing access to your Secrets Manager secrets. If you're using the default Greengrass service role, Greengrass has permission to get the values of secrets with names that start with greengrass-.

  • Python version 2.7 installed on the core device and added to the PATH environment variable.

  • A ServiceNow account with an activated subscription to MetricBase. In addition, a metric and metric table must be created in the account. For more information, see MetricBase in the ServiceNow documentation.

  • A text type secret in AWS Secrets Manager that stores the user name and password to log in to your ServiceNow instance with basic authentication. The secret must contain "user" and "password" keys with corresponding values. For more information, see Creating a basic secret in the AWS Secrets Manager User Guide.

  • A secret resource in the Greengrass group that references the Secrets Manager secret. For more information, see Deploy secrets to the AWS IoT Greengrass core.

Connector Parameters

This connector provides the following parameters:

Version 4
PublishInterval

The maximum number of seconds to wait between publish events to ServiceNow. The maximum value is 900.

The connector publishes to ServiceNow when PublishBatchSize is reached or PublishInterval expires.

Display name in the AWS IoT console: Publish interval in seconds

Required: true

Type: string

Valid values: 1 - 900

Valid pattern: [1-9]|[1-9]\d|[1-9]\d\d|900

PublishBatchSize

The maximum number of metric values that can be batched before they are published to ServiceNow.

The connector publishes to ServiceNow when PublishBatchSize is reached or PublishInterval expires.

Display name in the AWS IoT console: Publish batch size

Required: true

Type: string

Valid pattern: ^[0-9]+$

InstanceName

The name of the instance used to connect to ServiceNow.

Display name in the AWS IoT console: Name of ServiceNow instance

Required: true

Type: string

Valid pattern: .+

DefaultTableName

The name of the table that contains the GlideRecord associated with the time series MetricBase database. The table property in the input message payload can be used to override this value.

Display name in the AWS IoT console: Name of the table to contain the metric

Required: true

Type: string

Valid pattern: .+

MaxMetricsToRetain

The maximum number of metrics to save in memory before they are replaced with new metrics.

This limit applies when there's no connection to the internet and the connector starts to buffer the metrics to publish later. When the buffer is full, the oldest metrics are replaced by new metrics.

Note

Metrics are not saved if the host process for the connector is interrupted. For example, this can happen during group deployment or when the device restarts.

This value should be greater than the batch size and large enough to hold messages based on the incoming rate of the MQTT messages.

Display name in the AWS IoT console: Maximum metrics to retain in memory

Required: true

Type: string

Valid pattern: ^[0-9]+$

AuthSecretArn

The secret in AWS Secrets Manager that stores the ServiceNow user name and password. This must be a text type secret. The secret must contain "user" and "password" keys with corresponding values.

Display name in the AWS IoT console: ARN of auth secret

Required: true

Type: string

Valid pattern: arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

AuthSecretArn-ResourceId

The secret resource in the group that references the Secrets Manager secret for the ServiceNow credentials.

Display name in the AWS IoT console: Auth token resource

Required: true

Type: string

Valid pattern: .+

IsolationMode

The containerization mode for this connector. The default is GreengrassContainer, which means that the connector runs in an isolated runtime environment inside the AWS IoT Greengrass container.

Note

The default containerization setting for the group does not apply to connectors.

Display name in the AWS IoT console: Container isolation mode

Required: false

Type: string

Valid values: GreengrassContainer or NoContainer

Valid pattern: ^NoContainer$|^GreengrassContainer$

Version 1 - 3
PublishInterval

The maximum number of seconds to wait between publish events to ServiceNow. The maximum value is 900.

The connector publishes to ServiceNow when PublishBatchSize is reached or PublishInterval expires.

Display name in the AWS IoT console: Publish interval in seconds

Required: true

Type: string

Valid values: 1 - 900

Valid pattern: [1-9]|[1-9]\d|[1-9]\d\d|900

PublishBatchSize

The maximum number of metric values that can be batched before they are published to ServiceNow.

The connector publishes to ServiceNow when PublishBatchSize is reached or PublishInterval expires.

Display name in the AWS IoT console: Publish batch size

Required: true

Type: string

Valid pattern: ^[0-9]+$

InstanceName

The name of the instance used to connect to ServiceNow.

Display name in the AWS IoT console: Name of ServiceNow instance

Required: true

Type: string

Valid pattern: .+

DefaultTableName

The name of the table that contains the GlideRecord associated with the time series MetricBase database. The table property in the input message payload can be used to override this value.

Display name in the AWS IoT console: Name of the table to contain the metric

Required: true

Type: string

Valid pattern: .+

MaxMetricsToRetain

The maximum number of metrics to save in memory before they are replaced with new metrics.

This limit applies when there's no connection to the internet and the connector starts to buffer the metrics to publish later. When the buffer is full, the oldest metrics are replaced by new metrics.

Note

Metrics are not saved if the host process for the connector is interrupted. For example, this can happen during group deployment or when the device restarts.

This value should be greater than the batch size and large enough to hold messages based on the incoming rate of the MQTT messages.

Display name in the AWS IoT console: Maximum metrics to retain in memory

Required: true

Type: string

Valid pattern: ^[0-9]+$

AuthSecretArn

The secret in AWS Secrets Manager that stores the ServiceNow user name and password. This must be a text type secret. The secret must contain "user" and "password" keys with corresponding values.

Display name in the AWS IoT console: ARN of auth secret

Required: true

Type: string

Valid pattern: arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

AuthSecretArn-ResourceId

The secret resource in the group that references the Secrets Manager secret for the ServiceNow credentials.

Display name in the AWS IoT console: Auth token resource

Required: true

Type: string

Valid pattern: .+

Create Connector Example (AWS CLI)

The following CLI command creates a ConnectorDefinition with an initial version that contains the ServiceNow MetricBase Integration connector.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyServiceNowMetricBaseIntegrationConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/4",
            "Parameters": {
                "PublishInterval" : "10",
                "PublishBatchSize" : "50",
                "InstanceName" : "myinstance",
                "DefaultTableName" : "u_greengrass_app",
                "MaxMetricsToRetain" : "20000",
                "AuthSecretArn" : "arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash",
                "AuthSecretArn-ResourceId" : "MySecretResource", 
                "IsolationMode" : "GreengrassContainer"
            }
        }
    ]
}'
Note

The Lambda function in this connector has a long-lived lifecycle.

In the AWS IoT Greengrass console, you can add a connector from the group's Connectors page. For more information, see Getting started with Greengrass connectors (console).

Input data

This connector accepts time series metrics on an MQTT topic and publishes the metrics to ServiceNow. Input messages must be in JSON format.

Topic filter in subscription

servicenow/metricbase/metric

Message properties
request

Information about the table, record, and metric. This request represents the seriesRef object in a time series POST request. For more information, see Clotho Time Series API - POST.

Required: true

Type: object that includes the following properties:

subject

The sys_id of the specific record in the table.

Required: true

Type: string

metric_name

The metric field name.

Required: true

Type: string

table

The name of the table to store the record in. Specify this value to override the DefaultTableName parameter.

Required: false

Type: string

value

The value of the individual data point.

Required: true

Type: float

timestamp

The timestamp of the individual data point. The default value is the current time.

Required: false

Type: string

Example input
{
    "request": {
        "subject":"ef43c6d40a0a0b5700c77f9bf387afe3",
        "metric_name":"u_count",
        "table": "u_greengrass_app"
        "value": 1.0,
        "timestamp": "2018-10-14T10:30:00"
    }
}

Output data

This connector publishes status information as output data on an MQTT topic.

Topic filter in subscription

servicenow/metricbase/metric/status

Example output: Success
{
    "response": {
        "metric_name": "Errors",
        "table_name": "GliderProd",
        "processed_on": "2018-10-14T10:35:00",
        "response_id": "khjKSkj132qwr23fcba",
        "status": "success",
        "values": [
            {
                "timestamp": "2016-10-14T10:30:00",
                "value": 1.0
            },
            {
                "timestamp": "2016-10-14T10:31:00",
                "value": 1.1
            }
        ]
    }
}
Example output: Failure
{
    "response": {
        "error": "InvalidInputException",
        "error_message": "metric value is invalid",
        "status": "fail"
    }
}
Note

If the connector detects a retryable error (for example, connection errors), it retries the publish in the next batch.

Usage Example

Use the following high-level steps to set up an example Python 3.7 Lambda function that you can use to try out the connector.

Note

  1. Make sure you meet the requirements for the connector.

  2. Create and publish a Lambda function that sends input data to the connector.

    Save the example code as a PY file. Download and unzip the AWS IoT Greengrass Core SDK for Python. Then, create a zip package that contains the PY file and the greengrasssdk folder at the root level. This zip package is the deployment package that you upload to AWS Lambda.

    After you create the Python 3.7 Lambda function, publish a function version and create an alias.

  3. Configure your Greengrass group.

    1. Add the Lambda function by its alias (recommended). Configure the Lambda lifecycle as long-lived (or "Pinned": true in the CLI).

    2. Add the required secret resource and grant read access to the Lambda function.

    3. Add the connector and configure its parameters.

    4. Add subscriptions that allow the connector to receive input data and send output data on supported topic filters.

      • Set the Lambda function as the source, the connector as the target, and use a supported input topic filter.

      • Set the connector as the source, AWS IoT Core as the target, and use a supported output topic filter. You use this subscription to view status messages in the AWS IoT console.

  4. Deploy the group.

  5. In the AWS IoT console, on the Test page, subscribe to the output data topic to view status messages from the connector. The example Lambda function is long-lived and starts sending messages immediately after the group is deployed.

    When you're finished testing, you can set the Lambda lifecycle to on-demand (or "Pinned": false in the CLI) and deploy the group. This stops the function from sending messages.

Example

The following example Lambda function sends an input message to the connector.

import greengrasssdk
import json

iot_client = greengrasssdk.client('iot-data')
SEND_TOPIC = 'servicenow/metricbase/metric'

def create_request_with_all_fields():
    return {
        "request": {
             "subject": '2efdf6badbd523803acfae441b961961',
             "metric_name": 'u_count',
             "value": 1234,
             "timestamp": '2018-10-20T20:22:20',
             "table": 'u_greengrass_metricbase_test'
        }
    }

def publish_basic_message():
    messageToPublish = create_request_with_all_fields()
    print("Message To Publish: ", messageToPublish)
    iot_client.publish(topic=SEND_TOPIC,
        payload=json.dumps(messageToPublish))

publish_basic_message()

def lambda_handler(event, context):
    return

Licenses

The ServiceNow MetricBase Integration connector includes the following third-party software/licensing:

This connector is released under the Greengrass Core Software License Agreement.

Changelog

The following table describes the changes in each version of the connector.

Version

Changes

4

Added the IsolationMode parameter to configure the containerization mode for the connector.

3

Upgraded the Lambda runtime to Python 3.7, which changes the runtime requirement.

2

Fix to reduce excessive logging.

1

Initial release.

A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.

See also