For the complete documentation index, see llms.txt. This page is also available as Markdown.

Insert Example

Overview

This document demonstrates the complete Insert flow using the AddToShipping feature from the EBusiness application. The flow starts with a POST request to the controller and ends with event publishing and subscriber processing.

Complete Flow Architecture

POST Request → Controller → Service → PreBus Plugins → Command Handler → RESTClient → External System

Response ← Controller ← Service ← Command Handler ← RESTClient ← External System

Detailed Flow Breakdown

1. POST Request

2. Controller (API Entry Point)

3. Service Layer (Business Orchestration)

4. PreBus Processing (Validation Pipeline)
   ├── AddToShippingSequence (Plugin Registration)
   ├── AddToShippingDataPacket (Validation Context)
   └── ValidateShipping Plugin (Business Rules)

5. Command Handler (RESTClient Integration)
   ├── Internal DTO → Request DTO Mapping
   ├── RESTClient Call to External System
   └── Response DTO Processing

6. Event Publishing (Asynchronous Processing)

7. Subscribers (Side Effects)

Step-by-Step Implementation

1. API Controller - The Entry Point

File: ShippingController_AddToShipping.cs

What Happens:

  • HTTP Method: POST /api/Shipping/AddToShipping

  • Input: AddToShippingDto from request body

  • Action: Calls the service layer to process the shipping

  • Response: HTTP 201 Created with shipping ID

2. Service Layer - Business Orchestration

File: ProcessShippingService_AddToShipping.cs

What Happens:

  • PreBus Processing: Executes business rule sequences (plugins)

  • Validation: Processes business rule sequences

  • ID Generation: Generates unique shipping ID

  • Command Creation: Creates AddToShippingCommand with DTO

  • Command Processing: Calls the command handler

  • Result: Returns success with generated shipping ID

2.1. PreBus Business Rule Sequence - Validation Pipeline

File: AddToShippingSequence.cs

What Happens:

  • Plugin Registration: Registers validation plugins in execution order

  • Sequential Processing: Executes plugins one by one

  • Error Collection: Collects validation errors from all plugins

  • Early Exit: Stops processing if any plugin fails

2.2. PreBus Data Packet - Validation Context

File: AddToShippingDataPacket.cs

What Happens:

  • Context Container: Holds DTO and application context

  • Error Collection: Collects validation errors from plugins

  • Data Sharing: Allows plugins to share data during validation

  • Logging: Provides logging capabilities for plugins

2.3. PreBus Validation Plugin - Business Rules

File: ValidateShipping.cs

What Happens:

  • Business Rule Validation: Implements specific validation logic

  • Database Access: Can access repository for data validation

  • Error Reporting: Adds errors to the data packet if validation fails

  • Async Support: Supports asynchronous validation operations

  • Dependency Injection: Receives logger and repository factory

2.4. PreBus Plugin Benefits

  • Modular Validation: Each plugin handles one validation concern

  • Reusable Rules: Plugins can be reused across different features

  • Testable: Each plugin can be unit tested independently

  • Configurable: Plugins can be enabled/disabled per feature

  • Extensible: Easy to add new validation rules

  • Ordered Execution: Plugins execute in defined sequence

3. Command Handler - RESTClient Integration

File: AddToShippingHandler.cs

What Happens:

  • DTO Mapping: Converts internal DTO to Request DTO for external system

  • RESTClient Call: Calls external shipping service via RESTClient

  • Response Processing: Handles success/failure responses from external system

  • Logging: Logs success/failure of external service call

  • Event Publishing: Fires events based on external service result

4. NServiceBus Handler - Message Processing

File: AddToShippingNsbHandler.cs

What Happens:

  • Message Reception: Receives AddToShippingCommand from message bus

  • Logging: Logs handler execution

  • Delegation: Calls the actual command handler

  • Context Bridge: Converts NServiceBus context to FlexBase context

6. Event Publishing - Asynchronous Processing

Event: ShippingAddedEvent

What Happens:

  • Event Creation: FlexBase creates event with shipping data

  • Message Bus: Event is published to message bus

  • Subscriber Notification: All subscribers are notified

7. RESTClient Integration - External Communication

File: ShippingRESTClient_AddToShipping.cs

What Happens:

  • HTTP Client: Creates HTTP client for external communication

  • Serialization: Converts Request DTO to JSON

  • HTTP Request: Sends POST to external shipping system

  • Response Handling: Processes HTTP response from external system

7.1. Request DTO - External Contract

File: AddToShippingRequestDto.cs

What Happens:

  • External Contract: Designed for external system consumption

  • Serialization: Optimized for JSON serialization

  • Validation: May include external system specific validation

7.2. Response DTO - External Contract

File: AddToShippingResponseDto.cs

What Happens:

  • External Contract: Designed for external system responses

  • Deserialization: Optimized for JSON deserialization

  • External Fields: May include external system specific fields

7.3. Mapping Configuration - DTO Transformation

File: ShippingRESTClientMapperProfile.cs

What Happens:

  • Request Mapping: Converts internal DTO to external request format

  • Response Mapping: Converts external response to internal DTO format

  • Field Transformation: Handles different field names and types

  • Business Logic: Applies business rules during mapping

8. Event Subscribers - Side Effects

File: NotifyLogisticsOnShippingAdded.cs

What Happens:

  • Event Reception: Receives ShippingAddedEvent from message bus

  • Side Effects: Executes business logic (emails, notifications, etc.)

  • Additional Events: Can fire more events if needed

Data Transfer Objects (DTOs)

Internal DTOs - Application Contracts

Input DTO: AddToShippingDto

Command: AddToShippingCommand

External DTOs - External System Contracts

Request DTO: AddToShippingRequestDto

Response DTO: AddToShippingResponseDto

DTO Mapping Relationships

Flow Summary

Synchronous Flow (Immediate Response)

  1. POST Request → Controller receives request

  2. Service Processing → Business orchestration and PreBus validation

  3. PreBus Plugins → Sequential validation of business rules

  4. Command Handler → RESTClient integration

    • Internal DTO → Request DTO mapping

    • External system API call

    • Response DTO processing

  5. Response → HTTP 201 with shipping ID

Asynchronous Flow (Event Processing)

  1. Event Publishing → ShippingAddedEvent published to message bus

  2. Subscriber Processing → NotifyLogisticsOnShippingAdded executes

  3. Side Effects → Emails, notifications, inventory updates

  4. Additional Events → Can trigger more business processes

External Communication Flow

  1. Internal DTO → Request DTO mapping

  2. RESTClient Call → HTTP request to external system

  3. External Response → Response DTO from external system

  4. Response Mapping → Response DTO to Internal DTO

  5. Data Integration → External data integrated with internal data

Key Benefits

  • Separation of Concerns: Each layer has a single responsibility

  • Testability: Each component can be tested independently

  • Scalability: Asynchronous processing handles high loads

  • Maintainability: Clear, readable code structure

  • Event-Driven: Loose coupling between components


This AddToShipping example demonstrates how FlexBase enables clean, maintainable, and scalable insert operations with proper separation of concerns and event-driven architecture! 🚀

Last updated