Ruby Connector

Overview

Runs a user-supplied Ruby script inside a sandbox. The script is validated against an allowlist of methods before execution. This connector does not execute arbitrary Ruby, and eval, system, exec, require, instance_eval, direct instance / global variables, and method / constant definitions are all rejected. Use it for in-runbook data transformation, validation, and small computations that don't justify a dedicated connector.

Prerequisites

• Familiarity with Ruby syntax and with the allowed methods listed under the Evaluate Ruby Code action.
• Knowledge of the Ruby 3.4 standard library and the ActiveSupport 8.1 core extensions the allowlist draws from.

Authentication

None. This connector runs entirely in-process and requires no credentials.

Triggers

None. This connector is outbound only.

Actions

Evaluate Ruby Code

Runs a Ruby script with caller-defined input and output schemas. Values assigned to output[:field] inside the script are returned under results.

Use case: reshape data between actions, derive computed fields, validate an invariant and fail the job on breach, format timestamps or sizes, or decrypt secret inputs before passing them to a later step.

Input Parameters

Example Input

{
"input_schema": [
  { "id": "i", "label": "Number", "type": "integer", "required": true },
  { "id": "a", "label": "First string", "type": "string", "required": true },
  { "id": "b", "label": "Second string", "type": "string", "required": true }
],
"output_schema": [
  { "id": "greeting", "label": "Greeting", "type": "string", "required": true }
],
"input": { "i": 4, "a": "hello", "b": "world" },
"proc": "if input['i'] > 3\n  output['greeting'] = input['a'] + ' moon'\nelse\n  output['greeting'] = 'bye ' + input['b']\nend"
}

Output

Results object fields

Fields are defined by output_schema. The runtime enforces the declared types and required flags; wrong types or missing required fields raise IPaaS::Job::FailJob with Nested field 'results' invalid: ….

Example Output

{
"results": { "greeting": "hello moon" }
}

Allowed Ruby methods

Every method call in the script is validated against the allowlist before execution. The groups below sample the most frequently used methods per category. For the full authoritative list, see connector/lib/ipaas/connector/common/proc_rules/valid_methods_rule.rb.

Calling anything outside the allowlist (including eval, system, exec, require, instance_eval, method / constant definitions, direct instance / class / global variables) is rejected at validation time with Method '<name>' not allowed..

Available iPaaS helpers

In addition to the allowed Ruby methods, every helper registered via proc_safe is callable from the script. The groups below are grouped by intended audience. The first four are what most runbook authors will ever need; the rest are primarily for connector-authoring contexts and pass validation here without being idiomatic.

Runbook-native (common)

Secrets

Cache & store

Environment

Data & name helpers

JWT

Advanced (primarily for connector authoring, available but not idiomatic here)

Error Handling

Errors surface at three points:

Best Practices

• Return data through output[:field] = value. The script's return value is discarded.
• Access inputs via input[:key] or input['key']. The hash is with_indifferent_access.
• Call decrypt_secret_string(input[:x]) for any secret_string input; wrap outgoing secret values with make_secret_string(value) when the output_schema declares a secret_string field.
• Use fail_job!('reason') for unrecoverable conditions instead of raising a raw exception.
• If the validator rejects a method, pick an allowed alternative from the lists above. Never try to bypass the allowlist (any workaround involving send, eval, or constant lookup will be rejected).
• Keep scripts small. For logic that repeats across runbooks, add a dedicated connector action instead of pasting a large script into each runbook.

Execution Limits

The Ruby connector imposes no timeout or memory cap of its own. Long-running scripts are subject to the surrounding job runner's limits.

Best Practices

• Use the Ruby connector for glue logic only. Reshape data, validate invariants, compute derived fields. Anything that calls an external API belongs in a dedicated connector.
• Declare input_schema and output_schema up front. The surrounding runbook editor uses them to validate wiring, and the runtime uses them to type-check at the boundaries.
• Treat the allowlist as the contract. If a method you want isn't allowed, the idiomatic path is to either rephrase the expression or add a dedicated action in a purpose-built connector.
• Prefer fail_job!('reason') over raise. It produces a clean error on the runbook run without a Ruby stack trace leaking to the operator.
• Protect secret inputs: decrypt with decrypt_secret_string only as late as needed, and never log(...) a decrypted value.

Common Use Cases

• Reshape action output: map action_output('list_devices') into a slimmer array of hashes before handing it to the next step.
• Custom validation: assert an invariant on upstream data (fail_job!('no users found')) so the runbook stops before a destructive action.
• Derived fields: compute a hash (hexdigest), build a query string (URI.encode_www_form), or normalise a timestamp (1.hour.ago.iso8601) for downstream actions.
• Secret handling: call decrypt_secret_string(input[:token]), use the plain value in a computed header, and surface the result as a secret_string via make_secret_string(...).
• Human-readable formatting: number_to_human_size(bytes) or strftime('%Y-%m-%d') for values rendered in Xurrent records.

References

• Ruby 3.4 standard library
• ActiveSupport 8.1 core extensions
• Base64
• Time
• URI