Step Definitions

Step Definitions are fundamental components within process definitions. They define the behavior, configuration, and relationships of each step in a process.

Overview

The StepDefinition class encapsulates the definition of a step within a process. It includes metadata about the step, its configuration, inputs, outputs, and its relationship with other steps. Understanding the structure and components of StepDefinition is essential for defining and managing process steps.

Fields

Field	Type	Description
namespace	String	Same value as the process definition namespace.
name	String	The name of the step, used for identification and referring to workers.
type	StepType	The type of the step, determining its behavior and execution logic.
ref	String	Reference identifier for the step, allowing linkage to other steps for passing outputs as inputs.
optional	boolean	Indicates if the step is optional, meaning the process can continue even if this step fails.
createdBy	String	Username or identifier of the user who defined the step.
updatedBy	String	Username or identifier of the user who last updated the step.
created	long	Epoch timestamp marking when the step was created.
updated	long	Epoch timestamp marking when the step was last updated.
configuration	StepConfiguration	Configuration settings specific to the step, defining its operational parameters.
children	List<StepDefinition>	List of child steps, allowing for nested or hierarchical step structures within the process.
input	Map<String, Object>	Input data provided to the step, used during its execution.
output	Map<String, Object>	Output data produced by the step after execution, which can be used by subsequent steps.

StepType

The StepType enum defines the various types of steps that can exist within a process. Each type determines the execution behavior and the nature of the step.

Step Type	Description
HTTP	Executes HTTP or REST API requests, useful for interacting with external APIs or services.
WAIT	Introduces a delay or pause in the process execution. You can wait for seconds, months, or years!
WORKER	Delegates execution to a worker service or background job.
FAIL	Intentionally fails the step, useful for testing error handling and process termination.
PYTHON	Executes Python scripts or commands within the step.
JAVASCRIPT	Executes JavaScript code or scripts within the step.
JQ	Utilizes jq for processing and transforming JSON data within the step.
NOOP	Performs no operation, effectively acting as a placeholder within the process.
DEPENDSON	Specifies dependencies on other steps, ensuring certain steps are completed first.
INTEGRATION	Integrates with external systems or services, facilitating seamless interoperability.
EXIT	Terminates the process execution, often used for cleanup or finalization tasks.
LIST	Container type that executes a list of steps sequentially.
PARALLEL	Container type that executes multiple steps in parallel.
FOREACH	Container type that iterates over a collection, executing steps for each item.
SWITCH	Container type that branches execution based on specified conditions or criteria.

Step Configuration

Field	Type	Description
errorPolicyName	String	Defines the policy to handle errors that occur during the step's execution. Check Error Policy for details
useCache	boolean	Indicates whether the step should utilize caching mechanisms to store or retrieve data.
cacheKey	String	Key used to identify and retrieve cached data specific to the step.
cacheTimeoutSeconds	long	Specifies the duration (in seconds) for which cached data remains valid.
skipStep	boolean	Determines if the step should be skipped during execution, regardless of other conditions.
skipReason	String	Provides a reason for why the step is being skipped, aiding in debugging and auditing.
jqTransformer	String	Defines a jq transformation script for processing JSON data within the step.

Usage Examples

Example: Defining an HTTP Step

A step that performs an HTTP GET request to fetch data from an external API.

{
  "namespace": "default",
  "name": "getCustomerDetail",
  "type": "HTTP",
  "ref": "customerDetails",
  "optional": false,
  "configuration": {
    "errorPolicyName": "retry_3_times_and_fail",
    "useCache": true,
    "cacheKey": "{{ context.input.customerEmail }} ",
    "cacheTimeoutSeconds": 36000
  },
  "children": [],
  "input": {
    "method": "GET",
    "url": "http://localhost:8080/api/test/get",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json",
      "Authorization": "Bearer test"
    },
    "params": {
      "customerEmail": "{{ context.input.customerEmail }} "
    }
  }
}

Best Practices

• Consistent Naming: Use clear and descriptive names for steps to enhance readability and maintainability.
• Modular Design: Break down complex processes into smaller, reusable steps to simplify debugging and testing.
• Error Handling: Define appropriate errorPolicyName in StepConfiguration to manage failures gracefully.
• Caching Strategy: Leverage caching by setting useCache and defining cacheKey to optimize performance for repetitive tasks.