External Portal Config
Data Entity
Description
Per-organization configuration for integrating with an external portal system (e.g., HLF's Dynamics-based 'Min Side' portal). Stores API credentials, sync settings, and integration state for bidirectional data exchange between Meander and the external portal.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations — one config per organization | requiredunique |
portal_type |
enum |
Type of external portal being integrated | required |
portal_base_url |
string |
Base URL of the external portal API endpoint | required |
api_key_encrypted |
text |
Encrypted API key or client secret for authenticating with the external portal | - |
client_id |
string |
OAuth2 client ID for external portal authentication | - |
client_secret_encrypted |
text |
Encrypted OAuth2 client secret | - |
auth_method |
enum |
Authentication method used to connect to the external portal | required |
sync_enabled |
boolean |
Whether automatic sync with the external portal is active | required |
sync_direction |
enum |
Direction of data sync | required |
sync_interval_minutes |
integer |
How often (in minutes) the sync job runs. Null means manual-only. | - |
sync_scope |
json |
JSON object describing which data entities are included in sync (e.g. {"peer_mentor_statuses": true, "certifications": true}) | - |
last_sync_at |
datetime |
Timestamp of the most recent successful sync | - |
last_sync_status |
enum |
Outcome of the most recent sync attempt | - |
last_sync_error |
text |
Error message from the most recent failed sync, for admin diagnostics | - |
webhook_url |
string |
URL on the external portal that Meander calls to push events (outbound webhook) | - |
webhook_secret_encrypted |
text |
Encrypted secret used to sign outbound webhook payloads (HMAC) | - |
inbound_webhook_token_encrypted |
text |
Encrypted token the external portal must include in inbound webhook requests to Meander | - |
field_mapping |
json |
JSON mapping of Meander field names to external portal field names for data transformation during sync | - |
is_active |
boolean |
Whether this integration config is active. Inactive configs are preserved for audit but do not trigger syncs. | required |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last update timestamp | required |
created_by |
uuid |
User ID of the admin who created this config | - |
updated_by |
uuid |
User ID of the admin who last modified this config | - |
Database Indexes
idx_external_portal_configs_organization_id
Columns: organization_id
idx_external_portal_configs_is_active
Columns: is_active
idx_external_portal_configs_last_sync_at
Columns: last_sync_at
Validation Rules
portal_base_url_format
error
Validation failed
webhook_url_format
error
Validation failed
sync_interval_range
error
Validation failed
field_mapping_schema
error
Validation failed
sync_scope_schema
error
Validation failed
auth_method_credential_completeness
error
Validation failed
connectivity_test_before_enable
warning
Validation failed
Business Rules
one_config_per_organization
Each organization may have at most one external portal config. The organization_id column has a unique constraint enforcing this at the database level.
credentials_required_when_sync_enabled
If sync_enabled is true, the selected auth_method's required credentials must be present (e.g. api_key_encrypted for api_key method, client_id + client_secret_encrypted for oauth2).
sync_interval_required_when_auto_sync
If sync_enabled is true and the integration requires scheduled sync (not event-driven only), sync_interval_minutes must be set to a positive integer.
deactivate_does_not_delete
Disabling the integration sets is_active=false and sync_enabled=false; it never deletes the record. Config history is preserved for audit.
org_admin_scope
Only Organization Admins (scoped to their own organization) and Global Admins may read or modify this config. Coordinators and Peer Mentors have no access.
audit_on_credential_change
Any change to api_key_encrypted, client_secret_encrypted, webhook_secret_encrypted, or inbound_webhook_token_encrypted must emit an audit log entry recording the change without logging the credential value itself.
no_sync_while_inactive
The sync scheduler must not enqueue sync jobs for configs where is_active=false or sync_enabled=false.