Skip to main content
This guide explains how to configure Stuut’s Microsoft Dynamics 365 Finance & Operations integration. Stuut signs in to Finance & Operations with OAuth 2.0 as a dedicated user and reads the standard OData data entities. Once connected, Stuut imports historical data and then syncs hourly. The guide has two parts:
  • Collections (steps 1–8): what every customer sets up. Stuut only reads from Finance & Operations.
  • Cash Application write-back (steps 9–13): optional. Stuut posts the payments it applies as customer payment journals and settles the invoices. This needs a Stuut extension installed in your environment and a second security role.
This covers Finance & Operations only. Business Central is a different product with a different Stuut connector, and these settings do not apply to it.

What Stuut reads and writes

Part 1: Collections

Stuut is a multi-tenant Microsoft Entra ID application, and a Global Administrator grants admin consent to it once. Stuut then signs in as a user with the delegated user_impersonation scope and calls Finance & Operations only. It does not call Microsoft Graph. You do not need to change any Entra ID API permissions, now or for Cash Application later. What Stuut can see and do is decided entirely by the security roles of the Finance & Operations user it signs in as (steps 2 and 3).
The consent screen is shared across Stuut’s Microsoft integrations, so it may list mail permissions this connector never uses.

2. Create a dedicated Dynamics user

Create or identify a dedicated Finance & Operations user for Stuut, for example collections@yourcompany.com, rather than an individual administrator’s everyday account. Stuut signs in as this user, so the data it can read is exactly the data this user can read. Give the user the standard System user role plus the Stuut role from step 3. Do not give it System administrator.

3. Create the Stuut Integration – Collections role

Create a security role named Stuut Integration – Collections and give it View (read) access on the entities below. A denied entity fails the whole model rather than degrading it, so grant all of them.
If you are also installing the Stuut extension for Cash Application (step 9), you can skip building this role by hand. The extension ships a ready-made role with the same name and exactly these entities.
To build the role:
  1. Go to System administration → Security → Security configuration.
  2. On the Roles tab, click Create new and name the role.
  3. Under Privileges, add the auto-generated View privilege of each entity above. No duty is needed.
  4. Click Publish all.
  5. Go to System administration → Users → Users, open the Stuut user and click Assign roles. Add the role.
  6. With the role selected, click Assign organizations → Grant access to specific organizations individually, and select only the legal entity that the Stuut connection will use. Do not leave it at all organizations.
Sandboxes do not share security configuration with production. Apply the same role in both environments, and connect the sandbox first if you have one.

4. Two entities that are easy to miss

The last two rows above are optional for the sync to run, but leaving them out loses data without any error. The affected models still report Done, so the gap does not show up in the sync status. CustomerElectronicAddresses — needed if your customer email addresses live on the customer Contact information grid. Without it Stuut reads only CustomersV3.PrimaryContactEmail, which Dynamics fills only when an email row is marked Primary on that grid. A customer with three email addresses and the Primary marker on a phone number reaches Stuut with no address at all, and cannot be emailed. Employees — needed if you want Stuut to assign a collector to each customer. CustomersV3.EmployeeResponsibleNumber holds a personnel number, not a name or address, so Stuut cannot match it to a user on its own. Without this entity, supply a list mapping each personnel number to a name and email instead.

5. Collect the connection settings

Sandboxes use their own host name.
The legal entity is fixed once the connection is created. Changing it means removing the connection and building it again, so confirm which one is in scope first. If you need several legal entities, each one gets its own connection.

6. Connect Dynamics 365 to Stuut

Log in to Stuut and navigate to General Settings → Connectors → All Connectors. Choose Microsoft Dynamics 365 Finance & Operations from the list. Click Add and follow the instructions in the window: enter the instance URL, sign in as the dedicated Dynamics user, then choose the legal entity.

7. Validate the connection

Click Check Health in the top right. If everything was set up correctly the connection shows as Linked. The Overview tab reports each model separately, so Customers, Contacts, Invoices, Credit Memos and Payments each show Done once the import finishes. The Logs tab lists every request including failures, which is the fastest way to find an entity the role is still missing.

8. Optional: invoice PDFs

Stuut attaches the invoice PDF to collections email when it can find one. It reads the attachment on the sales order named Customer invoice, which is what Print Management writes when Save to Attachments is enabled for the customer invoice report.
If your process files a scanned or signed copy somewhere else instead, tell your Stuut contact where it lives. Attachments held against the customer invoice journal are not exposed by the standard data entities and need a different approach. Stuut’s user will also need View on that entity, in addition to the Collections role.

Part 2: Cash Application write-back (optional)

With write-back on, a payment approved in Stuut is posted to Finance & Operations automatically. Nobody needs to open or post a journal in Finance & Operations. Standard OData cannot post a journal, so Stuut posts through a small extension, the StuutPaymentConnector model, installed in your environment. Stuut never writes through the standard data entities. Complete Part 1 first. Collections keeps working on its own whether or not you go on to Part 2.

9. Install the Stuut extension

Stuut provides the StuutPaymentConnector deployable package. Your Dynamics administrator or implementation partner installs it through your normal release process:
  • Lifecycle Services (LCS) for LCS-managed environments.
  • Power Platform admin center for unified (Power Platform-hosted) environments.
Install it in your sandbox first, then production. The package adds a custom service, StuutPaymentService, and two security roles. It does not change any standard Finance & Operations object.

10. Assign the Cash Application roles

Give the Stuut user these roles, each scoped to the connection’s legal entity only (Assign organizations, as in step 3):
Do not skip Accounts receivable payments clerk. Without it the payment journal still posts, but Finance & Operations does not settle the marked invoice, so both the payment and the invoice remain open. Stuut detects this and flags the payment (see How a payment is posted), but every payment will need settling by hand until the role is added.

11. Choose a customer payment journal

Stuut posts into a journal name you choose. Use an existing journal name with journal type Customer payment under General ledger → Journal setup → Journal names (often CustPay), or create one for Stuut. Set New voucher to One voucher number only. Send the journal name to your Stuut contact.

12. Map your bank accounts in Stuut

In Stuut, go to General Settings → Connectors → Bank accounts and link each bank account Stuut sees deposits on to its Finance & Operations bank account. The bank account is the offset on every journal line, so a deposit on an unmapped account cannot be posted.

13. Turn write-back on

Write-back is off on every connection by default. Once steps 9–12 are done, your Stuut contact turns it on and checks that Stuut can reach the extension.

How a payment is posted

For each approved deposit, Stuut:
  1. Creates one customer payment journal in your journal name.
  2. Adds one line per customer payment, dated with the deposit date, with the bank account as the offset.
  3. Marks each invoice the payment applies to, for the applied amount.
  4. Posts the journal. Posting settles the marked invoices in the same step.
  5. Checks Finance & Operations’ settlement records to confirm each invoice was settled for its applied amount, then records the voucher on the payment in Stuut.
If anything fails before posting, Stuut deletes the unposted journal so nothing is left half-done, and shows the error on the payment in Stuut. If the journal posts but an invoice is not settled, or is settled for less than the applied amount, Stuut keeps the voucher on the payment, moves the payment back out of approved, and shows an error naming each open invoice with its applied and settled amounts. Stuut never posts that journal again or creates a second one. Settle the invoices against the voucher in Finance & Operations; the next sync, or approving the payment again, then completes it in Stuut.

What Stuut does not post

Stuut posts payments applied in full to invoices. It refuses the following and shows the reason on the payment, so your team can apply it in Finance & Operations directly:
  • Payments that include a credit memo or an adjustment (for example a short-pay or bank fee write-off).
  • Payments with an unapplied remainder. Stuut does not post a balance on account.
  • Payments in a different currency from the invoice.

A few things to know

  • Posting date. The journal is dated with the deposit date. A closed or on-hold fiscal period for that date stops the post.
  • Inactive bank accounts. Finance & Operations does not check bank account status on this path, so an inactive bank account does not stop a post. Keep the mapping in step 12 current.
  • Idle environments are slow to wake. After an environment has been idle, the first call to the extension can take several minutes. Stuut waits for it and confirms the result, so this delays a post but does not fail it.

Troubleshooting