Context API

Every service handler receives a context object (ctx) that provides methods to access task data and control execution flow.

Data Access

ctx.input

The input data for the current message. This is the payload that was routed to this service node based on the task template graph.

TypeScript

createService('1.0.0', (ctx) => {
  const input = ctx.input
  // input is the data routed to this service node
})

Python

def handler(ctx):
    input = ctx.input
    # input is the data routed to this service node

ctx.configuration

The static configuration set on the service node in the task template editor.

TypeScript

createService('1.0.0', (ctx) => {
  const config = ctx.configuration
  // config is the JSON set in the UI for this service node
})

Python

def handler(ctx):
    config = ctx.configuration
    # config is the dict set in the UI for this service node

ctx.taskId

The unique identifier of the current task execution.

ctx.debug

A logger that sends messages to the Requence UI in real time. Available methods: log, info, warn, error.

TypeScript

createService('1.0.0', (ctx) => {
  ctx.debug.log('Processing started')
  ctx.debug.warn('Something looks off')
})

Python

def handler(ctx):
    ctx.debug.log("Processing started")
    ctx.debug.warn("Something looks off")

Flow Control

ctx.retry(delay?)

Instructs Requence to retry this service after an optional delay in milliseconds (minimum 100 ms). No code executes after this call.

TypeScript

createService('1.0.0', async (ctx) => {
  const db = await getDbConnection()

  if (!db.isConnected) {
    ctx.retry(2000) // retry in 2 seconds
  }

  return db.query('SELECT ...')
})

Python

def handler(ctx):
    db = get_db_connection()

    if not db.is_connected:
        ctx.retry(2000)  # retry in 2 seconds

    return db.query("SELECT ...")

Caution

It is your responsibility to prevent infinite retry loops. Requence does not currently enforce a maximum retry count.

ctx.abort(reason?)

Instructs Requence to abort this service immediately. If the on fail output is not connected, the entire task will fail.

TypeScript

createService('1.0.0', (ctx) => {
  if (!ctx.input.requiredField) {
    ctx.abort('Missing required field')
  }

  return processData(ctx.input)
})

Python

def handler(ctx):
    if not ctx.input.get("requiredField"):
        ctx.abort("Missing required field")

    return process_data(ctx.input)

ctx.toOutput(name, value)

Routes execution to a specific named output on the service node. This is used when your service has multiple outputs defined in the service definition.

TypeScript

createService('1.0.0', (ctx) => {
  if (ctx.input.type === 'pdf') {
    return ctx.toOutput('pdf', { url: '...' })
  }

  return ctx.toOutput('other', { raw: ctx.input })
})

Python

def handler(ctx):
    if ctx.input.get("type") == "pdf":
        return ctx.to_output("pdf", {"url": "..."})

    return ctx.to_output("other", {"raw": ctx.input})

ctx.defer(reason?)

Marks the current message as deferred. The service acknowledges the message but signals that the work will be completed later via the act() API. This is useful for long-running processes or external callbacks.

TypeScript

createService('1.0.0', (ctx) => {
  const messageKey = ctx.defer('waiting for external process')
  // Store messageKey to use later with service.act()
})

Python

def handler(ctx):
    message_key = ctx.defer("waiting for external process")
    # Store message_key to use later with service.act()