How Do I Handle Inputs from an External Source?

Within the DSL, inputs from an external source are modelled as either: external domain responses or instructions. For each of these, the model domain class provides methods to allow for responses to be sent back into the domain.

For example, when using an external domain, we can handle a response by invoking the handle(…) method provided by the external domain’s input port:

 XYZDomain.externalDomain().handle(new ExternalDomainResponseInput());

Noting here that the model name is "XYZ" and the external domain is called "External Domain".

The result of the handle(…) method call is a CompletableFuture<Done>, which completes once the flow has applied the input to the current state. The Done object, which is returned after the future completes, provides a detailed view of what the end result of applying the input was:

@AllArgsConstructor
@Getter
public class Done implements CborSerializable {
    private final String aggregateId;
    private final String aggregateStatus;
    private final String commandName;
    private final Result result;

    public enum Result {
        EXECUTED, DUPLICATE, UNEXPECTED, ERROR
    }
}

Of particular interest here is the Result enum field, which communicates the result of the attempt to send the response back into the domain. The possible values are:

EXECUTED: means the input was successfully applied to the current state, but offers no guarantees about the resulting operations (actions, notifications, domain functions)
DUPLICATE: means the input was deemed a business duplicate of a previously handled input and was therefore not applied to the current state
UNEXPECTED: means the input was deemed inappropriate for the current state of the flow and was therefore not applied to the state
ERROR: means an issue was encountered while executing one of the operations triggered by applying the input (actions, notifications, domain functions)

Generally speaking, unless you have specific requirements - e.g. raising a system event on certain duplicate responses - you can ignore the outcome of applying the input, and consider the operation a success (as long as the future itself doesn’t fail).