Skip to content

Troubleshooting#

This page covers common issues encountered when configuring and operating the UNS Export Integration, along with diagnostic steps and resolution guidance.

MQTT Broker Connectivity#

Events Are Not Reaching the Broker#

Symptoms: No messages appear in the MQTT client after performing manufacturing operations.

Diagnostic steps:

  1. Verify container deployment

    • Navigate to the environment's Service Resources.
    • Confirm that both the HouseKeeper CDM Builder Light and the Data Platform UNS Connector containers are deployed and running.
    • If missing, review the environment configuration to ensure Light CDM Events and UNS are both enabled. Refresh the browser if containers were recently deployed.

  2. Verify MQTT broker reachability

    • From a terminal with access to the MES network, test connectivity:

      # Test TCP connectivity to the broker
nc -zv <mqtt-broker-address> <mqtt-broker-port>

    • If the connection fails, check firewall rules, DNS resolution, and broker service status.

  3. Verify broker credentials

    • Confirm the MQTT broker username and password in the environment configuration match the broker's authentication settings.
    • Check the broker's access logs for authentication failures.

  4. Check automation controller status

    • Navigate to Data Platform > Data Platform Workflows.
    • Verify that the automation controller is listed and does not show error states.

Connection Drops or Intermittent Delivery#

Symptoms: Events are delivered inconsistently or stop arriving after a period.

Resolution:

  • Check broker resource utilization (CPU, memory, connection limits).

  • Review the distributedMessageSend task settings in the workflow. The default configuration includes:

    Setting Default Adjustment
    requestTimeout 60s Increase if the broker has high latency.
    requestAttempts 10 Increase for unreliable network conditions.
    requestSleepBetweenAttempts 1000ms Increase for broker rate limiting scenarios.

  • Verify the UNS Connector container logs for connection error messages.

Missing or Incomplete Events#

Only Some Event Types Appear#

Symptoms: ResourceStateChange events are published, but MaterialOperations events are missing (or vice versa).

Resolution:

  1. Navigate to Data Platform > Data Platform Workflows and open the automation controller.
  2. Verify the IoT Event Definition bindings. Each desired event type must have a corresponding AutomationControllerIoTEventDef entry with SupportedEventVariant set to Light.
  3. Confirm that the CDM event definitions in Data Platform > IoT Event Definition have the Has Light Variant property enabled.

Events Arrive with Missing Properties#

Symptoms: Published event payloads do not contain expected properties.

Resolution:

  • Light CDM Events include only essential properties by default. Additional properties must be explicitly enabled.
  • Navigate to Administration > Entity Type, select the relevant entity, and verify the Is To Enrich CDM toggle for the desired properties.
  • After enabling additional properties, regenerate the entity type schema by selecting Generate on the top ribbon.

Warning

Schema regeneration is required after enabling additional CDM properties. Events will not include the new properties until regeneration is complete.

Default Values in Topic Hierarchy#

Symptoms: Topics show DefaultEnterprise, DefaultSite, or DefaultArea instead of actual entity names.

Cause: The CDM event payload does not include the expected entity references. This occurs when:

  • The Enterprise, Site, or Area entities are not configured in the MES.
  • The entities exist but are not associated with the resource or area generating the event.

Resolution:

  1. Verify that the manufacturing hierarchy is properly configured:

    • Administration > Enterprise — at least one enterprise must exist.
    • Administration > Site — sites must be associated with the enterprise.
    • Administration > Area — areas must be associated with the appropriate site.
    • Verify that resources generating events are assigned to the correct area in the hierarchy.

Workflow Errors#

Code Execution Task Failures#

Symptoms: The workflow triggers but no MQTT message is published. No errors are visible in the MQTT client.

Diagnostic steps:

  1. Open the automation controller in Data Platform > Data Platform Workflows.
  2. Review the workflow execution logs for the codeExecution task.

  3. Common causes:

    • Syntax errors in custom TypeScript code if the workflow was modified.
    • Null reference errors if the CDM event payload structure differs from expected.
    • Event definition name parsing — the code extracts the event name by finding the last \ character. If the event definition path format changes, this parsing may fail.

Resolution: If you modified the code execution task, revert to the default implementation and test. The default code handles null values with fallback defaults and should work with all standard CDM events.

distributedMessageSend Failures#

Symptoms: The code execution task succeeds but the MQTT message is not delivered.

Diagnostic steps:

  1. Check that the UnsExportIntegration.SendToMqtt service is registered and responsive.
  2. Verify the UNS Connector container is running.
  3. Review the container logs for the UNS Connector for connection or publishing errors.

Environment Configuration Issues#

UNS Business Scenario Not Available in Cortex#

Symptoms: The UNS Export Integration business scenario does not appear in the Cortex chatbot.

Resolution:

  1. Verify the chatbot scope is set to LandingPage/DataPlatform. Navigate to the Data Platform menu entry and open the chatbot from the Activity Center.
  2. If the chatbot was opened in another scope, select Restart.

  3. Confirm that:

    • The IoT Data Platform Advanced module is licensed.
    • MES Analytics feature is enabled.
    • Light CDM Events are enabled.
    • UNS is enabled with valid MQTT broker configuration.

Containers Not Appearing After Configuration#

Symptoms: HouseKeeper CDM Builder Light or Data Platform UNS Connector containers are not visible in Service Resources.

Resolution:

  1. Refresh the browser to update the container list.
  2. If still missing, re-apply the environment configuration and verify that both Light CDM Events > Enabled and UNS > Enabled are set to true.
  3. Check the environment deployment logs for container provisioning errors.

Diagnostic Checklist#

Use this checklist to systematically diagnose UNS Export Integration issues:

  • Light CDM Events are enabled in environment configuration
  • UNS is enabled in environment configuration
  • MQTT broker address, port, and credentials are correct
  • HouseKeeper CDM Builder Light container is running
  • Data Platform UNS Connector container is running
  • Automation controller exists in Data Platform Workflows
  • IoT Event Definition bindings include the desired event types with Light variant
  • Manufacturing hierarchy (Enterprise > Site > Area > Resource) is properly configured
  • MQTT client can connect to the broker with the same credentials
  • Test manufacturing operation produces an event (for example, resource state change)
  • MQTT client receives the event on the expected topic