Core for Dynamics 365 BC - en-US

Supported Microsoft Dynamics 365 Business Central versions

Microsoft Dynamics 365 Business Central integration with DEXPRO Core is possible from the following version onward, due to minimum technical requirements:

The prerequisite for operation is that the respective Microsoft Dynamics 365 Business Central version is still in regular (mainstream) support. Extended support is excluded.

DEXPRO Core is the shared base module for all DEXPRO apps (SQUEEZE, Breeze Interface, Advanced Workflow, Freeze, eInvoice Sender). Every one of those apps depends on DEXPRO Core, so the Core version installed must always be equal to or higher than the version required by the dependent app.

Licenses

DEXPRO Core is the free, shared base module that every DEXPRO app for Microsoft Dynamics 365 Business Central depends on. It is not sold on its own; you receive it automatically as part of the license for any DEXPRO app you purchase.

How licensing works

DEXPRO Core has no separate price and no standalone subscription. When you license one or more DEXPRO apps (for example SQUEEZE, Advanced Workflow, Freeze, or the eInvoice Sender), the Core module is licensed together with them at no additional cost. Because all DEXPRO apps require Core, it must always be installed and active alongside the app that uses it.

Cloud licensing and entitlements

On Business Central online (SaaS), access to DEXPRO Core objects is granted through entitlements that map to the Microsoft license SKUs (plans) assigned to a user. A user who already holds a qualifying Microsoft license automatically gains the corresponding access to DEXPRO Core objects, so no extra Core-specific license needs to be assigned.

DEXPRO Core ships entitlements for the following Microsoft license types:

Entitlements are handled automatically by the platform. As an administrator you only manage the Microsoft license plans assigned to each user in the Microsoft 365 admin center; the matching DEXPRO Core access follows from them.

On-premises licensing

On supported On-Premises deployments, access to DEXPRO Core objects follows the permissions granted by the DEXPRO app licensed for the installation, combined with the DEXPRO Core permission sets assigned to each user.

Obtaining the DEXPRO modules

DEXPRO apps for Microsoft Dynamics 365 Business Central are distributed through Microsoft AppSource and directly by DEXPRO Solutions GmbH. Whichever route you choose, the DEXPRO Core base module is installed automatically as a dependency.

From Microsoft AppSource

The DEXPRO apps are published on Microsoft AppSource, the official marketplace for Business Central extensions. To install an app:

Because every DEXPRO app depends on DEXPRO Core, the Core module is installed automatically in the same step. You do not need to search for or install Core separately.

From DEXPRO Solutions GmbH

You can also obtain the modules directly from DEXPRO Solutions GmbH, for example for On-Premises deployments or partner-managed installations. In this case you receive the app packages (.app files) and publish them to your environment in dependency order, with DEXPRO Core published first.

After installation

Once an app is installed and its setup has run, DEXPRO Core registers the module in its internal registry so that Core knows which DEXPRO modules are present and active. You can review and manage this registry in Core Setup.

Extension Management showing the installed DEXPRO apps

Prerequisites

Permission sets

DEXPRO Core ships a small set of permission sets that control who can configure the module and who can work with Core documents and rules day to day. Assign them to users in the same way as any other Business Central permission set.

Available permission sets

Two of the permission sets are intended for direct assignment to users. The third is an internal building block that is referenced only by the module's entitlements and is not meant to be assigned on its own.

Permission set Audience Rights
DEXPRO Core Admin Administrators and consultants who set up and maintain the module. Full Read, Insert, Modify, Delete (RIMD) on all DEXPRO Core tables, plus execute rights on all objects. Required to run setup, manage the DEXPRO Apps registry, configure the File Viewer and OAuth/OpenID connections, and create jobs.
DEXPRO Core User Day-to-day users who process documents and work with rules. Reduced rights on configuration tables (for example Core Setup and the DEXPRO Apps registry are read/modify but no delete), and full rights on operational data such as Core documents and rules. The OAuth 2.0 and OpenID connection settings are read-only — enough for features such as the File Viewer to request tokens — and their setup pages are not included, so connections and client secrets can only be maintained with DEXPRO Core Admin. Suitable for purchasing agents and processing clerks.
DEXPRO Core Objects - Exec Internal building block — not for direct assignment. Wildcard execute permission on the module's objects. Not included in the Admin and User sets, but referenced only by the module's entitlements, which make the module's objects available to licensed users. Assign the Admin or User set instead.

Permission set list filtered to the DEXPRO permission sets

Assigning a permission set

Assign DEXPRO Core Admin only to the people responsible for configuration. Regular processing users should receive DEXPRO Core User.

Do not assign DEXPRO Core Objects - Exec directly. It grants only execute rights and, on its own, does not give the data access users need. It exists only for the module's entitlements.

Core Setup

The Core Setup card is the central configuration page for the DEXPRO Core module. From here you control document numbering, logging, the HTTP timeout, the automatic cleanup of old documents, and the File Viewer, and you reach the other Core configuration pages.

You can open it from the Role Center or by searching for Core Setup (it is listed under the Administration usage category).

Core Setup card with its actions and FastTabs

Menu

The following actions are available on the Core Setup card:

FastTabs

Numbering

General

Cleanup

File Viewer (SharePoint Preview)

Automatic cleanup job

When Core Setup is initialized, a recurring Job Queue Entry is created automatically to keep the document list tidy. It runs every 720 minutes (twice a day), starting at 05:00, and deletes old Core documents whose status is Deleted, Closed, or Cancelled and that are older than the configured Cleanup Interval.

You can re-create the cleanup job at any time with the Create Jobs action if it was removed. See "Cleanup and Job Queue" for details.

If the user setting up Core does not have permission to manage Job Queue Entries, a message is shown and the cleanup job is not created. An administrator with Job Queue permission should then run Create Jobs.

DEXPRO Apps registry

The Core Setup card embeds the DEXPRO Apps part, which lists the installed DEXPRO modules and lets you activate or deactivate them. See the "DEXPRO Apps" page for details.

Copying the configuration to other companies

The Copy Configuration to Companies action opens a wizard that copies the DEXPRO Core configuration from the current company to one or more other companies in one run.

Copy Configuration to Companies wizard, welcome step

  1. Welcome — explains what the wizard does and warns: The existing configuration in the target companies will be replaced.
  2. Select Configuration Parts — choose which parts to copy:
    • Core Setup — copies the Core Setup including the Document Nos. number series. The number series is created in the target company if it does not exist there yet.
    • Custom Field Mappings — replaces the custom field mappings of every document class that has custom field mappings in the current company. Document classes without mappings here are left untouched in the target companies.
    • Generic Field Mappings — replaces the generic field mappings (Generic Additional Fields) in the target companies.
    Installed DEXPRO apps such as SQUEEZE and Breeze Interface can add their own setup to this list.
  3. Select Target Companies — use the assist button of the Target Companies field to select one or more companies. The current company cannot be a target.
  4. Review — check the selected parts and companies, then choose Next to start copying.
  5. Copy Completed — shows one result line per part, for example Core Setup: copied to 2 of 3 company(ies). A part with nothing to copy in the current company (for example no generic field mappings) is skipped and counted as 0. Choose Finish to close the wizard.

The wizard checks your input before it moves on:

Copying starts when you choose Next on the Review step and overwrites the selected parts in the target companies. Each company is saved as soon as it has been processed: if an error occurs, the wizard stays on the Review step, and the companies processed before the error keep the copied configuration.

DEXPRO Apps

The DEXPRO Apps registry lists every installed DEXPRO module and lets you activate or deactivate each one. It is embedded as a part on the Core Setup card and is how DEXPRO Core knows which modules are present and which are currently active.

{add screenshot of Core Setup here}

Purpose

Each DEXPRO app registers itself with Core when it is installed. The registry gives you a single place to see the installed modules and to turn their functionality on or off, without uninstalling anything.

Fields

Menu

Usage

When you toggle Active, Core updates the module's own setup table accordingly. This keeps the registry and the individual module setup in sync, so you can manage activation from one place.

Core Documents

The Core Documents list is the central place where all incoming DEXPRO Core documents are collected and tracked. Each line represents one document received through a DEXPRO app, together with its processing status and a link to the Business Central record it created.

You can open it from the Role Center or by searching for Core Documents (it is listed under the Documents usage category).

Core Documents list with document status and the Document Data FactBox

Columns

Editing and deletion

The list is designed to reflect what was received, so Insert and Modify are disabled — you do not create or change documents here manually. Delete is allowed only for documents in certain statuses.

If you try to delete a document in a status that does not permit it, Core shows a validation message: "You can only delete a Core Document if the Status is Deleted, Imported, Closed or Cancelled." Documents in other statuses are protected from deletion.

Deleted view

A separate Deleted view lets you review documents that have been marked as deleted, keeping the main list focused on active documents.

Drilldown to the created record

Use the drilldown on Linked-to Record Id to jump straight to the Business Central record that was created from the document — for example the purchase invoice or purchase order. This makes it easy to trace a document to its result.

FactBoxes

Document lifecycle

The Status field reflects where a document is in its lifecycle. The possible statuses are:

StatusMeaning
ImportedThe document has been received into Core but not yet transferred to a Business Central record.
TransferredThe document has been transferred and a Business Central record has been created.
ResynchronizeThe document is flagged to be synchronized again with its source.
FinishedProcessing of the document is complete.
ClosedThe document has been closed and is no longer actively processed.
DeletedThe document has been marked as deleted.
RejectedThe document was rejected during processing.
CancelledProcessing of the document was cancelled.
On HoldThe document is temporarily paused and awaits further action.
Custom ProcessingThe document is handled by custom, app-specific processing.

The set of statuses is extensible, so a downstream DEXPRO app can add its own status values where needed.

Document Class Setup

The Document Class Setup maps each Document Class to the process step that Core should run next for documents of that class. It lets you tailor how different kinds of documents flow through the DEXPRO apps.

Open the list from Core Setup (Document Class Setups action) or by searching for Document Class Setups.

Document Class Setup list

Concepts

Document Class

The Document Class classifies an incoming document. It is an extensible enum, so the available values depend on which DEXPRO apps are installed:

Next Process Step

The Next Process Step determines what happens to a document of a given class after it is received. It is also an extensible enum, so installed apps can add their own steps — for example, the Breeze Interface app contributes an additional value.

Document Class Setup card

Open a line to see the card for a single Document Class.

Document Class Setup card for Invoice / Credit Memo

Usage

Because both Document Class and Next Process Step are extensible, the values you see reflect the DEXPRO apps installed in your environment. Installing an app can add new classes and steps to choose from.

Field Mapping

Field mapping controls how data from an incoming document is written into Business Central records. DEXPRO Core offers three mapping surfaces, each for a different kind of field, so you can cover standard fields, arbitrary JSON fields, and custom app fields.

Open the mapping lists from Core Setup (Field Mapping action) or by searching for the individual pages.

Standard Field Mapping

The Field Mappings page maps source document fields to Business Central target tables and fields. Mappings are defined per Document Class and can apply to the document header or the document lines.

Use this when you need to map the well-known fields of a document class to their standard Business Central destinations.

Field Mappings list with source and target fields

Generic Additional Fields

The Generic Additional Fields page maps arbitrary JSON field names from the source data to a target table and field. This is useful when the source contains extra fields that are not part of the standard mapping.

Use this for ad hoc or additional source fields that you want to route into Business Central without a code change.

{add screenshot of Generic Additional Fields here}

Custom Field Mapping

The Custom Field Mapping page maps custom app fields in the range 50000-99999 to target fields. This is intended for fields added by other extensions (the customer/partner field range) that need to be populated from the source data.

Use this when your environment has custom fields that must be filled during document creation.

Custom Field Mapping page

Which mapping to use

Use caseMapping surface
Standard, well-known fields of a document class (header or line)Standard Field Mapping
Extra JSON fields present in the source dataGeneric Additional Fields
Custom fields (50000-99999) added by another extensionCustom Field Mapping

Use the Validate flag on Generic Additional Fields when the target field has validation logic that must run (for example to trigger dependent field updates). Leave it off to set the value directly.

Copying mappings to other companies

The Generic Additional Fields and Custom Field Mapping pages each have a Replace mapping in companies action that copies the mapping to other companies:

On the Custom Field Mapping page, only the mappings of the document class selected at the top of the page are replaced. To copy the Core Setup and both kinds of mappings in one step, use Copy Configuration to Companies on the Core Setup card.

OAuth 2.0 and OpenID Setup

DEXPRO Core provides shared authentication setup for the DEXPRO apps that call external services. Two setup lists are available: one for OAuth 2.0 client-credentials connections and one for OpenID Connect connections. Both keep secrets in Business Central isolated storage so they are never shown again after entry.

Purpose

Several DEXPRO features connect to external services — for example the Freeze archive, the SQUEEZE tenant, Digivoice, and Microsoft Graph. These connections need to authenticate. Instead of each app defining its own credentials, Core stores the connection settings centrally and issues the tokens the apps need.

DEXPRO OAuth 2.0 Setup Entries

The DEXPRO OAuth 2.0 Setup Entries page holds client-credentials connections. Each entry defines how Core obtains a token for a given service.

DEXPRO OAuth 2.0 Setup Entries list

Open ID Setup Entries

The Open ID Setup Entries page holds OpenID Connect connections.

Open ID Setup Entries list

Entering a secret

Secrets are entered through a dialog and written straight to isolated storage. They are used when Core requests tokens on behalf of the apps.

For security, secrets are never displayed again after they are entered. If a secret changes, re-enter it through the dialog — you cannot read the stored value back from the page.

Permissions

Of the DEXPRO Core permission sets, only DEXPRO Core Admin includes the DEXPRO OAuth 2.0 Setup Entries and Open ID Setup Entries pages and the dialog for entering a client secret. Only users with this permission set can therefore create, change or delete connections and enter secrets.

DEXPRO Core User grants read access to the stored connection settings only. This lets features such as the File Viewer request tokens for regular users without giving them access to the setup pages.

Prerequisites

File Viewer

The File Viewer lets users preview document attachments directly inside Business Central, on the standard attachment FactBoxes of document pages. It uploads the attachment to SharePoint/OneDrive through Microsoft Graph and shows the returned preview inline, so users can read a file without downloading it.

Purpose and business value

Processing incoming documents usually means checking the attached file (for example the original invoice PDF) while working on the Business Central record. The File Viewer removes the download-open-switch-back cycle by showing the file next to the record, which speeds up review and reduces errors.

Usage

{add screenshot of Document Attachment FactBox with File Viewer here}

How it works

When you preview an attachment, the file is uploaded to SharePoint/OneDrive via Microsoft Graph, and Graph returns a preview URL that Business Central renders inside the viewer control.

Setup

The File Viewer is enabled and configured from the File Viewer (SharePoint Preview) group on the Core Setup card. The recommended way to configure it is the File Viewer Setup Wizard, which walks you through the credentials, the connection test, and the SharePoint site.

Prerequisites

Error handling

When you enable the File Viewer, Core validates the prerequisites. If a required setting is missing (for example the credentials or the SharePoint site), enabling fails with an error and the viewer stays off until the missing information is provided.

File Viewer Setup Wizard

The File Viewer Setup Wizard is an assisted, multi-step guide that configures the File Viewer (SharePoint document preview) end to end. It collects the Microsoft Entra ID credentials, tests the connection to Microsoft Graph, sets the SharePoint site, and finally activates the viewer.

Launch it from the Core Setup card with the Setup File Viewer action.

File Viewer Setup wizard, welcome step

Steps

  1. Welcome — introduces the wizard and what it will configure.
  2. Credentials — enter the Tenant ID, Client ID, and Client Secret of your Microsoft Entra ID app registration. A link to the Azure Portal is provided to help you find or create these values.
  3. Connection Test — the wizard performs an OAuth 2.0 authentication against Microsoft Graph. While it runs you see Testing connection...; on success it shows Connection test successful. Access token retrieved from Microsoft Graph. (green), and on failure Connection test failed. (red).
  4. SharePoint — enter the SharePoint Site URL and initialize the storage that will hold the previewed files.
  5. Done — completing this step activates the File Viewer.

Usage (step by step)

Validation messages

If you see Connection test failed., re-check the credentials on the previous step and the Microsoft Graph permissions granted to the app registration, then test again.

Prerequisites

Rule Engine

The Rule Engine is a configurable, priority-ordered decision engine shared across the DEXPRO apps. It lets you express business decisions as rules instead of code — for example choosing the next process step, checking plausibility, or assigning an account in SQUEEZE, and deciding stage transitions or assignees in Advanced Workflow.

Purpose and business value

Many document-processing decisions differ by customer, vendor, amount, or document type. The Rule Engine puts those decisions in the hands of configurators: rules are evaluated in priority order, and the first matching rule determines the outcome. This keeps behavior transparent and adjustable without a development change.

Concepts

Rule Set

A Rule Set is scoped to exactly one primary table and can reference up to 50 related tables. It groups everything the engine needs to evaluate one kind of decision.

Rule Group

A Rule Group organizes rules within a rule set and orders them so they are evaluated in a defined sequence.

Rule

A Rule defines the actual condition to match. It supports:

Rule Condition

A Rule Condition compares a field against a value using a comparison operator. It can compare to a single value or to a reusable value set.

Value Set

A Value Set is a reusable list of values used by the In Set operator, so the same list can be referenced from many conditions.

Rule Validity Period

A Rule Validity Period restricts when a rule applies using weekday, time-of-day, and date windows.

Comparison operators

Testing rules

An interactive Rule Test page lets you evaluate a rule set against sample data and see which rule matches, so you can verify your configuration before it goes live.

Rules Test page for a rule group

Validation messages

Rule Sets

The Rule Sets list is where you create and manage the rule sets used by the Rule Engine. Each rule set targets one primary table, may reference related tables, and contains the rule groups that hold the individual rules.

Open it by searching for Rule Sets (it is listed under the Administration usage category).

Rule Sets list with the Rule Groups part

Fields

Rule Groups

The rule set embeds its Rule Groups, which order and organize the rules that belong to the set. From a rule group you open the individual Rule Cards.

Usage

A rule set may have only one primary table ("Only one primary table allowed per rule set") and at most 50 tables in total ("Maximum allowed: 50 tables").

Rule Card

The Rule Card is where you define a single rule: its conditions, how those conditions are combined, when it is valid, and whether it is active. It belongs to a rule group within a rule set.

Rule card with General and Rule Conditions

General

The Valid To date must not be earlier than the Valid From date.

Conditions

The Conditions subpage lists the individual comparisons that make up the rule. To add a condition:

Only operators that are valid for the selected field's data type can be used; an operator that does not apply to the field type is rejected.

Validity Periods

The Validity Periods subpage lets you further restrict when the rule applies using weekday, time-of-day, and date windows — in addition to the Valid From / Valid To dates on the card.

Testing the rule

Use the interactive Rule Test page to evaluate the rule (and its rule set) against sample data and confirm it matches as expected before relying on it in production.

Usage

Document Creation Logs

The Document Creation Logs are diagnostic records that capture what happens during purchase document creation. They are written only when logging is enabled in Core Setup and are used to troubleshoot how a Core document became a Business Central record.

Purpose

When a purchase document is created from a Core document, several steps read the source data and build the record. If the result is not what you expect, these logs show the source JSON alongside the actual record JSON at each creation point, so you can pinpoint where a value came from or where it diverged.

Enabling logging

Logging adds overhead and produces data at every creation point. Enable it only while investigating an issue, and switch it off again afterward.

Reading the logs

Open the Document Creation Logs list from Core Setup (Document Creation Logs action) or by searching for the page. Each entry corresponds to a creation point during document creation.

{add screenshot of Document Creation Logs here}

To compare the data, open the JSON Comparison view. It shows the source JSON (what the document provided) next to the record JSON (what was written to the Business Central record) so you can spot differences directly.

{add screenshot of JSON Comparison here}

Troubleshooting workflow

Role Center

DEXPRO Core ships a dedicated Role Center for purchasing agents. It gives people who process incoming documents an at-a-glance overview through activity cues that drill down to Core Documents, plus quick links to the Core pages they use most.

The Purchasing Agent profile

The Role Center is delivered as the DEXPRO Purchasing Agent profile. Selecting this profile makes the DEXPRO Core Role Center the user's home page.

DEXPRO role centre with its activity tiles

Activity cues

The Core Activities cues summarize the Core documents by status and let you drill down to the underlying list. The cues include:

Choosing a cue opens the Core Documents list filtered to the matching documents.

DEXPRO section

The Role Center includes a DEXPRO section with direct links to:

Selecting the profile

An administrator can also assign this profile to users by default from the Profiles (Roles) page.

Cleanup and Job Queue

DEXPRO Core keeps the Core Documents list tidy with a recurring cleanup task that runs through the Business Central Job Queue. This page explains what the job does, how to (re)create it, and the permissions it needs.

The cleanup job

A recurring Job Queue Entry (Core Cleanup Tasks) is created automatically when Core Setup is initialized. It:

Each run deletes at most 50 documents. If more documents are eligible, the remaining ones are deleted in the following runs — with the default schedule of two runs a day, that is up to 100 documents per day.

The job's identifier is stored in the Cleanup Job GUID field on Core Setup.

Job Queue Entries showing the Core cleanup task

(Re)creating the job

If the job was removed, or if it was never created because of missing permissions, you can recreate it:

Adjusting how long documents are kept

Change the Cleanup Interval DateFormula on Core Setup to keep documents for a different period. For example, -2M keeps two months of completed documents before they are eligible for deletion.

Permissions

Creating and running Job Queue Entries requires the standard Business Central Job Queue permissions, in addition to the DEXPRO Core permission set.

Troubleshooting

If the user initializing Core Setup lacks Job Queue permission, Core shows a message and does not create the cleanup job. Have an administrator with Job Queue permission open Core Setup and run Create Jobs.

Only documents in Deleted, Closed, or Cancelled status are removed. Documents in other statuses are never deleted by the cleanup job, regardless of age.

Extensibility

This page is for developers and partners who build on top of DEXPRO Core. It describes Core's extension surface: the interfaces you implement, the extensible enums you add values to, the integration events you subscribe to, and the public codeunit APIs you can call.

Interfaces

DXP ISource Document

Implemented per DXP Document Class enum value to describe how a source document of that class is turned into processed data. Methods:

DXP IDocument Processing

Bound per DXP Target Document Process enum value to perform the actual processing. Method:

Extensible enums

Add your own values to these enums from a dependent app to introduce new document types, processes, steps, and statuses.

Integration events

Key events are published from DXP Document Mgt. and DXP Document Transfer Mgt.:

Subscribe to the OnBefore events to adjust or skip default behavior, and to the OnAfter events to enrich the created records (for example to populate custom fields not covered by field mapping).

Further extension points:

Public codeunit APIs

Typical extension pattern