Skip to content

Martini Workflows Wait For Event Node

Overview

The Wait For Event Node pauses workflow execution and resumes only when a specific named event is received. Use it to synchronize workflows with external systems, coordinate asynchronous operations, and build responsive event-driven automation without polling or tight coupling between services.

What You Will Learn

  • How to add and configure a Wait For Event node
  • How Wait For Event node execution works at runtime
  • How to test and trigger waiting workflows from Martini Designer and the REST API

When To Use This

Use the Wait For Event node when you need to:

  • Wait for external system notifications before continuing workflow execution, such as payment confirmations or shipping updates
  • Implement approval workflows that pause until a user or downstream service signals a decision
  • Coordinate multi-system integrations by holding a workflow until a dependent service completes its work
  • React to real-time data changes in event-driven architectures without polling

Prerequisites

Adding a Wait For Event Node to Your Workflow

The Wait For Event node is available in the Workflow Designer node palette and can be placed anywhere in your workflow execution path.

  1. Navigate to your Martini package and open your workflow.
  2. Add the Wait For Event node to the Workflow Designer canvas.
  3. Position the node where you want execution to pause.
  4. Connect any preceding nodes to the Wait For Event node using workflow edges.
  5. Connect the Wait For Event node's output edge to the nodes that should run after the event is received.

Expected result: The Wait For Event node appears in your workflow canvas and is ready for configuration.

Configuring the Wait For Event Node

Click the expand icon () on the Wait For Event node to open the Wait For Event Panel, which contains all configuration options.

The panel contains three configurable areas:

Configuring the Event Name

The Event Name determines which event will resume the workflow. You can use either a static name or a dynamically evaluated expression.

Case-sensitive event names

Event names must match exactly, including letter casing. For example, order-confirmed and Order-Confirmed are treated as two different events.

Setting a Static Event Name

Use a static name when the event identifier is fixed and known during development.

  1. In the Wait For Event panel, locate the Event Name field.
  2. Confirm that the Language dropdown next to the field is set to Plain Text.
  3. Enter the exact event name to wait for.

Example static event names:

  • order-payment-confirmed
  • user-approval-received
  • inventory-restock-complete

Expected result: The workflow waits for an event that exactly matches the name you entered.

Setting a Dynamic Event Name

Use a dynamic name when the event identifier depends on workflow data known only at runtime, such as an order ID or a user-specific identifier.

  1. In the Wait For Event panel, locate the Event Name field.
  2. Click the Language dropdown next to the field and select your preferred scripting language.
  3. Enter a script expression — the evaluated result will be converted to a string and used as the event name.

Example dynamic event name expressions (Groovy):

  • Wait for an event specific to an order: "order-confirmed-" + orderId
  • Wait for a user-specific approval event: "approval-" + userId + "-" + requestType

Expected result: At runtime, the expression is evaluated and the resulting string is used as the event name to wait for.

Expression result cannot be null

If the expression evaluates to null at runtime, the workflow throws an exception and execution stops. Ensure the expression always produces a valid event name.

Configuring Max Wait Time and Adding Timeout Logic

The Max Wait Time sets an upper bound on how long the workflow will wait for the event. If the event does not arrive within this window, execution continues along a dedicated timeout path instead of waiting indefinitely.

By default, no Max Wait Time is set, so the workflow waits until the event arrives or Martini is stopped.

Setting the Max Wait Time

  1. In the Wait For Event panel, enter a numeric value in the Max Wait Time input field.
  2. Select a time unit from the dropdown beside the field:
    • Seconds
    • Minutes
    • Hours
    • Days

Expected result: The Timeout edge handle () appears on the Wait For Event node.

Adding Timeout Logic

Connect your timeout handling logic to the Timeout edge handle to define what the workflow does when the wait period expires. Common timeout responses include:

  • Retry logic: Re-enter a loop that waits again or attempts alternative processing
  • Error logging: Log timeout details for diagnostics
  • Cleanup operations: Release reserved resources or notify stakeholders of the timeout

Connect nodes to the Timeout edge using the same process as any other workflow edge.

Configuring Event Data Mapping

The Event Data Mapping panel lets you extract properties from the incoming event payload and assign them to workflow properties so downstream nodes can use them.

The mapping panel has two sides:

  • Left — Event Properties: Properties from the event payload. These must be declared manually, and the property names must exactly match the field names in the event payload (case-sensitive).
  • Right — Current Workflow Properties: Workflow properties available at this node. You can also define new workflow properties here for use in subsequent nodes in the workflow.

Event properties are local to the mapping panel

Properties declared on the left side are only available within the Event Data Mapping panel. To use event data in downstream nodes, map the event properties to workflow properties on the right side.

Declaring Event Properties

Declare one property for each field you expect in the event payload. Property names must match the payload field names exactly.

Example: For an event with the following payload:

1
2
3
4
{
  "firstName": "Zeron",
  "lastName": "Gesicht"
}

Declare two event properties: firstName and lastName.

Mapping Event Properties to Workflow Properties

After declaring event properties, draw mappings from the left side (event properties) to the right side (workflow properties) in the data mapping panel.

graph LR
    subgraph panel["Event Data Mapping"]
        direction LR
        subgraph left["Event Properties"]
            ep1["eventProperty1"]
            ep2["eventProperty2"]
        end
        subgraph right["Current Workflow Properties"]
            wp1["workflowProperty1"]
            wp2["workflowProperty2"]
        end
        ep1 --> wp1
        ep2 --> wp2
    end

See Data Mapping for detailed instructions on creating and managing mappings.

How Wait For Event Node Execution Works

Understanding the runtime behavior of the Wait For Event node helps you design reliable event-driven workflows and diagnose issues when they arise.

Execution flow when a workflow reaches a Wait For Event Node:

  1. Node activation: Workflow execution reaches the Wait For Event node and immediately pauses.
  2. Event name resolution:
    • If the event name is static, the configured plain text value is used directly.
    • If the event name is dynamic, the script expression is evaluated. The string representation of the result becomes the event name to wait for. If the expression returns null, an exception is thrown.
  3. Timeout countdown: If a Max Wait Time is configured, the countdown begins the moment the node activates.
  4. Waiting for the event:
    • In debug mode, the workflow waits synchronously for the event.
    • In normal execution mode, the workflow waits asynchronously.
    • The workflow holds its execution context until the event arrives or the timeout occurs.
    • The wait state is persistent, allowing workflows to continue waiting across Martini Runtime restarts.
  5. On event received (before timeout):
    • The event payload is mapped to workflow properties according to the configured data mapping.
    • Workflow execution resumes from the Wait For Event node along its normal output path, preserving the existing execution context.
  6. On timeout (when Max Wait Time expires before event arrives): Execution proceeds along the Timeout edge path.

Testing Your Wait For Event Node

Once your workflow is waiting for an event, you can quickly verify your Wait For Event node configuration or trigger continuation in production by sending the specified event. This is especially useful for confirming that your event names, data mapping, and timeout logic work as expected before deploying your workflow.

Sending Events from the Workflow Designer

For testing and development, you can send events directly from a running workflow in the Workflow Designer:

  1. Open the workflow that is currently waiting for an event.
  2. Locate the Wait For Event node that is actively waiting.
  3. Right-click the active Wait For Event node.
  4. Select Send Workflow Event from the context menu.
  5. Configure the event in the Send Workflow Event dialog:
    • Event Name: Pre-populated from the Wait For Event node configuration. Modify it only to test mismatch scenarios — it must match exactly for the event to be received.
    • Event Model Data: If data mapping is configured, the dialog displays fields for each declared event property. Enter test values as needed.
  6. Click the Send button to trigger the event.

Expected result: The workflow resumes execution immediately and processes the event data according to the configured mappings.

Sending Events via REST API

For programmatic integration and production systems, use Martini's REST API to send workflow events.

Common request parameters:

  • event: The event name that must exactly match your Wait For Event node configuration (case-sensitive).
  • eventModel: JSON object containing the event payload. Property names must match what you declared in the Wait For Event node's data mapping panel.

Test API Calls Directly in Martini Designer

You can test these API requests without switching to external tools by using Martini Designer's built-in HTTP Client. Learn more: Creating and Sending Requests in HTTP Client

Send Event to a Specific Running Workflow Instance

Use this endpoint when you need to resume one particular running workflow by its instance ID.

To locate running workflow instance IDs for waiting workflows, see Managing Running Workflows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /workflow-api/event/{id}
Content-Type: application/json

{
  "event": "order-payment-confirmed",
  "eventModel": {
    "orderId": "12345",
    "amount": 99.99,
    "paymentMethod": "credit-card"
  }
}

Replace {id} with the specific running workflow instance ID.

Expected result: The identified workflow instance receives the event and resumes execution with the provided data.

Send Event to All Matching Workflow Instances

Use this endpoint when multiple running workflows may be waiting for the same event name.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /workflow-api/event
Content-Type: application/json

{
  "event": "order-payment-confirmed",
  "eventModel": {
    "orderId": "12345",
    "amount": 99.99,
    "paymentMethod": "credit-card"
  }
}

Expected result: Every currently running workflow with a Wait For Event node configured for order-payment-confirmed receives the event and resumes execution with the provided data.

Wait For Event Node Benefits and Use Cases

Event-driven workflow control solves coordination challenges in complex automation scenarios. By pausing execution until a specific signal arrives, the Wait For Event node eliminates the need for polling loops, reduces resource consumption, and keeps workflow logic clean and readable.

Common implementation scenarios include:

  • Order processing pipelines: Pause after placing an order and resume only when payment confirmation arrives from a payment gateway
  • Approval workflows: Hold a request in progress until a manager or automated system sends an approval or rejection event
  • Multi-system orchestration: Coordinate multiple services by waiting for each to signal completion before moving to the next stage
  • Data ingestion workflows: Wait for an external data feed or file processing system to signal that data is ready before starting transformation

Wait For Event Troubleshooting

Problem Detection Cause Fix
Workflow never resumes Workflow execution appears stopped with no output Event not received and no timeout configured Terminate the waiting workflow instance if needed, then verify that the event name exactly matches the Wait For Event configuration.
Event data not available to downstream nodes Workflow properties remain empty after the event is received Event properties were not mapped to workflow properties in the data mapping panel Open the Wait For Event panel, verify that event properties are declared, and draw mappings to the desired workflow properties.
Property values are wrong or missing Mapped workflow properties contain unexpected values Property names in the data mapping panel do not match the actual event payload field names Confirm that declared event property names exactly match the event payload field names, including case. orderId and orderid are treated as different fields.
Timeout triggers immediately Timeout logic executes without waiting for the event The Max Wait Time value is zero or negative Verify the numeric Max Wait Time value is positive and that a valid time unit is selected.
Dynamic event name causes an exception Workflow throws an error and stops at the Wait For Event node The event name expression evaluated to null Ensure your script expression always returns a non-null string. Add a null check or provide a fallback value in your expression.

Helpful Resources