Documentation

Workflow Scripts

Table of Contents

Overview

Script tasks in our workflow engine enable dynamic data processing and decision making. You can use Script tasks to generate values that serve as inputs to other tasks in your workflow.

Basic Usage

Each Script task requires a unique identifier in the Task ID field. Other tasks can access the output from this script by referencing the same ID in their Input Task ID field.

Basic Example

# Simple script that returns a value to be used by another task
return 500  # This value will be available to any task that references this Script's Task ID

Returning Complex Data

Scripts can return objects to provide structured data to other tasks:

# Return an object with multiple values
return {
  'invoice_amount': 2500,
  'user_id': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  'training_id': 'q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
}

Targeting Specific Tasks

You can target outputs to specific tasks using the for_task_id field within a list structure:

# Return different inputs for different tasks
return {
  'list': {
    'items': [
      {'invoice_amount': 1000, 'for_task_id': 'create_invoice_1'},
      {'invoice_amount': 2000, 'for_task_id': 'create_invoice_2'}
    ]
  }
}

Conditional Task Execution

Use the skip field to conditionally skip tasks:

# Skip a task based on a condition
premium_user = input_task['is_premium'] # Assumes an input task calculated this.

if premium_user:
  return {'skip': 'charge_fee_task'}
else:
  return {'invoice_amount': 1500}

Returning a List of Inputs

When you need more advanced control over task execution, you can use the special list output format. This powerful feature allows a single Script task to:

  • Provide inputs to multiple downstream tasks
  • Run the same task multiple times with different inputs
  • Selectively target specific tasks by ID
  • Conditionally skip certain tasks

The structure follows this pattern:

return {
  'list': {
    'items': [
      # Each item in this array can be an input to a task
      {'field1': 'value1', 'field2': 'value2', 'for_task_id': 'specific_task_id'},
      {'field1': 'value3', 'field2': 'value4'}  # No for_task_id means available to any task
    ]
  }
}

The for_task_id field is optional and specifies which task should receive this particular input. When multiple inputs would run on the same task, that task is run multiple times (once for each input). A single script can compute the inputs to multiple tasks by returning a list of inputs that each have a for_task_id field and then setting that script as the input task to each subsequent task.

Task-Specific Input Formats

Create a Credential Record

Assigns credentials to users, typically after completing training or certification programs.

return {
  'duration': 86400,         # Duration in seconds (24 hours)
  'training_id': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  'user_id': 'q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2',
  'invoice_amount': 9900,    # $99.00
  'meta_data': {'level': 'intermediate', 'expires': '2023-12-31'}
}

Create an Invoice Item

Adds a single line item to an invoice for billing purposes.

return {
  'invoice_amount': 5000     # $50.00
}

Credit or Debit User's Account

Adjusts a user's account balance by adding or removing funds.

return {
  'amount_cents': 2500,      # $25.00 credit
  'create_account_if_needed': True,
  'note': 'Referral bonus',
  'user_id': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
}

Emit a Webhook

Sends HTTP requests to external systems to trigger actions or share data.

return {
  'url': 'https://api.example.com/webhooks/process',
  'method': 'post',
  'body': '{"status": "completed", "order_id": "order_123"}',
  'headers': [
    {'name': 'Content-Type', 'value': 'application/json'},
    {'name': 'X-API-Key', 'value': 'secret_key_123'}
  ],
  'username': 'api_user',
  'password': 'api_password'
}

Generate an Invoice

Creates a complete invoice for a user based on their reservations or activities.

return {
  'reservation_ids': ['a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6', 'q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'],
  'bill_to_user_id': 'g3h4i5j6k7l8m9n0p1q2r3s4t5u6v7w8',
  'memo': 'Training services provided in Q3',
  'payment_instructions': 'Due within 30 days',
  'invoice_number_prefix': 'TRAIN-'
}

Run a Script

Executes custom logic to transform data or make decisions based on workflow inputs.

# Access data from a previous Script task
previous_amount = input_task['amount']
return {
  'new_amount': previous_amount * 1.1  # Add 10%
}

Send a Slack Message

Delivers notifications to users or channels in Slack for real-time updates.

return {
  'channel': 'team-updates',
  'user': 'john.doe@example.com',
  'users': ['alice@example.com', 'bob@example.com'],
  'text': 'Training certificate issued: {certificate_id}',
  'vars': {
    'certificate_id': 'CERT-001-2023'
  }
}

Send an Email

Sends customized emails to users with variable content.

return {
  'recipient_id': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  'cc_ids': ['q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2', 'g3h4i5j6k7l8m9n0p1q2r3s4t5u6v7w8'],
  'bcc_ids': ['x9y0z1a2b3c4d5e6f7g8h9i0j1k2l3m4'],
  'subject': 'Your Training Certificate',
  'body': 'Congratulations, {name}! Your certificate is ready.',
  'vars': {
    'name': 'John Doe'
  }
}

Update a Custom Property

Modifies property values associated with users or resources in the system.

return {
  'property_name': 'Certification Level',
  'reservable_id': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  'value': 'advanced'
}

Advanced Example: Multiple Task Execution

This example shows how a single Script task can drive multiple downstream tasks:

user_id = 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
is_premium = True

# Prepare outputs for multiple tasks
outputs = []

# Always send confirmation email
outputs.append({
  'recipient_id': user_id,
  'subject': 'Registration Confirmed',
  'body': 'Thank you for registering!',
  'for_task_id': 'send_email_task'
})

# Conditionally apply credits for premium users
if is_premium:
  outputs.append({
    'amount_cents': 5000,
    'user_id': user_id,
    'note': 'Premium member bonus',
    'for_task_id': 'credit_account_task'
  })

# Return all outputs
return {
  'list': {
    'items': outputs
  }
}

Best Practices

  1. Give Script tasks descriptive IDs that indicate their purpose
  2. Keep scripts simple and focused on a single responsibility
  3. Use comments to document complex logic
  4. Test your scripts with various inputs to ensure they behave as expected
  5. Consider error handling for important workflows