Interfaces and Integrations

In our ERP solution, the setup of interfaces is mostly automated, i.e., when opening the Interface List page via the 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 has the following subsections:

• 'General' FastTab
  • Interface Log
  • Running Modes
• 'Authorization' FastTab
• 'Parameters' FastTab
• 'Mapping Setup'/'Setup' FastTab
• Activating Interfaces
• Authorization Endpoint Setup
  • Basic Application Endpoint
  • OAuth2 Application Endpoint
  • JWT Application Endpoint
    • JWT Signing
    • Standard Claims
    • Token Exchange
  • API Key Application Endpoint
• Interface Cue Setup

'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 enabled 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.

Running Modes

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 on 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:

• empty: only shown if no mode selection is available
• Test: sets the test environment up with default parameters, if available
• Productive: sets the productive environment up 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 Authorization FastTab shows fields context-dependent:

• if Authorization Type = empty, no other fields are displayed
• if Authorization Type = API Key, only the Authorization Code field is displayed
• if Authorization Type = Basic, only the Authorization Code field is displayed
• if Authorization Type = JWT (JSON Web Token), only the Authorization Code field is displayed
• if Authorization Type = 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. See Authorization Endpoint Setup for configuration details.

'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.

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.

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

• red font = mandatory dealer-specific parameter has no value yet; interface cannot be fully functional
• green font = mandatory dealer-specific parameter has a value
• black font = optional parameter; potentially required for convenience functionalities, i.e., when a value is filled, the feature described in the Instructions field can be used

'Mapping Setup'/'Setup' FastTab

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, please proceed as follows:

• Click on the object name in the Name column to open the relevant table.
• Add new lines for all applicable values and fill them correspondingly.

• Close the table, and confirm the Do you want to complete the interface setup for [...]? dialog by clicking on Yes.
  • When clicking on Yes, the Completed checkbox is automatically selected, and the Name value turns from red to green font.
  • When clicking on No, the Name value stays in red font, and the Completed checkbox remains cleared. You can restart the setup again later on, 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! Objects with the Mandatory checkbox cleared are optional.

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), click on the Activate Interface button in the menu bar. The General > Active toggle switch is enabled.

If any requirement is missing, our ERP solution will show a dialog 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 on the OK button, the interface is enabled and fully functional. When not adding the required value(s) and confirming by clicking on the OK button, the interface cannot be activated.

To deactivate an active interface, click on the Deactivate Interface button in the menu bar of the General FastTab. The General > Active toggle switch is disabled. 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.

This chapter has the following subsections:

• Basic Application Endpoint
• OAuth2 Application Endpoint
• JWT Application Endpoint
  • JWT Signing
  • Standard Claims
  • Token Exchange
• API Key Application Endpoint

Basic Application Endpoint

The Basic application endpoint stores the credentials for HTTP Basic authentication. Open the Basic Application Endpoints page via the 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:

OAuth2 Application Endpoint

The OAuth2 application endpoint stores the configuration for OAuth2 authentication. Open the OAuth2 Application Endpoints page via the 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:

To authenticate on behalf of individual users, click on 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 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):

Setup information about the other FastTabs can be found below:

• JWT Signing
• Standard Claims
• Token Exchange

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:

• To import from a PEM file, click on Import Private Key (File) in the menu bar.
• To paste the key directly, select the key format (PEM or XML (RSAKeyValue)) in the Key Format field, paste the key text in the Private Key field, and click on Apply Key in the menu bar.

• 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:

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.

Token Exchange

By default, the signed JWT is used directly as a bearer token. When the Use Token Exchange toggle switch is selected 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:

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 on Show Redirect URI in the menu bar and register the displayed URI on the integration key in the provider portal.
• Click on Request Consent in the menu bar to open the consent authorization dialog and grant access.

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 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:

To view cached tokens and their expiry information, click on 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 table via the search (ALT+Q) to manage the configuration.

The following columns are available:

Below, please find a list of all interfaces and integrations currently supported by Aptean Equipment DMS: