Function Call Task (`call`)

Purpose

The generic Call task enables the execution of a specified, named function within a workflow. This allows seamless integration with custom business logic, reusable workflow components, or functions defined externally (e.g., in a Resource Catalog).

Note: This describes the generic function call using a function name. For specific protocol interactions like HTTP, gRPC, OpenAPI, or AsyncAPI, refer to their dedicated task pages.

Usage Example

document:
  dsl: '1.0.0'
  namespace: custom-functions
  name: call-custom-example
  version: '1.0.0'
use:
  functions:
    validateAddress:
      call: expression
      with:
        code: |
          function validateAddress(street, city, zipCode) {
            // Basic validation logic
            if (!street || !city || !zipCode) {
              return { valid: false, error: "Missing required fields" };
            }
            // Additional validation logic here
            return { valid: true, normalized: { street, city, zipCode } };
          }
do:
  - checkAddress:
      call: validateAddress
      with:
        street: "${ .customer.address.street }"
        city: "${ .customer.address.city }"
        zipCode: "${ .customer.address.zip }"
      # Output of the 'validateAddress' function becomes output of this task
  - processValidationResult:
      switch:
        - caseValid:
            when: "${ .checkAddress.valid }"
            then: setNormalizedAddress
        - default:
            then: raiseValidationError
  - setNormalizedAddress:
      set:
        normalizedAddress: "${ .checkAddress.normalized }"
      then: exit
  - raiseValidationError:
      raise:
        error:
          type: "https://example.com/errors/validation"
          status: 400
          detail: "${ .checkAddress.error }"
      then: exit

In this example, the checkAddress task calls a function named validateAddress, passing arguments derived from the current context or input using the with property.

Additional Examples

Example: Calling a Function with No Arguments

do:
  - triggerProcessing:
      # Assumes 'startBackgroundJob' function requires no specific arguments
      call: startBackgroundJob
      # No 'with' property needed
  - monitorJob:
      # ...

Example: Calling a Catalog Function

# Assumes 'globalUtils' catalog is imported via workflow.use.catalogs
# Assumes 'logMessage:1.0' function exists in that catalog
do:
  - recordInfo:
      call: logMessage:1.0@globalUtils # Function:Version@CatalogName
      with:
        level: INFO
        message: "Processed item ${ .itemId }"

Configuration Options

call (String, Required)

Specifies the name of the function to execute. This name must correspond to:

• A function defined in the workflow’s use.functions section.
• A function available from an imported Resource Catalog.
• A built-in function provided by the runtime (like http, grpc, etc., although using their specific task pages is recommended).

with (Object, Optional)

A simple key/value map defining the arguments to pass to the called function. Values can be static or derived using Runtime Expressions.

Authentication

The generic function call task itself does not have a dedicated authentication property within its with block. If the function being called requires authentication to perform its internal operations, that logic must be handled inside the function’s implementation (potentially using secrets or context passed via with).

If the function definition itself is hosted in a protected location (like a secured Resource Catalog), authentication would be configured on the catalog’s endpoint definition, not on the call task.

Error Handling: If authentication fails while trying to access the function definition from a protected catalog, the runtime should raise an Authentication or Authorization error related to accessing the catalog endpoint. Errors related to authentication within the called function’s logic are the responsibility of the function itself to handle or raise appropriately.

Data Flow

This task supports standard configuration for the Data Flow (including input, output, export, and schemas). Refer to those pages for details on these common properties and how they apply generally.

Note:

• The transformedInput to the Call task is available for use within runtime expressions in the with arguments.
• The rawOutput of the Call task is the result returned by the executed function.
• Standard output.as and export.as process this function result.

Flow Control

This task supports standard configuration for the Flow Control (including conditional execution with if and branching with then). Refer to those pages for details on these common properties and how they apply generally.