External System

In Codebricks, a Command Usecase can integrate with external systems. These systems allow the usecase to interact with third-party services, external APIs, or packages, enabling more complex workflows and communication with external resources.

Plan External System

Add External System

Connect External System

Implement External System

External Systems enable the use of outbound adapters within the domain layer, allowing a Command use case to interact with third-party APIs, services, or libraries while preserving the domain layer's independence from infrastructure-specific code. This separation keeps the domain layer focused on business logic, enhancing modularity and maintainability.

An external system in Codebricks has two main components:

• Domain Service: This defines the interface, including input and output parameters, and is modeled using the Codebricks planner.
• Infrastructure Service: This implements the actual interaction with the external system.

The external system is connected through the command handler, and its interface is resolved within the aggregate.

Domain Service

The Domain Service implementation is found at: Mail/src/shared/domain/services/EmailProvider.ts.

1import { EmailDeliveryStatusEnum } from "shared/domain/enums/EmailDeliveryStatusEnum";
2import { EmailDeliveryStatusValueObject } from "shared/domain/valueObjects/EmailDeliveryStatusValueObject";
3
4export interface EmailProviderInput {
5    taskId: string;
6    title: string;
7    description: string;
8    assigneeId: string;
9    assigneeEmail: string;
10}
11
12export interface EmailProviderOutput {
13    emailDeliveryStatus: EmailDeliveryStatusValueObject;
14}
15
16export interface EmailProvider {
17    resolve(input: EmailProviderInput): Promise<EmailProviderOutput|null>;
18}

This file provides three interfaces:

Output Interface Definition: The EmailProviderInput interface defines the structure of the data provided to the external system. The input coming out of the domain and therefore does not need to be validated by value objects.

Input Interface Definition: The EmailProviderOutput interface defines the structure of the data received from the external system. The output will enter the domain and therefore does needs to be validated by value objects.

Service Interface Definition: The EmailProvider interface defines the actual port to the external system using the Input interface as an argument and the Output interface as a return type.

Infrastructure Service

The Infrastructure Service implementation is found at: Mail/src/shared/infrastructure/external/EmailProviderService.ts.

1import { OverwriteProtectionBody } from "@codebricks/typebricks";
2import { EmailProvider, EmailProviderOutput, EmailProviderInput } from "shared/domain/services/EmailProvider";
3
4export class EmailProviderService implements EmailProvider {
5    @OverwriteProtectionBody(false)
6    async resolve(input: EmailProviderInput): Promise<EmailProviderOutput|null> {
7        //TODO: Implement Service
8        return null;
9    }
10}

Domain Service Interface: The EmailProviderService implements EmailProvider to act as an adapter to the port provided by the Domain service.

Service Method: The resolve method can be overwrite-protected and is the place where the calls to a 3rd Party system happen.