Examples #

Practical configuration samples and workflows for common XPro use cases.

Processor Configuration #

PostgreSQL with NATS #

A standard setup using PostgreSQL and NATS JetStream:

processingMode: 'xml-billdata'

database:
  type: postgresql
  host: 'db.example.com'
  port: 5432
  database: 'xpro'
  schema: 'public'
  username: 'xpro_user'
  password: '${XPRO_DB_PASS}'
  faultTolerance:
    usePerRecordSavepoints: true
  retry:
    enabled: true
    maxRetries: 3
    retryIntervalSeconds: 30
    batchSize: 10

nats:
  enabled: true
  url: 'tls://nats.example.com:4222'
  credentialsFile: '/opt/xpro/etc/nats.creds'
  jetstream:
    enabled: true
    streamName: 'xpro'
    retentionDays: 90

daemon:
  subject: 'filewatcher.events'

metrics:
  exportDir: '/opt/xpro/var/data/metrics'
  filenamePrefix: 'xpro_metrics'

Oracle with Enterprise Features #

Enterprise edition with Oracle Database:

processingMode: 'xml-billdata'

database:
  type: oracle
  host: 'oracle.example.com'
  port: 1521
  database: 'XPRO'
  schema: 'XPRO_OWNER'
  username: 'xpro_user'
  password: '${XPRO_DB_PASS}'
  faultTolerance:
    usePerRecordSavepoints: true
  retry:
    enabled: true
    maxRetries: 5
    retryIntervalSeconds: 60
    batchSize: 25

nats:
  enabled: true
  url: 'tls://nats.example.com:4222'
  credentialsFile: '/opt/xpro/etc/nats.creds'
  jetstream:
    enabled: true
    streamName: 'xpro-enterprise'
    retentionDays: 365

daemon:
  subject: 'filewatcher.events'

File Watcher Configuration #

Basic Watcher #

Watch a single directory with simple thresholds:

mappingId: 'billing'
sourceDir: '/data/xpro/incoming'
targetDir: '/data/xpro/processing'
archiveDir: '/data/xpro/archive'

fileThreshold: 1000
maxWaitTime: 300

nats:
  url: 'tls://nats.example.com:4222'
  credentialsFile: '/opt/xpro/etc/nats.creds'
  subject: 'filewatcher.events'

Watcher with Time-Based Schedules #

Different thresholds for business hours vs overnight batch processing:

mappingId: 'billing'
sourceDir: '/data/xpro/incoming'
targetDir: '/data/xpro/processing'
archiveDir: '/data/xpro/archive'

fileThreshold: 500
maxWaitTime: 300

timeSchedules:
  - name: 'night-batch'
    startTime: '22:00'
    endTime: '06:00'
    fileThreshold: 25000
    maxWaitTime: 1800

  - name: 'day-adhoc'
    startTime: '06:00'
    endTime: '22:00'
    fileThreshold: 100
    maxWaitTime: 120

nats:
  url: 'tls://nats.example.com:4222'
  credentialsFile: '/opt/xpro/etc/nats.creds'
  subject: 'filewatcher.events'

pollInterval: 5
stableWaitTime: 3
workerPoolSize: 4
copyMaxRetries: 3

Workflow: End-to-End Test #

A complete test from XML generation through processing:

# 1. Generate test XML files
xpro xmlgen --count 100 --output /data/xpro/incoming/

# 2. Verify database connection
xpro dbcheck

# 3. Process in oneshot mode (no daemon required)
xpro processor --mode oneshot --input /data/xpro/incoming/

# 4. Check results in database
psql -h db.example.com -U xpro_user -d xpro \
  -c "SELECT COUNT(*) FROM file_state WHERE status = 'success';"

Workflow: Daemon Mode with File Watcher #

Running as persistent services:

# 1. Start the file watcher
sudo systemctl start xpro-file-watcher

# 2. Start the processor daemon
sudo systemctl start xpro-processor

# 3. Drop XML files into the watched directory
cp /data/incoming/*.xml /data/xpro/incoming/

# 4. Monitor processing
journalctl -u xpro-processor -f

Workflow: Generate Config and Customize #

# Generate default configs
xpro config init --output /etc/xpro/config.yml
xpro config init --watcher --output /etc/xpro/watcher-config.yml

# Edit to match your environment
sudo vi /etc/xpro/config.yml
sudo vi /etc/xpro/watcher-config.yml

# Validate database connection
xpro dbcheck

# Start services
sudo systemctl start xpro-file-watcher xpro-processor

Docker Compose Stacks #

XPro provides pre-built Docker Compose configurations:

Stack	Components
`nats-postgres.yml`	NATS + PostgreSQL
`nats-oracle.yml`	NATS + Oracle
`temporal-postgres.yml`	Temporal + PostgreSQL
`temporal-oracle.yml`	Temporal + Oracle

Example:

docker compose -f nats-postgres.yml up -d

Next Steps #

CLI Reference — Full command documentation
Troubleshooting — Common issues and fixes