Workflow Scripts
Table of Contents
- Overview
- Basic Usage
- Basic Example
- Returning Complex Data
- Targeting Specific Tasks
- Conditional Task Execution
- Returning a List of Inputs
- Task-Specific Input Formats
- Create a Credential Record
- Create an Invoice Item
- Credit or Debit User's Account
- Emit a Webhook
- Generate an Invoice
- Run a Script
- Send a Slack Message
- Send an Email
- Update a Custom Property
- Advanced Example: Multiple Task Execution
- Best Practices
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
- Give Script tasks descriptive IDs that indicate their purpose
- Keep scripts simple and focused on a single responsibility
- Use comments to document complex logic
- Test your scripts with various inputs to ensure they behave as expected
- Consider error handling for important workflows