Skip to main content

Set Up the Kepware Integration

availability
Feature availability by platform, plan type, and user type
Platform:AvailableWebNot availableMobile
Plan Type:Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:Not availableRequesterNot availableFull UserAvailableAdministrator

To connect the Kepware integration to MaintainX®, you create a connector instance in MaintainX and then configure a Kepware agent in KEPServerEX. The agent transmits metric tags from your KEPServerEX 6 to the MaintainX platform.

Before you begin, review the requirements for your Kepware installation and your MaintainX account. If you run into issues after setup, see Troubleshoot the Kepware Integration.

Create a Connector Instance and Access Token​

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

danger

Keep your token secure. Don't share it with unauthorized users.

  1. Log in to MaintainX as an Administrator.
  2. From the sidebar, select Settings. Under Organization Settings, select Integrations.
  3. On the Integrations page, go to the Connectors tab.
  4. On the Kepware tile, select Connect (or Manage if you've already set up an integration). The Kepware dialog appears.
  5. Select + Create New Instance.
  6. In the Instance name field, enter a descriptive name (for example, Plant 1 Fan A).
  7. Follow the steps to create a new connector instance until the Token appears.
  8. Copy the Token and save it for later use.
  9. Select Connect to finish provisioning the connector instance with the token you saved.
  10. When the confirmation message appears, select Done to close the dialog.
note

The token is only displayed once when you create the connector instance. If you lose the token for a connector instance, you can revoke it and create a new one. For more information, see Revoke an Access Token.

After you create the connector instance, it appears in the Instances list with the status Waiting for Connection. It changes to Connected once the Kepware agent connects to MaintainX.

Choose Your Region​

The MaintainX platform operates in multiple regions. When you configure the Kepware agent, you must point it at the agent endpoint for your organization's region.

RegionAgent Endpoint
US1 (United States)https://agent.maintainx.com
EU1 (Europe)https://agent.eu1.maintainx.com

To identify your region:

Your region is assigned when your MaintainX organization is created. To find it, check your MaintainX login URL:

  • Organizations that log in at app.getmaintainx.com are on US1.
  • Organizations that log in at app.eu1.maintainx.com are on EU1.

If you're unsure which region your organization is on, contact MaintainX Support.

Configure the Kepware Agent​

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 KEPServerEX Configuration screen, right-click the IoT Gateway and select New Agent.

  2. In the Name field, enter a name for the agent, such as MaintainX REST Agent.

  3. Select Rest Client from the Type dropdown, then Next.

  4. On the Rest Client - Endpoint page, enter the following information:

    • URL: Enter the agent endpoint for your region followed by /agent/kepware/sensorReadings. For more information, see Choose Your Region to determine which endpoint applies to your organization.

      RegionURL
      US1https://agent.maintainx.com/agent/kepware/sensorReadings
      EU1https://agent.eu1.maintainx.com/agent/kepware/sensorReadings

    • Method: Select POST.

    • Rate (ms): Enter 60000.

    • Timeout (s): Enter 30.

    • Narrow Format: Ensure this option is selected. Narrow Format sends only tags whose value or quality has changed since the last scan. Wide Format sends all enabled tags on every scan, which can generate many events per transmission and increase the risk of exceeding the 1,000-event limit.

    • Max events per: Enter 1000. This sets the maximum number of events in each transmission to MaintainX.

      warning

      MaintainX rejects any transmission with more than 1,000 events.

    Definition of the fields in the Rest Client - Endpoint page:

    FieldDescription
    URLThe endpoint to which the Kepware agent 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.

  5. Select Next.

  6. 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 the Rest Client - Headers page:

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

  7. Select Finish.

warning

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

After the Kepware agent is created, add the tags you want to monitor. For more information, see Configure Kepware Tags.

Manage Access Tokens​

Each connector instance authenticates with MaintainX using an access token, which is displayed only once, when you first create the connector instance. If you lose the token or need to replace it, you can revoke it and generate a new one.

Revoke an Access Token​

Revoke an access token if it's been lost, exposed to anyone outside your trusted network, or if you're rotating credentials as part of a security review.

warning

Running the Kepware agent with an invalid or revoked token stops data flow until you generate a new token and update your configuration.

To revoke a token:

  1. Log in to MaintainX as an Administrator.

  2. From the sidebar, select Settings. Under Organization Settings, select Integrations.

  3. On the Integrations page, go to the Connectors tab.

  4. On the Kepware tile, select Manage.

  5. In the Kepware dialog, go to the Instances list and select the connector instance whose token you want to revoke.

  6. In the Manage Instance dialog, select Revoke Token.

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

Regenerate an Access Token​

Once you revoke a token, generate its replacement from the same Manage Instance dialog.

To regenerate a token:

  1. Select Generate New Token.
  2. Copy the new token from the Token field.
  3. On the Kepware agent, edit the HTTP Header property and replace the old token with the new one.

Limitations​

  • The Kepware integration works with the Kepware IoT Gateway REST Client agent. For more information, see Kepware Agent.
  • Each connector instance connects one KEPServerEX 6 deployment.
  • The Kepware agent sends tag readings in the default Kepware message format. For more information, see Payload Format.
  • Each transmission can include a maximum of 1,000 events. For more information, see Rate Limiting.
  • MaintainX receives the tag quality flag from Kepware but doesn't display it.