Skip to main content

Event Examples: Iterable Mode

Complete JSON examples for Iterable events - process each item in an array separately.

Overview​

Iterable mode processes each item in an array separately. The workflow executes once for each element in the specified array field.

Use Cases​

  • Send notifications to multiple recipients
  • Process order line items individually
  • Publish to multiple social media accounts
  • Batch processing of array data
  • Multi-target operations

Basic Iterable Event​

Process each recipient in a notification:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Process Each Recipient",
  "description": "Sends notification to each recipient in the array",
  "workflowEntityTypeId": "event-type-uuid",
  "condition": {
    "type": "rule",
    "field": "message.type",
    "comparison": "equals",
    "value": "notification.broadcast"
  },
  "tfCondition": "Iterable",
  "logicField": "message.recipients",
  "script": "print('Will process', message.recipients.length, 'recipients');",
  "arguments": [],
  "logic": []
}

Example Message:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "type": "notification.broadcast",
  "subject": "Server Maintenance",
  "content": "Scheduled maintenance tonight at 3 AM EST",
  "recipients": [
    {
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "phone": "+1-555-0101"
    },
    {
      "name": "Bob Smith",
      "email": "bob@example.com",
      "phone": "+1-555-0102"
    },
    {
      "name": "Charlie Brown",
      "email": "charlie@example.com",
      "phone": "+1-555-0103"
    }
  ]
}

Workflow Behavior:

  • Workflow executes 3 times (once per recipient)
  • Each iteration has access to ___iterableItem___

Accessing Current Item in Downstream Entities​

In child Prompt or Action entities, access the current recipient:

// In a downstream Action entity script
const recipient = ___iterableItem___;

print('Sending to:', recipient.name);
print('Email:', recipient.email);
print('Phone:', recipient.phone);

// Use the recipient data
await sendEmail(recipient.email, message.subject, message.content);

Iterable - Process Order Items​

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Process Each Order Item",
  "description": "Processes each item in an order separately",
  "workflowEntityTypeId": "event-type-uuid",
  "condition": {
    "type": "rule",
    "field": "message.type",
    "comparison": "equals",
    "value": "order.created"
  },
  "tfCondition": "Iterable",
  "logicField": "message.items",
  "script": "print('Processing order with', message.items.length, 'items');",
  "arguments": [],
  "logic": []
}

Example Message:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "type": "order.created",
  "orderId": "order-12345",
  "customerId": "customer-789",
  "total": 299.97,
  "items": [
    {
      "productId": "prod-101",
      "name": "Wireless Mouse",
      "quantity": 2,
      "price": 29.99
    },
    {
      "productId": "prod-102",
      "name": "USB Cable",
      "quantity": 3,
      "price": 9.99
    },
    {
      "productId": "prod-103",
      "name": "Laptop Stand",
      "quantity": 1,
      "price": 89.99
    }
  ]
}

Downstream Script Access:

// In child Action entity
const item = ___iterableItem___;

print('Processing item:', item.name);
print('Quantity:', item.quantity);
print('Price:', item.price);
print('Subtotal:', item.quantity * item.price);

// Check inventory for this item
var inventoryLevel = await checkInventory(item.productId);
if (inventoryLevel < item.quantity) {
  print('WARNING: Low inventory for', item.name);
}

Iterable - Multi-Account Publishing​

Publish content to multiple social media accounts:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Publish to Each Account",
  "description": "Publishes content to multiple social media accounts",
  "workflowEntityTypeId": "event-type-uuid",
  "condition": {
    "type": "rule",
    "field": "message.type",
    "comparison": "equals",
    "value": "content.publish"
  },
  "tfCondition": "Iterable",
  "logicField": "message.accounts",
  "script": "print('Publishing to', message.accounts.length, 'social media accounts');",
  "arguments": [],
  "logic": []
}

Example Message:

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "type": "content.publish",
  "content": "Just launched our new product line! Check it out at example.com/products",
  "imageUrl": "https://cdn.example.com/product-launch.jpg",
  "accounts": [
    {
      "platform": "mastodon",
      "instanceUrl": "https://mastodon.social",
      "accessToken": "token-123"
    },
    {
      "platform": "mastodon",
      "instanceUrl": "https://fosstodon.org",
      "accessToken": "token-456"
    },
    {
      "platform": "bluesky",
      "handle": "@company.example.com",
      "accessToken": "token-789"
    }
  ]
}

Downstream Script:

// In child Action entity
const account = ___iterableItem___;

print('Publishing to', account.platform, '-', account.instanceUrl || account.handle);

if (account.platform === 'mastodon') {
  await postToMastodon(
    account.instanceUrl,
    account.accessToken,
    message.content
  );
  print('✓ Posted to Mastodon');
} else if (account.platform === 'bluesky') {
  // Post to Bluesky
  print('✓ Posted to Bluesky');
}

Iterable with Non-Array Value​

If logicField points to a non-array value, workflow proceeds normally (single execution):

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Process User or Users",
  "description": "Handles both single user and array of users",
  "workflowEntityTypeId": "event-type-uuid",
  "condition": {
    "type": "rule",
    "field": "message.type",
    "comparison": "equals",
    "value": "user.update"
  },
  "tfCondition": "Iterable",
  "logicField": "message.users",
  "script": "print('Processing user(s)');",
  "arguments": [],
  "logic": []
}

Array Message (3 executions):

{
  "type": "user.update",
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    { "id": 3, "name": "Charlie" }
  ]
}

Single User Message (1 execution):

{
  "type": "user.update",
  "users": { "id": 1, "name": "Alice" }
}

API Endpoint​

POST /api/workflow-entities
Content-Type: application/json

Key Points​

  1. logicField: Points to an array in the message (e.g., message.recipients)
  2. iterableItem: Access current item in child entity scripts
  3. Multiple executions: Workflow runs once for each array element
  4. Non-array handling: Single execution if value is not an array
  5. Performance: Consider array size - large arrays mean many executions

Best Practices​

  1. Ensure logicField points to an array in the message
  2. Access current item via ___iterableItem___ in child entities
  3. Handle both array and single-value gracefully
  4. Consider batch size limits for large arrays
  5. Use for fan-out patterns where each item needs independent processing
  6. Test with different array sizes