Skip to main content

Yardrail Extensions

Yardrail extends CWL v1.2 with custom step classes, an input type, and a requirement, all under the yr: namespace (https://yardrail.com/cwl#). The extension schema is defined in pkg/workflows/schema/yardrail-ext.yml.

Step Classes​

Typed Connector Classes​

Each connector's API operations are generated as individual CWL Process classes under a per-connector namespace (e.g. https://yardrail.com/cwl/slack#, https://yardrail.com/cwl/notion#). The class name matches the oapi-codegen operation name from the connector's OpenAPI spec.

Namespace convention: https://yardrail.com/cwl/<connector>#

Examples:

  • slack:ChatPostMessageWithFormdataBody
  • notion:RetrieveADatabase
  • canva:CreateDesign

Inputs/Outputs: derived from the connector function's request/response schema. Declare them as standard CWL inputs/outputs on the step's run: block.

Execution flow:

  1. The class IRI is resolved to a {connectorID, function} pair via the generated class registry
  2. Step inputs are JSON-marshaled as arguments
  3. Calls Host.CallConnector(ctx, stepID, "connector.function", argsJSON)
  4. In the worker, this becomes a Temporal Activity that fetches credentials via interlink and dispatches to the connector handler
  5. The JSON response is unmarshaled as step outputs

Example:

$namespaces:
yr: "https://yardrail.com/cwl#"
slack: "https://yardrail.com/cwl/slack#"

steps:
send:
run:
class: slack:ChatPostMessageWithFormdataBody
inputs:
channel: string
text: string
outputs:
ts: string
channel: string
in:
channel: channel
text: message
out: [ts, channel]

yr:HumanApproval​

Suspends workflow execution until a person approves it in the UI, or the timeout elapses.

Class-level fields:

FieldTypeRequiredDescription
eventTypestringyesEvent type of the approval (e.g. "order.review"); the API's resume call selects the open pause by it
timeoutstringyesISO-8601 duration before the approval times out (e.g. "PT48H"); a timeout fails the run
instructionsstringnoMarkdown shown to the reviewer

The step's label is the title shown to the reviewer; without one, the step ID is used.

Inputs: the step's own inputs are the review items shown to the reviewer, each named by its input label. Wire them with in: like any other step input.

Outputs:

OutputTypeDescription
decisionstring"approved" once a reviewer approves

decision is the only output a HumanApproval step may declare; any other declared output fails the step.

Example:

steps:
approve:
label: "Review the order summary"
run:
class: yr:HumanApproval
eventType: "order.review"
timeout: "PT48H"
instructions: |
Check the order count matches the shop dashboard, then approve.
inputs:
summary:
type: string
label: "Order summary"
outputs:
decision: string
in:
summary: draft/summary
out: [decision]

after:
run:
class: ExpressionTool
requirements:
InlineJavascriptRequirement: {}
inputs:
decision: string
outputs:
out: string
expression: '${return {"out": "decision: " + inputs.decision};}'
in:
decision: approve/decision
out: [out]

yr:Log​

Emits a message to the workflow run's journal. No outputs.

Inputs:

InputTypeDescription
messagestringThe message to log

Execution: Calls Host.Log(ctx, message) → published as a run event via interlink → visible in the run journal and SSE stream.

Example:

steps:
log_message:
run:
class: yr:Log
inputs:
message: string
outputs: []
in:
message: message
out: []

yr:Agent​

A multi-turn agentic LLM step with optional tool calling. Sends a prompt to the org's configured inference backend, optionally dispatching tool calls to connectors in a loop.

Class-level fields:

FieldTypeRequiredDescription
systemstringyesLLM system instructions
toolsAgentTool[]noTools the agent can call during its reasoning loop
maxTurnsintnoMaximum tool-call loop iterations (default: 20)
outputSchemaJSON SchemanoSchema the final answer must match. The step outputs the raw answer as text and the parsed object as output, and fails if the answer does not match

The CWL loader reads the property names name and id inside outputSchema as CWL identifiers and rejects the document; use other property names.

AgentTool can be defined two ways:

  1. Typed class reference — just the class field. Name, description, connector, function, and parameters are derived from the connector schema automatically:

    tools:
    - class: slack:ChatPostMessageWithFormdataBody
  2. Manual definition — explicit name, description, connector, function, and parameters (JSON Schema object):

    tools:
    - name: retrieve-a-database
    description: "Get metadata of a Notion database"
    connector: notion
    function: retrieve-a-database
    parameters:
    properties:
    databaseId: { type: string }
    required: [databaseId]

Inputs: standard CWL inputs forwarded to the model as the user message.

Output: {"text": "..."} — the model's final response text.

Requires: a configured inference backend in the org.


yr:PublishToSite​

Publishes the current run's file outputs to a Site, creating a new live version.

Inputs:

InputTypeDescription
site_idstringThe site to publish to

Outputs:

OutputTypeDescription
version_idstringThe created version's ID

Execution: Calls Host.PublishToSite(ctx, siteID).

Example:

steps:
publish:
run:
class: yr:PublishToSite
inputs:
site_id: string
outputs:
version_id: string
in:
site_id: target_site
out: [version_id]

Input Types​

yr:Connector​

A connector port input — resolved at install/bind time, not supplied by the trigger caller. ExtractInputFields() filters these out so the trigger-input modal only shows user-facing inputs.

inputs:
slack:
type: yr:Connector
message:
type: string

In the example above, only message appears in the trigger modal.


Requirements​

yr:TriggerRequirement​

Declares what can start a workflow run.

Fields:

FieldTypeDescription
triggersTrigger[]Array of trigger definitions

Each Trigger has:

FieldTypeRequiredDescription
kindenumyesyr:connector_event, yr:schedule, yr:webhook, or yr:manual
connectorstringfor connector_eventConnector ID that emits the event
eventTypestringnoEvent type to match
schedulestringfor scheduleCron expression or interval

Example:

requirements:
yr:TriggerRequirement:
triggers:
- kind: yr:webhook
- kind: yr:schedule
schedule: "0 9 * * MON-FRI"
- kind: yr:manual

Host Interface​

The workflow runtime delegates side effects to a Host interface implemented by the worker:

MethodPurpose
CallConnector(ctx, stepID, funcName, inputsJSON)Dispatches a connector function call
Log(ctx, message)Emits a journal message
Now(ctx)Replay-safe current time
NewID(ctx)Replay-safe unique ID generation
InferenceClient()LLM backend for yr:Agent
AgentStore()SGP session store for yr:Agent
RunID()Current run's unique ID
PublishToSite(ctx, siteID)Publishes run outputs to a site, returns version ID