Aggregator Integration Service Configuration¶

This page explains the settings used by aggregator-integration-service. See the installation overview, guide for running without Docker, or Docker guide for build and startup instructions.

The service has no business API. Port 9016 is used only for health and management endpoints. Do not make it available through the public gateway.

Runtime and service discovery¶

Property	Value / Default	Env Variable	Description
`server.port`	`0` base; `9016` dev	`SERVER_PORT`	HTTP port used for health and management endpoints. The main configuration lets the system choose a port, while the development profile uses `9016`.
`server.shutdown`	`graceful`	`SERVER_SHUTDOWN`	Controls how the service stops. `graceful` lets Kafka listeners and scheduled jobs finish within the shutdown time limit.
`spring.profiles.active`	`${ACTIVE_PROFILE:dev}`	`ACTIVE_PROFILE` or `SPRING_PROFILES_ACTIVE`	Selects the active Spring profile. The default is `dev`.
`spring.application.name`	`aggregator-integration-service`	`SPRING_APPLICATION_NAME`	Service name used by Spring and Eureka. Keep it stable because discovery and health checks depend on it.
`spring.lifecycle.timeout-per-shutdown-phase`	`30s`	`SPRING_LIFECYCLE_TIMEOUT_PER_SHUTDOWN_PHASE`	Maximum time allowed for each clean shutdown phase. The default matches the 30-second provider response timeout.
`spring.main.allow-bean-definition-overriding`	`true`	`SPRING_MAIN_ALLOW_BEAN_DEFINITION_OVERRIDING`	Controls whether a later Spring bean can replace an earlier bean with the same name. Use `false` when your configuration does not require replacements.
`eureka.client.service-url.defaultZone`	`http://localhost:8761/eureka/`	`EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE`	URL of the Eureka server used to find `client-service` for refunds.
`eureka.instance.prefer-ip-address`	`true`	`EUREKA_INSTANCE_PREFER_IP_ADDRESS`	Controls whether Eureka registers the service by IP address or hostname. `true` uses the IP address; `false` uses the hostname.

Docker Compose uses environment variables to make Eureka registration and updates happen more often. These values come from the deployment and are not defaults in the aggregator YAML files.

Health and management endpoints¶

Property	Value / Default	Env Variable	Description
`management.endpoints.web.exposure.include`	`*`	`MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE`	Selects the actuator endpoints available over HTTP. `*` enables all endpoints. In production, enable only the endpoints you need, such as `health,info,prometheus`.
`management.endpoint.health.probes.enabled`	`true`	`MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED`	Turns liveness and readiness health checks on or off. `true` provides `/actuator/health/liveness` and `/actuator/health/readiness`.

The service does not use Spring Security to protect actuator endpoints. Keep port 9016 private with firewall or network rules, and do not route it through the public gateway. The Compose health check uses port 9016 and also checks that Eureka reports the service as UP.

A successful liveness check only shows that the Java process is running. It does not confirm that Kafka topics are assigned, Infozillion accepts requests, delivery reports are updating, or refunds can reach client-service. Monitor these operations separately.

Kafka and dead-letter topics¶

Property	Value / Default	Env Variable	Description
`aggregator.consumer.group`	`aggregator-integration`	`AGGREGATOR_CONSUMER_GROUP`	Kafka consumer group used for `sms.outbound.<mnoUserId>` topics. All instances in the same deployment should use the same group.
`aggregator.consumer.concurrency`	`1`	`AGGREGATOR_CONSUMER_CONCURRENCY`	Number of Kafka listener threads in each service instance. The number of topic partitions limits how many threads can receive work at the same time.
`aggregator.dlt.group`	`aggregator-integration-dlt`	`AGGREGATOR_DLT_GROUP`	Separate Kafka consumer group used for `sms.outbound.*.dlt` topics. The default is set in code rather than profile YAML.
`spring.kafka.bootstrap-servers`	`localhost:9092`	`KAFKA_BOOTSTRAP_SERVERS`	Comma-separated Kafka broker addresses used for the first connection.
`spring.kafka.consumer.auto-offset-reset`	`earliest`	`SPRING_KAFKA_CONSUMER_AUTO_OFFSET_RESET`	Controls where reading starts when the consumer group has no saved position. `earliest` starts with the oldest available message.
`spring.kafka.consumer.max-poll-records`	`10`	`KAFKA_MAX_POLL_RECORDS`	Maximum number of Kafka messages returned in one poll. Each message can cause one provider request.
`spring.kafka.consumer.properties.max.poll.interval.ms`	`600000`	`KAFKA_MAX_POLL_INTERVAL_MS`	Maximum time allowed to process messages from one poll before Kafka removes the consumer from its group. The default is ten minutes.
`spring.kafka.consumer.properties.metadata.max.age.ms`	`30000`	`KAFKA_METADATA_MAX_AGE_MS`	How often Kafka refreshes topic information. The default lets newly created MNO-user topics appear within about 30 seconds.
Consumer key/value deserializers	`StringDeserializer`	Spring standard overrides	Converts Kafka keys and values to strings. The listener then reads the value as JSON.
Producer key/value serializers	`StringSerializer`	Spring standard overrides	Converts dead-letter message keys and values to strings before sending them to Kafka.

Kafka poll size¶

Each Kafka message can wait up to mnpsp.timeout-seconds for the provider. Keep this calculation safely below the poll interval:

max.poll.records × worst-case per-record processing time < max.poll.interval.ms

With the default settings, 10 × 30 seconds = 300 seconds. This leaves about 300 seconds for database work, request retries, scheduling delays, and Java pauses. If processing takes too long, Kafka may remove the consumer from its group and deliver messages again.

Infozillion/MNPSP¶

Property	Value / Default	Env Variable	Description
`mnpsp.base-url`	`https://api.mnpspbd.com`	`MNPSP_BASE_URL`	Main Infozillion URL without an API path at the end. Compose uses `mnpsp-stub` by default.
`mnpsp.aggregator-api-key`	Empty	`MNPSP_AGGREGATOR_API_KEY`	Infozillion API key included in SMS and delivery-report requests. A real provider normally requires this value.
`mnpsp.mno.url-path`	`/a2p-sms/api/v1`	`MNPSP_MNO_URL_PATH`	URL path added to the main URL for MNO SMS requests.
`mnpsp.iptsp.url-path`	`/a2p-sms-iptsp/api/v1`	`MNPSP_IPTSP_URL_PATH`	URL path added to the main URL for IPTSP SMS requests.
`mnpsp.mno.dlr-path`	`/a2p-proxy-api/api/v1`	`MNPSP_MNO_DLR_PATH`	URL path added to the main URL for MNO delivery reports. The default is set in `MnpspClient`, not `application-dev.yml`.
`mnpsp.iptsp.dlr-path`	`/a2p-proxy-api-iptsp/api/v1`	`MNPSP_IPTSP_DLR_PATH`	URL path added to the main URL for IPTSP delivery reports. The default is set in code.
`mnpsp.timeout-seconds`	`30`	`MNPSP_TIMEOUT_SECONDS`	Maximum time to wait for an SMS or delivery-report response from Infozillion. The worker waits for the request to finish.

The service adds /send-sms or /check-delivery-report to these paths. Do not include those final parts in the settings, or they will appear twice in the URL.

The HTTP client does not have separate settings for connection timeout, proxy, trusted TLS certificates, or connection pooling. Configure these through Java and the network, or update the HTTP client configuration if your environment requires them.

Circuit breakers¶

SMS requests and delivery-report requests use separate circuit breakers so failures in one do not stop the other.

Property suffix under `resilience4j.circuitbreaker.instances`	`mnpspSend`	`mnpspDlr`	Description
`slidingWindowSize`	20	20	Number of recent requests used to calculate the failure rate.
`minimumNumberOfCalls`	5	5	Minimum number of requests required before the circuit breaker checks the failure rate.
`failureRateThreshold`	50	50	Failure percentage that opens the circuit and temporarily stops requests.
`waitDurationInOpenState`	30s	30s	Time to wait before allowing test requests after the circuit opens.
`permittedNumberOfCallsInHalfOpenState`	3	3	Number of test requests allowed while checking whether the provider has recovered.

Delivery-report worker¶

Property	Value / Default	Env Variable	Description
`dlr.poller.enabled`	`true`	`DLR_POLLER_ENABLED`	Controls whether the scheduled delivery-report worker runs. It is enabled when the setting is missing.
`dlr.poller.poll-ms`	`2000`	`DLR_POLLER_POLL_MS`	Delay after one delivery-report check finishes before the next check starts. The code fallback is `5000`, but the development YAML sets `2000`.
`dlr.poller.batch-size`	`1000`	`DLR_POLLER_BATCH_SIZE`	Maximum number of due recipient rows claimed in one run before they are grouped by provider transaction.

Refund worker and internal HTTP¶

Property	Value / Default	Env Variable	Description
`refund.retry.enabled`	`true`	`REFUND_RETRY_ENABLED`	Controls whether the scheduled refund worker runs. It is enabled when the setting is missing.
`refund.retry.poll-ms`	`30000`	`REFUND_RETRY_POLL_MS`	Delay between checks for refunds in the `PENDING` state.
`admin.api.key`	Empty	`ADMIN_API_KEY`	Key sent to `client-service` in the `X-Admin-API-Key` header. It must match the value used by `client-service`.

Database and Flyway¶

Property	Value / Default	Env Variable	Description
`spring.datasource.url`	`jdbc:postgresql://localhost:5432/sms_gateway?currentSchema=sms_aggregator`	`DB_URL`	JDBC URL used to connect to PostgreSQL. One connection accesses the aggregator schema and selected router tables.
`spring.datasource.username`	`appuser`	`DB_USERNAME`	Username used by the application and Flyway to connect to PostgreSQL.
`spring.datasource.password`	`apppass`	`DB_PASSWORD`	Password used to connect to PostgreSQL. Replace the development value outside local development.
`spring.jpa.hibernate.ddl-auto`	`validate`	`SPRING_JPA_HIBERNATE_DDL_AUTO`	Controls how Hibernate handles the database schema. `validate` checks the tables without changing them. Hibernate should not create the production schema.
`spring.jpa.properties.hibernate.default_schema`	`sms_aggregator`	`SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULT_SCHEMA`	Default PostgreSQL schema for aggregator-owned tables. Router table mappings use the `sms_router` schema directly.
`spring.jpa.open-in-view`	`false`	`SPRING_JPA_OPEN_IN_VIEW`	Controls whether a database session stays open outside a transaction. Keep this `false`; required data must be loaded inside a transaction.
`spring.flyway.enabled`	`true`	`SPRING_FLYWAY_ENABLED`	Controls whether Flyway updates the aggregator schema at startup.
`spring.flyway.schemas`, `default-schema`	`sms_aggregator`	Spring standard overrides	Schemas that Flyway manages and uses by default. Flyway manages only aggregator audit and refund tables.
`spring.flyway.baseline-on-migrate`	`true`	`SPRING_FLYWAY_BASELINE_ON_MIGRATE`	Allows Flyway to create a starting version for an existing schema without migration history. Review this carefully before a production migration.
`spring.flyway.baseline-version`	`0`	`SPRING_FLYWAY_BASELINE_VERSION`	Starting migration version used when Flyway creates a baseline.

Database connection pool¶

Property	Value / Default	Env Variable	Description
`spring.datasource.hikari.maximum-pool-size`	10	`SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE`	Maximum number of database connections in the pool.
`spring.datasource.hikari.minimum-idle`	2	`SPRING_DATASOURCE_HIKARI_MINIMUM_IDLE`	Minimum number of unused database connections kept ready.
`spring.datasource.hikari.connection-timeout`	30000 ms	`SPRING_DATASOURCE_HIKARI_CONNECTION_TIMEOUT`	Maximum time to wait for a database connection from the pool.
`spring.datasource.hikari.idle-timeout`	600000 ms	`SPRING_DATASOURCE_HIKARI_IDLE_TIMEOUT`	Time an unused connection can remain in the pool before it is removed.
`spring.datasource.hikari.max-lifetime`	1800000 ms	`SPRING_DATASOURCE_HIKARI_MAX_LIFETIME`	Maximum time a connection can stay in the pool. Keep it shorter than the timeout used by the database or network.
`spring.datasource.hikari.pool-name`	`AggregatorIntegrationHikariCP`	`SPRING_DATASOURCE_HIKARI_POOL_NAME`	Name used to identify this connection pool in logs and metrics.

The pool is shared by Kafka message processing, delivery-report jobs, audit and outbox writes, Flyway, and refund jobs. Delivery-report HTTP requests keep a database transaction open and may hold connections for a long time. Ten connections may be too few under heavy load, but adding connections without checking database capacity can overload PostgreSQL.

Credential encryption¶

Property	Value / Default	Env Variable	Description
`jasypt.encryptor.password`	`dev-only-jasypt-master-key`	`JASYPT_ENCRYPTOR_PASSWORD`	Master password used to decrypt `mno_user_config.aggregator_password`. It must match the router's value and must be kept secret in production.
`jasypt.encryptor.algorithm`	`PBEWITHHMACSHA512ANDAES_256`	`JASYPT_ENCRYPTOR_ALGORITHM`	Algorithm used to decrypt protected credentials. It must match the algorithm used by the router when encrypting them.
`jasypt.encryptor.iv-generator-classname`	`org.jasypt.iv.RandomIvGenerator`	`JASYPT_ENCRYPTOR_IV_GENERATOR_CLASSNAME`	Class that creates the initialization vector used during encryption and decryption.

An incorrect password may not fail at startup. The error usually appears when the service loads a carrier credential. Test credential decryption with a controlled non-production route, and never log the unencrypted secret.