Local Learning API Configuration Reference

This document describes the project-specific configuration used by the Local Learning API. It covers the custom keys consumed by application code and intentionally excludes generic Quarkus settings.

The canonical mapping for these properties is LocalCustomConfig

Design Notes

• Scope: this document focuses on feddb.*, global.socket.*, and gitlab.issue.*.
• Backward compatibility: property names and defaults are intentionally kept aligned with the previous direct @ConfigProperty usage.
• Source of truth: some defaults live in code, some in application.properties, and some are profile-specific overrides.
• Operational rule: use secure deployment-specific overrides for secrets and endpoint URLs.

Quick Reference

Property	Type	Default	Purpose
global.socket.uri	URI	ws://localhost:8080 in shipped config	Defines the upstream websocket endpoint.
global.socket.reconnect.attempts	int	5 in code, -1 in shipped config	Controls reconnect retry behavior.
global.socket.reconnect.delay.init	int	1000	Defines the initial reconnect delay in milliseconds.
global.socket.reconnect.delay.reconnect	int	30000	Defines the maximum reconnect delay in milliseconds.
feddb.export.file	String	none, %dev=test/test_data.csv	Provides a fixed export source for local/testing scenarios.
feddb.export.on-failure.load-all	boolean	none, %dev=true	Enables a broad export fallback when selection is empty.
feddb.permission.add-on-create	boolean	none, true in shipped config	Creates a default permission entry for new cohorts.
feddb.permission.user-name	String	none	Supplies the default permission user binding.
feddb.permission.group-name	String	none	Supplies the default permission group binding.
feddb.permission.query-retry-time	int	3	Defines the default permission retry budget.
feddb.request.data-statistics.enabled	boolean	true	Enables request data statistics processing.
feddb.request.data-statistics.return-all-on-empty	boolean	false, %dev=true	Falls back to all patients when a request resolves empty.
feddb.user.system-user-name	String	SYSTEM	Identifies the technical system owner for persisted records.
feddb.calendar.gregorian.adoption	String	pragmatic	Defines historical calendar date validation behavior.
gitlab.issue.token	String	none	Authenticates GitLab issue creation.
gitlab.issue.project-id	int	9	Selects the target GitLab project.

Global Socket Client

global.socket.uri

• Type: URI
• Default: none in code, set to ws://localhost:8080 in the shipped application.properties
• Required: yes
• Purpose: Base URI of the outbound websocket connection to the global platform.
• Runtime effect: The local service uses this endpoint for its persistent upstream websocket connection. If the URI is wrong, the local node cannot connect, reconnect, or deliver upstream events.
• Allowed values: Any valid websocket URI such as ws://host:port or wss://host:port

global.socket.reconnect.attempts

• Type: int
• Default: 5 in code, set to -1 in the shipped application.properties, %dev=5
• Required: no
• Purpose: Maximum number of reconnect attempts for the upstream websocket connection.
• Runtime effect: -1 means reconnect forever, which is appropriate for resilient deployments. Finite values are useful in development and tests to avoid endless retry loops.
• Allowed values: -1 for infinite retries, or any integer greater than or equal to 0

global.socket.reconnect.delay.init

• Type: int
• Default: 1000
• Required: no
• Purpose: Initial reconnect delay in milliseconds.
• Runtime effect: This value is the base of the exponential backoff sequence. Lower values reconnect more aggressively; higher values reduce reconnect pressure on unstable systems.
• Allowed values: Any integer greater than or equal to 0

global.socket.reconnect.delay.reconnect

• Type: int
• Default: 30000
• Required: no
• Purpose: Maximum reconnect delay in milliseconds.
• Runtime effect: Caps the exponential backoff to prevent reconnect intervals from growing without bound.
• Allowed values: Any integer greater than or equal to 0

Export Behavior

feddb.export.file

• Type: String
• Default: none in code, %dev=test/test_data.csv
• Required: no
• Purpose: Optional classpath resource used as a fixed export source during testing or local development.
• Runtime effect: If set, export flows can bypass live cohort/query data and serve the configured test file instead. This is useful for local testing, but it should not be relied on in production data flows.
• Allowed values: A classpath-relative resource path

feddb.export.on-failure.load-all

• Type: boolean
• Default: none in code, %dev=true
• Required: no
• Purpose: Enables a fallback that loads all query data if the initial learning export selection returns no rows.
• Runtime effect: This is mainly a development and troubleshooting escape hatch. Enabling it changes failure semantics and may export more data than the original filtered request intended.
• Allowed values: true, false

Default Permission Provisioning

feddb.permission.add-on-create

• Type: boolean
• Default: none in code, set to true in the shipped application.properties
• Required: no
• Purpose: Controls whether a default cohort permission entry is created automatically when a cohort is created.
• Runtime effect: If enabled, newly created cohorts receive an automatic default permission record. If disabled, permissions must be created explicitly by later application logic or administrative action.
• Allowed values: true, false

feddb.permission.user-name

• Type: String
• Default: none
• Required: no
• Purpose: Optional default user ID applied to automatically created permission entries.
• Runtime effect: If provided, the default permission record is bound to this user identifier. If absent, no default user binding is written.
• Allowed values: Any valid user identifier understood by the surrounding access model

feddb.permission.group-name

• Type: String
• Default: none
• Required: no
• Purpose: Optional default group ID applied to automatically created permission entries.
• Runtime effect: If provided, the default permission record is bound to this group identifier. If absent, no default group binding is written.
• Allowed values: Any valid group identifier understood by the surrounding access model

feddb.permission.query-retry-time

• Type: int
• Default: 3
• Required: no
• Purpose: Default retry count stored on automatically created permission records.
• Runtime effect: This value influences how many query retries the default permission allows before downstream logic treats the retry budget as exhausted.
• Allowed values: Any integer greater than or equal to 0

Data Statistics Requests

feddb.request.data-statistics.enabled

• Type: boolean
• Default: true
• Required: no
• Purpose: Master switch for the request data statistics feature.
• Runtime effect: If disabled, incoming request-statistics events are ignored and no request entities are created.
• Allowed values: true, false

feddb.request.data-statistics.return-all-on-empty

• Type: boolean
• Default: false, %dev=true
• Required: no
• Purpose: Enables a fallback to all patients when a statistics request resolves to an empty patient set.
• Runtime effect: This can be useful during development or partial data setups, but it changes the semantics of an empty selection and should therefore be used deliberately.
• Allowed values: true, false

Shared Local Identity

feddb.user.system-user-name

• Type: String
• Default: SYSTEM
• Required: no
• Purpose: Technical user name used for system-owned entities such as workflows and files.
• Runtime effect: This value is written into persistence and used in ownership checks. Changing it later can break lookup behavior for already stored system-owned records unless a migration is performed.
• Allowed values: Any stable identifier intended for system ownership

Calendar Validation

feddb.calendar.gregorian.adoption

• Type: String
• Default: pragmatic
• Required: no
• Purpose: Defines how historical Gregorian calendar adoption gaps are validated for patient dates.
• Runtime effect: The mapper rejects dates that fall into the configured historical gap. This directly changes whether older imported dates are accepted or rejected.
• Allowed values:
• catholic: rejects dates from 1582-10-05 through 1582-10-14
• british: rejects dates from 1752-09-03 through 1752-09-13
• pragmatic: allows all dates

GitLab Issue Integration

gitlab.issue.token

• Type: String
• Default: none
• Required: yes for authenticated GitLab issue creation
• Purpose: Private token sent by the local GitLab REST client.
• Runtime effect: Without a valid token, the local service cannot create issues through the configured GitLab project API.
• Allowed values: A valid GitLab private token

gitlab.issue.project-id

• Type: int
• Default: 9
• Required: no
• Purpose: Target GitLab project ID for issue creation.
• Runtime effect: This determines which project receives issues submitted by the local service.
• Allowed values: Any valid GitLab project ID visible to the configured token

Operational Guidance

• Keep global.socket.uri environment-specific; it is infrastructure, not business logic.
• Treat gitlab.issue.token as a secret and do not commit production values.
• Be careful with fallback flags such as feddb.export.on-failure.load-all and feddb.request.data-statistics.return-all-on-empty; both intentionally weaken strict behavior for local or troubleshooting scenarios.
• If you add a new custom property to the local service, update both LocalCustomConfig and this reference in the same change.