Utilities Tasks

Logging

Log

task: "Utilities/Log@1"
name: log
inputs:
  message: "Hello World"

Mapping

Map

The Map task maps values from one object to another. The result of the mapping is stored in the output variable.

task: "Utilities/Map@1"
name: map
inputs:
  subject: "Hello World"
  emailBody: "Hello {{subject}}"
outputs:
  - name: "result"
    mapping: "result"

Output:

{
  "result": {
    "subject": "Hello World",
    "emailBody": "Hello Hello World"
  }
}

Error

The Error task is used to throw an error.

task: "Utilities/Error@1"
name: error
inputs:
  message: "Error message"

HTTP Request

The HTTP Request task handles REST API communications with advanced features like retry policies, response caching, and event tracking.

Key Features:

• Automatic content handling for JSON/x-www-form-urlencoded/XML
• Exponential backoff retry mechanism
• Response caching with multiple expiration strategies
• Security header sanitization for event logging
• Multi-format response parsing (JSON, XML, PDF base64 encoding)

YAML Structure:

task: "Utilities/HttpRequest@1"
name: httpRequest
inputs:
  url: "https://api.example.com/data"
  method: "POST"
  contentType: "application/json" # Supported: application/json, application/x-www-form-urlencoded
  retryOptions:
    limit: 3 # Max retry attempts
    codes: [500, 503] # HTTP status codes triggering retries
  enableActionEvents: true
  eventName: "API_CALL_EVENT"
  responseContentType: "application/json" # Auto-detected from response headers
  cache:
    enabled: true
    duration: "1h" # Supports "EndOfDay|TZ" (e.g., "EndOfDay|CST")
    useSlidingExpiration: false # Reset expiration window on access
  headers:
    - name: "Authorization"
      value: "Bearer ${API_TOKEN}"
  body:
    key: "value"
outputs:
  - name: "response"
    mapping: "response"

Attribute Details:

Input Parameter	Description
retryOptions.limit	Maximum retry attempts using exponential backoff (2^attempt seconds)
cache.duration	Supports ISO 8601 durations or "EndOfDay" with optional timezone
contentType	Defaults to JSON. Form-encoded data requires key-value pairs in body
responseContentType	Fallback if Content-Type header missing. Supports JSON/XML auto-conversion

Response Structure:

{
  "response": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "data": "payload" // Type varies by content:
      // - JSON: object
      // - XML: converted JSON
      // - PDF: base64 string
      // - Other: raw string
    }
  }
}

Best Practices:

1. Use EndOfDay caching for daily batch operations
2. Avoid caching POST/PUT methods except for idempotent operations
3. Use environment variables for sensitive headers like Authorization
4. Enable retry for 5xx status codes and network failures
5. Use sliding expiration for frequently accessed static data

Error Handling:

• Throws WorkflowRuntimeException for non-2xx responses
• Retries follow pattern: 2s, 4s, 8s delays by default
• Failed requests generate action events with sanitized details

Download File

The Download File task handles file downloads with caching and retry capabilities.

task: "Utilities/DownloadFile@1"
name: downloadFile
inputs:
  url: "https://jsonplaceholder.typicode.com/todos/1.zip"
  fileName: "file.zip" # Optional - File name to save the downloaded file as
  method: "POST"
  headers:
    - name: "Content-Type"
      value: "application/json"
  body:
    name: "John Doe"
    email: ""
  decompress:
    enabled: true
    type: "zip" # Optional - Type of compression to use (zip, gzip, tar, rar, 7z)
    filter: "*.csv" # Optional - Filter to apply to the decompressed files
  cache:
    enabled: true
    duration: "1h" # Supports ISO 8601 or "EndOfDay|TZ"
    useSlidingExpiration: false
  retryOptions:
    limit: 3
    codes: [500, 503]
outputs:
  - name: "files"
    mapping: "files"
  - name: "folder"
    mapping: "folder"

Attribute Details:

Input Parameter	Description
cache.duration	File cache duration (same format as HTTP Request)
cache.enabled	Enable disk caching of downloaded files
retryOptions.limit	Max retry attempts with exponential backoff
decompress	Decompress the downloaded file if the file is compressed

Output:

{
  "files": ["/temp/unzipped/file1", "/temp/unzipped/file2"],
  "folder": "/temp/unzipped"
}

CSV

The CSV task is used to read a CSV file.

task: "Utilities/CSV@1"
name: csv
inputs:
  file: "/path/to/file.csv"
  options:
    delimiter: "," # Optional - Delimiter used in the CSV file
    columns: ["name", "email"] # Optional - Columns to read from the CSV file
outputs:
  - name: "data"
    mapping: "data"

Set Variable

The Set Variable task is used to set a variable.

task: "Utilities/SetVariable@1"
name: setVariable
inputs:
  name: "getData.results"
  value:
    extends: "getData.results"
    mapping:
      - name: "name"
        value: "John Doe"
      - name: "email"
        value: "[email protected]"

Sequence Number/Get

The SequenceNumber/Get task is used to obtain the next sequence number.

task: "SequenceNumber/Get@1"
name: getSequenceNumber
inputs:
  sequenceNumber: "OrderNumber"

Utilities/Export

The Utilities/Export task is used to export data to a file. The exported file URL is stored in the output variable.

task: "Utilities/Export@1"
name: export
inputs:
  name: "contacts" # Name of the export, added to the file name
  fileType: "Csv" # File type to export (Csv, Xlsx, Json)
  data:
    - name: "John Doe"
      email: "[email protected]"
outputs:
  - name: "fileUrl"
    mapping: "fileUrl" # URL of the exported file

Utilities/Lock (Proposed)

The Utilities/Lock workflow task is used to lock a resource.

task: "Utilities/Lock@1"
name: lock
inputs:
  resource: "resourceName"
  lockDuration: 60 # Optional - Lock duration in seconds
  timeout: 60 # Optional - Timeout in seconds
  retryInterval: 5 # Optional - Retry interval in seconds

Utilities/Unlock (Proposed)

The Utilities/Unlock workflow task is used to unlock a resource.

task: "Utilities/Unlock@1"
name: unlock
inputs:
  resource: "resourceName"

Utilities/ValidateHMAC@1

The Utilities/ValidateHMAC task is used to validate a HMAC signature. It is typically used to validate webhook requests.

task: "Utilities/ValidateHMAC@1"
name: validateHMAC
inputs:
  secret: "your-secret-key"
  algorithm: "SHA256"
  signature: "signature"
  payload: "payload"
outputs:
  - name: "isValid"
    mapping: "isValid"

Utilities/ValidateReCaptcha@1

The Utilities/ValidateReCaptcha task is used to validate a ReCaptcha response. It is typically used to validate webhook requests.

task: "Utilities/ValidateReCaptcha@1"
name: validateReCaptcha
inputs:
  secret: "your-recaptcha-secret"
  token: "token"
  throwException: true # Optional - Throw an exception if the validation fails
  version: "v3" # Optional - Version of the ReCaptcha (v2, v3)
outputs:
  - name: "isValid"
    mapping: "isValid"

Utilities/Template

The Utilities/Template task is used to render a template using handlebars.

Inputs:

• template - The template to render. Use the $raw property to pass templated strings.
• data - The data to render the template with.

Outputs:

• result - The rendered template.

task: "Utilities/Template@1"
name: template
inputs:
  template:
    $raw: "{{name}} is {{age}} years old."
  data:
    name: "John Doe"
    age: 30
outputs:
  - name: "result"
    mapping: "result"