From CZZ to ERP

Multi-module Spring Boot projects for processing comerzzia integration messages and sending them to external ERP systems through different messaging technologies.

Purpose

Processing layer for the comerzzia to ERP integration ecosystem:

  • Polls comerzzia database for pending documents

  • Transforms entities to ERP format (JSON/XML)

  • Publishes transformed messages to messaging systems (Kafka, Pub/Sub)

  • Consumes messages with retry logic - optional, configurable

  • Sends data to external ERP systems via HTTP

  • Provides monitoring and comprehensive error handling with retry logic

Processing Flow

Messages are polled from comerzzia database, transformed to ERP format, published to messaging systems, and consumed to be sent to external ERP systems via HTTP.

flowchart LR
	A[(comerzzia DB)] -->|Producer<br/>Cron| B[Entity-Specific<br/>Topics]
	B -.->|Consumer| C[Message Processor]
	C -->|HTTP| D[ERP System]
	C -.->|Failed Messages| E[Entity-Specific<br/>DLQ Topics]

	style A fill:none,stroke:#666,stroke-width:3px
	style B fill:none,stroke:#666,stroke-width:3px
	style C fill:none,stroke:#666,stroke-width:3px
	style D fill:none,stroke:#666,stroke-width:3px
	style E fill:none,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5

Technologies

  • Java 8+

  • Maven 3.6+

  • Spring Boot 2.7.18

  • Spring Integration

  • Micrometer & Prometheus: Metrics and observability

  • Jackson: JSON/XML processing

Applications implementations

Kafka Processor

Asynchronous processing via Apache Kafka topics with retry logic and DLQ.

Pub/Sub Processor

Asynchronous processing via Google Cloud Pub/Sub topics with retry logic and DLQ.

Common library for processing control services

Java JAR library. Shared utilities, models, and business logic. Processor Common Library Module

Supported Entities

All modules process the following comerzzia entities:

Entity Description

tickets

Sales tickets (etickets)

cashjournal

Cash journal closures

OpenAPI REST API Documentation

Observability / health check

  • Spring Boot Actuator

    • Health checks, metrics, and application info endpoints

    • Prometheus metrics export via /actuator/prometheus

  • Monitor-UI embedded

Business Metrics (Prometheus)

Micrometer converts . to _ and appends _total to counters. Names below are the exact Prometheus metric names. For counters, use rate(metric[5m]) or increase(metric[5m]) in PromQL, not the raw value.

Global Counters — type: counter

Prometheus metric Description Incremented by

messages_received_total

Messages confirmed delivered to messaging system

Producer: on ACK

messages_processed_total

Messages processed successfully

Consumer: on success

messages_failed_total

Messages failed on first attempt

Consumer: first attempt error / Producer: transformation error

messages_sent_to_error_topic_total

Messages sent to DLQ after max retries

Consumer: max retries reached

messages_retried_total

Total retries performed (success + failure)

Consumer: on retry result

retry_success_total

Retries that eventually succeeded

Consumer: retry success

retry_failure_total

Retries that failed again

Consumer: retry failure

retry_scheduled_total

Retries republished to main topic

Consumer: before republish

Per-Entity Counters — type: counter

Prometheus metric Labels Description Incremented by

entity_messages_received_total

entity

Messages delivered per entity

Producer: on ACK

entity_messages_processed_total

entity, result (success/failure)

Messages processed per entity and result

Consumer: on success or failure / Producer: transformation error

entity_retries_total

entity

Retries per entity (scheduled + success + failure)

Consumer

entity_messages_sent_to_dlq_total

entity

Messages sent to DLQ per entity

Consumer: on DLQ send

errors_by_type_total

error_type

Errors grouped by exception class name

Consumer: on DLQ send

Processing Time — type: histogram

Prometheus metric Description

entity_processing_time_seconds_count

Number of observations

entity_processing_time_seconds_sum

Total accumulated time (seconds)

entity_processing_time_seconds_max

Max time recorded in current interval

entity_processing_time_seconds\{quantile="0.5"}

p50 (median)

entity_processing_time_seconds\{quantile="0.95"}

p95

Average processing time per entity (PromQL):

rate(entity_processing_time_seconds_sum[5m]) / rate(entity_processing_time_seconds_count[5m])

Common Configuration

Environment Variables

Required for all modules:

uidActividad=<comerzzia_activity_uid>

Database Configuration

All modules require database connection configured via Spring Boot datasource properties in application.yml or profile-specific files (e.g., application-dev.yml).

Error Handling

All modules include comprehensive error handling with:

  • Configurable retry logic

  • Dedicated DLQ topics for failed messages

  • Error tracking in database with full context

  • Timeout protection

  • Graceful shutdown with executor cleanup