# Configure ODD Platform
This page is the post-deployment configuration reference for the running Platform — every `application.yml` key the Platform consumes. For the deployment path itself (Docker Compose, Helm, AWS EKS, build from source), start at [Deployment Options](/configuration-and-deployment/deployment.md).
## Configuration approaches
There are two ways to configure the Platform:
* **Environment variables** are used for simple entries
* Configuring via **YAML** can come in handy when it is necessary to define a complex configuration block (e.g OAuth2 authentication or logging levels).
YAML entries VS environment variables
Here is an example of how to define the following block and configure the Platform with it using environment variables.
YAML:
```yaml
spring:
datasource:
url: URL
username: USERNAME
password: PASSWORD
custom-datasource:
url: URL
username: USERNAME
password: PASSWORD
```
To configure the Platform using environment variables, replace semicolons with underscores and uppercasing words, like so:
* `SPRING_DATASOURCE_URL=URL`
* `SPRING_DATASOURCE_USERNAME=USERNAME`
* `SPRING_DATASOURCE_PASSWORD=PASSWORD`
* `SPRING_CUSTOM_DATASOURCE_URL=URL`
* `SPRING_CUSTOM_DATASOURCE_USERNAME=USERNAME`
* `SPRING_CUSTOM_DATASOURCE_PASSWORD=PASSWORD`
## Connect your database
For all of its features ODD Platform uses PostgreSQL database and PostgreSQL database only. These variables are needed to be defined to connect ODD Platform to database:
* `spring.datasource.url`: [JDBC string](https://jdbc.postgresql.org/documentation/80/connect.html) of your PostgreSQL database. Default value is `jdbc:postgresql://127.0.0.1:5432/odd-platform`
* `spring.datasource.username`: your PostgreSQL user's name. Default value is `odd-platform`
* `spring.datasource.password`: your PostgreSQL user's password. Default value is `odd-platform-password`. **Override this before any non-localhost deployment** — see [Management endpoint exposure and credential hygiene](#management-endpoint-exposure-and-credential-hygiene) for why the shipped default is a load-bearing operator-override.
These variables are optional and will be used to connect to PostgreSQL and store Lookup Tables. Each of the three keys is declared in `R2DBCConfiguration` as `@Value("${spring.custom-datasource.X:}")` — the trailing colon with no value means **the @Value default is the empty string**, not the JDBC URL / username / password values listed below. When a key is unset (or blank), the bean factory falls back to the corresponding primary `spring.datasource.*` value at startup. The values below are therefore the **fallback** an operator observes with a default deployment, not the `spring.custom-datasource.*` keys' own defaults — so overriding `spring.datasource.url` will also change what `spring.custom-datasource.url` resolves to:
* `spring.custom-datasource.url`: [JDBC string](https://jdbc.postgresql.org/documentation/80/connect.html) of your PostgreSQL database where we store Lookup Tables. Falls back to `spring.datasource.url` when unset; the platform's primary `spring.datasource.url` default is `jdbc:postgresql://127.0.0.1:5432/odd-platform`. Note: you can specify any {database\_host}, {database\_port} or {database\_name} but schema, where Lookup Tables are stored always is lookup\_tables\_schema.
* `spring.custom-datasource.username`: your PostgreSQL user's name for custom-datasource. Falls back to `spring.datasource.username` when unset; the platform's primary `spring.datasource.username` default is `odd-platform`.
* `spring.custom-datasource.password`: your PostgreSQL user's password for custom-datasource. Falls back to `spring.datasource.password` when unset; the platform's primary `spring.datasource.password` default is `odd-platform-password`.
So that your database connection defining block would look like this:
{% tabs %}
{% tab title="YAML" %}
```yaml
spring:
datasource:
url: jdbc:postgresql://{database_host}:{database_port}/{database_name}
username: {database_username}
password: {database_password}
# [OPTIONAL]
custom-datasource:
url: jdbc:postgresql://{database_host}:{database_port}/{database_name}
username: {database_username}
password: {database_password}
```
{% endtab %}
{% tab title="Environment variables" %}
```
SPRING_DATASOURCE_URL=jdbc:postgresql://{database_host}:{database_port}/{database_name}
SPRING_DATASOURCE_USERNAME={database_username}
SPRING_DATASOURCE_PASSWORD={database_password}
# [OPTIONAL]
SPRING_CUSTOM_DATASOURCE_URL=jdbc:postgresql://{database_host}:{database_port}/{database_name}
SPRING_CUSTOM_DATASOURCE_USERNAME={database_username}
SPRING_CUSTOM_DATASOURCE_PASSWORD={database_password}
```
{% endtab %}
{% endtabs %}
## Security
Please follow the [Enable security](/configuration-and-deployment/enable-security.md) section for enabling security in ODD Platform.
### Management endpoint exposure and credential hygiene
The platform's Spring Boot Actuator endpoints (`/actuator/**`) are intentionally **whitelisted ahead of the authentication chain** in every `auth.type`, and the shipped configuration enables the `env` and `info` endpoints. The shipped database password is a well-known string. Together these defaults turn a default deployment into a one-line-away-from-full-PostgreSQL-compromise system if exposed on a non-trusted network. The mitigations below are the operator's responsibility today. For the *monitoring* use of these endpoints — wiring liveness/readiness probes to `/actuator/health` and scraping `/actuator/prometheus` — see [Health and monitoring](/configuration-and-deployment/health-and-monitoring.md).
#### `/actuator/**` is anonymously reachable in every auth mode
`SecurityConstants.WHITELIST_PATHS` contains `/actuator/**`. Reachable before the auth chain runs in `DISABLED`, `LOGIN_FORM`, `OAUTH2`, and `LDAP` alike. The shipped `application.yml` enables `management.endpoint.env.enabled=true` but sets **no** `management.endpoint.env.show-values`, so the Spring Boot default (`NEVER`) applies — `/actuator/env` redacts *every* property **value** (`******`) for every caller, authenticated or not, including `spring.datasource.url`. What an unauthenticated caller scraping `/actuator/env` *does* learn is the **configuration-key schema**: which keys and property sources are present — which OAuth2 providers are wired (by their key prefixes), whether LDAP is configured, whether REMOTE attachment storage is set up, and that a JDBC datasource is configured (the key, not its value). Values stay masked unless an operator sets `show-values` to `WHEN_AUTHORIZED` or `ALWAYS`; the exposure to mitigate is the unauthenticated reachability of the endpoint and the configuration schema it reveals.
Apply at least one of the mitigations below for any deployment reachable from outside a fully-trusted network:
| Mitigation | How | Recommended for |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Separate management port | Set `management.server.port: 8081` and route `:8081` only on your internal management network. | All production deployments. |
| Firewall the actuator path | Add a reverse-proxy rule rejecting `/actuator/**` from the public CIDR range; allow only your monitoring network. | Single-port deployments where a separate management port is infeasible. |
| Restrict default exposure | Set `management.endpoints.web.exposure.include: health,prometheus` (drop `env, info`). | All production deployments — combine with one of the network-level mitigations above. |
A platform-side default-restriction is tracked upstream; until it ships, do not rely on the platform default for any reachable deployment.
#### The database password ships with a well-known default
`application.yml` ships `spring.datasource.password: odd-platform-password` as the default. An operator deploying ODD without explicitly overriding the property deploys with a public, documented credential. (The JDBC URL *value* is masked at `/actuator/env` under the default `show-values: NEVER` described above — but the password itself is public, and a database whose host is co-located with or guessable from the deployment topology is then one well-known credential away from compromise.) Override `spring.datasource.password` (and `spring.custom-datasource.password` if `spring.custom-datasource.*` is configured separately from the primary datasource) before exposing the platform on any non-localhost network. This is the same class of silent-insecure-default risk that previously affected attachment storage on container restart — read once, override before deployment, never assume the shipped default is safe.
#### Configuration-properties classes include credentials in `toString()`
`ODDLDAPProperties` and `ODDOAuth2Properties.OAuth2Provider` carry Lombok's `@Data` annotation alongside their `password` and `clientSecret` fields, respectively. `@Data` generates a `toString()` that includes every field verbatim — there is no `@ToString.Exclude` on any credential field today. A future log statement (`log.info("loaded properties: {}", properties)`) or an exception handler that emits properties on boot failure would write LDAP passwords and OAuth client secrets in cleartext to log infrastructure. Treat the platform's application logs as credential-sensitive: route them to an audit-grade log sink, redact at the log-pipeline tier if you cannot guarantee end-to-end access control, and do not store them in unrestricted long-term archives. A platform-side `@ToString.Exclude` rollout across credential fields is tracked upstream.
## Select session provider
ODD Platform stores HTTP session state in one of three places: the platform JVM (in-memory), the platform's PostgreSQL database, or an external Redis data store. The provider is selected with `session.provider` (`SESSION_PROVIDER` env var) and accepts one of three values:
* `IN_MEMORY` — sessions live in a `ConcurrentHashMap` inside the JVM. **ODD Platform defaults to this value.**
* `INTERNAL_POSTGRESQL` — sessions are persisted to the platform's PostgreSQL database (`SPRING_SESSION` / `SPRING_SESSION_ATTRIBUTES` tables).
* `REDIS` — sessions are persisted to an external [Redis](https://redis.io/) data store via Spring Session's `@EnableRedisWebSession`.
Quick selection guidance:
* Single-instance deployment, restart-tolerant logout acceptable → `IN_MEMORY`
* Multi-instance deployment or persistence across restarts is required → `INTERNAL_POSTGRESQL` (no extra infrastructure) or `REDIS` (if you already operate Redis or need sub-millisecond session reads)
Each provider has operator-visible characteristics that affect sizing, multi-instance behavior, and connection wiring. Read the relevant subsection before deploying.
### `IN_MEMORY` (default)
Sessions are kept in a `ConcurrentHashMap` inside the platform JVM, wrapped by Spring Session's `ReactiveMapSessionRepository`. Suitable for local development and single-instance evaluations where session loss on restart is acceptable.
#### Characteristics & caveats
* **Sessions are lost on every platform restart.** The session map lives in heap; any restart (deploy, crash, container recycle) clears it and forces every authenticated user to log in again.
* **No multi-instance support.** Two ODD Platform instances behind a load balancer each maintain a separate session map. A request that lands on a different instance than the one that authenticated the user appears unauthenticated. **Collector data-source registration is especially affected** — the `/ingestion/datasources` filter writes a `collectorId` into the request's session, and the subsequent `POST /ingestion/datasources` handler reads it back; if the two requests hit different replicas, the handler raises an `IllegalStateException("Collector id is null")` returned to the collector as HTTP 500. For multi-replica deployments choose `INTERNAL_POSTGRESQL` or `REDIS`.
* **Eviction is by Spring Session expiry only.** The repository wraps a raw `ConcurrentHashMap` with no secondary eviction policy (no LRU, no max-entries cap). A long-running platform with many short-lived sessions accumulates map entries until each entry's TTL elapses; high-traffic deployments running with the shipped default `spring.session.timeout: -1` (no timeout) accumulate sessions indefinitely. **Set a finite `spring.session.timeout`** (see [Session lifetime](#session-lifetime-spring-session-timeout) below) to bound the in-memory footprint.
{% tabs %}
{% tab title="YAML" %}
```yaml
session:
provider: IN_MEMORY
```
{% endtab %}
{% tab title="Environment variables" %}
```
SESSION_PROVIDER=IN_MEMORY
```
{% endtab %}
{% endtabs %}
### `INTERNAL_POSTGRESQL`
Sessions are persisted in the platform's own PostgreSQL database, in the `SPRING_SESSION` and `SPRING_SESSION_ATTRIBUTES` tables. ODD Platform implements a custom JOOQ-based reactive `JooqSessionRepository` for this provider — the standard `spring.session.jdbc.*` Spring Session keys do **not** apply. Connection settings reuse the existing platform `spring.datasource.*` configuration; no additional database wiring is required.
#### Characteristics & caveats
* **Sessions survive platform restarts.** Authenticated users remain logged in across deploys (until their session row's TTL has passed).
* **Multi-instance support.** All ODD Platform instances point at the same database, share the session tables, and can serve requests for any authenticated user regardless of which instance answered the original login.
* **Expired-session cleanup runs hourly and is not configurable.** A `@Scheduled(fixedRate = 1, timeUnit = HOURS)` housekeeping job (`PostgreSQLSessionHousekeepingJobHandler.deleteExpiredSessions`) deletes rows whose `EXPIRY_TIME` is in the past from both `SPRING_SESSION` and `SPRING_SESSION_ATTRIBUTES`. Expired session rows therefore remain in the tables for **up to one hour past their TTL** before being cleaned. The cadence is hardcoded — there is no config key to tune it.
* **Sizing implication.** When sizing the database (connection pool, disk, vacuum schedule), assume the session tables hold the high-water-mark count of authenticated users plus up to one hour of post-expiry stragglers. For high-cardinality / short-TTL deployments (many users, short `spring.session.timeout`), the post-expiry overhang can dominate steady-state row count.
{% tabs %}
{% tab title="YAML" %}
```yaml
session:
provider: INTERNAL_POSTGRESQL
```
{% endtab %}
{% tab title="Environment variables" %}
```
SESSION_PROVIDER=INTERNAL_POSTGRESQL
```
{% endtab %}
{% endtabs %}
### `REDIS`
Sessions are persisted to an external Redis data store via Spring Session's `@EnableRedisWebSession`. Suitable for multi-instance deployments that already operate Redis, or that need sub-millisecond session reads. ODD Platform does not bundle Redis; the operator must provide a Redis 6+ instance and supply its connection settings under the `spring.data.redis.*` namespace (Spring Boot 3.x; the legacy `spring.redis.*` prefix from Spring Boot 2.x has been removed and will not bind).
#### Characteristics & caveats
* **Sessions survive platform restarts and span instances** — same persistence behavior as `INTERNAL_POSTGRESQL`, but reads and writes happen against Redis directly.
* **Connection wiring is operator-supplied.** Unlike `INTERNAL_POSTGRESQL` (which reuses the platform's existing PostgreSQL connection), Redis settings must be configured separately. ODD Platform's `application.yml` ships **no Redis defaults** — every operator deploying with `REDIS` must set at least the host and port, plus credentials and TLS for any production deployment.
* **TLS, pool sizing, and command timeouts inherit Spring Data Redis defaults** unless explicitly overridden. For managed Redis providers (AWS ElastiCache, Redis Cloud, Azure Cache for Redis) and any TLS-required Redis deployment, set `spring.data.redis.ssl.enabled: true`. For high-concurrency deployments, tune the Lettuce connection pool with `spring.data.redis.lettuce.pool.*`.
* **Eviction is delegated to Redis.** ODD Platform does not run a housekeeping job for Redis-stored sessions; the Redis server's own per-key TTL and `maxmemory-policy` govern session eviction. Configure your Redis instance accordingly.
{% hint style="warning" %}
**The** [**health endpoint**](/configuration-and-deployment/health-and-monitoring.md) **is blind to Redis by default.** With `REDIS` selected, every authenticated request depends on Redis — but the bundled configuration ships `management.health.redis.enabled: false`, and the `REDIS` session wiring registers no health contributor of its own. A Redis outage (server down, unreachable, or evicting under `maxmemory`) therefore returns errors to every logged-in user while `/actuator/health` keeps reporting `UP` — a load balancer or Kubernetes readiness probe pointed at it keeps routing traffic to a platform that cannot serve a single authenticated request. If you deploy with `REDIS`, set `management.health.redis.enabled: true` so the Redis indicator participates in the health verdict, and do not rely on a bare `/actuator/health` probe alone to detect a session-store outage.
{% endhint %}
#### Required and optional connection keys (Spring Boot 3.x — `spring.data.redis.*`)
* `spring.data.redis.host`: Redis host. Defaults to `localhost`.
* `spring.data.redis.port`: Redis port. Defaults to `6379`.
* `spring.data.redis.username`: Redis ACL username. Optional; omit for password-only or no-auth Redis.
* `spring.data.redis.password`: Redis password. Optional but recommended for any production deployment.
* `spring.data.redis.database`: Redis logical database index. Defaults to `0`.
* `spring.data.redis.ssl.enabled`: enable TLS for the Redis connection. Boolean, defaults to `false`. Set to `true` for any managed-Redis or TLS-terminated Redis deployment.
* `spring.data.redis.timeout`: command timeout. Duration string (for example `5s`). Defaults to Spring Data Redis's internal default.
* `spring.data.redis.lettuce.pool.*`: Lettuce connection-pool sizing (`max-active`, `max-idle`, `min-idle`, `max-wait`). Optional; tune for high-concurrency deployments.
ODD Platform does not extend or override Spring Boot's Redis property catalogue — the full set of keys recognized under `spring.data.redis.*` in your Spring Boot version applies as-is.
{% tabs %}
{% tab title="YAML" %}
```yaml
session:
provider: REDIS
spring:
data:
redis:
host: redis.your-domain.com
port: 6380
username: odd-platform
password: ${REDIS_PASSWORD}
database: 0
ssl:
enabled: true
timeout: 5s
```
{% endtab %}
{% tab title="Environment variables" %}
```
SESSION_PROVIDER=REDIS
SPRING_DATA_REDIS_HOST=redis.your-domain.com
SPRING_DATA_REDIS_PORT=6380
SPRING_DATA_REDIS_USERNAME=odd-platform
SPRING_DATA_REDIS_PASSWORD=...
SPRING_DATA_REDIS_DATABASE=0
SPRING_DATA_REDIS_SSL_ENABLED=true
SPRING_DATA_REDIS_TIMEOUT=5s
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**`spring.redis.*` (the Spring Boot 2.x prefix) is silently ignored.** Spring Boot 3.x removed the `spring.redis.*` namespace and relocated all Redis properties under `spring.data.redis.*`. Configuration written against the older prefix will not bind, the platform falls back to `localhost:6379` defaults, and the symptom is connection failures against your real Redis instance with no obvious "wrong key" error. Migrate any pre-3.x configuration to `spring.data.redis.*` (and `SPRING_DATA_REDIS_*` for env vars).
{% endhint %}
### Session lifetime (`spring.session.timeout`)
Spring Session's timeout controls how long an authenticated session remains valid between requests. ODD Platform's shipped default is `-1`, which means **sessions never expire**.
{% hint style="warning" %}
**`spring.session.timeout: -1` means sessions never expire.** A user who logs in once remains authenticated until their session record is explicitly invalidated (logout, cache eviction, or — for `IN_MEMORY` — platform restart). For any deployment that is internet-facing or serves multiple users, set `spring.session.timeout` to a finite duration so stolen cookies and forgotten sessions eventually lapse.
{% endhint %}
* `spring.session.timeout`: session idle timeout. Duration string (for example `30m`, `8h`, `1d`). Defaults to `-1` (no timeout). Applies to all three providers (`IN_MEMORY`, `INTERNAL_POSTGRESQL`, `REDIS`).
{% tabs %}
{% tab title="YAML" %}
```yaml
spring:
session:
timeout: 30m
```
{% endtab %}
{% tab title="Environment variables" %}
```
SPRING_SESSION_TIMEOUT=30m
```
{% endtab %}
{% endtabs %}
### Cookie attributes (`Secure`, `SameSite`, `HttpOnly`)
ODD Platform does **not** stamp `Secure`, `SameSite`, or `HttpOnly` attributes on the session cookie at the application tier — there is no `CookieWebSessionIdResolver` bean in the platform's session configuration today. The browser-side cookie posture is whatever Spring's default `SESSION` cookie defaults are (no `Secure`, no `SameSite` directive, `HttpOnly` set), which is unsuitable for any internet-facing deployment.
Operators **must** stamp the production attributes at the deployment topology layer — typically the TLS-terminating reverse proxy or load balancer. For nginx, the directive looks like:
```nginx
location / {
proxy_pass http://odd-platform:8080;
proxy_cookie_path / "/; Secure; HttpOnly; SameSite=Strict";
}
```
Match the equivalent for your ingress controller (Traefik, Envoy, Cloud Load Balancer, etc.). Until a platform-side default-stamping bean ships upstream, this stamping is the operator's responsibility — running ODD over plain HTTP or behind a permissive proxy means the session cookie travels in clear and is vulnerable to cross-site-request and cookie-leak attacks regardless of which `auth.type` is configured.
### Java-serialised session attributes under `INTERNAL_POSTGRESQL`
The `INTERNAL_POSTGRESQL` provider stores session attribute values as raw bytes produced by Java's native `SerializationUtils.serialize` / `.deserialize`. Java native serialisation has a well-known deserialisation-gadget surface — code paths reachable on attribute load are influenced by the byte stream, so a write-access compromise of the `SPRING_SESSION_ATTRIBUTES` table yields a deserialisation entry point on the next session read.
Defence-in-depth recommendations for deployments running `INTERNAL_POSTGRESQL`:
* Restrict write access to the `SPRING_SESSION_ATTRIBUTES` table to a single platform service account; do not share database credentials with other applications that store data in the same Postgres instance.
* Deploy the platform's PostgreSQL with strong network segmentation — the database should not be reachable from any service except the platform itself.
* If you cannot guarantee write-access isolation, prefer the `REDIS` provider — Spring Session's Redis serialiser uses a string-key Jackson JSON serialiser rather than Java native serialisation.
A platform-side migration to JSON serialisation for session attributes is tracked upstream.
## Enable Metrics
ODD Platform can represent some of the metadata it ingests as time-series charts — for example, row counts on a MySQL table or the on-disk size of a Redshift database. Metrics handling splits into two independent concerns that share the `metrics.*` config namespace but do different jobs:
* **Storage** (`metrics.storage`) — the storage tier the platform uses for ingested metrics. This selects where the platform **writes** metric points as they arrive from collectors **and** where it **reads them back** when rendering UI charts. Both directions hit the same backend — you cannot write to one and read from another.
* **Export** (`metrics.export.*`) — where the platform **pushes metrics out** as OpenTelemetry telemetry, for long-term retention and dashboarding in your observability stack.
Configure the two independently; it is valid (and common) to run with `INTERNAL_POSTGRES` storage and no OTLP export, or with `PROMETHEUS` storage and OTLP export disabled, or any other combination.
### Metric storage backend
`metrics.storage` selects the storage tier for metric writes and reads:
* `INTERNAL_POSTGRES` (default) — metrics are **written to and read from** the ODD Platform's own PostgreSQL database (`metric_series` / `metric_point` tables). Zero additional infrastructure; suitable for most single-cluster deployments.
* `PROMETHEUS` — metrics are **remote-written to** an external Prometheus instance (via the [Prometheus remote-write protocol](https://prometheus.io/docs/specs/remote_write_spec/) at `/api/v1/write`, using Snappy-compressed Protobuf-encoded write requests) **and queried from** the same instance (via the [instant-query API](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries) at `/api/v1/query`). Suitable when you already run Prometheus for observability and want to avoid storing duplicate metric data in ODD's PostgreSQL.
`metrics.prometheus-host` is the base URL of the Prometheus instance and is only consulted when `metrics.storage=PROMETHEUS`. Both `/api/v1/write` and `/api/v1/query` are called on this single host. Defaults to `http://localhost:9090`.
{% hint style="warning" %}
**`metrics.storage=PROMETHEUS` requires `metrics.prometheus-host` to be set.** The platform validates this at startup — if `metrics.prometheus-host` is empty (or unset) while `metrics.storage=PROMETHEUS`, ODD Platform fails to start with `IllegalStateException: Prometheus host is not defined`. Set it to the Prometheus base URL (for example `http://prometheus:9090`) in the same configuration change that flips the storage backend.
{% endhint %}
{% hint style="warning" %}
**The Prometheus instance must accept remote-write AND queries on the same endpoint.** ODD Platform does not support splitting read and write paths across different hosts.
* **Prometheus server flag** — `--web.enable-remote-write-receiver` must be enabled on the Prometheus process. It is **disabled by default** in Prometheus v2.33+; without it, every ODD Platform metric write returns `404 Not Found` and is silently dropped. The ingestion API still returns `200` to the collector because the remote-write happens downstream of the HTTP acknowledgement, so collector logs will not surface the failure — the symptom is empty charts in the UI.
* **Endpoint must support both paths** — `POST /api/v1/write` (for writes) and `GET /api/v1/query` (for reads) must both resolve to the same Prometheus-compatible host.
* **Read-only Prometheus-compatible backends do not work.** A [Thanos](https://thanos.io/) querier, [Mimir](https://grafana.com/oss/mimir/) in query-only mode, or any other backend that exposes `/api/v1/query` but rejects `/api/v1/write` cannot be used as a `metrics.storage=PROMETHEUS` target. Point `metrics.prometheus-host` at the write-accepting Prometheus instance itself (or at a Mimir distributor that terminates both paths).
{% endhint %}
{% tabs %}
{% tab title="YAML" %}
```yaml
metrics:
storage: PROMETHEUS # INTERNAL_POSTGRES (default) or PROMETHEUS
prometheus-host: http://prometheus:9090
```
{% endtab %}
{% tab title="Environment variables" %}
```
METRICS_STORAGE=PROMETHEUS
METRICS_PROMETHEUS_HOST=http://prometheus:9090
```
{% endtab %}
{% endtabs %}
{% hint style="danger" %}
**Multi-tenant deployments cannot share an `INTERNAL_POSTGRES` instance — the default backend has no tenant column.** The `odd.tenant-id` configuration is **only** appended to Prometheus series (see [Prometheus tenant label](#prometheus-tenant-label-odd-tenant-id) below); on `INTERNAL_POSTGRES` the metric tables (`metric_series`, `metric_point`, `metric_entity`) have no `tenant_id` column at all. Two ODD Platform deployments writing to the same Postgres instance see each other's metrics on every entity's Metrics tab — there is no platform-side filter. If your deployment needs metric isolation across tenants, choose `PROMETHEUS` storage and configure `odd.tenant-id` per deployment, or run each deployment against its own Postgres instance / schema. The same class of silent-default risk that previously affected attachment storage on container restart applies here. The operator-facing framing of this caveat — including the workflow guidance for choosing between the two backends — is on [Active platform features → Metrics Ingestion](/features/active-platform-features/metrics-ingestion.md#known-operator-caveats).
{% endhint %}
{% hint style="warning" %}
**Switching `metrics.storage` after a deployment has been live is one-way — historical metric data does not migrate.** The two storage backends are independent stores; the platform writes to whichever is configured and reads from the same one. After a switch (either direction), the previously-stored history remains in the old backend but is **no longer queryable from the platform UI or API**. Plan storage-backend changes as one-time cutovers and annotate the cutover date in your runbook — the Metrics tab on each entity will show no data older than the switch. Operator-facing framing on [Active platform features → Metrics Ingestion](/features/active-platform-features/metrics-ingestion.md#known-operator-caveats).
{% endhint %}
### Metric export to OTLP
Independent of where metrics are stored, ODD Platform can push metrics as OpenTelemetry telemetry to an [OTLP collector](https://opentelemetry.io/docs/collector/). Downstream you can forward that stream to [Prometheus](https://prometheus.io/), [New Relic](https://newrelic.com/), or any backend that accepts [OTLP exporters](https://aws-otel.github.io/docs/components/otlp-exporter).
* `metrics.export.enabled`: must be set to `true` to build and wire the OTLP exporter bean. Defaults to `false`.
* `metrics.export.otlp-endpoint`: OTLP collector endpoint (gRPC). Defaults to `http://localhost:4317`.
{% tabs %}
{% tab title="YAML" %}
```yaml
metrics:
export:
enabled: true
otlp-endpoint: {otlp-endpoint-url}
```
{% endtab %}
{% tab title="Environment variables" %}
```
METRICS_EXPORT_ENABLED=true
METRICS_EXPORT_OTLP_ENDPOINT={otlp-endpoint-url}
```
{% endtab %}
{% endtabs %}
## Enable Alert Notifications
Any alert that is created inside the platform can be sent via webhook and/or [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) and/or email notifications (via [Google SMTP](https://support.google.com/a/answer/176600?hl=en), [AWS SMTP](https://repost.aws/knowledge-center/ses-set-up-connect-smtp), etc). Such notifications contain information such as:
1. Name of the entity upon which alert has been created
2. Data source and namespace of an entity
3. Owners of an entity
4. Possibly affected entities
ODD Platform's outbound notification delivery tails the `alert` table through a PostgreSQL logical-replication slot. Because the slot durably tracks its position in the write-ahead log, delivery resumes from the last unprocessed alert after a platform restart or a transient interruption of the database connection — alerts raised during the downtime are delivered once delivery catches up, not dropped. Alert *creation* itself is a plain database insert and does not depend on replication; this prerequisite applies only to outbound notification delivery. To enable it, the underlying PostgreSQL database must be configured for logical replication.
For the user-facing description of the alerting feature — alert types, the per-entity alert tabs, the lifecycle, and per-entity halt configuration — see [Active platform features → Alerting](/features/active-platform-features/alerting.md). For the user-facing description of the outbound notification channels (Slack incoming webhook, email, generic webhook) and the Prometheus AlertManager inbound webhook, see [Active platform features → Notifications](/features/active-platform-features/notifications.md).
{% hint style="info" %}
**Slack here is the outgoing alert webhook, not the Discussions Slack app.** The alert-notifications integration is a one-way [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) — the platform POSTs alert messages to a channel via `notifications.receivers.slack.url`. It is **distinct** from the [full Slack app](#enable-data-collaboration) used by Data Collaboration for in-app per-entity discussion threads (OAuth + Events API; bidirectional). Each integration is configured separately: enabling the alert webhook does not surface the **Discussions** tab on data-entity pages, and enabling Data Collaboration does not route alerts. See [Main Concepts → Terms & Aliases](/introduction/main-concepts.md#terms-and-aliases) for the side-by-side comparison.
{% endhint %}
### PostgreSQL Configuration
PostgreSQL database must be [configured](https://www.postgresql.org/docs/current/config-setting.html) in order to leverage the replication mechanism of the Platform along with the granting the database user replication permissions.
#### Database settings
To configure the database, add the following entries to the `postgresql.conf` file:
```
max_wal_senders = 1
wal_keep_size = 16
wal_level = logical
max_replication_slots = 1
```
Or if the replication mechanism is already configured, just increment the `max_wal_senders` and `max_replication_slots` numbers.
#### Database user permissions
ODD Platform database user must be granted with replication permissions:
```sql
ALTER ROLE {database_username} WITH REPLICATION
```
{% hint style="info" %}
User permissions and database configuration may vary from one on-demand/cloud provider to another.
For instance, In AWS RDS, PostgreSQL instances are managed services where certain aspects of replication management are automated. This is done to minimize the risk of misconfiguration. Due to this managed nature, some settings are either not exposed or are altered differently compared to a standard PostgreSQL setup. To enable notifications in such an environment, follow these steps (only differences are mentioned): 1. Alter the `rds.logical_replication` parameter in your database instance's Parameter Group by setting it to `1`, instead of directly modifying the `wal_level` parameter. 2. Ensure the ODD user connecting to the database has the `rds_replication` role. The Master username of the database typically already has this role by default. If using a different username, you may need to assign the necessary role using the command `GRANT rds_replication TO {your_database_username}; 3.`If you changed max\_wal\_senders to 5 (as it's mentioned as a minimal value in Parameter Group) and then constantly getting messages like "The parameter max\_wal\_senders was set to a value incompatible with replication. It has been adjusted from 5 to 55" in the events list of the database instance, please, consider adjusting the parameter from 5 to the mentioned value in the parameter group to exclude automatic change done by RDS.
{% endhint %}
### ODD Platform configuration
Following variables need to be defined:
* `notifications.enabled`: must be set to `true`. Defaults to `false`. **Feature toggling**: this value is captured at JVM boot and frozen for the lifetime of the process; restart the JVM for a change to take effect. The same boot-immutable pattern applies to every platform-feature flag in this document — see [Features → Data Collaboration](/features/features.md#data-collaboration) for the catalogue and the chrome-invariance framing.
* `notifications.message.downstream-entities-depth`: limits the amount of fetching of affected data entities **in terms of lineage graph level.** Defaults to 1
* `notifications.wal.advisory-lock-id`: ODD Platform uses [PostgreSQL advisory lock](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) in order to make sure that in a case of horizontal scaling only one instance of the Platform processes alert messages. This setting defines advisory lock id. Defaults to `100`
* `notifications.wal.replication-slot-name`: PostgreSQL replication slot name will be created if it doesn't exist yet. Defaults to `odd_platform_replication_slot`
* `notifications.wal.publication-name`: PostgreSQL publication name will be created if it doesn't exist yet. Defaults to `odd_platform_publication_alert`
* `notifications.receivers.slack.url`: [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) URL. The clickable links rendered inside Slack messages use [`odd.platform-base-url`](#odd-platform-base-url) — there is **no** `notifications.receivers.slack.*` base-URL setting.
* `notifications.receivers.webhook.url`: Generic webhook URL
* `notifications.receivers.email.host`: the SMTP server.
* `notifications.receivers.email.port`: the port used for the email protocol (SMTP, IMAP, or POP3)
* `notifications.receivers.email.protocol`: the email transport protocol. **Use the lowercase value `smtp`** — any other value (including uppercase `SMTP`) silently disables STARTTLS and SMTP AUTH; see the caveat below.
* `notifications.receivers.email.smtp.auth`: a boolean value (true or false) indicating whether the SMTP server requires authentication
* `notifications.receivers.email.smtp.starttls`: a boolean indicating whether to use STARTTLS, a security protocol that upgrades an unencrypted connection to an encrypted one
* `notifications.receivers.email.password`: the password used for email authentication
* `notifications.receivers.email.sender`: the email address sending the notifications
* `notifications.receivers.email.notification.emails`: the list of recipients for the email notifications
{% hint style="warning" %}
**A generic-webhook receiver must respond `HTTP 200` — `201` / `202` / `204` are treated as a delivery failure and the alert is dropped.** The platform's webhook sender treats any response status other than exactly `200 OK` as a failed delivery, so a receiver that returns `202 Accepted` (a common async-ingest convention) silently loses alerts with no operator-visible cause. Configure the endpoint behind `notifications.receivers.webhook.url` to return `200` on accept.
{% endhint %}
{% hint style="warning" %}
**The email `protocol` value must be the lowercase string `smtp` for STARTTLS and SMTP AUTH to engage.** The platform sets `mail.smtp.auth` and `mail.smtp.starttls.enable` only when `notifications.receivers.email.protocol` equals `smtp` exactly. Any other value — including uppercase `SMTP` — takes a fall-through branch that sets neither, so authentication and STARTTLS never engage and credentials can transit unauthenticated and unencrypted, with no boot warning. Always configure `protocol: smtp` (lowercase).
{% endhint %}
#### `odd.platform-base-url`
ODD Platform URL exposed to **three** internal consumers — the Slack-notification sender, the email-notification sender, and the integration-parameter substitution context. The two notification senders use it to build clickable links inside alert messages (the generic webhook receiver does **not** consume this key — it gets the full alert payload directly and is expected to construct any URLs it needs from that payload). The platform also substitutes the resolved value as the `platform_url` parameter in integration configurations — this is how Airflow plugins, dbt artifacts, and similar integrations resolve their reference to the ODD platform URL at runtime. **Defaults are inconsistent across consumers**: the notification senders default to `http://localhost:8080`, while the integration-substitution context defaults to the placeholder string `http://your.odd.platform`. Both defaults are unreachable from outside the host machine; set this key to your real deployment URL (for example `https://odd.your-domain.com`) in any non-local environment.
{% hint style="warning" %}
**Operators deploying integrations must set `ODD_PLATFORM_BASE_URL` even if alert notifications are disabled.** The integration-parameter substitution context reads the same key to populate the `platform_url` parameter exposed to integration configurations. If the key is unset, integrations that reference `platform_url` receive the literal string `http://your.odd.platform` — a placeholder that will not connect to anything — and the integration will fail in confusing ways at runtime with no error from ODD Platform itself.
{% endhint %}
ODD Platform configuration would look like this:
{% tabs %}
{% tab title="YAML" %}
```yaml
notifications:
enabled: true
message:
downstream-entities-depth: {downstream_entities_depth_to_fetch}
wal:
advisory-lock-id: {postgresql_advisory_lock_id}
replication-slot-name: {postgresql_replication_slot_name}
publication-name: {postgresql_publication_name}
receivers:
slack:
url: {slack_incoming_webhook_url}
webhook:
url: {webhook_url}
email:
host: {host}
port: {port}
protocol: {protocol} # SMTP, SMTPS, IMAP, IMAPS, POP3, POP3S
smtp:
auth: true # Set to true if SMTP server requires authentication
starttls: true # Set to true to enable STARTTLS
password: {email_password}
sender: {sender_email}
notification:
emails: {1@mail.com,2@mail.com}
odd:
platform-base-url: {platform_url}
```
{% endtab %}
{% tab title="Environment variables" %}
```
NOTIFICATIONS_ENABLED=true
NOTIFICATIONS_MESSAGE_DOWNSTREAM_ENTITIES_DEPTH={downstream_entities_depth_to_fetch}
NOTIFICATIONS_WAL_ADVISORY_LOCK_ID={postgresql_advisory_lock_id}
NOTIFICATIONS_WAL_REPLICATION_SLOT_NAME={postgresql_replication_slot_name}
NOTIFICATIONS_WAL_PUBLICATION_NAME={postgresql_publication_name}
NOTIFICATIONS_RECEIVERS_SLACK_URL={slack_incoming_webhook_url}
NOTIFICATIONS_RECEIVERS_WEBHOOK_URL={webhook_url}
NOTIFICATIONS_RECEIVERS_EMAIL_HOST={host}
NOTIFICATIONS_RECEIVERS_EMAIL_PORT={port}
NOTIFICATIONS_RECEIVERS_EMAIL_PROTOCOL={protocol} # SMTP, SMTPS, IMAP, IMAPS, POP3, POP3S
NOTIFICATIONS_RECEIVERS_EMAIL_SMTP_AUTH=true # Set to true if SMTP server requires authentication
NOTIFICATIONS_RECEIVERS_EMAIL_SMTP_STARTTLS=true # Set to true to enable STARTTLS
NOTIFICATIONS_RECEIVERS_EMAIL_PASSWORD={email_password}
NOTIFICATIONS_RECEIVERS_EMAIL_SENDER={sender_email}
NOTIFICATIONS_RECEIVERS_EMAIL_NOTIFICATION_EMAILS={1@mail.com,2@mail.com}
ODD_PLATFORM_BASE_URL={platform_url}
```
{% endtab %}
{% endtabs %}
### Example: Gmail SMTP
A minimal, working configuration for Gmail's SMTP over STARTTLS. Gmail requires an [**app password**](https://support.google.com/accounts/answer/185833) (generated from your Google account with 2-Step Verification enabled) — your regular account password will not work.
{% tabs %}
{% tab title="YAML" %}
```yaml
notifications:
enabled: true
wal:
advisory-lock-id: 100
replication-slot-name: odd_platform_replication_slot
publication-name: odd_platform_publication_alert
receivers:
email:
host: smtp.gmail.com
port: 587
protocol: SMTP
smtp:
auth: true
starttls: true
sender: odd-alerts@your-domain.com
password: {gmail_app_password}
notification:
emails: ops@your-domain.com,data-team@your-domain.com
odd:
platform-base-url: https://odd.your-domain.com
```
{% endtab %}
{% tab title="Environment variables" %}
```
NOTIFICATIONS_ENABLED=true
NOTIFICATIONS_WAL_ADVISORY_LOCK_ID=100
NOTIFICATIONS_WAL_REPLICATION_SLOT_NAME=odd_platform_replication_slot
NOTIFICATIONS_WAL_PUBLICATION_NAME=odd_platform_publication_alert
NOTIFICATIONS_RECEIVERS_EMAIL_HOST=smtp.gmail.com
NOTIFICATIONS_RECEIVERS_EMAIL_PORT=587
NOTIFICATIONS_RECEIVERS_EMAIL_PROTOCOL=SMTP
NOTIFICATIONS_RECEIVERS_EMAIL_SMTP_AUTH=true
NOTIFICATIONS_RECEIVERS_EMAIL_SMTP_STARTTLS=true
NOTIFICATIONS_RECEIVERS_EMAIL_SENDER=odd-alerts@your-domain.com
NOTIFICATIONS_RECEIVERS_EMAIL_PASSWORD={gmail_app_password}
NOTIFICATIONS_RECEIVERS_EMAIL_NOTIFICATION_EMAILS=ops@your-domain.com,data-team@your-domain.com
ODD_PLATFORM_BASE_URL=https://odd.your-domain.com
```
{% endtab %}
{% endtabs %}
### Known limitations
ODD Platform builds its `JavaMailSender` with only the keys documented above. The JavaMail session inherits defaults for every other SMTP parameter, and several of those defaults are operator-hostile in production deployments. None of the following is currently exposed as an ODD configuration key — where a workaround exists it is noted, but the limitations are real and should drive your choice of SMTP relay.
{% hint style="warning" %}
**SMTP timeouts are unset — an unreachable SMTP server will hang notification delivery.** The JavaMail defaults for `mail.smtp.connectiontimeout`, `mail.smtp.timeout` (read), and `mail.smtp.writetimeout` are **infinite**. If the configured SMTP host is unreachable, slow, or stalls mid-response, the notification thread blocks until the TCP stack eventually tears the connection down — there is no application-level timeout to cut it short. Use an SMTP relay you control (or a trusted managed service) and monitor its availability separately from ODD Platform.
{% endhint %}
{% hint style="warning" %}
**Only STARTTLS is supported — implicit-TLS ports (e.g. Gmail port 465, many corporate relays) will not work.** ODD Platform exposes `notifications.receivers.email.smtp.starttls` but does not expose `mail.smtp.ssl.enable`, which is the JavaMail flag required to open an implicit-TLS connection. If your SMTP server only accepts connections on an implicit-TLS port, you must front it with a STARTTLS-capable relay (port 587 is the common choice). Gmail over port 587 with STARTTLS (the example above) works; Gmail over port 465 does not.
{% endhint %}
{% hint style="warning" %}
**Self-signed or internal-CA SMTP certificates require a JVM-level workaround.** `mail.smtp.ssl.trust` is not exposed as an ODD configuration key. If your SMTP relay presents a certificate signed by a private CA, the connection will fail certificate validation unless you either (a) add the CA to the JVM truststore of the ODD Platform container (`$JAVA_HOME/lib/security/cacerts` or a `-Djavax.net.ssl.trustStore=...` override) before starting the process, or (b) use an SMTP relay with a publicly-trusted certificate. There is no configuration-file path to this.
{% endhint %}
{% hint style="warning" %}
**Non-ASCII subjects and bodies may be mangled.** The MIME message is built without an explicit charset, so JavaMail falls back to the JVM default. Containers that do not set `file.encoding` or `LANG` explicitly can end up with `US-ASCII` defaults, which corrupt non-Latin alert content. If your alert text includes non-ASCII characters, set `JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8` on the ODD Platform container.
{% endhint %}
{% hint style="danger" %}
**Silent partial delivery: if one recipient fails, subsequent recipients are skipped.** `EmailNotificationSender` iterates over the recipient list in `notifications.receivers.email.notification.emails` and calls the SMTP server once per recipient. If recipient N fails (bad address, mailbox full, server-side policy rejection), the exception is wrapped as a `RuntimeException` and the loop terminates — recipients N+1, N+2, … **never receive the alert**. There is no retry and no partial-failure metric. Keep the recipient list short, use distribution lists on the SMTP side for fan-out, and validate addresses before adding them to the list.
{% endhint %}
### Cleaning up
{% hint style="danger" %}
ODD Platform **doesn't clean up** replication slot it has created. If you need to disable Alert Notification functionality, please perform the following steps along with disabling a feature on a ODD Platform side
{% endhint %}
In order to remove replication slot and publication, these SQL queries must be run against the database:
* ```sql
SELECT pg_drop_replication_slot('<>');
```
where `<>` is a name of replication slot defined in the ODD Platform. Default is `odd_platform_replication_slot`
* ```sql
DROP PUBLICATION IF EXISTS <>;
```
where `<>` is a name of publication defined in the ODD Platform. Default is `odd_platform_publication_alert`
## Prometheus AlertManager Integration
In addition to raising alerts internally (failed jobs, data-quality tests, schema changes, distribution anomalies — see the [Alerting](/features/active-platform-features/alerting.md) feature), ODD Platform exposes an **inbound webhook** that accepts Prometheus [AlertManager](https://prometheus.io/docs/alerting/latest/alertmanager/) notifications. Each inbound alert becomes a **Distribution Anomaly** alert on the referenced data entity, visible in the Alerts section and on the entity's page.
### Endpoint
```
POST /ingestion/alert/alertmanager
```
Response: `204 No Content` on success. The endpoint consumes the AlertManager webhook body and always returns empty.
### Payload shape
The platform accepts a subset of the [AlertManager webhook schema](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config) — specifically `alerts[].labels`, `alerts[].generatorURL`, and `alerts[].startsAt`. Other top-level AlertManager fields (`version`, `status`, `receiver`, `groupLabels`, `commonLabels`, …) are accepted and ignored.
```json
{
"alerts": [
{
"labels": {
"entity_oddrn": "//postgresql/host/pg-host/databases/shop/schemas/public/tables/orders",
"alertname": "OrdersRowCountDropped"
},
"generatorURL": "https://prometheus.example.com/graph?g0.expr=...",
"startsAt": "2026-04-24T12:34:56"
}
]
}
```
{% hint style="warning" %}
**The `entity_oddrn` label is required for the alert to route to a data entity.** ODD Platform reads `alerts[].labels["entity_oddrn"]` to determine which data entity the alert belongs to. An alert submitted without this label is stored with an empty owner, will not appear on any entity's page, and is effectively orphaned. Configure your AlertManager route or your alerting rules to include the target entity's ODDRN as a label.
{% endhint %}
### Example AlertManager receiver configuration
A minimal `alertmanager.yml` receiver forwarding every alert to ODD Platform:
```yaml
route:
group_by: ['job']
group_wait: 1s
group_interval: 5m
repeat_interval: 12h
receiver: odd-platform
receivers:
- name: odd-platform
webhook_configs:
- url: 'http://odd-platform:8080/ingestion/alert/alertmanager'
```
The reference example shipped with the platform is at [`docker/examples/config/alertmanager.yaml`](https://github.com/opendatadiscovery/odd-platform/blob/main/docker/examples/config/alertmanager.yaml) in the odd-platform repo. To make an alert route to a specific entity, attach `entity_oddrn` as a label in your Prometheus alerting rules — for example:
```yaml
groups:
- name: orders
rules:
- alert: OrdersRowCountDropped
expr: row_count{table="orders"} < 1000
labels:
entity_oddrn: "//postgresql/host/pg-host/databases/shop/schemas/public/tables/orders"
annotations:
summary: "Orders table row count dropped below 1000"
```
### Authentication
{% hint style="danger" %}
**The AlertManager webhook endpoint is not authenticated.** ODD Platform whitelists the entire `/ingestion/**` namespace in Spring Security, and the ingestion auth filter controlled by `auth.ingestion.filter.enabled` only guards `/ingestion/entities` (POST) — it does **not** cover `/ingestion/alert/alertmanager`. Anyone with network reach to the platform can POST arbitrary AlertManager-shaped payloads and create alerts on any data entity whose ODDRN they can guess. Toggling `auth.ingestion.filter.enabled` has no effect on this endpoint.
{% endhint %}
Because no application-level authentication is enforced on this endpoint today, protect it at the perimeter. Any of these approaches works:
* **Network segmentation** — expose ODD Platform only on a private network or VPN; in Kubernetes, keep AlertManager and the platform in the same cluster and use a NetworkPolicy so only the AlertManager pod can reach `/ingestion/alert/alertmanager`.
* **Reverse proxy with its own authentication** — put an authenticating proxy in front of ODD Platform (for example, nginx with `auth_request` delegating to an SSO sidecar, or Envoy with `ext_authz`) and require AlertManager to present a proxy-validated credential on every webhook call.
* **mTLS termination** — require client certificates on `/ingestion/alert/alertmanager` at the ingress or load balancer layer, and issue a certificate only to the AlertManager pod.
A platform-side fix to extend the ingestion auth filter to cover this endpoint is tracked upstream. Until it ships, apply one of the perimeter controls above for any deployment where the platform's network is not fully trusted.
For the broader ingestion-auth model — what `auth.ingestion.filter.enabled` does cover, the [per-endpoint deployment matrix](/configuration-and-deployment/enable-security.md#deployment-matrix-per-endpoint-per-auth-config) showing reachability under each `auth.type` value, and the write-shape caveats on the [statistics endpoint](/configuration-and-deployment/enable-security.md#statistics-endpoint-write-shape-and-replay-behaviour) — see [Enable security](/configuration-and-deployment/enable-security.md) and [Server-to-server (S2S) API keys](/configuration-and-deployment/enable-security/authentication/s2s.md).
## Enable Data Collaboration
Data collaboration feature allows users to initiate discussion about specific data entity in messengers directly from the ODD Platform. Thread replies are tracked by ODD Platform and saved in it, allowing users to retrieve conversation's context and decisions from one place.
For the user-facing description of the feature — the per-entity **Discussions** tab, how a discussion flows from the platform out to Slack and back, the message-lifecycle model — see [Active platform features → Data Collaboration](/features/active-platform-features/data-collaboration.md).
At the moment ODD Platform supports only Slack as a target messenger. It uses Slack APIs to send messages and [Slack Events API](https://docs.slack.dev/apis/events-api/) to receive message's thread replies.
{% hint style="info" %}
**Slack here is the full Slack app for in-app discussions, not the alert webhook.** The Data Collaboration integration uses an OAuth-token-driven Slack app (`datacollaboration.slack-oauth-token`) and the [Slack Events API](https://docs.slack.dev/apis/events-api/) webhook to read replies back into the platform — bidirectional. It is **distinct** from the [outgoing alert webhook](#enable-alert-notifications) used by alert notifications (`notifications.receivers.slack.url`, one-way write only). Each integration is configured separately: enabling this one does not route alerts, and enabling the alert webhook does not surface the **Discussions** tab on data-entity pages. See [Main Concepts → Terms & Aliases](/introduction/main-concepts.md#terms-and-aliases) for the side-by-side comparison.
{% endhint %}
### Creating Slack application
Go to the [Slack apps](https://api.slack.com/apps) website and click on `Create New App -> From an app manifest`
Creating an app
Select a workspace you want to add an application to and click `Next`
Selecting a workspace to install application to
Enter the following manifest into the YAML section, replace the `` with URL of your ODD Platform deployment and click `Next`.
The four bot scopes below match exactly what the platform exercises today (`channels:history` and `channels:read` for reading messages and metadata, `chat:write` for posting via the OAuth bot token, `users:read` for resolving user display names). Previous versions of this manifest also requested `incoming-webhook` — that scope was copy-paste leftover from a Slack example and was never used by the platform; if you are reinstalling or auditing scopes, you can safely omit it.
```yaml
display_information:
name: ODD Data Collaboration
features:
bot_user:
display_name: ODD Data Collaboration
always_online: false
oauth_config:
scopes:
bot:
- channels:history
- channels:read
- chat:write
- users:read
settings:
event_subscriptions:
request_url: https:///api/slack/events
bot_events:
- message.channels
org_deploy_enabled: false
socket_mode_enabled: false
token_rotation_enabled: false
```
Inserting a YAML manifest
Review your application's scopes and permissions and click `Create`
Reviewing scopes and permissions
Proceed with Slack instructions on how to install application into workspace and you should be good to go.
### ODD Platform configuration
Following variables need to be defined:
* `datacollaboration.enabled`: must be set to `true`. Defaults to `false`. **Feature toggling**: this value is captured at JVM boot and frozen for the lifetime of the process — runtime configuration changes (for example via Spring Boot Actuator's `/actuator/refresh`) are not reflected by the feature resolver or by the platform's feature-active endpoint. Restart the JVM process for a change to take effect. Top-level UI navigation tabs (Data Modelling and adjacent surfaces) remain visible regardless of this setting; the per-page affordances inside those tabs do honour the flag. See [Features → Data Collaboration](/features/features.md#data-collaboration) for the chrome-invariance caveat.
* `datacollaboration.receive-event-advisory-lock-id`: PostgreSQL advisory lock id for a job, which translates events from messengers to messages. Defaults to `110`
* `datacollaboration.sender-message-advisory-lock-id`: PostgreSQL advisory lock id for a job, which sends messages created in the platform to messengers. Defaults to `120`
* `datacollaboration.message-partition-period`: time interval in days for a message table partition in PostgreSQL. Defaults to `30`
* `datacollaboration.sending-messages-retry-count`: how many times the Platform will attempt to send a message to provider. Cannot be less than zero. Defaults to `3`
* `datacollaboration.slack-oauth-token`: Slack application OAuth token used for communicating with Slack. Can be retrieved in the `OAuth & Permissions` section of a Slack application.\\