UNS Topic Mapping and Customization#

This guide explains how the UNS Export Integration constructs MQTT topics from CDM event data, how ISA-95 entities map to the topic hierarchy, and how to customize the mapping logic for your organization's needs.

Default Topic Structure#

All CDM events published through the UNS Export Integration follow this hierarchical topic pattern:

Enterprise/Site/Area/Resource/Event

Each level represents a node in the manufacturing hierarchy, derived from the ISA-95-aligned CDM model. This structure enables consumers to subscribe at any level of granularity.

Examples:

CDM-to-UNS Entity Mapping#

Although ISA-95 terminology is used as the foundation, it is important to understand how Critical Manufacturing MES entities map to the UNS structure. MES nomenclature does not always match ISA-95 one-to-one.

Table: CDM Entity to UNS Level Mapping

Topic Construction Logic#

The automation controller workflow includes a Code Execution task that transforms raw CDM event data into the MQTT topic. The logic performs the following steps:

1. Extract Hierarchy Names#

The code reads entity names from the raw CDM event payload:

const enterpriseName = rawData?.Enterprise?.Name?.trim() || "DefaultEnterprise";
const siteName = rawData?.Site?.Name?.trim() || "DefaultSite";
const areaName = rawData?.Area?.Name?.trim() || "DefaultArea";

If any level is missing or has an empty name, the corresponding default value is used.

2. Construct Base Topic#

The base topic is built from the first three hierarchy levels:

let topic = `${enterpriseName}/${siteName}/${areaName}`;

3. Conditionally Add Resource#

If the event payload includes a Resource object, the resource name is appended:

if (rawData?.Resource != null) {
    const resourceName = rawData?.Resource?.Name?.trim() || "DefaultResource";
    topic += `/${resourceName}`;
}

4. Append Event Type#

The CDM event definition name is extracted from the IoT event metadata and appended as the final topic level:

let eventName = inputs?.iotEvent?.value?.AppProperties?.EventDefinition;
eventName = eventName.substring(eventName.lastIndexOf("\\") + 1);
topic += `/${eventName}`;

5. Sanitize Topic#

Spaces are replaced with hyphens for MQTT topic compatibility:

topic = topic.replace(/ /g, "-");

Customizing the Topic Structure#

You can modify the topic construction logic to match your organization's UNS namespace design.

Editing the Workflow Code#

1. Navigate to Data Platform > Data Platform Workflows.
2. Open the automation controller created for UNS Export Integration.
3. Locate the Code Execution task in the Setup workflow.
4. Modify the TypeScript code in the task settings.

Common Customizations#

Adding a Facility Level#

To include the Facility entity between Site and Area:

const facilityName = rawData?.Facility?.Name?.trim() || "DefaultFacility";
let topic = `${enterpriseName}/${siteName}/${facilityName}/${areaName}`;

This produces topics like:

Acme-Corp/Austin-Fab/Building-A/Assembly/Oven-02/MaterialOperations

Using a Custom Topic Prefix#

To add a fixed prefix for namespace organization:

const prefix = "cmf/mes";
let topic = `${prefix}/${enterpriseName}/${siteName}/${areaName}`;

This produces topics like:

cmf/mes/Acme-Corp/Austin-Fab/Assembly/Oven-02/ResourceStateChange

Alternative Separator Characters#

While / is the standard MQTT topic separator, you can adjust how entity names are formatted. For example, to use underscores instead of hyphens for space replacement:

topic = topic.replace(/ /g, "_");

Filtering Events by Type#

To publish only specific event types, add a conditional check before the send step:

const allowedEvents = ["ResourceStateChange", "MaterialOperations"];
if (!allowedEvents.includes(eventName)) {
    return { dataOut: null }; // Skip this event
}
return { dataOut: { topic, raw: rawData } };

Subscribing to Topics#

MQTT clients can subscribe to topics using wildcard patterns to consume events at different granularity levels.

MQTT Wildcard Reference#

Subscription Examples#

Table: MQTT Subscription Patterns

Event Payload Structure#

Each MQTT message carries a JSON payload containing the full CDM event data. The payload structure includes:

Table: CDM Event Payload Sections

Best Practices#

Topic Design#

• Start with ISA-95 hierarchies and evolve based on actual consumer patterns.
• Keep topics human-readable to simplify debugging and monitoring.
• Avoid deep nesting beyond five or six levels, which can complicate wildcard subscriptions.
• Use consistent naming conventions across sites and environments.

Data Volume Management#

• Subscribe only to the events your consumers need rather than using catch-all wildcards in production.
• Consider aggregation or filtering at the workflow level for high-frequency events.
• Configure MQTT broker retention and expiry policies based on consumer latency requirements.

Security#

• Use TLS encryption (port 8883 by default) for all broker connections.
• Configure topic-level ACLs on the MQTT broker to restrict publish and subscribe permissions.
• Rotate broker credentials periodically through environment configuration updates.

Related Topics#

• Guides: UNS Integration Customization ⧉ — developer guide for customizing UNS integration
• Configuring UNS Export Integration — end-to-end setup guide
• Master Data Package Reference — metadata package structure reference
• Real-Time Shop-Floor Insights with UNS and MQTT — hands-on tutorial with example scenarios