Skip to content
Hantera OMS Developer Portal Developer Portal

Rule Effects

Rule effects are the actions that rules execute in response to system events. A rule component returns one or more effects that instruct the system what operations to perform.

Effect Categories

Actor Command Effects

Apply commands to specific actor types (current primary effect category):

orderCommand

Apply commands to orders:

from {
  effect = 'orderCommand'
  type = 'createComputedOrderDiscount'
  componentId = 'free-shipping'
  description = 'Free Shipping'
  parameters = { threshold = '500' }
}

See Order Commands for available command types.

paymentCommand

Apply commands to payments:

from {
  effect = 'paymentCommand'
  type = 'setDynamicFields'
  fields = {
    externalId = 'PAY-12345'
  }
}

See Payment Commands for available command types.

ticketCommand

Apply commands to tickets:

from {
  effect = 'ticketCommand'
  type = 'assign'
  userId = 'user-123'
}

See Ticket Commands for available command types.

skuCommand

Apply commands to SKUs:

from {
  effect = 'skuCommand'
  type = 'setDynamicFields'
  fields = {
    supplier = 'SUPPLIER-001'
  }
}

See Sku Commands for available command types.

assetCommand

Apply commands to assets:

from [{
  effect = 'assetCommand'
  type = 'setDynamicFields'
  fields = {
    location = 'WAREHOUSE-A'
  }
}]

See Asset Commands for available command types.

System Operation Effects

messageActor

Send messages to other actors:

from {
  effect = 'messageActor'
  actorType = 'order'
  actorId = '550e8400-e29b-41d4-a716-446655440000'
  messages = [{
    type = 'applyCommands'
    body = {
      commands = [{
        type = 'addTag'
        value = 'processed'
      }]
    }
  }]
}

Fields:

  • actorType - Type of actor (order, payment, ticket, sku, asset)
  • actorId - ID of the actor (or ‘new’ to create)
  • messages - Array of messages to send

scheduleJob

Schedule a job to run later:

from {
  effect = 'scheduleJob'
  definition = 'process-order'
  at = datetime.now addHours 24
  parameters = {
    orderId = order.id
  }
}

Fields:

  • definition - Job definition/component ID
  • at - When to run (instant or nothing, defaults to immediate if omitted)
  • parameters - Parameters to pass (optional)

sendEmail

Queue an email for delivery:

from {
  effect = 'sendEmail'
  to = input.order.invoiceAddress.email
  subject = 'Order Confirmation'
  body = {
    plainText = 'Thank you for your order!'
    html = '<h1>Thank you!</h1>'
  }
  category = 'order-confirmation'
  dynamic = { orderId = input.order.orderId :: text }
}

Fields:

  • to - Recipient email address (required)
  • subject - Email subject line (required)
  • body - Email body with plainText and/or html (at least one required)
  • cc - CC recipients array (optional)
  • bcc - BCC recipients array (optional)
  • from - Sender email address (optional, uses system default)
  • fromName - Sender display name (optional)
  • replyTo - Reply-to email address (optional)
  • category - Category for tracking (optional, defaults to ‘rule’)
  • dynamic - Custom metadata/tracking data (optional)

Validation Effect

validationError

Prevent an operation and return an error:

from {
  effect = 'validationError'
  code = 'INVALID_STATE'
  message = 'Operation not allowed in current state'
}

Fields:

  • code - Error code (string)
  • message - Error message (string)

Important: Only works in Before hooks. After hooks cannot prevent operations.

Effect Syntax

Single Effect

Return one effect:

hook OnOrderCreated


from {
  effect = 'orderCommand'
  type = 'addTag'
  value = 'processed'
}

Multiple Effects

Return array of effects:

hook OnOrderCreated


from [
  {
    effect = 'orderCommand'
    type = 'addTag'
    value = 'confirmed'
  },
  sendEmail {
    to = order.customer.email
    subject = 'Order Confirmed'
    body = { html = '<h1>Thank you!</h1>' }
    dynamic = {}
  }
]

No Effects

Return empty array when no effects needed:

param input: OnOrderCreated


from input.order.total > 1000 match
  false |> []  // No effects
  true |> [{ effect = 'orderCommand', ... }]

Combining Effects

Rules can combine different effect types:

param input: OnOrderCreated


from [
  // Add discount
  {
    effect = 'orderCommand'
    type = 'createComputedOrderDiscount'
    componentId = 'loyalty-discount'
    description = 'Loyalty Member Discount'
  },
  // Send email
  sendEmail {
    to = order.customer.email
    subject = 'Order Confirmed'
    body = { html = '<h1>Thank you!</h1>' }
    dynamic = { orderId = order.id }
  },
  // Schedule follow-up
  {
    effect = 'scheduleJob'
    definition = 'order-follow-up'
    at = datetime.now addDays 7
    parameters = { orderId = order.id }
  }
]

Common Patterns

Conditional Effects

Use pattern matching to conditionally execute effects:

param input: OnOrderCreated


from order.total >= 500 match
  true |> {
    effect = 'orderCommand'
    type = 'addTag'
    value = 'high-value'
  }

Effect Based on Data

Build effects dynamically:

param input: OnOrderCreated


let tags = input.order.total match
  when input.order.total >= 1000 |> ['high-value', 'priority']
  when input.order.total >= 500 |> ['high-value']
  |> []


from tags select tag => {
  effect = 'orderCommand'
  type = 'addTag'
  value = tag
}

Validation Errors

Prevent operations in before hooks:

param input: OnOrderBeforeCreated


let errors = validateOrder(input.order)


from errors count > 0 match
  false |> []
  true |> errors select e => {
    effect = 'validationError'
    code = e.code
    message = e.message
  }

See Also