UNS Bridge Connector für Business Central
Verbinden Sie Ihren Unified Namespace mit Microsoft Dynamics 365 Business Central durch eine schreibgeschützte Integration für Shopfloor-Ausführungskennzahlen.
Erweiterung herunterladen
Laden Sie die neueste Version für Business Central herunter
Überblick
UNS Bridge Connector ist eine Business Central-Erweiterung, die eine sichere, schreibgeschützte Brücke zwischen Ihrem Unified Namespace (UNS) und BC Manufacturing erstellt. Sie nimmt aggregierte Ausführungs-KPIs von Ihrem Shopfloor auf und macht diese auf Fertigungsaufträgen und Arbeitsgangzeilen sichtbar – ohne Ihre Planungsdaten zu verändern.
Hauptfunktionen
- Echtzeit-KPI-Erfassung: Menge produziert, Ausschuss, Laufzeit, Stillstandzeit, Verfügbarkeit, Produktivität
- UNS-Topic-Mapping für automatische Arbeitsplatzauflösung
- Idempotente API mit automatischer Duplikaterkennung
- Schutz vor ungeordneten Nachrichten durch Quellzeitstempel
- Vollständiger Audit-Trail im Integrations-Eingang
- Referenzdaten-APIs zum Aufbau eigener Bridges
Anwendungsfälle
Für ERP-Partner & Admins
Verstehen Sie den Ausführungsfortschritt ohne Business Central zu verlassen. Sehen Sie Echtzeit-Produktions-KPIs auf freigegebenen Fertigungsaufträgen, verfolgen Sie Verfügbarkeit und Produktivität pro Arbeitsgang und überwachen Sie den Integrationsstatus über den Integrations-Eingang.
Für Bridge-Entwickler
Bauen Sie eine UNS-zu-ERP-Bridge, die MQTT-Nachrichten in BC-API-Aufrufe übersetzt. Nutzen Sie die UNS-Topic-Mapping-API zur Auflösung von Topic-Pfaden zu Arbeitsplätzen, rufen Sie Referenzdaten (Artikel, Arbeitspläne, Arbeitsplätze) ab und senden Sie Ausführungsereignisse mit Idempotenzgarantie.
Architektur
Die Erweiterung folgt einer ereignisgesteuerten Architektur mit integrierten Resilienz-Mustern. Ein UNS-Bridge-Dienst abonniert MQTT-Topics, löst Topic-Mappings auf und sendet Ausführungsereignisse an Business Central. Nachrichten durchlaufen den Integrations-Eingang zur Validierung und Protokollierung, werden dann in der Ausführungstabelle gespeichert und aktualisieren schliesslich Zusammenfassungsfelder auf Fertigungsaufträgen.
Systemarchitektur
Idempotenz
Jede Nachricht erfordert eine eindeutige GUID (messageId). Wird dieselbe messageId zweimal gesendet, wird das Duplikat sicher ignoriert. Dies gewährleistet konsistente Daten auch bei Netzwerk-Wiederholungen.
Schutz vor Reihenfolgeverletzungen
Jede Nachricht enthält einen sourceTimestamp. Trifft eine ältere Nachricht nach einer neueren ein, wird sie bestätigt, überschreibt aber nicht die neueren Daten.
Dynamische Arbeitsgangauflösung
Beim Senden eines Ausführungsereignisses ohne operationNo löst das System diese dynamisch aus dem workCenter-Feld auf. Es durchsucht die Arbeitsgangzeilen des Fertigungsauftrags und findet den passenden Arbeitsgang. Bei genau einem Treffer wird dieser verwendet. Bei null oder mehreren Treffern schlägt die Anfrage mit einer klaren Fehlermeldung fehl.
UNS-Topic-Mapping
Das UNS-Topic-Mapping bietet statische Integrationskonfiguration für die Zuordnung von UNS-Topics (Unified Namespace) zu ERP-Arbeitsplätzen. Mappings werden in Business Central gespeichert und vom Bridge-Dienst zur Laufzeit abgerufen.
Funktionsweise
- Mappings sind nur Konfiguration: UNS-Topic → Arbeitsplatz
- Mappings werden im ERP gespeichert und sind über die BC-Admin-UI prüfbar
- Die Bridge ruft aktive Mappings per API ab und cached sie lokal
- Die Bridge löst das UNS-Topic zum Arbeitsplatz auf, bevor sie Ausführungsereignisse sendet
- Die Arbeitsgangnummer wird zur Ausführungszeit dynamisch basierend auf dem Fertigungsauftrag aufgelöst
Admin-Oberfläche
Öffnen Sie die Seite UNS-Topic-Mappings in Business Central (suchen Sie nach 'UNS Topic Mappings'), um Mappings zu erstellen, zu bearbeiten und zu löschen. Jedes Mapping kann aktiviert oder deaktiviert werden und enthält Gültigkeitsdaten für zeitlich begrenzte Konfigurationen.
Mapping-Felder
| Feld | Beschreibung |
|---|---|
unsTopic | UNS-Topic-Pfad (z.B. mb/v1/werk/linie1/station5/montage) |
workCenterNo | Ziel-Arbeitsplatz in Business Central (optional für Auto-Discovery) |
status | Aktiv oder Inaktiv |
description | Lesbare Beschreibung des Mappings |
validFrom | Gültig ab Datum |
validTo | Gültig bis Datum (leer = kein Ende) |
Auto-Discovery-Workflow
Das Feld workCenterNo ist optional, um Auto-Discovery zu unterstützen. Ihre Bridge kann neu entdeckte UNS-Topics ohne Arbeitsplatzzuweisung registrieren. Benutzer können dann später über die Admin-UI Arbeitsplätze zuweisen. Nicht zugeordnete Topics werden in der UI mit einem Achtung-Stil angezeigt.
Ausführungsereignisse-API
Die primäre API zum Senden von Shopfloor-Ausführungs-KPIs an Business Central.
Endpunkt
POST /api/alpamayo/shopfloor/v1.0/companies({'{'}id{'}'})/executionEventsAuthentifizierung
Verwenden Sie OAuth 2.0 Bearer Token mit der Ressource https://api.businesscentral.dynamics.com. Der aufrufende Benutzer muss den Berechtigungssatz ALP Shopfloor Exec zugewiesen haben.
Anfrage-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"
}Feldreferenz
| Feld | Typ | Beschreibung |
|---|---|---|
messageId | GUID | Eindeutiger Identifikator für Idempotenz * |
orderNo | Code[20] | Freigegebene Fertigungsauftragsnummer * |
operationNo | Code[10] | Arbeitsgangnummer (erforderlich, wenn Arbeitsplatz mehrere Arbeitsgänge im Auftrag hat) |
workCenter | Code[20] | Arbeitsplatzcode (erforderlich, wenn operationNo nicht angegeben) |
qtyProduced | Integer | Gesamtmenge produziert |
qtyRejected | Integer | Ausschussmenge (muss ≤ qtyProduced sein) |
runtimeSec | Decimal | Laufzeit in Sekunden |
downtimeSec | Decimal | Stillstandzeit in Sekunden |
availability | Decimal | Verfügbarkeitsverhältnis (0.0 bis 1.0) |
productivity | Decimal | Produktivitätsverhältnis (0.0 bis 1.0) |
actualCycleTimeSec | Decimal | Tatsächliche Taktzeit in Sekunden |
sourceTimestamp | DateTime | Zeitstempel vom Quellsystem (ISO 8601) * |
source | Code[20] | Quellsystem-Kennung (z.B. MES-SCADA) |
* Required field
Antworten
Referenzdaten-APIs
Schreibgeschützte APIs zum Abrufen von BC-Stammdaten. Nutzen Sie diese, um Ausführungsereignisse anzureichern oder Daten vor dem Senden zu validieren.
Artikel-API
Fertigungsartikel mit Arbeitsplan- und Stücklistenreferenzen
GET /api/alpamayo/shopfloor/v1.0/companies()/itemsArbeitsplätze-API
Arbeitsplätze mit Kapazitäts- und Effiziendaten
GET /api/alpamayo/shopfloor/v1.0/companies()/workCentersFertigungsaufträge-API
Fertigungsaufträge mit Status, Menge und Terminen
GET /api/alpamayo/shopfloor/v1.0/companies()/productionOrdersArbeitsgangzeilen-API
Fertigungsauftrags-Arbeitsgangzeilen mit Arbeitsgangdetails
GET /api/alpamayo/shopfloor/v1.0/companies()/prodOrderRoutingLinesIntegrations-Eingang-API
Nachrichtenverarbeitungsstatus und Fehlerdetails
GET /api/alpamayo/shopfloor/v1.0/companies()/integrationInboxUNS-Topic-Mapping-API
CRUD-Operationen für UNS-Topic zu Arbeitsplatz-Mappings
GET/POST/PATCH/DELETE /api/alpamayo/shopfloor/v1.0/companies()/unsTopicMappingsDatenmodell
Erweiterungstabellen
ALP Integration Inbox (50001)
ALP Integration Inbox (50001) - Speichert jede eingehende Nachricht mit Verarbeitungsstatus (Empfangen, Verarbeitet, Fehlgeschlagen) und Fehlerdetails. Dient als Audit-Trail und zur Fehlerbehebung.
ALP Operation Execution (50002)
ALP Operation Execution (50002) - Speichert aggregierte Ausführungs-KPIs pro Auftrags-/Arbeitsgang-Kombination. Wird per Upsert-Logik aktualisiert – neuere Zeitstempel überschreiben ältere Daten.
ALP UNS Topic Mapping (50005)
ALP UNS Topic Mapping (50005) - Speichert UNS-Topic zu Arbeitsplatz-Mappings mit Gültigkeitsdaten und Audit-Feldern.
Tabellenerweiterungen
Production Order
Fertigungsauftrag - Fügt Ausführungsverfolgungsfelder hinzu: ALP Last Exec Update At, ALP Execution Source und aggregierte KPIs (Menge produziert, Menge Ausschuss, Verfügbarkeit, Produktivität).
Prod. Order Routing Line
FA-Arbeitsgangzeile - Fügt arbeitsgangbezogene Ausführungsfelder hinzu: ALP Qty. Produced, ALP Qty. Rejected, ALP Actual Availability, ALP Actual Productivity, ALP Source Timestamp.
Berechtigungssätze
ALP Shopfloor View (50040)
Für Dashboard-Betrachter, Produktionsplaner und Vorgesetzte. Gewährt schreibgeschützten Zugriff auf alle Erweiterungstabellen und -seiten.
ALP Shopfloor Exec (50041)
Für Integrations-Dienstkonten und Bridge-Anwendungen. Gewährt Einfügen/Ändern auf Ausführungstabellen und Ausführungsrecht auf der Ausführungs-API.
Benutzerzuweisung
| Role | Permission Sets |
|---|---|
| Dashboard-Betrachter → ALP Shopfloor View | ALP Shopfloor View |
| Shopfloor-Gerät (SCADA/MES) → ALP Shopfloor View + ALP Shopfloor Exec | ALP Shopfloor View + ALP Shopfloor Exec |
| Integrations-Dienstkonto → ALP Shopfloor View + ALP Shopfloor Exec | ALP Shopfloor View + ALP Shopfloor Exec |
Integrationsleitfaden
Einrichtungsschritte
- Installieren Sie die UNS Bridge Connector-Erweiterung aus AppSource oder Ihrem Bereitstellungspaket
- Erstellen Sie einen Dienstkontobenutzer in Business Central mit dem Berechtigungssatz ALP Shopfloor Exec
- Registrieren Sie eine Azure AD-Anwendung und konfigurieren Sie OAuth 2.0 für den API-Zugriff
- Konfigurieren Sie UNS-Topic-Mappings in Business Central, um Ihre MQTT-Topics Arbeitsplätzen zuzuordnen
- Deployen Sie Ihren Bridge-Dienst, der UNS-Topics abonniert und Ausführungsereignisse sendet
Fehlerbehandlung
Bei Validierungsfehlern gibt die API 400 Bad Request zurück und der Integrations-Eingang-Eintrag wird als Fehlgeschlagen mit einer Fehlermeldung markiert. Häufige Fehler sind:
- Fertigungsauftrag nicht gefunden oder nicht im Status Freigegeben
- Menge Ausschuss übersteigt Menge produziert
- Verfügbarkeit oder Produktivität ausserhalb des Bereichs 0-1
- Keine Arbeitsgangzeile gefunden für Auftrag und Arbeitsplatz
- Mehrere Arbeitsgangzeilen gefunden - Arbeitsgangnummer muss angegeben werden
- Arbeitsplatz-Abweichung zwischen Payload und Arbeitsgangzeile
Best Practices
- Generieren Sie für jede Nachricht eine neue UUID v4 – messageIds niemals wiederverwenden
- Verwenden Sie genaue sourceTimestamp-Werte von der Systemuhr Ihres MES/SCADA
- Implementieren Sie Wiederholungslogik mit exponentiellem Backoff für Netzwerkfehler
- Cachen Sie UNS-Topic-Mappings lokal und aktualisieren Sie periodisch
- Überwachen Sie die Integrations-Eingang-API auf fehlgeschlagene Einträge und implementieren Sie Alerting
- Verwenden Sie OData-Filter, um nur freigegebene Fertigungsaufträge abzufragen: $filter=status eq 'Released'
Kommunikationsmuster
Diese Sequenzdiagramme veranschaulichen die wichtigsten Kommunikationsmuster zwischen der UNS-Bridge und Business Central.
Vollständiger Produktionszyklus
Zeigt den kompletten Ablauf von der Auftragsfreigabe über die Ausführung bis zum Abschluss.
Topic-Auto-Discovery
Wie die Bridge neue UNS-Topics entdeckt und zur Zuordnung registriert.
Idempotenz-Handling
Sichere Behandlung von doppelten Nachrichten durch Netzwerk-Retries.
Out-of-Order-Schutz
Wie verspätet ankommende ältere Nachrichten neuere Daten nicht überschreiben.
Bridge-Implementierungsmuster
Eine typische UNS-Bridge folgt diesem Ablauf, um MQTT-Nachrichten in BC-Ausführungsereignisse zu übersetzen.
- UNS-Topics abonnieren (z.B. mb/v1/+/+/+/execution)
- Bei Nachrichtenempfang UNS-Topic-Mapping nachschlagen, um Arbeitsplatz aufzulösen
- Aktiven Fertigungsauftrag für diesen Arbeitsplatz bestimmen (aus Ihrem MES-Kontext)
- Ausführungsereignis-Payload erstellen mit messageId, orderNo, workCenter und KPIs
- POST an den executionEvents-API-Endpunkt
- Erfolg (200) behandeln oder bei transienten Fehlern wiederholen
Support & Quellcode
Für technischen Support kontaktieren Sie Alpamayo unter [email protected] oder besuchen Sie unsere Website, um eine Beratung zu vereinbaren.
Unterstützte Sprachen: Englisch (en-US), Deutsch (de-DE)
Quellcode und technische Dokumentation sind auf GitHub verfügbar.
Auf GitHub ansehen