Microsoft Dynamics 365 Finance & Operations

Workist verbindet sich über die Datenentitäten von Dynamics 365 Finance & Operations (F&O) mit Ihrer Umgebung. Workist liest Debitoren und freigegebene Produkte als Stammdaten, legt abgeschlossene Bestellungen als Verkaufsaufträge an und Anfragen als Verkaufsangebote. In F&O wird nichts installiert.

Überblick

Voraussetzungen

• Eine App-Registrierung in Microsoft Entra ID mit Client-Secret. Workist meldet sich damit ohne Benutzerinteraktion an.
• Die App ist in F&O als Anwendung freigegeben und einem Benutzer zugeordnet, der diese Datenentitäten nutzen darf:
  • lesen: CustomersV3, ContactPersons, CDSCustomerContactPersons, CustomerPostalAddresses, CDSReleasedDistinctProducts, CustomerProductDescriptionsV2
  • anlegen: SalesOrderHeadersV2 bzw. SalesOrderHeadersV4, SalesOrderLines, SalesOrderHeaderDocumentAttachmentsV2, SalesQuotationHeaders, SalesQuotationLines
  • löschen: SalesOrderHeadersV2 bzw. SalesOrderHeadersV4, damit Workist einen unvollständigen Auftrag zurücknehmen kann
• Workist muss Ihre F&O-Umgebung über das Internet erreichen, direkt oder über ein API-Gateway.

Datenfluss

Richtung	Inhalt	Zeitpunkt
F&O → Workist	Debitoren, Kontaktpersonen, Postadressen, freigegebene Produkte, externe Artikelnummern	täglich um 06:00 Uhr deutscher Zeit und auf Knopfdruck
Workist → F&O	Verkaufsauftrag mit Positionen, Bestelldokument (PDF) und Original-E-Mail	sobald eine Bestellung abgeschlossen ist
Workist → F&O	Verkaufsangebot mit Positionen	sobald eine Anfrage abgeschlossen ist

Was wir aus Finance & Operations lesen

Stammdaten in Workist	Quelle in Finance & Operations	Datenentitäten
Kunden	Debitoren	CustomersV3, ContactPersons, CDSCustomerContactPersons
Kundenkontakte	Kontaktpersonen der Debitoren	ContactPersons, CDSCustomerContactPersons
Lieferadressen	Postadressen der Debitoren	CustomerPostalAddresses
Artikel	Freigegebene Produkte	CDSReleasedDistinctProducts
Kundenspezifische Artikelnummern	Externe Artikelnummern der Debitoren (nur einem Debitor zugeordnete, nicht Debitorengruppen)	CustomerProductDescriptionsV2

• Ist in der Integration eine Data Area ID eingetragen, liest Workist nur diese juristische Person. Ohne Data Area ID liest Workist alle.
• Mit den Optionen der Integration lassen sich die Produkte eingrenzen: nur Lagerartikel (IsStockedProduct = Ja) und nur Produkte, bei denen Verkaufs- und Lagereinheit gepflegt sind.
• Rechnungsadressen, Einheitenumrechnungen, Rahmenverträge und Angebote liest Workist nicht aus F&O.

Welche Felder Workist im Einzelnen übernimmt, steht in der Feldreferenz.

Was wir in Finance & Operations schreiben

Verkaufsauftrag (aus Bestellungen)

1. Workist legt den Auftragskopf an: Debitor, Bestellnummer als Bestellanforderung des Kunden, Lieferadresse, Kundenkontakt und Lieferdatum.
2. Workist legt die Positionen an: Artikelnummer, Menge, Einheit, Produktdimensionen aus den Artikel-Stammdaten und Lieferdatum. Preise ermittelt F&O selbst.
3. Workist hängt das Bestelldokument (PDF) und, bei E-Mail-Eingang, die Original-E-Mail (.eml) an den Auftrag.

Auf Wunsch hält Workist jeden Auftrag in F&O an (IsSalesProcessingStopped), damit er vor der Weiterverarbeitung geprüft wird.

Verkaufsangebot (aus Anfragen)

Workist legt den Angebotskopf mit dem Debitor an und danach die Positionen mit Artikelnummer, Menge, Einheit und Produktdimensionen.

Daten im Detail

• Lieferdaten überträgt Workist nur, wenn das Feld im Kanal aktiviert ist. Liegt ein Lieferdatum in der Vergangenheit, setzt Workist das heutige Datum, weil F&O Daten in der Vergangenheit ablehnt.
• Die juristische Person (Data Area ID) nimmt Workist aus den Kunden-Stammdaten, sonst aus der Integration.
• Als Referenz am Beleg in der Workbench speichert Workist die Auftrags- bzw. Angebotsnummer aus F&O. Über In externer Anwendung öffnen springen Sie direkt zum Auftrag bzw. Angebot in F&O.

Einrichtung in der Workbench

1. Legen Sie die App-Registrierung in Microsoft Entra ID an und geben Sie die App in F&O frei (siehe Voraussetzungen).

2. Öffnen Sie in der Workbench Einstellungen → Geschäftssysteme (ERP) → Integrationen und klicken Sie bei Microsoft Dynamics 365 Finance and Operations auf Verbinden.

3. Tragen Sie die Verbindung ein:

   Feld	Inhalt
   Name der Integration	frei wählbar
   Tenant-ID	ID Ihres Entra-ID-Mandanten
   Umgebungs-URL	URL Ihrer F&O-Umgebung
   API Data URL (optional)	Adresse eines API-Gateways vor F&O; leer lassen, wenn Workist direkt auf die Umgebung zugreift
   Client-ID (in der deutschen Oberfläche „Mandanten-ID (Anwendungs-ID)“), Client-Secret	aus der App-Registrierung
   Datenbereichs-ID	juristische Person, zum Beispiel usmf
   Bestellungskanäle	Kanäle, deren Bestellungen als Verkaufsaufträge angelegt werden
   Kanäle für Angebotsanfragen	Kanäle, deren Anfragen als Verkaufsangebote angelegt werden

4. Optional:

   Option	Wirkung
   Nur Artikel importieren, bei denen IsStockedProduct auf "Ja" gesetzt ist	liest nur Lagerartikel
   Nur Artikel importieren, bei denen sowohl SalesUnitSymbol als auch InventoryUnitSymbol gesetzt sind	liest nur Produkte mit Verkaufs- und Lagereinheit
   Articles have multiple versions	für Produkte mit mehreren Versionen: Workist nutzt die versionierte Produktnummer als Artikelnummer und überträgt die Artikelnummer 2
   Sales order header entity	V2 (Standard) oder V4; V4 kennt zusätzlich Auftragserfasser und Retail-Kanal
   Order taker personnel number, Retail channel RecId	Personalnummer des Auftragserfassers bzw. Retail-Kanal für jeden Auftrag (nur mit V4)
   Put every pushed sales order on hold in F&O	setzt jeden Auftrag auf angehalten
   Delete the sales order again if creating its lines fails	Standard: an. Siehe Fehlerbehandlung
   Delete the whole sales order if uploading an attachment (PDF/email) fails	Standard: aus. Siehe Fehlerbehandlung
   Disable master data transfer	Workist liest keine Stammdaten aus F&O, weder geplant noch auf Knopfdruck

5. Klicken Sie auf Erstellen. Mit Stammdaten Update starten laden Sie die Stammdaten sofort.

Wie die Stammdaten in den Kanälen ankommen und wie Workist die Kanäle umstellt, steht unter Was alle Konnektoren gemeinsam haben.

Fehlerbehandlung

Lehnt F&O einen Beleg ab, erscheint er wieder unter den offenen Belegen, mit der Meldung aus F&O. Workist versucht es nicht automatisch erneut. Beheben Sie die Ursache und schließen Sie den Beleg nach Erneut assistieren wieder ab.

• Bestellung ohne Kundennummer: Workist überträgt sie nicht und meldet den Fehler am Beleg.
• Fehler beim Anlegen einer Position: Workist versucht alle Positionen und meldet jede fehlgeschlagene Position mit Artikelnummer. Danach löscht Workist den Auftrag wieder. Ist „Delete the sales order again if creating its lines fails“ aus, bleibt der unvollständige Auftrag in F&O stehen und seine Nummer steht am Beleg. Vervollständigen oder löschen Sie ihn dann in F&O, bevor Sie die Bestellung erneut abschließen.
• Fehler beim Anhängen von PDF oder E-Mail: Im Standard bleibt der Auftrag bestehen und der Beleg gilt als übertragen; die Meldung steht am Beleg. Ist „Delete the whole sales order if uploading an attachment (PDF/email) fails“ an, löscht Workist den Auftrag und markiert den Beleg als fehlgeschlagen.
• Kann Workist einen Auftrag nicht wieder löschen, steht ein Hinweis mit der Auftragsnummer am Beleg. Entfernen Sie den Auftrag dann von Hand.
• Fehlende Berechtigung: Meldet F&O fehlende Rechte, steht das am Beleg. Ein erneuter Versuch hilft erst, wenn der Benutzer der App die Rechte hat.

Einschränkungen

• Verkaufsangebote legt Workist derzeit mit der Währung USD und der Sprache en-US an.
• Scheitert eine Angebotsposition, löscht Workist das bereits angelegte Verkaufsangebot nicht. Es bleibt unvollständig in F&O stehen.
• Workist prüft vor dem Anlegen nicht, ob es zur Bestellung schon einen Auftrag gibt. Wird eine Bestellung erneut abgeschlossen, entsteht ein weiterer Auftrag.

Feldreferenz

Gelesene Felder

Kunden

Workist-Spalte	Aus Finance & Operations
client_id1	CustomerAccount
client_id2	PartyNumber
client_contact_person1	FirstName + LastName der ersten Kontaktperson des Debitors
company_name	OrganizationName
address1	AddressStreet
zip_code	AddressZipCode
city	AddressCity
country	AddressCountryRegionId
extra_data	dataAreaId, EmployeeResponsibleNumber

Kundenkontakte

Workist-Spalte	Aus Finance & Operations
partition_id	Debitorenkonto, dem die Kontaktperson zugeordnet ist (CustomerAccountNumber)
contact_id	ContactPersonId – sonst ContactPersonPartyNumber
first_name	FirstName
last_name	LastName
phone	PrimaryPhoneNumber
email	PrimaryEmailAddress

Lieferadressen

Workist-Spalte	Aus Finance & Operations
partition_id	CustomerAccountNumber
address_id1	AddressLocationId
name	AddressDescription
address1	AddressStreet
zip_code	AddressZipCode
city	AddressCity
country	AddressCountryRegionId

Artikel

Workist-Spalte	Aus Finance & Operations
article_id1	ItemNumber; mit „Articles have multiple versions“: ProductNumber
article_id2	ProductNumber; mit „Articles have multiple versions“: ItemNumber
description	ProductName, ergänzt um Größe, Farbe, Stil und Version, wenn vorhanden
description_boosted	ProductDescription
gross_price	SalesPrice
order_units	SalesUnitSymbol
sales_units	SalesUnitSymbol
extra_data	Produktdimensionen ProductSizeId, ProductColorId, ProductStyleId, ProductVersionId, ProductConfigurationId (gehen in die Auftragsposition) sowie CurrencyCode, SalesUnitSymbol, SalesPrice, InventoryUnitSymbol, UnitCost, IsStockedProduct

Kundenspezifische Artikelnummern

Workist-Spalte	Aus Finance & Operations
partition_id	CustomerAccountNumber
article_id1	ItemNumber
article_id2	CustomerProductNumber
description	CustomerProductDescription
extra_data	ProductSizeId, ProductColorId, ProductVersionId, ProductStyleId, ProductConfigurationId, dataAreaId

Geschriebene Felder

Aufgeführt sind die Felder, die Workist befüllt. Auftrags- und Angebotsnummer, Preise, Summen und alle übrigen Felder setzt F&O selbst.

Verkaufsauftrag – Kopf

Feld	Inhalt
OrderingCustomerAccountNumber	Kunde (Kundennummer)
dataAreaId	Data Area ID aus den Kunden-Stammdaten – sonst „Data Area ID“ der Integration
DeliveryAddressLocationId	Lieferadresse (Adress-ID aus den Stammdaten)
RequestedShippingDate	Lieferdatum (Kopf); ein Datum in der Vergangenheit wird durch das heutige ersetzt
ContactPersonId	Kundenkontakt, wenn zugeordnet
CustomerRequisitionNumber	Bestellnummer
IsSalesProcessingStopped	Yes, wenn „Put every pushed sales order on hold“ aktiv ist – sonst nicht gesendet
OrderTakerPersonnelNumber	„Order taker personnel number“ (nur mit Kopf-Entität V4)
RetailChannelTable	„Retail channel RecId“ (nur mit Kopf-Entität V4)

Verkaufsauftrag – Positionen

Feld	Inhalt
ItemNumber	Artikelnummer (mit „Articles have multiple versions“: Artikelnummer 2)
OrderedSalesQuantity	Menge
SalesUnitSymbol	Einheit
ProductSizeId ProductColorId ProductStyleId ProductVersionId ProductConfigurationId	Produktdimension aus den Artikel-Stammdaten
RequestedShippingDate	Lieferdatum der Position – sonst Lieferdatum des Kopfs

Verkaufsangebot – Kopf

Feld	Inhalt
dataAreaId	Data Area ID aus den Kunden-Stammdaten – sonst „Data Area ID“ der Integration
RequestingCustomerAccountNumber	Kunde (Kundennummer)
CurrencyCode	fest: USD
LanguageId	fest: en-US

Verkaufsangebot – Positionen

Feld	Inhalt
LineCreationSequenceNumber	Position (fortlaufend ab 1)
ItemNumber	Artikelnummer (mit „Articles have multiple versions“: Artikelnummer 2)
RequestedSalesQuantity	Menge
SalesUnitSymbol	Einheit
ProductColorId ProductSizeId ProductStyleId ProductVersionId ProductConfigurationId	Produktdimension aus den Artikel-Stammdaten