Skip to main content

Kepware IoT Gateway - Setup and Configuration Guide

availability
Platform:WebMobile
Plan Type:BasicEssentialPremiumEnterprise
User Type:RequesterFull UserAdministrator

This article explains how to configure your Kepware server to transmit metric tags to the MaintainX platform using the Kepware IoT Gateway REST Client.

Kepware Connector Overview
Kepware Connector Overview

Requirements​

On-Premise​

  • Kepware ServerEx6: A licensed version of Kepware Server Ex6 running.
  • Kepware IoT Gateway Plugin: A licensed version of the IoT Gateway Plugin installed and running. For more information, see the Kepware IoT Gateway Plugin documentation.
  • Network: Ensure that the outgoing network traffic from the host system can access https://agent.maintainx.com/ on port 443.

MaintainX Account​

  • Connector permissions. Please contact your organization administrator to request access to the Kepware Connector feature.

Configuration Overview​

Create a Connector and an Access Token​

To configure the Kepware connector, you need an access token. The token authenticates Kepware's REST API request with the MaintainX platform. For security purposes, every Kepware instance must have its own token.

danger

It's important to keep your token secure. Do not share it with unauthorized users.

  1. Log into MaintainX as an Administrator.
  2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
  3. On the Integrations page, go to the Connectors tab.
  4. Navigate to the Kepware tile, and select Connect.
  5. Follow the steps to create a new instance until the Token appears.
  6. Copy the Token and save it for later use.
info

The Token is only displayed once when you create the Kepware instance. If you lose the token for a Kepware instance, you can revoke it and create a new one. See Revoke and Regenerate a Kepware Access Token.

Create a MaintainX Agent in Kepware​

note

These are the recommended settings to provide the best experience. If you choose to use different settings, you might encounter issues with the integration such as rate limiting.

  1. From the KepwareServerEx6 Configuration screen, right-click on the IoT Gateway and select New Agent.

  2. In the Name field, enter the MaintainX REST Agent. Select Rest Client from the Type dropdown. Click Next.

  3. On the Rest Client - Endpoint Page, enter the following information:

    • URL: Enter https://agent.maintainx.com/agent/kepware/sensorReadings.
    • Method: Select POST.
    • Rate (ms): 60000.
    • Timeout (s): 30.
    • Narrow Format: Ensure this option is selected.
    • Max events per: 1000.
    warning

    Anything above 1000 will be rejected by the MaintainX platform.

    Definition of the fields in Rest Client - Endpoint Page:

    FieldDescription
    URLThe endpoint to which the REST client will send data.
    MethodThe HTTP method used for the request (e.g., GET, POST).
    Rate (ms)The frequency, in milliseconds, at which data is sent to the endpoint.
    Timeout (s)The duration, in seconds, the client waits for a response before timing out.
    Wide FormatProduces an output that includes all enabled tags in the agent with every scan.
    Narrow FormatProduces output based on tags that have changed value or quality.
    Max events perThe maximum number of events to include in each data transmission.

  4. Click Next.

  5. On the Rest Client - Headers Page, enter the following information:

    Content-Type: application/json; charset=utf-8
    Authorization: <MaintainX-Connector-Token>

    Definition of the fields in Rest Client - Headers Page:

    FieldDescription
    MaintainX-Connector-TokenAccess token you copied when you created a new Kepware instance. It is used for authentication to the MaintainX platform.

  6. Click Finish.

warning

The MaintainX Kepware connector only supports the default message format. Modifying the message template will cause errors.

Adding new Tags to the MaintainX Agent​

  1. Right-click on the agent you created and select New Iot Item.

  2. In the Server Tag field, browse for the tag you want to add to the agent.

  3. On the Scan Rate field, enter the rate at which the tag should be scanned.

    note

    It is recommended to set the scan rate to 10000ms or higher to avoid rate limiting.

  4. Select your publishing mode.

    note

    It is strongly recommended to use Only on data Changes to reduce the amount of unnecessary data being sent to MaintainX. Failure to do so could lead to rate limiting.

  5. Select OK.

Revoke and Regenerate a Kepware Access Token​

The access token for a Kepware instance is only displayed once, when you first create the instance. If you lose the token, you can revoke it and generate a new one.

To revoke and regenerate a token:

  1. Log into MaintainX as an Administrator.
  2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
  3. On the Integrations page, go to the Connectors tab.
  4. Navigate to the Kepware connector, and select Manage.
  5. In the Kepware dialog, go to the Instances list and select the instance whose token you want to revoke.
  6. In the Manage Instance dialog, select Revoke Token.

The instance's Status changes to Disconnected, and in the Token field shows Revoked.

  1. Select Generate New Token.
  2. Copy the new token from the Token field.
  3. On the Kepware IoT Gateway Rest client for MaintainX, you have to edit the HTTP Header property and replace the old token with the new one.

Auto Create Meters​

Instead of manually creating meters, you can enable an option to automatically create them when a new Kepware tag is discovered via a connector. The meter name will reflect the path of the tag in Kepware.

To use auto create meters:

  1. Log into MaintainX as an Administrator.
  2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
  3. On the Integrations page, go to the Connectors tab.
  4. Navigate to the Kepware module tile, and select Connect.
  5. Toggle Auto Create Meters on.
  6. Follow the steps to create a new Kepware instance and token.

When a new tag is discovered, meters will be created automatically, using data reported by the tag.

Troubleshooting​

Sensors are not being created in MaintainX​

If you are not seeing any sensors being created in MaintainX, check the following:

  1. Ensure that the Kepware agent uses the default message format.
    1. Right-click on the MaintainX REST agent and select Property.
    2. In the Message section, reset the message format by selecting Defaults on the bottom left.
    3. Select OK to save the changes.

Contact the MaintainX Support Team​

If you continue to experience trouble with configuring the Kepware connector, contact the MaintainX Support team.

Resources​