Skip to main content

Set Up and Configure the Kepware IoT Gateway

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 ServerEx6 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's Administrator to request access to the OT Data Connectors 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, select Settings, and under ORGANIZATION SETTINGS, select Integrations.
  3. On the Integrations page, go to the Connectors tab.
  4. Navigate to the Kepware tile, and select Connect. The Kepware dialog appears.
  5. Select + Create New Instance.
  6. Follow the steps to create a new instance until the Token appears.
  7. 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. Select 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. Select 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, select Settings, and under ORGANIZATION SETTINGS, 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 it shows Revoked.

  7. Select Generate New Token.

  8. Copy the new token from the Token field.

  9. 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.

Map Tags to Meters​

After you add your Kepware tags in the MaintainX module, use smart tag mapping to connect your tags to meters in MaintainX.

The smart tag mapping system uses AI to analyze data tags you make available through your organization's Kepware connectors. For each tag, the system suggests a meter name, a unit of measurement, and an asset to assign the meter to. Using the tag management tool, you can:

  • View the Kepware tags that are available through your organization's Kepware connectors.
  • Review MaintainX's suggestions for mapping tags to assets in your organization.
  • Automatically create meters for your tags and associate them with the correct assets.

The tag mapping AI provides a confidence rating for each suggestion. You can edit any suggestion before creating the meter, and easily update mapped tags at any time.

For detailed instructions, see Smart Tag Mapping for OT Data.

info

The smart tag mapping system replaces the Auto Create Meters feature, which is no longer available. If you have existing OT connectors that connect to meters you configured using the Auto Create Meters feature, the smart tag mapping system will not affect them.

Troubleshooting​

Contact the MaintainX Support Team​

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

Resources​