UNS Bridge Connector for Business Central

Connect your Unified Namespace to Microsoft Dynamics 365 Business Central with a read-only integration for shopfloor execution metrics.

Download Extension

Get the latest version for Business Central

Checking for updates...

BC 26.0+CloudMIT License

Overview

UNS Bridge Connector is a Business Central extension that creates a secure, read-only bridge between your Unified Namespace (UNS) and BC Manufacturing. It ingests aggregated execution KPIs from your production floor and makes them visible on Production Orders and Routing Lines without modifying your planning data.

Key Features

Real-time KPI ingestion: quantity produced, rejected, runtime, downtime, availability, productivity
UNS Topic Mapping for automatic Work Center resolution
Idempotent API with automatic duplicate detection
Out-of-order message protection via source timestamps
Complete audit trail in Integration Inbox
Reference data APIs for building custom bridges

Use Cases

For ERP Partners & Admins

Understand execution progress without leaving Business Central. View real-time production KPIs on Released Production Orders, track availability and productivity per routing operation, and monitor integration health via the Integration Inbox.

For Bridge Developers

Build a UNS-to-ERP bridge that translates MQTT messages into BC API calls. Use the UNS Topic Mapping API to resolve topic paths to Work Centers, fetch reference data (Items, Routings, Work Centers) to enrich messages, and post execution events with idempotency guarantees.

Architecture

The extension follows an event-driven architecture with built-in resilience patterns. A UNS Bridge service subscribes to MQTT topics, resolves topic mappings, and posts execution events to Business Central. Messages flow through the Integration Inbox for validation and audit, then persist to the Operation Execution table before updating summary fields on Production Orders.

System Architecture

Architecture overview showing data flow from Shopfloor through Edge Layer and UNS to Business Central

Idempotency

Every message requires a unique GUID (messageId). If the same messageId is sent twice, the duplicate is safely ignored. This ensures your data stays consistent even with network retries.

Out-of-Order Protection

Each message includes a sourceTimestamp. If an older message arrives after a newer one has been processed, the older message is acknowledged but does not overwrite the newer data.

Dynamic Operation Resolution

When sending an execution event without operationNo, the system dynamically resolves it from the workCenter field. It looks up the Production Order's routing lines and finds the matching operation. If exactly one match exists, it uses that operation. If zero or multiple matches exist, the request fails with a clear error message.

UNS Topic Mapping

The UNS Topic Mapping feature provides static integration configuration for mapping UNS (Unified Namespace) topics to ERP Work Centers. Mappings are stored in Business Central and fetched by the bridge service at runtime.

How It Works

Mappings are configuration-only: UNS Topic → Work Center
Mappings are stored in ERP and auditable via BC admin UI
Bridge fetches active mappings via API and caches them locally
Bridge resolves UNS topic to Work Center before sending execution events
Operation No. is resolved dynamically at execution time based on Production Order routing

Admin UI

Open the UNS Topic Mappings page in Business Central (search for 'UNS Topic Mappings') to create, edit, and delete mappings. Each mapping can be activated or deactivated, and includes validity dates for time-bounded configurations.

Mapping Fields

Field	Description
`unsTopic`	UNS topic path (e.g., mb/v1/plant/line1/station5/assembly)
`workCenterNo`	Target Work Center in Business Central (optional for auto-discovery)
`status`	Active or Inactive
`description`	Human-readable description of the mapping
`validFrom`	Start validity date
`validTo`	End validity date (empty = no end)

Auto-Discovery Workflow

The workCenterNo field is optional to support auto-discovery. Your bridge can register newly discovered UNS topics without a Work Center assignment. Users can then assign Work Centers later via the admin UI. Unmapped topics are displayed with an Attention style in the UI.

Execution Events API

The primary API for posting shopfloor execution KPIs to Business Central.

Endpoint

POST /api/alpamayo/shopfloor/v1.0/companies({'{'}id{'}'})/executionEvents

Authentication

Use OAuth 2.0 Bearer token with the https://api.businesscentral.dynamics.com resource. The calling user must have the ALP Shopfloor Exec permission set assigned.

Request Payload

{
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "orderNo": "101001",
  "operationNo": "10",
  "workCenter": "MACH0001",
  "qtyProduced": 100,
  "qtyRejected": 5,
  "runtimeSec": 3600,
  "downtimeSec": 300,
  "availability": 0.92,
  "productivity": 0.85,
  "actualCycleTimeSec": 36.5,
  "sourceTimestamp": "2024-01-24T10:30:00Z",
  "source": "MES-SCADA"
}

Field Reference

Field	Type	Description
`messageId`	GUID	Unique identifier for idempotency *
`orderNo`	Code[20]	Released Production Order number *
`operationNo`	Code[10]	Operation number (required if Work Center has multiple operations on the order)
`workCenter`	Code[20]	Work Center code (required if operationNo is not specified)
`qtyProduced`	Integer	Total quantity produced
`qtyRejected`	Integer	Quantity rejected (must be ≤ qtyProduced)
`runtimeSec`	Decimal	Runtime in seconds
`downtimeSec`	Decimal	Downtime in seconds
`availability`	Decimal	Availability ratio (0.0 to 1.0)
`productivity`	Decimal	Productivity ratio (0.0 to 1.0)
`actualCycleTimeSec`	Decimal	Actual cycle time in seconds
`sourceTimestamp`	DateTime	Timestamp from source system (ISO 8601) *
`source`	Code[20]	Source system identifier (e.g., MES-SCADA)

* Required field

Responses

200200 OK - Message processed successfully (or already processed)

400400 Bad Request - Validation failed (check error message in response)

Reference Data APIs

Read-only APIs for fetching BC master data. Use these to enrich execution events or validate data before posting.

Items API

Manufacturing items with routing and BOM references

GET /api/alpamayo/shopfloor/v1.0/companies()/items

Work Centers API

Work centers with capacity and efficiency data

GET /api/alpamayo/shopfloor/v1.0/companies()/workCenters

Production Orders API

Production orders with status, quantity, and dates

GET /api/alpamayo/shopfloor/v1.0/companies()/productionOrders

Routing Lines API

Production order routing lines with operation details

GET /api/alpamayo/shopfloor/v1.0/companies()/prodOrderRoutingLines

Integration Inbox API

Message processing status and error details

GET /api/alpamayo/shopfloor/v1.0/companies()/integrationInbox

UNS Topic Mapping API

CRUD operations for UNS topic to Work Center mappings

GET/POST/PATCH/DELETE /api/alpamayo/shopfloor/v1.0/companies()/unsTopicMappings

Data Model

Extension Tables

ALP Integration Inbox (50001)

ALP Integration Inbox (50001) - Stores every incoming message with processing status (Received, Processed, Failed) and error details. Used for audit trail and troubleshooting.

ALP Operation Execution (50002)

ALP Operation Execution (50002) - Stores aggregated execution KPIs per Order/Operation combination. Updated via upsert logic - newer timestamps overwrite older data.

ALP UNS Topic Mapping (50005)

ALP UNS Topic Mapping (50005) - Stores UNS topic to Work Center mappings with validity dates and audit fields.

Table Extensions

Production Order

Production Order - Adds execution tracking fields: ALP Last Exec Update At, ALP Execution Source, and aggregated KPIs (Qty. Produced, Qty. Rejected, Availability, Productivity).

Prod. Order Routing Line

Prod. Order Routing Line - Adds per-operation execution fields: ALP Qty. Produced, ALP Qty. Rejected, ALP Actual Availability, ALP Actual Productivity, ALP Source Timestamp.

Permission Sets

ALP Shopfloor View (50040)

For dashboard viewers, production planners, and supervisors. Grants read-only access to all extension tables and pages.

ALP Shopfloor Exec (50041)

For integration service accounts and bridge applications. Grants insert/modify on execution tables and execute permission on the execution API.

User Assignment

Role	Permission Sets
Dashboard Viewer → ALP Shopfloor View	`ALP Shopfloor View`
Shopfloor Device (SCADA/MES) → ALP Shopfloor View + ALP Shopfloor Exec	`ALP Shopfloor View + ALP Shopfloor Exec`
Integration Service Account → ALP Shopfloor View + ALP Shopfloor Exec	`ALP Shopfloor View + ALP Shopfloor Exec`

Integration Guide

Setup Steps

Install the UNS Bridge Connector extension from AppSource or your deployment package
Create a service account user in Business Central with the ALP Shopfloor Exec permission set
Register an Azure AD application and configure OAuth 2.0 for API access
Configure UNS Topic Mappings in Business Central to map your MQTT topics to Work Centers
Deploy your bridge service that subscribes to UNS topics and posts execution events

Error Handling

When validation fails, the API returns 400 Bad Request and the Integration Inbox entry is marked as Failed with an error message. Common errors include:

Production Order not found or not in Released status
Qty. Rejected exceeds Qty. Produced
Availability or productivity outside 0-1 range
No routing line found for Order and Work Center
Multiple routing lines found - Operation No. must be specified
Work Center mismatch between payload and routing line

Best Practices

Generate a new UUID v4 for each message - never reuse messageIds
Use accurate sourceTimestamp values from your MES/SCADA system clock
Implement retry logic with exponential backoff for network failures
Cache UNS Topic Mappings locally and refresh periodically
Monitor the Integration Inbox API for Failed entries and implement alerting
Use OData filters to query only Released production orders: $filter=status eq 'Released'

Communication Patterns

These sequence diagrams illustrate the key communication patterns between the UNS Bridge and Business Central.

Full Production Cycle

Shows the complete flow from order release through execution to completion.

Topic Auto-Discovery

How the Bridge discovers new UNS topics and registers them for mapping.

Idempotency Handling

Safe handling of duplicate messages due to network retries.

Out-of-Order Protection

How older messages arriving late do not corrupt newer data.

Bridge Implementation Pattern

A typical UNS Bridge follows this flow to translate MQTT messages into BC execution events.

Subscribe to UNS topics (e.g., mb/v1/+/+/+/execution)
On message received, look up UNS Topic Mapping to resolve Work Center
Determine the active Production Order for this Work Center (from your MES context)
Build the execution event payload with messageId, orderNo, workCenter, and KPIs
POST to the executionEvents API endpoint
Handle success (200) or retry on transient failures

Support & Source Code

For technical support, contact Alpamayo at [email protected] or visit our website to schedule a consultation.

Supported Languages: English (en-US), German (de-DE)

Source code and technical documentation are available on GitHub.

View on GitHub