Support

Connect Business Central

For: Business Central admins

Connect OneShift to Dynamics 365 Business Central so an approved statement becomes a draft sales invoice with the Excel export attached. You register an app in Microsoft Entra, add it in Business Central, then enter the details in OneShift.

01

Before you start

The connector uses the standard Business Central API only, so nothing needs installing in Business Central. One workspace has one active invoicing connector.

What you need

  • Someone who can register apps and grant admin consent in Microsoft Entra ID for your Business Central tenant.
  • Someone who can manage Microsoft Entra applications and permission sets in Business Central.
  • A OneShift workspace manager. The connector is set up under Workspace → Connectors, which only workspace managers can open.

The steps

  1. Register an app in Microsoft Entra ID and grant it the Business Central permission.
  2. In Business Central, add the app and assign two permission sets.
  3. In OneShift, enter the tenant, client and environment, then test the connection.
  4. Save, then choose the company and the item or G/L account for the invoice line, and save again.
Statements are invoiced in the company’s own currency. OneShift does not send a currency code, so the invoice is created in the Business Central company’s local currency. Testing the connection with a company selected checks that this currency matches your workspace currency.
02

Register the app in Microsoft Entra

OneShift signs in to Business Central as an application, not as a person, so it needs an app registration in your Business Central tenant.

  1. In Microsoft Entra ID, register an app for your Business Central tenant.
  2. Under API permissions, add the application permissionDynamics 365 Business Central / API.ReadWrite.All.
  3. Have an admin consent to it.
  4. Note the app’s Client ID and the Tenant ID. You enter both in OneShift later.

Create a client secret for the app and copy its value; you enter it in OneShift inEnter the connection in OneShift.

03

Add the app in Business Central

Consent in Entra is not enough on its own. Business Central has to know the app and give it rights.

  1. In Business Central, add the app under Microsoft Entra applications.
  2. Assign it these permission sets:
    Permission setWhat it covers
    D365 BASICExecute permission for the API pages.
    D365 SALES DOC, EDITCreating and editing sales documents, which is what a draft sales invoice is.
Both permission sets are needed. If the Entra permission is granted but the app is missing from Microsoft Entra applications in Business Central, OneShift can sign in but Business Central refuses its requests.
04

Enter the connection in OneShift

In OneShift, open Workspace → Connectors and expand the Business Central card (“Send approved statements as draft sales invoices.”). A pill on the card shows whether the connector is fully configured.

FieldWhat to enter
Tenant IDThe Microsoft Entra tenant ID of your Business Central tenant.
Client IDThe application (client) ID of the app you registered.
Client secretPaste the secret you created. The placeholder reads “Leave empty to use managed identity”, but an empty secret only works when the app trusts OneShift’s own identity with a federated credential, which an app you register in your tenant does not have. Without a secret the connection fails.
Environment nameThe name of the Business Central environment, for example Production. OneShift sends requests to that environment of Business Central’s online API.

Tenant ID, Client ID and Environment name are required. The client secret is not, and OneShift does not ask for one.

Test and save

  1. Select Test connection. “Connection successful.” means OneShift could sign in and list your companies. A failure shows the reason; seeTroubleshooting.
  2. Select Save. “Invoicing connector settings saved.” appears.
Save before choosing the company. The Company, Line type and Item / Account pickers stay disabled until credentials are saved, because they load from Business Central using the saved credentials.
05

Choose the company and invoice line

After the credentials are saved, the Invoice line part of the card lets you pick the company and the item or G/L account used on every invoice line.

FieldWhat to choose
CompanyPick from the companies in your environment (“Select company…”). Changing the company clears the item or account.
Line typeItem or G/L Account. Changing it clears the item or account.
Item / AccountPick one entry, shown as number and description. The list shows only entries of the chosen line type.
  1. Select the Company, the Line type, then the Item / Account.
  2. Optional: select Test connection again. With a company selected, it also checks that the company’s currency matches your workspace currency.
  3. Select Save. Save stores the whole connector, credentials and invoice line together.

The connector counts as fully configured only when credentials, company, line type and item or account are all saved. Until then invoicing actions stay unavailable.

Every invoice gets one line with this item or account, quantity 1, and the statement’s billable total as the unit price.

06

Sending statements to invoicing

The day-to-day flow is in the Billing guide under Statements. This is what the connector does behind it.

What “Send to invoicing” does

  1. Checks the statement and the customer, as listed below.
  2. Creates a draft sales invoice in your Business Central company.
  3. Adds the single invoice line.
  4. Attaches the statement’s Excel export to the invoice.
  5. Stores the invoice number on the statement and sets it to Invoiced.

What must be true first

  • The statement is Approved.
  • The connector is fully configured.
  • The customer has a “Customer No.” in its settings, and a customer with that number exists in your Business Central company.
  • The billable total is above zero. A zero total is never invoiced.
  • The statement’s currency matches the Business Central company’s currency. If the company reports no currency, the check passes.

Retrying and reverting

  • If a step fails, OneShift tries to delete the draft it created. If that also fails, the statement stays Approved and a retry resumes the existing invoice instead of making a second one.
  • Revert (workspace managers) deletes the draft invoice and returns the statement to Approved. It works while the invoice is still unposted, or if someone already deleted it in Business Central.

How Business Central statuses are read

Business Central statusIn OneShift
Draft, In ReviewStill a draft: it can be resumed and reverted.
Open, Paid, Canceled, CorrectivePosted: it cannot be reverted from OneShift. Correct it in Business Central, for example with a credit memo.
A statement marked as invoiced by hand cannot be reverted. There is no invoice in Business Central to delete, so “This statement was marked invoiced manually and cannot be reverted.”

The Excel export is attached to the invoice’s Attachments in Business Central. Business Central’s own behavior carries it over when the invoice is posted.

07

Troubleshooting

Messages come either from OneShift or from Business Central itself, which OneShift repeats as it received them.

When testing the connection

A failed test starts with “Could not connect to the invoicing system.” followed by the reason.

Message or symptomWhat it means and what to do
Authentication with the invoicing system failed: …Entra refused the sign-in. Check the Tenant ID, Client ID and client secret, and that admin consent was granted for API.ReadWrite.All.
Could not reach Business Central: …The request did not get through. Check the Environment name and try again.
The request to Business Central timed out.Business Central did not answer in time. Try again.
Business Central request failed with status … or a message from Business CentralBusiness Central refused the request. Common causes: the app is not listed or lacks a permission set. Check that the app is listed under Microsoft Entra applications with D365 BASIC and D365 SALES DOC, EDIT, and that the environment name is right.
The company currency (…) does not match the workspace currency (…). Invoices would be created in the wrong currency.Choose a company whose currency is your workspace currency, or change the workspace currency.
Tenant ID, Client ID and Environment name are required.Fill in all three fields.

When sending a statement

MessageWhat to do
Only approved statements can be sent to invoicing.Approve the statement first.
Invoicing connector is not configured.Finish the connector: credentials, company, line type and item or account must all be saved.
Customer has no external invoicing number. Set it in customer settings before sending.Set “Customer No.” in the customer’s settings to the customer’s number in Business Central.
Customer number ‘…’ was not found in the invoicing system.The number does not match a customer in the selected Business Central company. Correct the number or the selected company.
Nothing to invoice: the statement total is zero.A zero total, for example a prepaid month with no overage, is never invoiced.
Statement currency ‘…’ does not match the invoicing company’s currency ‘…’.The statement and the Business Central company use different currencies. Invoicing is not possible until they match.
Invoicing connector has no company configured.Choose a company in the connector and save.
The invoicing system did not return an invoice number for the created invoice.The statement stays Approved. Try again; the retry resumes the invoice that was created.
The statement was modified by another request while sending. Refresh and retry.Someone changed the statement at the same time. Reload it and send again.
The invoice has already been posted in the invoicing system and cannot be reverted.When reverting. The invoice is posted in Business Central; handle it there.

Other failures

  • The Company or Item / Account list is empty or will not load. The toast reads “Failed to load companies.” or “Failed to load items/accounts.” Check that the credentials are saved and still work.
  • Business Central rejects the attachment or a line. OneShift passes on Business Central’s own error text. The attachment step is described in the product’s design notes as not yet confirmed against every Business Central setup, so report persistent attachment errors to OneShift.