Integration Config
Data Entity
Description
Stores per-organization configuration for external system integrations, including accounting systems (Xledger, Dynamics) and the HLF external portal. Each record holds credentials, endpoint URLs, field mappings, sync settings, and operational state for one integration type per organization.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
FK to organizations — the tenant this config belongs to | required |
integration_type |
enum |
Which external system this config targets | required |
display_name |
string |
Human-readable label for this integration shown in the admin UI | required |
enabled |
boolean |
Whether this integration is active and should be used during sync | required |
base_url |
string |
Base URL of the external system's API endpoint | - |
api_key_encrypted |
text |
AES-256 encrypted API key or client secret for authenticating with the external system | - |
client_id |
string |
OAuth2 client ID for integrations using client credentials flow (e.g. Dynamics portal) | - |
client_secret_encrypted |
text |
AES-256 encrypted OAuth2 client secret | - |
tenant_id |
string |
Tenant or directory ID for Microsoft Dynamics integrations | - |
field_mappings |
json |
JSON object mapping Meander field names to external system field names (e.g. {"expense_amount": "Amount", "expense_date": "TransactionDate"}) | - |
accounting_code_mappings |
json |
JSON object mapping Meander expense types to external accounting codes (e.g. {"travel_km": "4001", "toll": "4002"}) | - |
sync_frequency |
enum |
How often data is pushed or pulled from the external system | - |
last_sync_at |
datetime |
Timestamp of the most recent successful sync with the external system | - |
last_sync_status |
enum |
Result of the most recent sync attempt | - |
last_sync_error |
text |
Error message from the last failed sync attempt, for admin diagnostics | - |
webhook_url |
string |
Inbound webhook URL registered with the external system (e.g. Dynamics portal webhook endpoint) | - |
webhook_secret_encrypted |
text |
AES-256 encrypted secret used to verify incoming webhook payloads | - |
extra_config |
json |
Catch-all JSON for integration-specific settings not covered by standard columns (e.g. Xledger company code, Dynamics environment name) | - |
created_by |
uuid |
FK to users — the admin who created this config | required |
updated_by |
uuid |
FK to users — the admin who last modified this config | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Record last-modified timestamp | required |
Database Indexes
idx_integration_configs_org_type
Columns: organization_id, integration_type
idx_integration_configs_org_id
Columns: organization_id
idx_integration_configs_enabled
Columns: enabled
Validation Rules
base_url_must_be_https
error
Validation failed
field_mappings_must_be_valid_json_object
error
Validation failed
display_name_not_empty
error
Validation failed
integration_type_must_be_known_value
error
Validation failed
encrypted_fields_must_not_be_stored_in_plaintext
error
Validation failed
sync_frequency_must_be_known_value
error
Validation failed
Business Rules
one_config_per_integration_type_per_org
Each organization may have at most one integration_configs row per integration_type. A unique constraint on (organization_id, integration_type) enforces this. If an org needs to reconfigure an integration, the existing record is updated rather than replaced.
disabled_integration_must_not_sync
When enabled = false, sync services must skip this config entirely and must not send data to or receive data from the external system.
credentials_required_before_enable
A config cannot be set to enabled = true unless the required credentials for its integration_type are present (e.g. api_key_encrypted or client_id + client_secret_encrypted).
sync_status_updated_after_every_attempt
After every sync attempt (success or failure) last_sync_at, last_sync_status, and (on failure) last_sync_error must be updated so admins have accurate diagnostics.
org_scoped_access_only
Organization admins may only read and write configs belonging to their own organization_id. Global admins have read access across orgs for support purposes but must not modify credentials.
webhook_secret_required_for_inbound_webhooks
If webhook_url is set, webhook_secret_encrypted must also be present. Incoming payloads without a valid HMAC signature derived from the secret must be rejected.