Microsoft Dynamics 365 Finance & Operations

Workist connects to your environment through the data entities of Dynamics 365 Finance & Operations (F&O). Workist reads customers and released products as master data, creates completed orders as sales orders and requests for quotation as sales quotations. Nothing is installed in F&O.

Overview

Prerequisites

• An app registration in Microsoft Entra ID with a client secret. Workist uses it to sign in without user interaction.
• The app is enabled as an application in F&O and mapped to a user that may use these data entities:
  • read: CustomersV3, ContactPersons, CDSCustomerContactPersons, CustomerPostalAddresses, CDSReleasedDistinctProducts, CustomerProductDescriptionsV2
  • create: SalesOrderHeadersV2 or SalesOrderHeadersV4, SalesOrderLines, SalesOrderHeaderDocumentAttachmentsV2, SalesQuotationHeaders, SalesQuotationLines
  • delete: SalesOrderHeadersV2 or SalesOrderHeadersV4, so that Workist can roll back an incomplete order
• Workist must be able to reach your F&O environment over the internet, directly or through an API gateway.

Data flow

Direction	Content	When
F&O → Workist	Customers, contact persons, postal addresses, released products, external item numbers	daily at 06:00 German time and on demand
Workist → F&O	Sales order with lines, order document (PDF) and original email	as soon as an order is completed
Workist → F&O	Sales quotation with lines	as soon as a request for quotation is completed

What we read from Finance & Operations

Master data in Workist	Source in Finance & Operations	Data entities
Customers	Customers	CustomersV3, ContactPersons, CDSCustomerContactPersons
Customer contacts	Customer contact persons	ContactPersons, CDSCustomerContactPersons
Delivery addresses	Customer postal addresses	CustomerPostalAddresses
Articles	Released products	CDSReleasedDistinctProducts
Customer-specific item numbers	Customer external item numbers (assigned to a single customer, not to customer groups)	CustomerProductDescriptionsV2

• If a data area ID is set in the integration, Workist only reads that legal entity. Without a data area ID, Workist reads all of them.
• The integration's options narrow down the products: only stocked products (IsStockedProduct = Yes) and only products with both a sales and an inventory unit.
• Workist does not read invoice addresses, unit conversions, framework agreements or quotes from F&O.

The field reference lists every field Workist takes over.

What we write to Finance & Operations

Sales order (from orders)

1. Workist creates the order header: customer, order number as the customer requisition, delivery address, customer contact and delivery date.
2. Workist creates the lines: item number, quantity, unit, product dimensions from the article master data and delivery date. F&O determines the prices itself.
3. Workist attaches the order document (PDF) and, for documents received by email, the original email (.eml) to the order.

On request, Workist puts every order on hold in F&O (IsSalesProcessingStopped) so it is reviewed before further processing.

Sales quotation (from requests for quotation)

Workist creates the quotation header with the customer and then the lines with item number, quantity, unit and product dimensions.

Data in detail

• Workist only transfers delivery dates when the field is enabled in the channel. If a delivery date is in the past, Workist sets today's date, because F&O rejects dates in the past.
• Workist takes the legal entity (data area ID) from the customer master data, else from the integration.
• As the reference on the document in the Workbench, Workist stores the order or quotation number from F&O. Open in external application takes you straight to the order or quotation in F&O.

Setup in the Workbench

1. Create the app registration in Microsoft Entra ID and enable the app in F&O (see Prerequisites).

2. In the Workbench, open Settings → Business Systems (ERP) → Integrations and click Connect next to Microsoft Dynamics 365 Finance and Operations.

3. Enter the connection:

   Field	Content
   Integration Name	any name
   Tenant ID	ID of your Entra ID tenant
   Environment URL	URL of your F&O environment
   API Data URL (optional)	address of an API gateway in front of F&O; leave empty if Workist accesses the environment directly
   Client ID (Application ID), Client Secret	from the app registration
   Data Area ID	legal entity, for example usmf
   Order Channels	channels whose orders are created as sales orders
   RFQ Channels	channels whose requests for quotation are created as sales quotations

4. Optional:

   Option	Effect
   Only import articles where IsStockedProduct is 'Yes'	reads stocked products only
   Only import articles that have both SalesUnitSymbol and InventoryUnitSymbol set	reads products with a sales and an inventory unit only
   Articles have multiple versions	for products with several versions: Workist uses the versioned product number as the item number and transfers part number 2
   Sales order header entity	V2 (default) or V4; V4 also knows the order taker and the retail channel
   Order taker personnel number, Retail channel RecId	order taker's personnel number or retail channel for every order (V4 only)
   Put every pushed sales order on hold in F&O	puts every order on hold
   Delete the sales order again if creating its lines fails	default: on. See Error handling
   Delete the whole sales order if uploading an attachment (PDF/email) fails	default: off. See Error handling
   Disable master data transfer	Workist reads no master data from F&O, neither scheduled nor on demand

5. Click Create. Trigger master data update loads the master data right away.

How the master data reaches the channels and how Workist switches the channels over is described under What all connectors have in common.

Error handling

If F&O rejects a document, it appears again among the open documents, with the message from F&O. Workist does not retry automatically. Fix the cause and complete the document again after Reopen for assistance.

• Order without a customer number: Workist does not transfer it and reports the error on the document.
• Error creating a line: Workist tries all lines and reports every failed line with its item number. Workist then deletes the order again. If "Delete the sales order again if creating its lines fails" is off, the incomplete order stays in F&O and its number is shown on the document. Complete or delete it in F&O before you complete the order again.
• Error attaching the PDF or email: by default, the order stays and the document counts as transferred; the message is shown on the document. If "Delete the whole sales order if uploading an attachment (PDF/email) fails" is on, Workist deletes the order and marks the document as failed.
• If Workist cannot delete an order again, a note with the order number is shown on the document. Remove the order manually.
• Missing permission: if F&O reports missing rights, the document says so. A new attempt only helps once the app's user has the rights.

Limitations

• Workist currently creates sales quotations with currency USD and language en-US.
• If a quotation line fails, Workist does not delete the sales quotation it already created. It stays incomplete in F&O.
• Workist does not check whether an order already exists for the document before creating one. If an order is completed again, another order is created.

Field reference

Fields read

Customers

Workist column	From Finance & Operations
client_id1	CustomerAccount
client_id2	PartyNumber
client_contact_person1	FirstName + LastName of the customer's first contact person
company_name	OrganizationName
address1	AddressStreet
zip_code	AddressZipCode
city	AddressCity
country	AddressCountryRegionId
extra_data	dataAreaId, EmployeeResponsibleNumber

Customer contacts

Workist column	From Finance & Operations
partition_id	Customer account the contact person belongs to (CustomerAccountNumber)
contact_id	ContactPersonId – else ContactPersonPartyNumber
first_name	FirstName
last_name	LastName
phone	PrimaryPhoneNumber
email	PrimaryEmailAddress

Delivery addresses

Workist column	From Finance & Operations
partition_id	CustomerAccountNumber
address_id1	AddressLocationId
name	AddressDescription
address1	AddressStreet
zip_code	AddressZipCode
city	AddressCity
country	AddressCountryRegionId

Articles

Workist column	From Finance & Operations
article_id1	ItemNumber; with “Articles have multiple versions”: ProductNumber
article_id2	ProductNumber; with “Articles have multiple versions”: ItemNumber
description	ProductName, extended by size, colour, style and version if present
description_boosted	ProductDescription
gross_price	SalesPrice
order_units	SalesUnitSymbol
sales_units	SalesUnitSymbol
extra_data	Product dimensions ProductSizeId, ProductColorId, ProductStyleId, ProductVersionId, ProductConfigurationId (passed on to the order line) plus CurrencyCode, SalesUnitSymbol, SalesPrice, InventoryUnitSymbol, UnitCost, IsStockedProduct

Customer-specific item numbers

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

Fields written

Listed are the fields Workist fills. F&O sets the order and quotation number, prices, totals and all other fields itself.

Sales order – header

Field	Content
OrderingCustomerAccountNumber	Client (customer number)
dataAreaId	Data area ID from the customer master data – else the integration's “Data Area ID”
DeliveryAddressLocationId	Delivery address (address ID from master data)
RequestedShippingDate	Delivery date (header); a date in the past is replaced by today
ContactPersonId	Customer contact, if matched
CustomerRequisitionNumber	Order number
IsSalesProcessingStopped	Yes when “Put every pushed sales order on hold” is on – else not sent
OrderTakerPersonnelNumber	“Order taker personnel number” (only with header entity V4)
RetailChannelTable	“Retail channel RecId” (only with header entity V4)

Sales order – lines

Field	Content
ItemNumber	Item number (with “Articles have multiple versions”: part number 2)
OrderedSalesQuantity	Quantity
SalesUnitSymbol	Unit
ProductSizeId ProductColorId ProductStyleId ProductVersionId ProductConfigurationId	Product dimension from the article master data
RequestedShippingDate	Line delivery date – else the header delivery date

Sales quotation – header

Field	Content
dataAreaId	Data area ID from the customer master data – else the integration's “Data Area ID”
RequestingCustomerAccountNumber	Client (customer number)
CurrencyCode	fixed: USD
LanguageId	fixed: en-US

Sales quotation – lines

Field	Content
LineCreationSequenceNumber	Position (counting from 1)
ItemNumber	Item number (with “Articles have multiple versions”: part number 2)
RequestedSalesQuantity	Quantity
SalesUnitSymbol	Unit
ProductColorId ProductSizeId ProductStyleId ProductVersionId ProductConfigurationId	Product dimension from the article master data