Integration Architecture
High-Level Architecture
A typical INTERA Integration consists of:
External System
↓
Integration Module
↓
Integration Instance
↓
Declared Capabilities
↓
INTERA Core
An Integration Module may expose one or more capabilities, including:
- DataSources;
- Metrics;
- external business objects;
- external Widgets;
- forms and supported write-back actions;
- other capabilities supported by the current INTERA Integration contract.
The Integration Module is responsible for communicating with the external system.
INTERA Core is responsible for consuming the capabilities declared by the Integration.
Integration Module
An Integration Module is the reusable software component that implements support for a particular external system or protocol.
Examples include:
- Microsoft Business Central;
- Billing system;
- Banking system;
- Database Server;
- a proprietary customer system.
The Integration Module defines:
- metadata;
- supported configuration;
- authentication requirements;
- declared capabilities;
- DataSources;
- optional external business-object providers;
- optional Metrics;
- optional Widgets;
- optional forms or write-back operations;
- error handling.
The module should expose only capabilities that it can support reliably.
Integration Instance
An Integration Instance is a configured use of an Integration Module.
For example:
Integration Module:
Microsoft Business Central
Integration Instances:
Business Central Production
Business Central Test
Each Integration Instance may have different:
- credentials;
- endpoint;
- tenant;
- company;
- database;
- account;
- enabled options;
- Integration-specific parameters.
The same Integration Module may therefore be instantiated multiple times.
Integration Metadata
Each Integration Module should declare basic metadata.
Typical metadata includes:
- Integration name;
- unique identifier;
- version;
- description;
- vendor or author;
- supported INTERA Core version;
- capability declarations.
For example:
id: business_central
name: Microsoft Business Central
version: 1.2.0
The exact schema is defined by the current Integration Contract.
Integration identifiers should remain stable between versions.
Configuration Contract
An Integration Module declares the configuration required to create an Integration Instance.
Configuration may include:
- API URL;
- database server;
- tenant;
- company;
- username;
- client ID;
- certificate;
- account;
- other system-specific settings.
The Integration should declare enough metadata for INTERA to:
- present the required fields;
- validate supported values;
- identify required and optional settings;
- handle sensitive fields correctly.
Sensitive values such as passwords, secrets, tokens, and certificates must be declared using the appropriate secure configuration types.
Authentication
Authentication is implemented by the Integration according to the requirements of the external system.
Supported methods may include:
- username and password;
- API key;
- OAuth;
- client credentials;
- certificates;
- database credentials;
- another supported authentication mechanism.
The Integration is responsible for translating the configured credentials into the authentication mechanism required by the external system.
Authentication failures should be returned through the standard Integration error model.
Capability Declaration
An Integration Module declares which capabilities it provides.
Depending on the Integration, these may include:
DataSources
Metrics
External business objects
Widgets
Forms
Write-back actions
INTERA should not assume that every Integration supports every capability.
For example, one Integration may provide only DataSources, while another may additionally provide specialized Widgets and write-back forms.
Capabilities should be declared explicitly.
DataSources
A DataSource is a named structured dataset exposed by an Integration.
Examples include:
customers
invoices
payments
tickets
transactions
vessels
alarms
A DataSource contract should define:
- unique name;
- display name;
- description;
- returned fields;
- field types;
- supported input parameters;
- supported filters;
- optional paging or result limits.
For example:
name: invoices
display_name: Invoices
A DataSource should have a clear and stable business purpose.
DataSource Fields
Each DataSource should describe the fields that it returns.
A field definition may include:
- name;
- display name;
- type;
- description;
- nullable state;
- other supported metadata.
For example:
fields:
- name: invoice_number
type: string
- name: invoice_date
type: date
- name: amount
type: number
Field names form part of the Integration contract and should not be changed unnecessarily between Integration versions.
DataSource Parameters
A DataSource may declare parameters required or supported by the external system.
Examples include:
- start date;
- end date;
- customer;
- status;
- company;
- currency;
- account;
- result limit.
For example:
parameters:
- name: from_date
type: date
- name: to_date
type: date
Parameters should be typed and validated where possible.
DataSource Filters
Where supported, a DataSource may expose filtering capabilities.
The Integration should clearly declare:
- which fields can be filtered;
- which operators are supported;
- expected value types.
Possible operators may include:
equals
not_equals
greater_than
less_than
contains
in
The exact set of operators depends on the Integration Contract and the external system.
Integration developers should reject unsupported filters explicitly rather than silently ignoring them.
DataSource Result Contract
A DataSource response should follow the standard INTERA response structure.
The response should clearly distinguish:
- successful result;
- empty result;
- validation error;
- authentication error;
- temporary external-system error;
- permanent configuration error.
Returned values must conform to the types declared by the DataSource.
Avoid changing a field from one type to another without a versioned contract change.
External Business Objects
An Integration may declare business objects that can be used by INTERA.
Examples may include:
- customers;
- vessels;
- products;
- suppliers;
- contracts;
- services.
The Integration contract for such objects should expose the information required by Core, including:
- object type;
- stable external identifier;
- display name;
- available fields;
- supported metadata.
The purpose of this contract is to provide INTERA with a predictable representation of relevant business objects.
The Integration developer does not need to implement or understand Core storage behaviour beyond the published contract.
Stable External Identifiers
Where an Integration exposes external business objects, each object should provide a stable identifier whenever the external system supports one.
For example:
customer_id
vessel_id
contract_id
product_id
The identifier should:
- remain stable where possible;
- uniquely identify the object within the relevant Integration context;
- not depend solely on a display name.
Integration developers should not make assumptions about how Core uses or manages these identifiers internally.
Metrics Declared by an Integration
An Integration may declare Metrics when it can provide a meaningful business value directly.
Examples include:
- current account balance;
- service status;
- exchange rate;
- network usage;
- current position.
A declared Metric should provide the metadata required by the current Metric contract, such as:
- name;
- display name;
- value type;
- unit where relevant;
- description;
- supported parameters.
The exact Metric schema is defined by the Integration Contract.
External Widgets
An Integration may declare Widgets that provide specialized user-interface functionality.
This is useful when the external system requires a presentation or interaction that cannot be represented adequately by a generic Core Widget.
An external Widget should declare:
- unique Widget type;
- display name;
- supported properties;
- supported sizes;
- configuration schema;
- required Integration Instance context.
External Widgets should follow the same general configuration principles as Core Widgets.
Integration-specific implementation details should remain inside the Integration.
Forms and Write-Back
An Integration may expose supported forms or write-back operations.
Examples may include:
- submitting a value;
- approving an action;
- updating a supported field;
- creating a supported external-system request.
The Integration must explicitly declare each supported operation.
The contract should define:
- operation name;
- input fields;
- field types;
- required fields;
- validation rules;
- permissions where applicable;
- success response;
- error response.
INTERA does not assume that a connected system is writable simply because it provides DataSources.
Write-back capability must be declared explicitly.
Error Handling
All Integration capabilities should use consistent error handling.
Errors should be classified clearly enough for INTERA Core to distinguish between conditions such as:
- invalid configuration;
- authentication failure;
- temporary connection failure;
- timeout;
- invalid parameter;
- unsupported operation;
- external-system rejection.
Error messages should provide enough information for troubleshooting without exposing secrets.
Avoid returning:
- passwords;
- access tokens;
- client secrets;
- private keys;
- sensitive connection strings.
Temporary and Permanent Errors
Where the Integration contract supports error classification, distinguish between temporary and permanent failures.
Temporary examples may include:
- network timeout;
- service temporarily unavailable;
- rate limit reached.
Permanent examples may include:
- invalid configuration;
- unsupported field;
- deleted endpoint;
- invalid credentials requiring administrator action.
This allows Core to handle failures appropriately without requiring knowledge of the external system.
Connection Test
An Integration should provide a connection test where supported.
The test should verify the minimum requirements necessary to use the Integration.
This may include:
- endpoint accessibility;
- authentication;
- selected tenant or company;
- required permissions.
A successful connection test should not be used to imply that every DataSource or optional capability has also been validated.
Individual capabilities should return their own errors when used.
Versioning
Integration developers should treat declared contracts as versioned interfaces.
Changes that may affect compatibility include:
- removing a DataSource;
- renaming a field;
- changing a field type;
- removing a configuration parameter;
- changing a Metric contract;
- changing Widget parameters.
Where possible, maintain backward compatibility.
Breaking changes should require an appropriate Integration version change and should be documented.
Integration Isolation
The Integration Module should contain external-system-specific logic.
Examples include:
- API request construction;
- SQL queries;
- authentication flow;
- external field naming;
- vendor-specific pagination;
- external error translation.
INTERA Core should interact with these features through the published Integration contracts.
This separation allows Core and individual Integrations to evolve independently.
Business-Oriented Contracts
Where possible, expose business-readable capabilities.
For example, prefer a DataSource such as:
invoices
with clearly named fields over exposing implementation details such as internal database table names.
Similarly, prefer:
remaining_amount
over an unexplained vendor-specific column name where the Integration can safely provide a normalized business name.
Technical source names may still be exposed where they are necessary for accurate configuration.
Integration Development Principles
When building an Integration:
- Keep external-system-specific logic inside the Integration.
- Declare capabilities explicitly.
- Use stable names and identifiers.
- Define field types clearly.
- Validate parameters.
- Return structured errors.
- Protect credentials and secrets.
- Avoid relying on undocumented Core behaviour.
- Maintain backward compatibility where possible.
- Document any external-system prerequisites.
Architecture Summary
The developer-facing architecture can be summarized as:
External System
↓
Integration Module
↓
Integration Instance
↓
Declared Contracts
├── DataSources
├── Metrics
├── Business Objects
├── Widgets
└── Forms / Write-Back
↓
INTERA Core
Integration developers should build against these published contracts.
They do not need to depend on assumptions about Core persistence, internal object lifecycle, synchronization strategy, or internal identity management.
For detailed schemas and implementation requirements, continue with Integration Contract, Integration Types, and Reference.
