Getting Started #

XPro serves three primary personas. Use this guide based on your role.

For Admins #

1. Install XPro #

Follow the Installation Guide to install via RPM, DEB, or tarball.

2. Configure Infrastructure #

Edit the environment file with your database credentials:

sudo vi /etc/xpro/xpro.env

# Database
XPRO_DB_HOST=your-db-host
XPRO_DB_PORT=5432
XPRO_DB_NAME=xpro
XPRO_DB_USER=xpro_user
XPRO_DB_PASS=your-password

# NATS
XPRO_NATS_URL=tls://nats.example.com:4222
XPRO_NATS_CREDS=/opt/xpro/etc/nats.creds

3. Verify Database Connectivity #

xpro dbcheck

4. Manage Services #

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

# Enable on boot
sudo systemctl enable xpro-file-watcher
sudo systemctl enable xpro-processor

# Check status
sudo systemctl status xpro-processor

5. Licensing #

XPro starts with a 15-day free trial automatically on first run. After the trial period, a license file is required.

# Check license/trial status
xpro version

The license file is located at /opt/xpro/etc/license.key. For Enterprise licensing, contact info@bluefunda.com.

See Enterprise vs Trial for details.

For Engineers #

1. Understand the Processing Pipeline #

XPro processes XML files through three coordinated components:

XML Files → File Watcher → NATS → Processor → Database

1. File Watcher monitors a source directory for incoming XML files
2. When a threshold is met (file count or time), it batches files and publishes a message to NATS
3. Processor receives the message, parses each XML file, and inserts records into the database

2. Configure the File Watcher #

Edit /etc/xpro/watcher-config.yml:

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

# Trigger batch when 1000 files arrive or after 5 minutes
fileThreshold: 1000
maxWaitTime: 300

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

Time-Based Schedules #

You can define different thresholds for peak and off-peak hours:

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

How Batching Works #

1. Files arrive in sourceDir
2. File watcher counts files and checks thresholds
3. When triggered (by file count or timeout), it creates a timestamped subdirectory in targetDir (e.g., 2025-10-19_10-30-00)
4. Files are copied to the batch directory with retry logic
5. A NATS message is published with the batch metadata
6. Original files are moved to archiveDir for deduplication

3. Configure the Processor #

Edit /etc/xpro/config.yml:

processingMode: 'xml-billdata'

database:
  type: postgresql
  host: 'your-db-host'
  port: 5432
  database: 'xpro'
  schema: 'public'
  username: 'xpro_user'
  password: 'your-password'
  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'

Processing Modes #

Fault Tolerance #

The processor supports per-record savepoints. If one record in a batch fails, only that record is skipped — the rest of the batch succeeds. Failed records are tracked and can be retried via the retry processor.

4. Generate Default Configuration #

If starting fresh, generate config templates:

xpro config init                       # Processor config
xpro config init --watcher             # Watcher config
xpro config init --output /tmp/my.yml  # Custom output path

5. Test with Generated XML #

Use xmlgen to create test files for validation:

xpro xmlgen --count 100 --output /data/xpro/incoming/

6. Run in Oneshot Mode #

For testing, process a directory of XML files without the daemon:

xpro processor --mode oneshot --input /data/xpro/test-batch/

For Auditors #

1. Check Processing Status #

XPro publishes status events to NATS subjects:

2. Review Logs #

Application logs are written to /var/log/xpro/:

# View processor logs
journalctl -u xpro-processor -f

# View file watcher logs
journalctl -u xpro-file-watcher -f

# Or directly
tail -f /var/log/xpro/processor.log

3. Metrics #

XPro exports processing metrics to /opt/xpro/var/data/metrics/:

• Processing time per file
• Success/failure counts per batch
• Throughput rates
• Database insert latency

These metrics can be integrated with Grafana, Datadog, or CloudWatch for dashboarding and alerting.

4. Audit Trail #

The audit log at /opt/xpro/var/data/audit/ records:

• File arrival timestamps
• Batch trigger events (threshold vs timeout)
• Processing outcomes per file
• Database insert confirmations
• Error details with file references

5. Database Verification #

Query the processing state directly:

-- Check recent processing status
SELECT file_name, status, error_code, processed_at
FROM file_state
ORDER BY processed_at DESC
LIMIT 100;

-- Count by status
SELECT status, COUNT(*)
FROM file_state
WHERE processed_at > NOW() - INTERVAL '24 hours'
GROUP BY status;

Next Steps #

• CLI Reference — Full command documentation
• Examples — Sample configurations and workflows
• Troubleshooting — Common issues and fixes