# 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](/docs/master-data/customers.md) | Debitoren | `CustomersV3`, `ContactPersons`, `CDSCustomerContactPersons` |
| [Kundenkontakte](/docs/master-data/customer-contacts.md) | Kontaktpersonen der Debitoren | `ContactPersons`, `CDSCustomerContactPersons` |
| [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Postadressen der Debitoren | `CustomerPostalAddresses` |
| [Artikel](/docs/master-data/articles.md) | Freigegebene Produkte | `CDSReleasedDistinctProducts` |
| [Kundenspezifische Artikelnummern](/docs/master-data/articles.md) | 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](#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](#überblick)).
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](#fehlerbehandlung) |
   | Delete the whole sales order if uploading an attachment (PDF/email) fails | Standard: aus. Siehe [Fehlerbehandlung](#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](/docs/data-exchange/connectors.md#common-behaviour).

## 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 |