--- alias: operation-guide-uns-troubleshooting tags: - data platform - UNS - MQTT - CDM - troubleshooting summary: "Diagnose and resolve common issues with the UNS Export Integration, including MQTT connectivity, missing events, and topic construction problems" --- # 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: ```bash # Test TCP connectivity to the broker nc -zv ``` - 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. 2. 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 ## Related Topics - [[operation-guide-configuring-uns-export-integration]] — end-to-end setup guide - [[operation-guide-uns-topic-mapping]] — topic structure and customization - [[operation-guide-uns-master-data-package-reference]] — metadata package reference