Configure Kepware Tags

availability

Feature availability by platform, plan type, and user type

Platform:	AvailableWebNot availableMobile
Plan Type:	Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:	Not availableRequesterNot availableFull UserAvailableAdministrator

Tags you add to the Kepware agent define which Kepware tag data the agent monitors and how it sends that data to MaintainX®. Configurable scan rates and publishing modes keep data volume within platform limits.

Prerequisites

• MaintainX connector instance and access token: Created in MaintainX when you set up the integration. For more information, see Set Up the Kepware Integration.
• Kepware agent: A Kepware agent configured in KEPServerEX for your connector instance.

Identify Your Kepware Tag Paths

Kepware organizes data points into a three-level hierarchy:

Kepware's three-level tag hierarchy: Channel, Device, and Tag

• Channel: A communication pathway configured with a specific driver (protocol and network settings).
• Device: A specific piece of hardware within a channel, such as a PLC or sensor, identified by its network address.
• Tag: A reference to a specific data point on a device.

When the Kepware agent sends a reading to MaintainX, the full Channel.Device.Tag path is used as the tag identifier. For example, a tag at McHenryPLC.101-11.HopperGate in Kepware appears under that same name in MaintainX.

Because the tag name MaintainX displays is derived directly from the path you configure in Kepware, smart tag mapping uses this name to suggest meter names and asset associations.

Supported Data Types

MaintainX supports the following data types for Kepware tags:

• Number
• String
• Boolean

MaintainX rejects tags that publish arrays, structures, or null values. To monitor the data inside one of these, add its individual scalar tags to the Kepware agent instead.

Add Tags to the Kepware Agent

MaintainX accepts only the default Kepware message format, so leave the agent's message template unchanged. For more information, see Payload Format.

1. Right-click the Kepware 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. In the Scan Rate field, enter the rate at which the tag should be scanned.

   note

   Set the scan rate to 10,000 ms or higher to avoid rate limiting. Lower scan rates generate more events per transmission.

4. Select your publishing mode.

   note

   Use Only on data Changes. This sends a reading only when the tag value changes, which significantly reduces event volume compared to always-on publishing. Sending unchanged values repeatedly risks exceeding the platform's 1,000-event-per-transmission limit.

5. Select OK.

Repeat these steps for each tag you want to monitor.

Payload Format

The Kepware IoT Gateway sends tag readings in a fixed JSON format. MaintainX parses this format to extract readings. The message template in the Kepware agent must not be modified. MaintainX only accepts the default Kepware payload structure.

Each POST body contains a batch of tag value records:

{
  "timestamp": 1741015474200,
  "values": [
    {
      "id": "Channel.Device.Tag",
      "v": 38.04,
      "q": true,
      "t": 1741015465070
    }
  ]
}

Field	Description
id	The full Channel.Device.Tag path. Used as the tag identifier in MaintainX.
v	The tag value at the time of the reading.
t	The Unix timestamp (milliseconds) for the reading. Used by MaintainX to record when the value was sampled.
q	Tag quality flag from Kepware (OPC quality codes: 192 = Good, 0 = Bad). Currently received but not surfaced in MaintainX.

warning

The outer timestamp field in the payload envelope isn't used by MaintainX. The per-value t field is the authoritative timestamp for each reading.

Map Tags to Meters

At this point, MaintainX has tag data flowing in, but each tag still needs to be mapped to a meter before it can update readings, trigger work orders, or power automations. Smart tag mapping uses AI to suggest a meter, unit, and asset for each tag, so you don't have to configure every mapping manually.

For more information, see Map Tags to Meters.

Verify Data Is Flowing

After you map your tags to meters, confirm that readings are reaching MaintainX.

1. From the sidebar, select Meters.
2. From the list, find a meter that's mapped to one of your Kepware tags.
3. Select the meter to open it.
4. In the Readings section, select See All Readings to confirm new readings are arriving.

Allow a few minutes after the Kepware agent starts sending data for the first readings to arrive. After that, readings arrive as tag values update in KEPServerEX. If no readings appear, see Not Seeing Data in MaintainX.