pn-paper-channel uses Spring Boot property files. The base defaults live in src/main/resources/application.properties. Environment-specific overrides are applied via environment variables (in production, injected by CloudFormation) or by placing an application.properties file in the config/ directory (for local development).
In production, all properties are set through CloudFormation ContainerEnvEntry* parameters. The environment variable name is derived from the property key by uppercasing and replacing dots and hyphens with underscores (e.g., pn.paper-channel.refinement-duration → PN_PAPERCHANNEL_REFINEMENTDURATION).
Core timing
| Property | Default | Description |
|---|
pn.paper-channel.refinement-duration | 10d | Duration of the perfezionamento (refinement) period. Accepts duration strings such as 10d, 5h, 30m, 60s. |
pn.paper-channel.compiuta-giacenza-ar-duration | 30d | Duration of the compiuta giacenza for AR products. Same format as refinement-duration. |
pn.paper-channel.enable-truncated-date-for-refinement-check | true | When true, truncates the datetime to a local date before comparing it against the refinement deadline. |
pn.paper-channel.cloudwatch-metric-cron | */30 * * * * * | Cron expression controlling how often CloudWatch metrics are pushed. |
Feature flags
| Property | Default | Description |
|---|
pn.paper-channel.pnaddr001continue-flow | true | For PNADDR001 address errors: true continues the flow; false persists the error to the database. |
pn.paper-channel.pnaddr002continue-flow | false | For PNADDR002 address errors: true continues the flow; false persists the error to the database. |
pn.paper-channel.prepare-two-phases | true | Enables the two-phase PREPARE flow (phase 1 normalize address, phase 2 execute). |
pn.paper-channel.enable-retry-con996 | true | Enables automatic retry of CON996 messages. |
pn.paper-channel.sendCon020 | true | When true, sends CON020 progress events to Delivery Push. |
pn.paper-channel.enabledocfilterruleengine | true | Enables the rule-engine-based document filter algorithm for selecting which attachments to send. |
pn.paper-channel.enable-simplified-tender-flow | false | Enables the new simplified tender workflow. Set to true in production (microservice-dev-cfg.json sets it to true). |
pn.paper-channel.paper-tracker-enabled | false | Enables the Paper Tracker feature. |
AWS configuration
DynamoDB tables
| Property | Local default | Description |
|---|
aws.dynamodb-request-delivery-table | RequestDeliveryDynamoTable | Table that stores paper delivery requests. |
aws.dynamodb-address-table | AddressDynamoTable | Table that stores request addresses (KMS-encrypted). |
aws.dynamodb-tender-table | TenderDynamoTable | Legacy tender table. |
aws.dynamodb-paper-channel-tender-table | pn-PaperChannelTender | New simplified-flow tender table. |
aws.dynamodb-paper-channel-geo-key-table | pn-PaperChannelGeokey | Geokey versions per tender and product. |
aws.dynamodb-paper-channel-cost-table | pn-PaperChannelCost | Costs per tender, product, lot, and zone. |
aws.dynamodb-delivery-driver-table | DeliveryDriverDynamoTable | Legacy delivery driver records. |
aws.dynamodb-cost-table | CostDynamoTable | Legacy cost records. |
aws.dynamodb-zone-table | ZoneDynamoTable | Country-to-zone mapping. |
aws.dynamodb-cap-table | CapDynamoTable | Italian CAP (postal code) to lot mapping. |
aws.dynamodb-delivery-file-table | DeliveryFileDynamoTable | Tracks tender file uploads. |
aws.dynamodb-paper-request-error-table | PaperRequestErrorDynamoTable | Records request processing errors. |
aws.dynamodb-paper-events-table | PaperEventsDynamoTable | Paper delivery events with TTL. |
aws.dynamodb-client-table | ClientDynamoTable | Client ID and prefix-value mappings. |
aws.dynamodb-attachments-config-table | AttachmentsConfig | Time-based configuration for attachment rules. |
aws.dynamodb-paper-event-error-table | PaperEventErrorDynamoTable | Out-of-order event errors with TTL. |
aws.dynamodb-paper-channel-delivery-driver-table | pn-PaperChannelDeliveryDriver | New simplified-flow delivery driver table. |
SQS queues
| Property | Local default | Description |
|---|
pn.paper-channel.queue-internal | local-paper_channel_requests | Internal scheduled-requests queue. |
pn.paper-channel.queue-delivery-push | local-delivery-push-inputs | Output queue sending events to Delivery Push. |
pn.paper-channel.queue-external-channel | local-ext-channels-outputs | Input queue receiving events from External Channel. |
pn.paper-channel.queue-national-registries | local-ext-channels-inputs | Input queue receiving responses from National Registries. |
pn.paper-channel.queue-f24 | pn-f24_to_paperchannel | Input queue receiving F24 responses. |
pn.paper-channel.queue-radd-alt | local-radd-alt-to-paper-channel | Input queue from RADD Alt. |
pn.paper-channel.queue-normalize-address | local-paper-normalize-address | Internal queue for PREPARE phase 1 (address normalization). |
pn.paper-channel.queue-paperchannel-to-delayer | local-paperchannel_to_delayer | Output queue sending events to pn-delayer. |
pn.paper-channel.queue-delayer-to-paperchannel | local-delayer_to_paperchannel | Input queue receiving events back from pn-delayer. |
pn.paper-channel.queue-url-ocr-inputs | local-ocr-inputs | Output queue for OCR requests. |
pn.paper-channel.queue-region-ocr-inputs | us-east-1 | AWS region of the OCR input queue. |
KMS
| Property | Local default | Description |
|---|
aws.kms.keyId | (set from LocalStack logs) | ARN of the KMS symmetric key used to encrypt address data in DynamoDB. |
EventBridge
| Property | Local default | Description |
|---|
pn.paper-channel.eventbus.name | paper-channel-event-bus-name | Name (or ARN) of the EventBridge event bus. In production this is arn:aws:events:<region>:<account>:event-bus/<project>-CoreEventBus. |
pn.paper-channel.eventbus.detail.type | PaperChannelOutcomeEvent | The detail-type field set on outgoing EventBridge events. |
pn.paper-channel.eventbus.source | pn-paper-channel | The source field set on outgoing EventBridge events. |
Client base paths and identifiers
| Property | Local default | Description |
|---|
pn.paper-channel.client-safe-storage-basepath | http://localhost:8120 | Base URL of the Safe Storage service. |
pn.paper-channel.client-national-registries-basepath | http://localhost:1080 | Base URL of the National Registries service. |
pn.paper-channel.client-external-channel-basepath | http://localhost:1080 | Base URL of the External Channel service. |
pn.paper-channel.client-datavault-basepath | http://localhost:1080 | Base URL of the Data Vault service. |
pn.paper-channel.client-address-manager-basepath | http://localhost:1080 | Base URL of the Address Manager service. |
pn.paper-channel.client-f24-basepath | http://localhost:1080 | Base URL of the F24 service. |
pn.paper-channel.safe-storage-cx-id | pn-cons-000 | Client ID sent to Safe Storage. |
pn.paper-channel.x-pagopa-extch-cx-id | pn-cons-000 | Client ID sent to External Channel. |
pn.paper-channel.address-manager-cx-id | pn-paper-channel | Client ID sent to Address Manager. |
pn.paper-channel.address-manager-api-key | _ | API key for Address Manager (set from Secrets Manager in production). |
pn.paper-channel.national-registry-cx-id | pn-paper-channel | Client ID sent to National Registries. |
pn.paper-channel.f24-cx-id | pn-paper-channel | Client ID sent to F24. |
F24 client
| Property | Default | Description |
|---|
pn.paper-channel.f24client.timeout-millis | 30000 | Read timeout in milliseconds for F24 service API calls. Should align with the visibility timeout of the internal queue. |
pn.paper-channel.f24client.retry-max-attempts | 0 | Maximum number of retry attempts for F24 client calls. |
Retry attempt counts
| Property | Default | Description |
|---|
pn.paper-channel.attempt-safe-storage | 3 | Max attempts to fetch a file from Safe Storage. |
pn.paper-channel.attempt-queue-safe-storage | -1 | Max attempts via queue for Safe Storage retries (-1 = unlimited). |
pn.paper-channel.attempt-queue-external-channel | 3 | Max attempts via queue to call External Channel. |
pn.paper-channel.attempt-queue-national-registries | 3 | Max attempts via queue to call National Registries. |
pn.paper-channel.attempt-queue-address-manager | 3 | Max attempts via queue to call Address Manager. |
pn.paper-channel.attempt-queue-f24 | 3 | Max attempts via queue to call F24. |
pn.paper-channel.attempt-queue-zip-handle | 3 | Max attempts for ZIP handling. |
TTL (time-to-live)
| Property | Default | Description |
|---|
pn.paper-channel.ttl-prepare | 14 | TTL in days for PREPARE-phase records. |
pn.paper-channel.ttl-execution-N_890 | 11 | TTL in days for 890 (raccomandata) execution records. |
pn.paper-channel.ttl-execution-N_RS | 11 | TTL in days for RS execution records. |
pn.paper-channel.ttl-execution-N_AR | 12 | TTL in days for AR execution records (national). |
pn.paper-channel.ttl-execution-I_AR | 13 | TTL in days for AR execution records (international). |
pn.paper-channel.ttl-execution-I_RS | 14 | TTL in days for RS execution records (international). |
pn.paper-channel.ttl-execution-days-demat | 365 | TTL in days for dematerialization event records. |
pn.paper-channel.ttl-execution-days-meta | 365 | TTL in days for meta event records. |
Cost rounding
| Property | Default | Description |
|---|
pn.paper-channel.cost-rounding-mode | HALF_UP | Java RoundingMode used for simplified cost calculation. Allowed values: HALF_UP, UP. |
Charge calculation modes
| Property | Default | Description |
|---|
pn.paper-channel.date-charge-calculation-modes | 1970-01-01T00:00:00Z;AAR,2024-01-01T00:00:00Z;COMPLETE | Semicolon-separated pairs of startConfigurationTime;calculationMode. Multiple entries are comma-delimited. Supported modes: AAR, COMPLETE. |
CloudWatch metrics
| Property | Default | Description |
|---|
pn.paper-channel.cloudwatch-metric-cron | */30 * * * * * | Spring cron expression for pushing custom metrics to CloudWatch. |
Allowed redrive status codes
| Property | Default | Description |
|---|
pn.paper-channel.allowed-redrive-progress-status-codes | RECAG005C,RECAG006C,RECAG007C,RECAG008C | Comma-separated status codes for which automatic redrive is allowed after a successful OK sent to Delivery Push. |
Miscellaneous
| Property | Default | Description |
|---|
pn.paper-channel.defaultattachmentconfigcap | ZIP##DEFAULT | Default parent CAP code for new CAP entries inserted into AttachmentsConfig. |
pn.paper-channel.required-demats | 23L | Comma-separated list of mandatory dematerialization codes (currently only applies to PNAG012 events). |
pn.paper-channel.complex-refinement-codes | RECAG007C | Comma-separated 890 status codes that must use the legacy complex refinement flow. |
pn.paper-channel.paper-weight | 5 | Weight (grams) of a single paper sheet. |
pn.paper-channel.letter-weight | 5 | Base weight (grams) of the envelope/letter. |
pn.paper-channel.paper-tracker-product-list | AR | Comma-separated list of product types tracked by the Paper Tracker feature. |
pn.paper-channel.radd-coverage-search-mode | LIGHT | Search mode for RADD coverage lookups. |