This article was created with the assistance of AI tools for research and drafting. It was reviewed, edited, and fact-checked by our human editorial team before publication.

Provides information about the basic settings for all interfaces and integrations used in Aptean Equipment DMS.

Interfaces and Integrations

Note

The interface and integration chapters below are work in progress. The present documentation does not necessarily describe the most recent functionalities or might be incomplete as the development is not yet completed. For the most recent information, check the Release Notes (until March 2026) or the New & Planned Features.

In our ERP solution, the setup of interfaces is mostly automated. When opening the Interface List page via the quick search (ALT+Q), the basic interface values like Interface Type, Description, Provider Code, Group Code, and applicable parameters are all automatically initialized including all their dependencies (except for dealer-specific parameters). This is valid for all new companies.

This chapter is divided into the following sections:

'General' FastTab

The General FastTab holds the basic interface information. The values are set up automatically. The read-only Provider Code and Group Code fields are used to define a specific manufacturer or partner and area (e.g., Trade, Service) to filter the list for a better overview. The values in the Provider Code field are taken from the Interface Providers table which is automatically filled upon interface initialization.

Interface Log

The Interface Log toggle switch can be manually activated by the dealer to log all interface activities and access further process or import/export file information via the Log button in the menu bar. Corresponding instructions are described in the relevant interface documentation.

Tip

When the Interface Log toggle switch is activated, also use the Delete Log Entries After value to regularly clear old interface activities.
Use this option with caution depending on your record preservation obligations!

Running Modes

CAUTION!

All current interface settings are overwritten when changing the mode! They cannot be restored.

The Switch Running Mode button is used to switch the interface and all of its settings between the different test and productive environments, if available. When clicking this button, users can select which mode to apply. After selecting a different mode, the default parameters of the mode are applied. By default, interfaces are initialized as Productive. The following modes are available:

Mode Description
empty Only shown if no mode selection is available.
Test Sets up the test environment with default parameters, if available.
Productive Sets up the productive environment with default parameters.
Individual Only shown if no valid test or productive mode is defined.

'Authorization' FastTab

The Authorization FastTab is used to define the authorization options required by the interface or integration to authenticate against the service outside of our ERP solution. The fields in the Authorization FastTab are displayed depending on the selected Authorization Type:

Authorization Type Displayed Fields
empty No other fields are displayed.
API Key Only the Authorization Code field is displayed.
Basic Only the Authorization Code field is displayed.
JWT (JSON Web Token) Only the Authorization Code field is displayed.
OAuth2 The Authorization Code and Scope fields are displayed.
The Scope field is used to define the interface-specific access parameters. These are automatically set up during initialization.

For all authorization types (except empty), the Authorization Code field references a dedicated application endpoint that holds the actual credentials for the selected authentication method. Configuration details can be found under Authorization Endpoint Setup.

'Parameters' FastTab

Parameters are used to set up specific options for interface usage. This comprises, for example, specific import or export file definitions, dealer-specific accounts or resources, URLs, currency or language codes, default values, etc. The Instructions field shows corresponding hints for filling the Value field.

Many Value fields in the Parameters FastTab support lookups, so that valid values can be directly selected. Other fields require plain text or numbers which are described in the relevant interface documentation or in the Instructions FactBox which is accessible via the i symbol in the upper right corner. When changing the user language, the instructions as well as parameter values are automatically localized if translations are available in the related tables.

Tip

In the Value field, you activate functionalities with 1 or yes and deactivate them with 0 or no.

The Secured Value checkbox is used to set up parameters where the actual value must not be readable by users. If the checkbox is selected, the entered value is replaced by dots (•), so that it is not possible to see or reverse engineer it.

Important

The checkbox selection is set up during parameter initialization and cannot be changed in a running environment.

Debugging is not possible with such parameters as no access is possible from outside.

The color coding in the Parameters FastTab has the following meaning:

Font Color Meaning
Red Mandatory dealer-specific parameter has no value yet; interface cannot be fully functional.
Green Mandatory dealer-specific parameter has a value.
Black Optional A value is only required for convenience functionalities. If you enter a value, you can use the feature described in the Instructions field.

After a new release, new parameters and setups might be required. The Update Parameters and Setups button in the menu bar adds missing and removes obsolete parameters and setups based on the current interface definition. Existing values are not changed.

Note

If a new mandatory parameter has no value and the interface is active, it is automatically deactivated.

'Mapping Setup'/'Setup' FastTab

Note

The Mapping Setup/Setup FastTab is only available in interfaces or integrations that require it.

The mapping setup shows different objects which have to be filled with values first, so that the interface can process any data. Usually, this applies only to dealer-specific objects like resources, items, etc. In most cases, values in the Parameters FastTab rely on a complete mapping setup to leverage the lookup feature via the selection field. To fill an object with the required data, proceed as follows:

Note

Depending on the scope of data to be added, the following process may take some time!

  • Click the object name in the Name column to open the relevant table.
  • Add new lines for all applicable values.
  • Fill in the new lines.
  • Close the table.
  • Confirm the Do you want to complete the interface setup for [...]? dialog window with Yes.
    • When you click Yes, the Completed checkbox is automatically selected, and the Name value turns from red to green font.
    • When you click No, the Name value stays in red font, and the Completed checkbox remains cleared. You can restart the setup later, but the interface cannot be activated until the mapping and parameter setup is complete.
  • Repeat these steps for all objects which have the Mandatory checkbox selected. Otherwise, the interface or integration cannot be activated!

Tip

Objects with the Mandatory checkbox cleared are optional.

After a new release, new parameters and setups might be required. The Update Parameters and Setups button in the menu bar adds missing and removes obsolete parameters and setups based on the current interface definition. Existing values are not changed.

Note

If a new mandatory parameter has no value and the interface is active, it is automatically deactivated.

Activating Interfaces

When all requirements are met (only green and/or black values in the Parameters FastTab, and/or only green values in the Mapping Setup FastTab), proceed as follows:

  • Click Activate Interface in the menu bar. The General > Active toggle switch is activated.

Note

If an interface or integration relies on a job queue, it is automatically added to the Job Queue Entries page and set up as described in the relevant interface documentation upon successful activation. A corresponding smart notification is displayed under the menu bar in that case.

If any requirement is missing, a dialog window is displayed with a list of all mandatory parameters or mapping setups which do not yet have a value.

When adding the required value(s) and confirming by clicking OK, the interface is activated and fully functional. When not adding the required value(s) and confirming by clicking OK, the interface cannot be activated.

Tip

In case an interface or integration does not work as intended anymore or there is an issue with a certain parameter, you can use the Restore or Restore > Restore Authorization / Restore Parameters / Restore Setup button in the corresponding FastTab. This resets all values to the default values entered upon interface initialization.

Deactivating Interfaces

To deactivate an active interface, proceed as follows:

  • Click Deactivate Interface in the menu bar of the General FastTab. The General > Active toggle switch is deactivated.

All existing log entries and configuration are retained.

Authorization Endpoint Setup

Each authorization type (except empty) requires a dedicated application endpoint to be configured. The endpoint holds the credentials and settings used to authenticate against the external service. Endpoints are managed centrally and can be referenced across multiple interfaces via the Authorization Code field in the Authorization FastTab.

Important

All credentials are stored securely, so that they cannot be restored, reverse-engineered, or read from the code in case of a password loss. Make sure to store all credentials securely in a different place as well in case of password resets.
For keyless environments (some on-prem or development systems), nothing changes.

This section is divided into the following subsections:

Basic Application Endpoint

The Basic application endpoint stores the credentials for HTTP Basic authentication. Open the Basic Application Endpoints page via the quick search (ALT+Q) to create and manage endpoints. The following fields are available when creating a new entry or editing an existing one on the Basic Application Endpoint Card page:

Field Description
Basic Endpoint Code Enter the unique identifier for the endpoint. This value is referenced in the Authorization Code field of the interface card.
Description Enter a descriptive name for the endpoint.
User Name Enter the user name used for HTTP Basic authentication when calling the external service.
Password Enter the password for HTTP Basic authentication. This value is stored securely and displayed as dots.
URL Enter the base URL of the external service this endpoint connects to.

OAuth2 Application Endpoint

The OAuth2 application endpoint stores the configuration for OAuth2 authentication. Open the OAuth2 Application Endpoints page via the quick search (ALT+Q) to create and manage endpoints. The following fields are available when creating a new entry or editing an existing one on the OAuth2 Application Endpoint Card page:

Field Description
OAuth Endpoint Code Enter the unique identifier for the endpoint. This value is referenced in the Authorization Code field of the interface card.
Description Enter a descriptive name for the endpoint.
Client ID Enter the application (client) ID registered with the external OAuth2 provider.
Client Secret Enter the client secret issued by the OAuth2 provider. This value is stored securely.
Authentication Endpoint URL only available if OAuth2 Authorization Method = Authentication Code Enter the URL to exchange an authorization code for an access token.
Token Endpoint URL Enter the URL used to request an access token from the OAuth2 provider.
OAuth2 Authorization Method Select the OAuth2 grant type:
• Authentication Code: Enter the Authentication Endpoint URL to specify the provider from which the code is retrieved.
• Client Credentials: You are prompted for your client credentials when Microsoft Dynamics Business Central first tries to access the interface associated with this authorization endpoint.
Client Authentication Method Select how client credentials are transmitted to the token endpoint:
• Send as Basic auth. header: The client credentials are sent in the HTTP request header.
• Send client credentials in body: The client credentials are sent in the HTTP request body.

To authenticate on behalf of individual users, click User Access Token in the menu bar to assign OAuth2 tokens per user.

JWT Application Endpoint

The JWT application endpoint stores the configuration for JSON Web Token (JWT) authentication. Open the JWT Application Endpoints page via the quick search (ALT+Q) to create and manage endpoints.

The following fields are available when creating a new entry or editing an existing one on the JWT Application Endpoint Card page (General FastTab):

Field Description
JWT Endpoint Code Enter the unique identifier for the endpoint. This value is referenced in the Authorization Code field of the interface card.
Description Enter a descriptive name for the endpoint.
Signing Algorithm Select the algorithm used to sign the JWT. Changing the algorithm clears any previously stored signing key.
Available options:
• HS256 (HMAC-SHA256): signs the JWT with a shared secret
• RS256 (RSA-SHA256): signs the JWT with an RSA private key
Include nbf Claim Activate this toggle switch to include the not-before (nbf) claim in the JWT payload with the current timestamp as its value.

Setup information about the other FastTabs can be found below:

JWT Signing

When Signing Algorithm = HS256 (HMAC-SHA256), the HS256 Signing Secret FastTab is displayed. Enter the shared secret in the Signing Secret HS256 field. This value is stored securely.

When Signing Algorithm = RS256 (RSA-SHA256), the RS256 Private Key FastTab is displayed. The read-only Has Private Key toggle switch indicates whether a private key has already been imported. If yes, it is activated.

To import an RSA private key, proceed as follows:

Important

Private keys are stored in isolated storage and do not transfer when an environment is copied or restored. Re-import the private key after any environment migration.

  • Click Import Private Key (File) in the menu bar to import the key from a PEM file.
    or
    Paste the key directly:
    • Select the format PEM or XML (RSAKeyValue) in the Key Format field.
    • Paste the key text in the Private Key field.
    • Click Apply Key in the menu bar.

Tip

To remove an existing private key, click Clear Private Key in the menu bar.

Standard Claims

The Standard Claims FastTab defines the built-in JWT payload claims:

Field Claim Description
Issuer iss Enter the issuer claim identifying who issued the JWT.
Subject sub Optional Enter the subject claim identifying the principal.
Audience aud Optional Enter the audience claim identifying the intended recipients.
Token Expiry (sec.) exp Enter the duration in seconds until the JWT expires.
Minimum value: 1
Default value: 3600

Additional custom claims can be defined in the Custom Claims FastTab at the bottom of the JWT Application Endpoint Card page by entering the corresponding Claim Name and Claim Value values in the table.

Note

The reserved names iss, sub, aud, exp, iat, nbf, and jti cannot be used as custom claim names.

Token Exchange

By default, the signed JWT is used directly as a bearer token. When the Use Token Exchange toggle switch is activated in the Token Exchange FastTab, the signed JWT is instead submitted to an external token endpoint in exchange for a separate access token. The following additional fields are available when the Use Token Exchange toggle switch is activated:

Field Description
Token Endpoint URL Enter the URL that receives the signed JWT via HTTP POST in exchange for an access token.
JSON Response Key Enter the field name in the token endpoint's JSON response that contains the access token.
Default value: access_token
Consent Authorization URL Optional Enter the authorization URL for requesting user consent (e.g., for DocuSign). Leave empty if no consent flow is required.
Consent Client ID Optional Enter the integration key or client ID used in the consent flow. Leave empty to use the Issuer value.
Consent Scope Optional Enter the space-separated list of scopes to request consent for (e.g., signature impersonation).
Consent Last Granted At Reference Timestamp of the last successful consent.
Token Expires At Reference Expiry timestamp of the currently cached access token.

If a consent flow is required, proceed as follows:

  • Fill out the Consent Authorization URL, Consent Client ID, and Consent Scope fields in the Token Exchange FastTab.
  • Click Show Redirect URI in the menu bar.
  • Register the displayed URI on the integration key in the provider portal.
  • Click Request Consent in the menu bar to open the consent authorization dialog window.
  • Grant access in the dialog window.

Access tokens retrieved via token exchange are cached automatically and refreshed when they expire.

API Key Application Endpoint

The API Key application endpoint stores the configuration for API key-based authentication. Open the API Key Application Endpoints page via the quick search (ALT+Q) to create and manage endpoints.

The endpoint retrieves a bearer token from an external URL using the configured API key as Basic authentication credentials. The token is cached automatically and refreshed when it expires.

The following fields are available when creating a new entry or editing an existing one on the API Key Endpoint Card page:

Field Description
API Key Endpoint Code Enter the unique identifier for the endpoint. This value is referenced in the Authorization Code field of the interface card.
Description Enter a descriptive name for the endpoint.
Token Retrieval URL Enter the HTTP endpoint URL that returns a bearer token when called with the API key as Basic authentication credentials.
API Key Enter the API key used as Basic authentication credentials when calling the token retrieval URL. This value is stored securely.
JSON Response Key Enter the field name in the JSON response that contains the token.
Default value: access_token

To view cached tokens and their expiry information, click Navigation > Tokens in the menu bar.

Interface Cue Setup

The Interface Cue Setup page allows administrators to configure the cues displayed on the Interfaces role center. Each cue shows a count of interface log entries, optionally filtered by interface type, log entry status, and whether entries have been handled.

Open the Interface Cue Setup page via the quick search (ALT+Q) to manage the configuration. The following columns are available:

Column Description
Cue Select the cue slot on the Interfaces role center that this line configures.
Description Enter the caption to be displayed on the cue on the Interfaces role center.
Cue Name Reference Specifies the system name of the cue control this line is linked to.
Show Cue When the checkbox is selected, the cue is visible on the Interfaces role center. Clear the checkbox to hide it.
Interface Type Filter Limits the count to log entries of a specific interface type. Leave empty to include all interface types.
Status Filter Indicates whether a status filter is active for this cue. Use the Cue Setup Status Filters page to configure which log entry statuses are counted.
Handled Filter Specifies whether the cue counts only unhandled entries (No), only handled entries (Yes), or all entries (Not filtered).

Supported Interfaces List

The following list contains all interfaces and integrations currently supported by our ERP solution: