> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Author a procedure

> Write a Python Procedure that runs in a Vercel Sandbox — the forge.yaml manifest, SDK primitives, canonical wire shapes, file bindings, and the built-in procedure catalog.

Last updated 2026-11-11

·
applies to 2026-11-03

·
main

A **Procedure** is a Python function that runs in an isolated Vercel Sandbox VM and communicates back to the platform through the `gloo-procedure-sdk`. It is the right tool for algorithmic work — pagination, data transformation, file generation, bulk API calls — where determinism, reproducibility, and sandboxed execution matter more than reasoning.

This guide is for builders authoring new Procedures. For using an existing Procedure as a workflow node or agent tool, see the individual procedure reference pages (e.g. [core-filter-by-date-range](https://docs.gloo.com/forge/build/built-in-procedures.md#core-filter-by-date-range), [linear-paginate-issues](https://docs.gloo.com/forge/build/built-in-procedures.md#linear-paginate-issues)).

When to use a Procedure vs an agent tool

Use a Procedure when the work is algorithmic and the output should be identical given the same inputs. Use an agent tool when the work requires judgment, tool chaining, or dynamic decision-making. A good signal: if you could write a unit test that fully specifies the expected output, it probably belongs in a Procedure.

***

## How Procedures connect to the platform

A Procedure runs in a Vercel Sandbox VM with no direct database access. It reads inputs and writes outputs exclusively through the `gloo-procedure-sdk`, which makes HTTP calls back to Convex via the `/api/v1/proceduresApi/*` routes. Those routes validate the wire shapes and dispatch to the same executors used by Convex-native agents.

PROCEDURE — SDK → PLATFORM CALL PATH

<ol aria-label="PROCEDURE — SDK → PLATFORM CALL PATH" />

This architecture means a Procedure's `put_file` call hits exactly the same execution path as a Convex-native agent's `putFile` tool call. The wire shapes are defined once and shared across both callers — drift between the SDK and the platform is detected at CI time.

***

## The `forge.yaml` manifest

Every Procedure lives in a directory containing a `forge.yaml` manifest and a Python entry point. The manifest is the single source of truth for the procedure's identity, I/O contract, sandbox config, and capability requirements.

```yaml theme={null}
procedureId: my-procedure          # unique, kebab-case
version: 0.1.0                     # semver
name: My Procedure                 # display name
description: >-
  One-sentence description.
source: builtin                    # "builtin" for platform-shipped; "workspace" for org-authored
runtime: python                    # only "python" supported today

sandbox:
  image: ghcr.io/tangogroup/gloo-forge/procedure-base-python:latest
  packages:
    pip: []                        # pip packages to install at image-build time
    npm: []
    apt: []
  timeoutSeconds: 60               # wall-clock limit for the sandbox run
  memoryMb: 512
  egressAllowlist: []              # hostnames the sandbox may reach (empty = no outbound)

capabilities:
  - file_hosting                   # always required if you call put_file or get_file
  - project_management             # add when calling invoke_capability with that domain

inputs:
  type: object
  required: [inputFile]
  properties:
    inputFile:
      type: string
      format: fileId
      description: Input file.

outputs:
  type: object
  required: [outputFile, count]
  properties:
    outputFile:
      type: string
      format: fileId
    count:
      type: integer

errors:
  - INVALID_INPUT
  - SCHEMA_MISMATCH
  - INTERNAL_ERROR

idempotent: true
deterministic: true
exposedAs:
  graphNode: true    # available as a workflow graph node
  agentTool: true    # available as an agent tool call
entrypoint: procedure.py
```

### Key manifest fields

| Field | Description |
| - | - |
| `procedureId` | Unique identifier. Used in workflow graph YAML and agent tool references. Kebab-case. |
| `version` | Semver. The executor pins to this version when the workflow graph is authored. |
| `sandbox.egressAllowlist` | Hostnames the sandbox may reach. Leave empty for pure-transform procedures with no outbound calls. Capability proxy calls (via `invoke_capability`) are not subject to this list — they route through Convex, not the sandbox's network stack. |
| `capabilities` | Platform capabilities the procedure needs. Must include `file_hosting` if you call `put_file` or `get_file`. Must include the relevant capability domain if you call `invoke_capability`. |
| `inputs` / `outputs` | JSON Schema for the procedure's typed I/O contract. Fields with `format: fileId` are resolved by the executor before the sandbox starts. |
| `idempotent` | `true` if the procedure can safely be retried. |
| `deterministic` | `true` if identical inputs always produce byte-identical outputs. Deterministic procedures can be used in eval replay. |

### Versioned accounting operation contracts

Accounting procedures may declare an `operationContract` when they implement a portable business operation through a vendor-specific client. The shared operation id and version describe what the procedure does; the binding records how this implementation reaches the vendor:

```yaml theme={null}
apiIntegrations:
  - vendorKey: sage_intacct
    connectionName: xml

operationContract:
  operationId: fetch-ar-aging
  version: 1.0.0
  binding:
    vendorKey: sage_intacct
    connectionName: xml
    client: intacct_xml
    operation: fetch_ar_aging
    documentedParameters: [locationid, ASOFDATE]
```

The initial accounting vocabulary defines `fetch-ar-aging`, `fetch-ap-aging`, and `fetch-gl-detail`. All three return only `rows: array<object>`; the aging operations also require `asOfDate` in `MM/DD/YYYY` form. A string description may annotate `rows`, but a manifest cannot add another output, constrain the row objects, or change the shared shape.

The binding's `vendorKey` and `connectionName` must exactly match one entry of `apiIntegrations`. That entry is the procedure's primary Connection; any other entries are auxiliary Connections the procedure also calls. Vendor-only inputs remain valid outside the portable contract—for example, an Intacct location identifier can accompany `asOfDate` without becoming part of every vendor implementation. Change the shared version when portable inputs or outputs change; do not silently redefine an existing version in a vendor manifest.

### Several Connections

`apiIntegrations` is an ordered list: one entry per vendor Connection the procedure calls, including two Connections on one vendor. A target (`vendorKey/connectionName`) may appear only once. Each Connection resolves its own Credential, which is bound to that Connection's host alone. The sandbox receives each Connection's values under its own namespace:

| Value | Environment variable |
| - | - |
| Rendered base URL | `GLOO_CONN_<VENDOR>__<CONNECTION>__API_BASE_URL` |
| Out-of-band credential field | `GLOO_CONN_<VENDOR>__<CONNECTION>__CRED_<FIELD>` |

`<VENDOR>` and `<CONNECTION>` are the `vendorKey` and `connectionName` in upper case, with each run of other characters replaced by one `_`. For example, `sage_intacct/xml` becomes `GLOO_CONN_SAGE_INTACCT__XML__API_BASE_URL`. There is no flat `GLOO_API_BASE_URL`. The connection clients read their own names, so prefer them over reading the variables directly.

### Prefer the connection client

Protocol behavior belongs to the engineered client for the Procedure's exact `(vendorKey, connectionName)` target. The client owns credential consumption, base URL and wire construction, pagination or polling, bounded retry, vendor error mapping, and response normalization. The Procedure owns the business operation: it maps typed Procedure inputs into a client method and maps that result into the manifest's output contract.

Before writing a direct HTTP or XML request:

1. Inspect the connection with the Builder's read-only `getConnectionClient` tool. For a client with resource families, start with its compact core-family index and search it with the requested accounting or operational terminology.
2. Follow family → exact operation → referenced type: inspect the most relevant family, choose a returned public operation, then read only the referenced types needed for its filters and result mapping. Use `get`/`read_one` for a known vendor key, `page`/`read_page` for one bounded batch or resumable checkpoint, and `iter`/`read_stream` for a bounded multi-page traversal.
3. Search with `includeExtended: true` only when core lacks the required grain. Core and extended affect discovery order only; they do not authorize a call or prove that an operation satisfies the Procedure. Use `path: []` only when explicit complete API browsing is necessary.
4. Retrieve the current generated contracts rather than copying operation signatures, schemas, or inventories into Procedure guidance. Use the selected operation's exact `pythonUsage` and `requiredPackages`; unlisted methods are private and must not be called.
5. If no client contract exists, preserve the grounded raw vendor fallback. If a contract exists but lacks the operation, fall back only when its `authoringFallbackPolicy` is `raw_allowed`; a `client_only` gap is client backlog. Keep vendor documentation as the grounding source for any raw fallback.

The generated catalog joins an explicit public-operation allowlist to signatures and annotations extracted from bundled Python source. Generation rejects missing or malformed public operations and rejects a builtin `operationContract` whose client module or allowlisted operation is absent.

In Forge Console, open a Vendor's connection row and select **Client** to inspect the same contract. **Operations** leads with friendly supported business actions and copyable Python usage. **Implementation** shows the authorized technical metadata and owned runtime files/tests. This surface is read-only and never includes credentials, environment values, or authenticated request captures.

### Sage Intacct REST read workflows

For `sage_intacct/oauth2`, start with core family discovery, inspect an exact selected family, then inspect a returned `typeName` only when you need its fields. Search extended families only when core lacks the required grain; use `path: []` only for explicit complete API browsing. This catalog is `client_only`: use the public `IntacctRestClient` surface and put a missing primitive on the connection-client backlog. Do not author raw Common Resources Query calls, configuration/admin access, mutations, or direct REST report requests.

The examples below are copy-ready operation bodies. They keep pagination bounded, follow only explicit related keys, and persist the records with the opaque checkpoint. The Procedure—not the client—owns selection and interpretation.
The workflow graph should pass typed dates, checkpoints, and file IDs and route the resulting file; it should not embed Sage field knowledge or accounting decisions.

#### Journal → source and lines

```python theme={null}
import json
from gloo_connection_clients import IntacctRestClient
from gloo_procedure_sdk import put_file

async def run(inputs):
    client = IntacctRestClient.from_environment()
    page = client.general_ledger.journal_entries.page(
        filters={"txn_sources": tuple(inputs["txnSources"])},
        checkpoint=inputs.get("checkpoint"),
        page_size=100,
    )
    records = []
    for summary in page["items"]:
        entry = client.general_ledger.journal_entries.get(key=summary["key"])
        lines = [
            client.general_ledger.journal_entry_lines.get(key=ref["key"])
            for ref in entry.get("lines", [])
        ]
        records.append({"entry": entry, "sourceId": entry["glJournal"]["id"], "lines": lines})
    saved = await put_file(
        source={"kind": "inline", "text": json.dumps({"records": records, "nextCheckpoint": page["next_checkpoint"]}), "contentType": "application/json", "filename": "journal-source.json"},
        bind={"kind": "workflow_output", "outputKey": "resultFile"},
    )
    return {"resultFile": saved["fileId"], "nextCheckpoint": page["next_checkpoint"]}
```

#### Vendor bills → payments and applications

```python theme={null}
import json
from gloo_connection_clients import IntacctRestClient
from gloo_procedure_sdk import put_file

async def run(inputs):
    client = IntacctRestClient.from_environment()
    bills_done = bool(inputs.get("billsComplete"))
    payments_done = bool(inputs.get("paymentsComplete"))
    bills_page = None if bills_done else client.accounts_payable.bills.page(
        filters={"posting_date_from": inputs["fromDate"], "posting_date_through": inputs["throughDate"]},
        checkpoint=inputs.get("billsCheckpoint"), page_size=100,
    )
    payments_page = None if payments_done else client.accounts_payable.payments.page(
        filters={"payment_date_from": inputs["fromDate"], "payment_date_through": inputs["throughDate"]},
        checkpoint=inputs.get("paymentsCheckpoint"), page_size=100,
    )
    bills = [client.accounts_payable.bills.get(key=row["key"]) for row in ([] if bills_page is None else bills_page["items"])]
    payments = [client.accounts_payable.payments.get(key=row["key"]) for row in ([] if payments_page is None else payments_page["items"])]
    applications = [
        client.accounts_payable.payment_details.get(key=ref["key"])
        for payment in payments for ref in payment.get("details", [])
    ]
    checkpoints = {"bills": None if bills_page is None else bills_page["next_checkpoint"],
                   "payments": None if payments_page is None else payments_page["next_checkpoint"]}
    complete = {"bills": bills_done or checkpoints["bills"] is None,
                "payments": payments_done or checkpoints["payments"] is None}
    payload = {"bills": bills, "payments": payments, "applications": applications,
               "checkpoints": checkpoints, "complete": complete}
    saved = await put_file(
        source={"kind": "inline", "text": json.dumps(payload), "contentType": "application/json", "filename": "vendor-bills-payments.json"},
        bind={"kind": "workflow_output", "outputKey": "resultFile"},
    )
    return {"resultFile": saved["fileId"], "checkpoints": checkpoints, "complete": complete}
```

#### Customer invoices → receipts and applications

```python theme={null}
import json
from gloo_connection_clients import IntacctRestClient
from gloo_procedure_sdk import put_file

async def run(inputs):
    client = IntacctRestClient.from_environment()
    invoices_done = bool(inputs.get("invoicesComplete"))
    receipts_done = bool(inputs.get("receiptsComplete"))
    invoices_page = None if invoices_done else client.accounts_receivable.invoices.page(
        filters={"invoice_date_from": inputs["fromDate"], "invoice_date_through": inputs["throughDate"]},
        checkpoint=inputs.get("invoicesCheckpoint"), page_size=100,
    )
    receipts_page = None if receipts_done else client.accounts_receivable.payments.page(
        filters={"paid_date_from": inputs["fromDate"], "paid_date_through": inputs["throughDate"]},
        checkpoint=inputs.get("receiptsCheckpoint"), page_size=100,
    )
    invoices = [client.accounts_receivable.invoices.get(key=row["key"]) for row in ([] if invoices_page is None else invoices_page["items"])]
    receipts = [client.accounts_receivable.payments.get(key=row["key"]) for row in ([] if receipts_page is None else receipts_page["items"])]
    applications = [
        client.accounts_receivable.payment_details.get(key=ref["key"])
        for receipt in receipts for ref in receipt.get("paymentDetails", [])
    ]
    checkpoints = {"invoices": None if invoices_page is None else invoices_page["next_checkpoint"],
                   "receipts": None if receipts_page is None else receipts_page["next_checkpoint"]}
    complete = {"invoices": invoices_done or checkpoints["invoices"] is None,
                "receipts": receipts_done or checkpoints["receipts"] is None}
    payload = {"invoices": invoices, "receipts": receipts, "applications": applications,
               "checkpoints": checkpoints, "complete": complete}
    saved = await put_file(
        source={"kind": "inline", "text": json.dumps(payload), "contentType": "application/json", "filename": "customer-invoices-receipts.json"},
        bind={"kind": "workflow_output", "outputKey": "resultFile"},
    )
    return {"resultFile": saved["fileId"], "checkpoints": checkpoints, "complete": complete}
```

#### Unreconciled bank transactions

```python theme={null}
import json
from gloo_connection_clients import IntacctRestClient
from gloo_procedure_sdk import put_file

async def run(inputs):
    client = IntacctRestClient.from_environment()
    page = client.cash_management.bank_transactions.page(
        filters={"posting_date_from": inputs["fromDate"], "posting_date_through": inputs["throughDate"]},
        checkpoint=inputs.get("checkpoint"), page_size=100,
    )
    records = [client.cash_management.bank_transactions.get(key=row["key"]) for row in page["items"]]
    # This documented-field interpretation belongs to the Procedure, not the client.
    unreconciled = [r for r in records if r.get("reconciliationInformation", {}).get("status") == "unmatched"]
    source_batches = [client.cash_management.bank_feeds.get(key=r["bankFeed"]["key"])
                      for r in unreconciled if r.get("bankFeed", {}).get("key")]
    payload = {"transactions": unreconciled, "sourceBatches": source_batches, "nextCheckpoint": page["next_checkpoint"]}
    saved = await put_file(
        source={"kind": "inline", "text": json.dumps(payload), "contentType": "application/json", "filename": "unreconciled-bank-transactions.json"},
        bind={"kind": "workflow_output", "outputKey": "resultFile"},
    )
    return {"resultFile": saved["fileId"], "nextCheckpoint": page["next_checkpoint"]}
```

These are REST object reads. The standard REST GL Details report remains the dedicated `iter_gl_detail_rows` operation. AR/AP aging and Custom Report Writer workflows use the separate `sage_intacct/xml` connection; do not reconstruct them from REST objects.

***

## SDK primitives

Install the SDK:

```bash theme={null}
pip install gloo-procedure-sdk
```

All SDK calls are `async`. The entry point receives a context object from the SDK runtime:

```python theme={null}
# procedure.py
from gloo_procedure_sdk import ProcedureContext

async def run(ctx: ProcedureContext) -> dict:
    # ctx.inputs   — resolved inputs from the manifest
    # ctx.session  — platform session token (managed by SDK, not for direct use)
    ...
    return { "outputFile": file_id, "count": 42 }
```

### `put_file` — write a file to platform storage

Writes content to platform storage and returns a `fileId`. The `bind` parameter tells the executor what scope to attach the file to.

```python theme={null}
from gloo_procedure_sdk import put_file

# Inline text
file_id = await put_file(
    ctx,
    source={"kind": "inline", "text": "hello", "contentType": "text/plain"},
    bind={"kind": "workflow_output", "outputName": "summary"},
)

# Inline binary (bytes are base64-encoded automatically)
file_id = await put_file(
    ctx,
    source={"kind": "inline", "bytes": my_bytes, "contentType": "application/pdf", "filename": "report.pdf"},
    bind={"kind": "workflow_output", "outputName": "report"},
)

# Server-rendered output (e.g. markdown-to-PDF)
file_id = await put_file(
    ctx,
    source={"kind": "render", "renderer": "markdown-to-pdf", "args": {"title": "Q3 Report"}},
    bind={"kind": "workflow_output", "outputName": "report"},
)
```

**`source` variants:**

| `kind` | Fields | Description |
| - | - | - |
| `"inline"` | `text` (str) **or** `bytes` (bytes), `contentType` (str), `filename` (str, optional) | Raw content. Pass `text` for UTF-8 strings; pass `bytes` for binary. The SDK handles encoding. |
| `"render"` | `renderer` (str), `args` (dict) | Platform-rendered output. The renderer name must be registered on the deployment. Pass `filename` as a top-level `put_file` kwarg, not inside `source`. |

**`bind` variants:**

| `kind` | Additional fields | Scope |
| - | - | - |
| `"workflow_output"` | `outputName` (str) | Attaches to the named output of the current workflow node. Required for files declared in `outputs:`. |
| `"run_scratch"` | — | Scoped to the current workflow run. Useful for intermediate files not declared as outputs. |
| `"worker_scope"` | — | Scoped to the current worker (agent). Persists across runs. |
| `"chat_attachment"` | — | Attaches to the current chat session. |

### `invoke_capability` — call a platform capability

Calls a capability registered on the deployment and returns the result. The capability proxy routes the call to the active provider (e.g. Linear for `project_management`).

```python theme={null}
from gloo_procedure_sdk import invoke_capability

issues = await invoke_capability(
    "project_management",
    "listTasks",
    {"filter": {"completedAt": {"gte": "2026-04-01"}}},
)
```

| Parameter | Type | Description |
| - | - | - |
| `capabilityDomain` | str | The capability domain (one of the platform's registered [capability domains](https://docs.gloo.com/forge/concepts/capabilities.md)). |
| `operation` | str | Operation name within the domain (e.g. `"listTasks"`, `"getProject"`). |
| `args` | dict | Operation-specific arguments. |

The procedure must declare the capability domain in its `forge.yaml` under `capabilities:`. Calls to undeclared capabilities are rejected at executor preflight.

### `get_file` — read a file from platform storage

Reads a file that was passed as an input to the procedure.

```python theme={null}
from gloo_procedure_sdk import get_file

# Read as text
content = await get_file(inputs["inputFile"], "text")

# Copy into the sandbox VM filesystem (useful for processing with CLI tools)
await get_file(inputs["inputFile"], "sandbox", dest_path="/tmp/input.json")

# Read raw bytes when the file is small enough for an inline response
payload = await get_file(inputs["inputFile"], "bytes")
```

| `mode` | Returns | Use when |
| - | - | - |
| `"text"` | `str` | Content fits in memory and you need to process it in Python. |
| `"sandbox"` | None (side effect: file written to `dest_path`) | You need to pass the file to a CLI tool or process it on disk. |
| `"bytes"` / `"stream"` | `dict` carrying raw bytes | The binary fits within the response path. |

### `emit_progress` — stream progress to the operator UI

Sends a progress update visible in the Forge Console while the procedure runs.

```python theme={null}
from gloo_procedure_sdk import emit_progress

emit_progress("Paginating issues...", fraction=0.3)
```

`fraction` is a float between 0.0 and 1.0. The console renders it as a progress bar. Call it periodically during long-running loops.

### `run_procedure` — chain into another Procedure

Invokes another procedure from within the current sandbox run. The child procedure runs synchronously and its outputs are available as the return value.

```python theme={null}
from gloo_procedure_sdk import run_procedure

result = await run_procedure(
    ctx,
    procedure_id="core-filter-by-date-range",
    version="0.1.0",
    inputs={
        "inputFile": issues_file_id,
        "dateField": "completedAt",
        "from": "2026-04-01T00:00:00Z",
        "to": "2026-04-30T23:59:59Z",
    },
)
filtered_file_id = result["outputFile"]
```

***

## Wire shapes and generated TypedDicts

The SDK's wire shapes are **canonically defined** once on the platform as Zod schemas. The SDK's Python TypedDicts in `gloo_procedure_sdk._generated.procedure_wire` are generated from those schemas, and a freshness check fails any change that leaves them stale, so the SDK and the platform validator cannot drift.

You can import the generated types for static analysis:

```python theme={null}
from gloo_procedure_sdk._generated.procedure_wire import (
    ProcedurePutFileBody,
    ProcedurePutFileBody_source,
    ProcedureInvokeCapabilityBody,
)
```

The canonical wire shapes (what the platform's Convex executor actually validates):

```python theme={null}
# Inline source — canonical shape
{
    "source": {
        "kind": "inline",
        "content": "hello",           # SDK translates text= / bytes= to content=
        "encoding": "utf8",           # "utf8" for text, "base64" for binary
        "contentType": "text/plain",
    },
    "bind": { "kind": "workflow_output", "outputName": "summary" },
    "mimeType": "text/plain",         # optional top-level override
    "filename": "output.txt",         # optional
}

# Render source — canonical shape
{
    "source": {
        "kind": "render",
        "renderer": "markdown-to-pdf",
        "args": { "title": "Q3 Report" },
    },
    "bind": { "kind": "workflow_output", "outputName": "report" },
}

# invoke_capability — canonical shape
{
    "capabilityDomain": "project_management",
    "operation": "listTasks",
    "args": { "filter": {} },
}
```

Python kwargs vs wire shape

The `put_file` Python surface uses `text=` and `bytes=` kwargs for ergonomics. The SDK translates these to `content` + `encoding` at the wire level before the HTTP call. You never write the wire shape directly — that's the SDK's job. The TypedDicts document the contract between the SDK and the platform, not the API you write against.

***

## File bindings in workflow graphs

When a procedure declares a file output in `forge.yaml`, the workflow graph editor exposes it as a typed `file` binding. Downstream nodes can reference the output by name:

```yaml theme={null}
nodes:
  - id: paginate
    type: procedure
    procedureId: linear-paginate-issues
    version: 1.1.0
    inputs:
      period: "2026-04"
    outputs:
      pagesFile: file          # declared in forge.yaml outputs

  - id: filter
    type: procedure
    procedureId: core-filter-by-date-range
    version: 0.1.0
    inputs:
      inputFile: { from: paginate.pagesFile }    # binding
      dateField: "completedAt"
      from: "2026-04-01T00:00:00Z"
      to: "2026-04-30T23:59:59Z"
    outputs:
      outputFile: file
```

The executor resolves `paginate.pagesFile` to a platform `fileId` before spawning the `filter` sandbox. The procedure receives it in `ctx.inputs["inputFile"]` as an opaque string.

***

## Built-in Procedures

Twelve procedures ship with the platform. They are the reference implementations for the patterns described in this guide.

| Procedure | What it does | Capabilities |
| - | - | - |
| [`core-filter-by-date-range`](https://docs.gloo.com/forge/build/built-in-procedures#core-filter-by-date-range) | Filter a JSON array by a date field within `[from, to]` | `file_hosting` |
| [`core-parse-csv`](https://docs.gloo.com/forge/build/built-in-procedures#core-parse-csv) | Convert a CSV file to a JSON array with typed fields | `file_hosting` |
| [`core-build-xlsx-workbook`](https://docs.gloo.com/forge/build/built-in-procedures#core-build-xlsx-workbook) | Build a multi-sheet Excel workbook from JSON data | `file_hosting` |
| [`linear-paginate-issues`](https://docs.gloo.com/forge/build/built-in-procedures#linear-paginate-issues) | Exhaustively paginate Linear issues across all teams | `file_hosting` |
| `core-clean-records` | Normalize whitespace and casing across a JSON record array | `file_hosting` |
| `core-classify-records-by-labels` | Assign label tags to records using a classifier | `file_hosting` |
| `core-audit-missing-fields` | Report which required fields are absent across a record set | `file_hosting` |
| `core-shape-capitalization-sheets` | Produce a capitalization table from structured input | `file_hosting` |
| `core-load-sanitized-intercompany-reports` | Load the bounded sanitized source-report fixture set | `file_hosting` |
| `core-reconcile-sanitized-intercompany-balances` | Reconcile sanitized intercompany balances for a reporting period | `file_hosting` |
| `core-assemble-intercompany-decision-packet` | Assemble an already-calculated human decision packet | None |
| `core-file-transport-roundtrip` | Verify brokered and direct large-file transport end to end | `file_hosting` |

***

## Test a procedure

`gloo_procedure_sdk` is preinstalled in the procedure sandbox. It is not published as a package for
your own machine, and it has no mock context, so test a procedure in two places:

1. **Its logic, locally.** Keep the work that turns inputs into outputs in plain Python functions
   that take and return ordinary values, and unit-test those with `pytest`. Leave the SDK calls
   (`get_file`, `put_file`, `invoke_capability`) in a thin `run` that calls them.
2. **The whole procedure, in Forge.** Build or refine it with Procedure Builder (**Platform →
   Procedures**). A version publishes only after it finalizes, passes validation in the sandbox and
   passes the judge, so the SDK calls are exercised against the platform before anything can call
   the procedure. With `procedures:write`,
   `GET /api/v3/procedures/{procedureId}/latest-validation-run?version={version}` reads the latest
   validation run of that version.

***

## What to double-check before shipping

* **`capabilities:` in `forge.yaml` matches every SDK call.** If you call `invoke_capability` with `capabilityDomain: "project_management"`, `project_management` must be in the manifest's `capabilities` list. Missing entries are caught at executor preflight, not at author time.
* **`egressAllowlist` is tight.** Add only the hostnames your procedure actually calls. Capability proxy calls (`invoke_capability`) do not leave the sandbox network — they route through Convex — and should not appear in the allowlist.
* **`bind.kind` matches the declared output.** Files declared in `outputs:` must use `bind: { kind: "workflow_output", outputName: "..." }` where `outputName` exactly matches the key in `outputs.properties`. Mismatches produce silent output-binding failures.
* **`idempotent: true` is accurate.** The executor may retry a procedure run on transient failures. If your procedure has side effects that should not repeat, set `idempotent: false`.

***

## Do it over the API

Writing a Procedure is source work; there is no API call that authors one. Once its version is in the catalog, these reads confirm what the platform registered. They use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). The quickstart's `ACCESS_TOKEN` does not carry every scope they need, so mint it again with `scope=procedures:read` from an app whose roles hold them (see [Requesting scopes at token mint](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) whose scopes include them.

Read the version's catalog entry and check that its capabilities, idempotency and exposure match the manifest:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/procedures/$PROCEDURE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {procedureId, version, status, runtime, capabilities, idempotent, deterministic, exposedAs}'
```

Add `?version=<semver>` to read a version other than the default. To see every version of the family, newest first, with its status and dispatch count:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/procedures/$PROCEDURE_ID/versions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {version, status, isLatestActive, versionDispatches}'
```

Both reads need `procedures:read`. Procedures are homed at the deployment root, so a credential whose grants cover only org units below the root sees none of them, and a missing Procedure and one you may not read both answer `404`. Source code and bundled files are never returned.

Over MCP, `forge_call_read_operation` reads the same entry. It is in the default `start` job:

```json theme={null}
{ "operationId": "getProcedure", "input": { "procedureId": "core-filter-by-date-range" } }
```

***

## See also

* [Configure Sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md) — sandbox resource limits, base images, and snapshot strategy
* [Compose a workflow](https://docs.gloo.com/forge/build/compose-a-workflow.md) — wire procedure nodes into workflow graphs
* [core-filter-by-date-range](https://docs.gloo.com/forge/build/built-in-procedures.md#core-filter-by-date-range) · [linear-paginate-issues](https://docs.gloo.com/forge/build/built-in-procedures.md#linear-paginate-issues) · [core-build-xlsx-workbook](https://docs.gloo.com/forge/build/built-in-procedures.md#core-build-xlsx-workbook) — built-in procedure reference pages


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.