Step Executors contract - models

Intro

This section describes the contract models used for communication between the platform and Step Executors.

Step Executors are external or pluggable components responsible for executing specific steps in the fulfillment plan. To integrate seamlessly, each executor must handle a predefined set of input commands and emit corresponding output events.

The contract defines:

Shared object models reused across messages
Input commands that trigger step execution, retries, cancellations, or pauses
Output events used to report execution results, errors, or state changes

All communication is performed asynchronously via messaging, and all contract types are versioned and structured for long-term compatibility.

Common elements reused in contract

A class containing basic information about what step to proceed with.

StepDTO

public record StepDTO(String stepId, String stepName, ExecutionStepAction action,
                      Set<ProductInfoDTO> productInfo, Set<ServiceInfoDTO> serviceInfos) implements Serializable {
}

Input Contract Models To Step Executors

The input api models are the following:

StartStepExecutionCommand

public record StartStepExecutionCommand(OrderIdDTO orderId,
                                        StepDTO stepDTO) implements Serializable {
}

JSON Example

{
  "orderId": {
      "value": "order-123"
  },
  "stepDTO": {
    "stepId": "",
    "stepName": "Validate Order",
    "action": "ADD",
    "productInfos": [
      {
      "orderItemId" :  "1",
      "name":  "MSISDN",
      "action":  "Add",
      "characteristics": []
      }
    ],
    "serviceInfos": [
      {
      "serviceItemId" :  "11",
      "name":  "MSISDN_CFS",
      "action":  "Add",
      "type": "CFS"
      }
    ]
  }
}

RerunStepExecutionCommand

public record RerunStepExecutionCommand(OrderIdDTO orderId,
                                        StepDTO stepDTO) implements Serializable {
}

HaltStepExecutionCommand

public record HaltStepExecutionCommand(OrderIdDTO orderId,
                                       StepDTO stepDTO) implements Serializable {
}

InterruptStepExecutionCommand

public record InterruptStepExecutionCommand(OrderIdDTO orderId,
                                            StepDTO stepDTO) implements Serializable {
}

PauseStepExecutionCommand

public record PauseStepExecutionCommand(OrderIdDTO orderId,
                                        StepDTO stepDTO) implements Serializable {
}

ResumeStepExecutionCommand

public record ResumeStepExecutionCommand(OrderIdDTO orderId,
                                         StepDTO stepDTO) implements Serializable {
}

RerunStepExecutionCommand

public record RerunStepExecutionCommand(OrderIdDTO orderId,
                                        StepDTO stepDTO) implements Serializable {
}

Output Contract Models From Step Executors

The output api models are the following:

StepExecutionSucceededEvent

public class StepExecutionSucceededEvent extends IntegrationEvent implements Serializable {
 
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-222"
    },
    "externalId": "ext-222",
    "channelName": "mobile",
    "creationDate": "2024-11-15T17:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-33445"
  },
  "stepId": {
    "value": "order-222"
  },
  "stepName": "CreateProduct"
}

StepExecutionFailedEvent

public class StepExecutionFailedEvent extends IntegrationEvent implements Serializable {
 
    private static final long serialVersionUID = 1L;
 
    public final ErrorContextDTO errorContextDTO;
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-666"
    },
    "externalId": "ext-666",
    "channelName": "mobile",
    "creationDate": "2024-11-15T21:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-11234"
  },
  "routingKey": "execution.plan.step.error",
  "errorContext": {
    "errorCode": "E001",
    "errorMessage": "Execution step failed due to timeout."
  },
  "stepId": {
    "value": "step-id-011"
  },
  "stepName": "CreateProduct"
}

StepExecutionPausedEvent

public class StepExecutionPausedEvent extends IntegrationEvent implements Serializable {
 
    private static final long serialVersionUID = 1L;
 
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-777"
    },
    "externalId": "ext-777",
    "channelName": "desktop",
    "creationDate": "2024-11-15T22:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-33456"
  },
  "stepId": {
    "value": "step-id-011"
  },
  "stepName": "CreateProduct"
}

StepExecutionResumedEvent

public class StepExecutionResumedEvent extends IntegrationEvent implements Serializable {
 
    private static final long serialVersionUID = 1L;
 
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-777"
    },
    "externalId": "ext-777",
    "channelName": "desktop",
    "creationDate": "2024-11-15T22:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-33456"
  },
  "stepId": {
    "value": "step-id-011"
  },
  "stepName": "CreateProduct"
}

StepExecutionStartedEvent

public class StepExecutionStartedEvent extends IntegrationEvent implements Serializable {
 
    private static final long serialVersionUID = 1L;
 
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-777"
    },
    "externalId": "ext-777",
    "channelName": "desktop",
    "creationDate": "2024-11-15T22:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-33456"
  },
  "stepId": {
    "value": "step-id-011"
  },
  "stepName": "CreateProduct"
}

StepExecutionInterruptedEvent

public class StepExecutionInterruptedEvent extends IntegrationEvent implements Serializable {
 
    private static final long serialVersionUID = 1L;
 
    public final StepIdDTO stepId;
    public final String stepName;
}

JSON Example

{
  "eventContext": {
    "id": {
      "value": "order-777"
    },
    "externalId": "ext-777",
    "channelName": "desktop",
    "creationDate": "2024-11-15T22:00:00Z",
    "sourceService": "ExecutionService",
    "eventId": "e-33456"
  },
  "stepId": {
    "value": "step-id-011"
  },
  "stepName": "CreateProduct"
}

Plan Builder's model and SpEL context Testing Methodology