Watch the tutorial

The Action Node calls an external application or API as part of a workflow. It is the primary mechanism for connecting your workflow to third-party systems — creating tickets in ServiceNow, sending messages in Slack, updating records in Salesforce, triggering webhooks, and more. The node sends a request to the selected application, receives a response, and stores the result in the Data Center for use by downstream steps.

The Action Node produces two output handles on the canvas — Success and Failure — allowing you to design distinct downstream paths for each outcome.

---

When to Use

Use an Action Node when your workflow needs to:

• Call an external system to create, read, update, or delete a record (e.g., create a ServiceNow ticket, update a Salesforce opportunity).
• Send a notification through a third-party channel (e.g., post a Slack message, send an SMS).
• Trigger a webhook or REST API endpoint and capture the response.
• Fetch data from an external system and make it available to downstream steps.
• Perform any automated action in a connected application as part of the workflow's processing.

---

Configuration

App, Connection, and Action

Configuring an Action Node involves three selections:

Once the app, connection, and action are selected, the node automatically loads the action's form — the fields and parameters required to execute the operation. This form is dynamically generated based on the selected action, so different actions display different fields.

Request Configuration

The request configuration defines the data that is sent to the external system. It supports several content structures:

Headers

Custom HTTP headers can be added as key-value pairs. These are useful for passing additional metadata, content type overrides, or custom authentication tokens.

There is one reserved header: x-app-secret. You cannot add this header manually — if your integration requires it, use a connector with the "Leena x-app-secret" authentication type instead.

Body

The request body carries the main payload sent to the external system. Two body types are supported:

When using form data, text values that resolve to objects are automatically stringified to ensure compatibility.

Dynamic Values

Any field in the request — headers, body fields, query parameters, URL path segments — can contain Data Center expressions. These expressions are enclosed in double curly braces (e.g., {{forms.leaveRequest.startDate}} or {{nodes.previousAction.executionData.ticketId}}). At runtime, each expression is resolved to its actual value from the Data Center before the request is sent.

Response Mapping

Response mapping lets you write values from the API response back into form fields or global constants, making them available to subsequent human-facing steps (Input or Approval Nodes) or other parts of the workflow.

Each mapping entry has two fields:

At runtime, each output field expression is resolved against the current Data Center values, and the result is written to the specified destination. Both the output field and the form field are required for each mapping entry.

Writing to form fields — the value becomes visible to the user in the next Input or Approval Node that displays that form. For example, if the API returns a ticket number, you can map it to a form field so the next approver can see it.

Writing to global constants — the value is stored at the workflow level and can be referenced anywhere in downstream nodes without being tied to a specific form.

Multiple mappings can be configured on a single Action Node. If a mapping entry has an empty output field or form field, it is skipped.

Testing the Action

The Action Node provides a built-in test capability that lets you run the API call directly from the workflow builder — without triggering a full workflow execution. Testing follows a three-step flow: autofill the request, execute the call, and save the response for downstream use.

Autofill

When you open the test panel, the system can automatically pre-fill the test request fields using data already available in the workflow. If your request configuration contains Data Center expressions (e.g., referencing a form field or a previous node's output), the autofill feature resolves those placeholders against the test data saved by other nodes in the same workflow. This gives you realistic, context-aware test inputs without manually copying values.

For example, if your Action Node's request body references a ticket title from a preceding Input Node, autofill pulls in whatever test value was saved for that Input Node's output — so you can test with representative data in a single click.

Fields that cannot be resolved (because the upstream node hasn't been tested yet or the expression is invalid) are left as-is, so you can fill them in manually.

Running the Test

Once the request fields are populated (via autofill, manual entry, or a combination), you execute the test. The system sends the request to the selected app and connection using the configured action — exactly as it would at runtime — and returns the full response including status code, headers, and response body.

If staging mode is enabled, the test runs against the staging environment instead of production, so you can safely test without affecting live data.

The test request and response are stored separately from the production configuration, so testing does not interfere with the published workflow.

Save Response to Data Center

After a successful test, you can save the API response to the Data Center. This is a critical step — it registers the response structure (fields, data types, nesting) so that downstream nodes can reference the Action Node's output during configuration.

Two save modes are available:

Once saved, the response fields become available as Data Center variables throughout the workflow — you can reference them in downstream Decision Nodes, Function Nodes, notification templates, response mappings, and more.

Recommended Test Workflow

1. Configure upstream nodes first and test them so their outputs are available for autofill.
2. Open the Action Node test panel and use Autofill to pre-populate the request with resolved values.
3. Fill in any remaining fields manually.
4. Run the test and verify the response status, headers, and body.
5. Save the response to the Data Center so downstream nodes can reference the output fields.
6. Configure response mapping, error mapping, and downstream logic using the now-available response fields.

Success and Error Messages

You can configure messages that are surfaced to the end user after the Action Node executes. These messages appear in the user interface as part of the workflow item's progress.

Success Message

A text message shown when the action completes successfully. Supports Data Center expressions, so you can include dynamic values from the response. For example: "Your ticket {{nodes.createTicket.executionData.data.ticketNumber}} has been created successfully."

Error Messages

Error messages can be configured in two ways, controlled by the Static Error toggle:

All success and error messages support Data Center expressions, which are resolved at runtime against the current Data Center values before being shown to the user.

Retry Configuration

When enabled, the system automatically retries the action if it fails, rather than immediately routing to the Failure path. This is useful for transient errors like network timeouts or temporary service unavailability.

During retries, the system uses an idempotency mechanism to ensure that the same action is not executed twice by the external system — even if the retry happens after a network interruption. This is particularly important for operations like creating records, where duplicate execution could cause data issues.

Retries are not available for Action Nodes inside a Synchronous Block.

Timeout Period

The timeout defines how long the system waits for the external system to respond before considering the call a failure.

If the external system does not respond within the timeout period, the action is treated as a failure. If Retry on Timeout is enabled, the system will retry before giving up.

Failure Handling

Fail Workflow Item

When enabled, if the action fails (after all retries are exhausted), the entire workflow item can be marked as failed. This works in combination with the Trigger Node's failure configuration:

• If the Trigger Node is set to generic error, a single configured error message is shown for all failures.
• If the Trigger Node is set to node-specific error, the individual Action Node's error message (static or mapped) is shown.

Failed items are also surfaced in scheduled failure reports.

Remove Failure Handle

Controls the node's output handles on the canvas:

When you toggle this setting on for an existing node, any edges already connected to the Failure handle are automatically removed from the canvas.

Masked Fields

You can specify fields that should be masked in execution logs, audit trails, and the progress tracker. This is useful for sensitive data like API keys, passwords, or personal identifiers that appear in the request or response.

If you save the test response with Overwrite mode, previously configured masked fields are cleared (since the response structure may have changed).

Progress Path

The Action Node appears in the workflow item's progress tracker with timestamps showing when the action was triggered, completed, or failed:

Two visibility settings control whether the node appears in the progress tracker:

Staging Mode

When enabled, the Action Node routes requests to a staging environment of the integration framework instead of production. This applies to both test executions and live workflow runs. Use this for testing integrations against sandbox environments without affecting live data.

---

Synchronous Block vs. Standalone

Action Nodes can be used in two modes, which significantly affect their behavior:

End-User OAuth (Synchronous Block Only)

When an Action Node inside a Synchronous Block uses a connection that requires end-user authentication (e.g., calling an API on behalf of the logged-in user), the system automatically prompts the user to authorize the connection before executing the action. This happens when the user opens the form or task that precedes the sync block.

The system scans all Action Nodes within the sync block, identifies which connections require OAuth, and checks whether the current user has valid tokens. If authentication is missing, the user is shown an OAuth prompt before they can proceed.

End-user OAuth connections are not allowed in standalone (async) Action Nodes, since there is no user present to authorize the connection during background execution.

---

Data Center Output

After execution, the Action Node makes the following data available in the Data Center for downstream nodes:

These values can be referenced by any downstream node using Data Center expressions like {{nodes.createTicket.executionData.data.ticketNumber}}.

Inside a For Each Loop

When an Action Node is placed inside a For Each loop, it executes once per iteration. Each execution receives the loop index and resolves Data Center expressions against the current iteration's context. Results are stored per iteration under the parent loop's data structure, so downstream nodes can access individual iteration results.

---

How It Works at Runtime

1. Request is prepared — all Data Center expressions in the request configuration (headers, body, query parameters) are resolved to their actual runtime values.
2. Form data is processed — if the body type is form data, text values that were parsed into objects are stringified back to ensure compatibility with the external API.
3. Action executes — the resolved request is sent to the external system via the selected connection and action. The system waits up to the configured timeout period for a response.
4. Response is captured — the full API response (data, status code, headers) is stored in the Data Center under this node's identifier and becomes available to all downstream nodes.
5. Response mapping runs — if mapping entries are configured, each output field expression is resolved against the updated Data Center values, and the result is written to the specified form field or global constant.
6. Success or failure is determined — if the API response indicates success (status code below 400), the action is marked as successful. If the status code is 400 or above, the action is treated as a failure.
7. Retry (if applicable) — if the action failed and retry is enabled with remaining attempts, the system waits for the configured interval and re-executes. The retry uses the same idempotency key to prevent duplicate operations. Each retry resolves the request fresh from the Data Center.
8. Path selection — if the action succeeded, the workflow follows the Success path. If it failed (after all retries), the workflow follows the Failure path. If Fail Workflow Item is enabled and the action failed, the workflow item may be marked as failed and the corresponding success or error message is surfaced to the user.

---

Validation Rules

The workflow builder validates Action Nodes at publish time:

• The node must have exactly one incoming edge. More than one incoming edge triggers an edge mismatch error.
• The node must not be abandoned — it cannot have zero incoming and zero outgoing edges.
• For standalone nodes (with the Failure handle active): both the Success and Failure handles must have an outgoing edge.
• For standalone nodes with Remove Failure Handle enabled: only the Success handle must have an outgoing edge.
• For nodes inside a Synchronous Block: at least one outgoing edge is required.
• A maximum of 2 outgoing edges is allowed (one per handle).
• End-user OAuth connections are not permitted on standalone (async) Action Nodes. If the selected connection requires end-user authentication, it can only be used inside a Synchronous Block.

---

Best Practices

• Always test your action before publishing. Use the built-in test capability with autofill to verify the request, response, and response mapping with representative data. Save the response to the Data Center so downstream nodes can reference the output fields during configuration.
• Use response mapping to surface key response data. If the API returns a ticket number, status, or reference ID, map it to a form field so downstream approvers or assignees can see it. Use global constants for values that need to be accessible across the entire workflow.
• Enable retry for actions calling external APIs that may experience transient failures. Set a reasonable interval (e.g., 30–60 seconds) and 2–3 attempts for most integrations. Enable "Retry on Timeout" only if the external system is idempotent (safe to call twice with the same input).
• Choose timeout values based on the external system. Fast APIs (internal services, webhooks) can use shorter timeouts. Slow APIs (batch operations, complex queries) may need the full 600-second range.
• Use the Failure handle to design graceful error paths. Send a notification, log the failure, or route to a manual fallback rather than letting the workflow silently fail.
• Use dynamic error mapping for user-facing workflows. Map specific HTTP status codes to clear, actionable messages. Use static error for internal or non-critical actions where a generic message is sufficient.
• Enable Fail Workflow Item only when the action is critical to the workflow's success. For non-critical integrations (e.g., logging, notifications), leave it disabled so the workflow can continue even if the action fails.
• Mask sensitive fields — if your request or response contains passwords, tokens, or personal data, add those fields to the masked fields list to keep them out of execution logs.
• Use staging mode for initial integration testing to avoid affecting live data in the external system. Switch to production mode once the integration is verified.
• Use Synchronous Blocks for real-time user interactions where the result must be shown immediately (e.g., creating a ticket right after form submission and displaying the ticket number). Keep synchronous actions fast (under 30 seconds) to avoid a poor user experience.
• Test upstream nodes first before testing an Action Node that depends on their output. This ensures autofill can resolve all Data Center expressions and gives you accurate test data.
• Use the progress path "Hide" setting for background integrations (logging, syncing) that don't need to be visible to end users in the progress tracker.