Packaging & Submission

Packaging and submission define how an INTERA Integration Module should be prepared before it is installed, reviewed, shared, or published.

A good integration package should be easy to inspect, easy to test, and safe to install. It should include not only the integration code, but also the manifest, configuration description, DataSource documentation, test notes, version history, and supporting material required for review.

The goal of packaging is to make the integration understandable as a complete product, not just as a technical script.

A complete integration package should answer:

- What external system does this integration connect to?
- What data can it provide?
- What configuration is required?
- What DataSources are available?
- Does it support entity synchronization?
- Does it expose any write-capable actions?
- How should it be tested?
- Which INTERA versions does it support?
- Who maintains it?

Folder structure #

Each Integration Module should be organized in a predictable folder structure.

A recommended package structure is:

example-billing-integration/
├── dist/
│   └── index.js
├── docs/
│   ├── overview.md
│   ├── configuration.md
│   ├── datasources.md
│   ├── sync.md
│   ├── errors.md
│   └── changelog.md
├── examples/
│   ├── sample-config.json
│   ├── sample-response-invoices.json
│   └── sample-response-customers.json
├── screenshots/
│   ├── configuration-screen.png
│   ├── datasource-test.png
│   └── dashboard-example.png
├── README.md
├── package.json
└── LICENSE

Minimum recommended structure:

example-integration/
├── dist/
│   └── index.js
├── README.md
└── package.json

For internal testing, a minimal package may be enough. For external review, customer installation, or future Online Store publication, the package should include documentation, examples, and version notes.

The dist/ folder should contain the executable integration entry point used by INTERA.

The docs/ folder should contain human-readable documentation.

The examples/ folder should contain safe sample data and example responses.

The screenshots/ folder should contain images that help reviewers and users understand how the integration appears inside INTERA.

The package should not include secrets, production credentials, customer data, private certificates, access tokens, or confidential exports.

Do not include:

- production API keys;
- passwords;
- bearer tokens;
- refresh tokens;
- private keys;
- customer databases;
- raw confidential exports;
- personal data;
- unrelated development files;
- temporary debug files;
- operating system metadata files.

Naming conventions #

Integration names should be stable, readable, and consistent.

Each integration usually has two names:

Technical ID
Used by INTERA internally.

Display name
Shown to INTERA administrators and users.

Example:

manifest: {
  id: "example_billing",
  name: "Example Billing",
  version: "1.0.0"
}

The technical ID should:

- be lowercase;
- be stable across versions;
- use underscores or hyphens consistently;
- avoid spaces;
- avoid customer-specific names unless the integration is private;
- avoid temporary words such as test, final, old, or new.

Good technical IDs:

odoo
example_billing
enigma_billing
fleet_manager
ship_certificates
banking_api
weather_feed

Poor technical IDs:

test
client1
new_billing
billing_final
plugin_v2
temporary_api

The display name should be understandable to an administrator.

Good display names:

Odoo
Example Billing
ENIGMA Billing
Fleet Manager
Ship Certificates
Banking API
Weather Feed

DataSource IDs should also be clear and stable.

Good DataSource IDs:

customers
invoices
overdue_invoices
payment_summary
active_services
open_tickets
vessel_positions
certificate_expiry

Poor DataSource IDs:

data
query1
dump
misc
report
all_records

Changing IDs later may break dashboards, Metrics, mappings, and role packages. Treat IDs as part of the public contract.

Manifest file #

The manifest describes the Integration Module.

It tells INTERA what the integration is, which version is installed, what type of system it connects to, and which capabilities it provides.

A minimal manifest may look like this:

manifest: {
  id: "example_billing",
  name: "Example Billing",
  version: "1.0.0",
  kind: "direct_api",
  capabilities: ["datasource"],
  defaultCacheTtlSec: 300
}

Recommended manifest fields:

id
Unique technical identifier.

name
Human-readable integration name.

version
Integration Module version.

kind
General integration type.

capabilities
Supported integration capabilities.

defaultCacheTtlSec
Default cache duration for DataSource results.

description
Short description of the integration.

vendor
External system vendor or integration author.

maintainer
Person or company responsible for maintenance.

supportedInteraVersions
Compatible INTERA versions.

homepage
Optional documentation or product page.

supportContact
Support email, URL, or partner contact.

Example extended manifest:

manifest: {
  id: "example_billing",
  name: "Example Billing",
  version: "1.1.0",
  kind: "direct_api",
  capabilities: ["datasource", "entity_provider"],
  defaultCacheTtlSec: 300,
  description: "Provides customers, invoices, payments, and service status from Example Billing.",
  vendor: "Example Software Ltd",
  maintainer: "Example Integrations Team",
  supportedInteraVersions: [">=1.0.0"],
  supportContact: "support@example.com"
}

The manifest should be accurate. Do not declare capabilities that the integration does not actually support.

For example, do not declare:

action

unless the integration has approved write-capable actions.

Do not declare:

entity_provider

unless the integration can actually synchronize entities.

The manifest is part of the integration contract. It should be kept up to date whenever the integration changes.

Required documentation #

Every submitted integration should include documentation.

The documentation should help three types of readers:

INTERA administrators
Need to know how to configure and use the integration.

INTERA reviewers
Need to know how to test and validate the integration.

Developers
Need to know how the integration is structured and maintained.

Recommended documentation files:

README.md
Overview, purpose, installation notes, and quick start.

docs/overview.md
What the integration does and what external system it connects to.

docs/configuration.md
Configuration parameters and required credentials.

docs/datasources.md
List of DataSources, parameters, and response shapes.

docs/sync.md
Entity synchronization behavior, if supported.

docs/errors.md
Known errors and troubleshooting guidance.

docs/changelog.md
Version history and release notes.

The README.md should include:

- integration name;
- short description;
- supported external system;
- supported INTERA versions;
- capabilities;
- installation notes;
- basic configuration instructions;
- quick test instructions;
- support or maintainer information.

The configuration documentation should include:

- every configuration field;
- whether each field is required;
- whether each field is a secret;
- example values where safe;
- where the administrator can find the value in the external system;
- common configuration mistakes.

The DataSource documentation should include:

- DataSource ID;
- DataSource name;
- purpose;
- supported parameters;
- required parameters;
- response format;
- example response;
- common errors;
- notes about caching or performance.

If the integration supports synchronization, the sync documentation should include:

- entity types synchronized;
- stable key fields;
- sync mode;
- sync frequency;
- manual sync support;
- dry-run support, if available;
- behavior for missing or inactive records;
- duplicate handling;
- partial failure behavior.

If the integration is write-capable, the documentation must clearly describe:

- what actions are supported;
- what external system records may be changed;
- required permissions;
- safety checks;
- audit behavior;
- rollback or recovery notes;
- known risks.

Example screenshots #

Screenshots help reviewers, administrators, and future users understand how the integration appears and behaves inside INTERA.

Recommended screenshots:

- integration catalog entry;
- Integration Instance configuration screen;
- successful connection test;
- DataSource test result;
- sync result or dry-run result;
- dashboard widget using integration data;
- error state example;
- Metric or Asset Mapping example, if relevant.

Screenshots should use safe demo data. Do not include real customer names, production balances, personal data, API keys, tokens, passwords, private URLs, or confidential business information.

Good screenshot examples:

Configuration screen with demo API URL and masked API key.
DataSource test result using sample customers.
Dashboard widget showing anonymized invoice summary.
Dry-run sync result showing sample record counts.

Poor screenshot examples:

Production customer list.
Real bank balances.
Visible API token.
Live database connection string.
Confidential invoice details.

Screenshots should be clear and focused. A reviewer should be able to understand what is being shown without reading the entire documentation first.

Recommended screenshot file names:

configuration-screen.png
connection-test-success.png
datasource-invoices-result.png
sync-dry-run-customers.png
dashboard-example.png
error-invalid-api-key.png

ersion release notes #

Every integration package should include version release notes.

Release notes explain what changed, whether the change is backward-compatible, and whether users need to update configuration, dashboards, Metrics, or mappings.

Recommended version format:

MAJOR.MINOR.PATCH

Use versions consistently:

PATCH
Bug fixes that do not change the public integration contract.

MINOR
Backward-compatible improvements, new optional parameters, new DataSources, or new entity providers.

MAJOR
Breaking changes such as renamed DataSources, changed configuration keys, removed fields, or changed response formats.

Example release notes:

## 1.1.0

Added:
- payment_summary DataSource.
- Optional currency filter for invoices DataSource.

Changed:
- Improved timeout handling for external API requests.

Fixed:
- Corrected date parsing for invoice due dates.

Compatibility:
- Backward-compatible with version 1.0.0.
- No configuration changes required.

Example breaking change release note:

## 2.0.0

Breaking changes:
- Renamed customer_balance DataSource to customer_financial_summary.
- Replaced config field apiToken with apiKey.
- Changed invoice response field total_due to amountDue.

Migration:
- Update dashboards and Metrics that reference customer_balance.
- Re-enter API credentials using the new apiKey field.
- Update any custom mappings that reference total_due.

Compatibility:
- Not backward-compatible with version 1.x.

Release notes should be written for administrators and developers. Avoid vague notes such as:

- improvements
- fixes
- updates
- changed stuff

Use clear, specific descriptions.

Submission checklist #

Before submitting an Integration Module for review, testing, installation, or future Online Store publication, complete the checklist below.

Package checklist #

[ ] Integration folder has a clear name.
[ ] dist/index.js or required entry point is present.
[ ] package.json is present, if required.
[ ] Manifest is present and valid.
[ ] README.md is present.
[ ] Documentation files are included.
[ ] Example responses or test data are included.
[ ] Screenshots are included, where relevant.
[ ] Changelog or release notes are included.
[ ] No production credentials are included.
[ ] No confidential customer data is included.

Manifest checklist #

[ ] id is stable and unique.
[ ] name is readable.
[ ] version is correct.
[ ] kind is correct.
[ ] capabilities are accurate.
[ ] defaultCacheTtlSec is set where applicable.
[ ] Supported INTERA versions are documented.
[ ] Maintainer or support contact is documented.

Configuration checklist #

[ ] All required configuration fields are documented.
[ ] Secret fields are marked as secrets.
[ ] No credentials are hard-coded.
[ ] Example values are safe.
[ ] Invalid configuration produces clear errors.
[ ] Connection test is documented, if available.

DataSource checklist #

[ ] Each DataSource has a stable ID.
[ ] Each DataSource has a readable name.
[ ] Each DataSource has a clear purpose.
[ ] Supported parameters are documented.
[ ] Response format is documented.
[ ] Example response is included.
[ ] Empty results are handled safely.
[ ] Errors are handled clearly.
[ ] Large responses are limited or paginated.

Sync checklist #

[ ] Entity Providers are documented, if supported.
[ ] Each synchronized entity has a stable key.
[ ] Repeated sync does not create duplicates.
[ ] Missing or inactive records are handled consistently.
[ ] Dry-run sync is supported or test process is documented.
[ ] Partial failure behavior is documented.
[ ] Sync errors are visible and understandable.

Metric and Asset Mapping checklist #

[ ] External identifiers are stable.
[ ] Asset Mapping approach is documented.
[ ] Metrics are traceable to source data.
[ ] Metric time context is explicit.
[ ] Units and currencies are documented.
[ ] Missing, delayed, or invalid values are handled.

Security checklist #

[ ] Integration uses read-only access where possible.
[ ] Secrets are not logged.
[ ] Secrets are not included in documentation or screenshots.
[ ] Parameters are validated before external calls.
[ ] SQL integrations do not expose arbitrary SQL execution.
[ ] File integrations validate file names, paths, and formats.
[ ] Write-capable actions are explicitly declared and documented.

Review readiness checklist #

[ ] Integration can be installed in a trial environment.
[ ] Integration Instance can be created successfully.
[ ] DataSources can be tested successfully.
[ ] Sync can be tested successfully, if supported.
[ ] Error cases have been simulated.
[ ] Performance has been tested with realistic data size.
[ ] Version release notes are complete.
[ ] Maintainer is identified.