> ## 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.

# Built-in procedures

> Reference for the procedures Forge ships: core-parse-csv, core-filter-by-date-range, core-build-xlsx-workbook and linear-paginate-issues — inputs, outputs, error codes and determinism.

This page documents four general-purpose built-in [procedures](https://docs.gloo.com/forge/concepts/procedures.md); Forge ships more, and you can see them all under **Platform → Procedures**. Each runs as deterministic code in a sandbox, reads and writes files through the `file_hosting` capability, and is exposed both as a workflow graph node and as an agent tool. Every procedure moves bulk data as files, so no agent has to hold a full record set in its context window.

| Procedure | What it does | Network egress | Deterministic |
| - | - | - | - |
| [`core-parse-csv`](#core-parse-csv) | Parses a CSV file against a typed schema. | None | Yes |
| [`core-filter-by-date-range`](#core-filter-by-date-range) | Keeps the records whose date field falls in a closed interval. | None | Yes |
| [`core-build-xlsx-workbook`](#core-build-xlsx-workbook) | Builds an Excel workbook from a typed sheets specification. | None | Yes |
| [`linear-paginate-issues`](#linear-paginate-issues) | Pages through every Linear team and filters issues to a month. | `api.linear.app` | No |

All four are idempotent: re-invoking one is safe. Workflow `router` nodes can branch on their error codes; `INVALID_INPUT` is almost always an authoring bug upstream and should fail fast rather than retry.

## Typical composition

A monthly engineering report chains the procedures with agents only where judgment is needed:

```text theme={null}
linear-paginate-issues
  ↓ ticketsFile
core-filter-by-date-range        ← only if the downstream agent needs a narrower window
  ↓ outputFile
classify (agent, low inference tier)   ← per-ticket category labels
  ↓ enrichedFile
core-build-xlsx-workbook
  ↓ workbookFile
compose-summary (agent, mid inference tier)
  ↓ summaryText
publish
```

Each step reads its input as a `file` and writes its output as a `file`. Token cost stays proportional to the records an agent actually needs to see, not the total count.

***

## core-parse-csv

`core-parse-csv` reads a CSV file, validates each row against a typed schema, and returns either inline records (up to 1,000 rows) or a file of records (above 1,000 rows).

| Field | Value |
| - | - |
| Runtime | Python, `procedure-base-python` image |
| Capabilities | `file_hosting` |
| Egress | None |
| Idempotent / deterministic | Yes / yes (apart from `fileId` strings in the file branch) |
| Errors | `INVALID_INPUT`, `SCHEMA_MISMATCH`, `INTERNAL_ERROR` |

### Inputs

| Field | Type | Required | Description |
| - | - | - | - |
| `inputFile` | `file` | Yes | The CSV file. UTF-8; a leading BOM is tolerated. CRLF and LF line endings are both accepted. |
| `schema` | `object` | Yes | Per-field type contract, keyed by CSV column header. |

Each `schema` value is a `{ type, required? }` descriptor:

```json theme={null}
{
  "name":   { "type": "string",  "required": true },
  "age":    { "type": "integer" },
  "active": { "type": "boolean" },
  "joined": { "type": "date", "required": true }
}
```

| Type | Accepts | Notes |
| - | - | - |
| `string` | Any string | No coercion. |
| `number` | Numeric literal | Integers and floats both become floats. |
| `integer` | Whole numbers | Floats with a non-zero fractional part are rejected. |
| `boolean` | `true` / `false` / `1` / `0` / `yes` / `no` / `y` / `n` / `t` / `f` | Case-insensitive. An empty cell is an error in a required field and `null` in an optional one. |
| `date` | `YYYY-MM-DD` or ISO 8601 datetime | Output keeps the input shape: dates stay dates, datetimes stay datetimes. |

`required` defaults to `false`. Columns in the CSV but absent from `schema` are dropped: `schema` is the authoritative list of fields that flow downstream.

### Outputs

The output shape depends on the parsed row count.

**Inline branch (1,000 records or fewer):**

```json theme={null}
{
  "records": [
    { "name": "Alice", "age": 30, "active": true, "joined": "2024-01-15" }
  ],
  "errors": []
}
```

**File branch (more than 1,000 records):**

```json theme={null}
{
  "recordsFile": "file_abc123",
  "recordCount": 5234,
  "errors": []
}
```

`recordsFile` is a JSON array of the same record shape. Inline records flow through workflow state and are cheap to consume; above about 1,000 records the payload would dominate the run's state, so the procedure switches to a file and the consumer that needs the data reads it.

### Row errors

`errors[]` is always present. Each entry describes one row-level validation failure:

```json theme={null}
{
  "rowNumber": 17,
  "field": "age",
  "message": "Value error, invalid literal for int() with base 10: 'thirty'"
}
```

* `rowNumber` is 1-indexed and counts the header as row 1, so the first data row is row 2.
* An empty `field` means a row-level failure, such as a required column missing from the header.
* Parsing **continues past row errors**; a bad row does not abort the run. Structural corruption, such as an embedded NUL byte, is a terminal `INVALID_INPUT`.
* `errors[]` is capped at 1,000 entries. When the cap is hit, the last entry is a sentinel with `rowNumber: -1`, for example `"additional 49000 validation error(s) omitted (cap=1000)"`.

### Error codes

| Code | When |
| - | - |
| `INVALID_INPUT` | Bad schema shape, missing or empty `inputFile`, or a structurally unparseable CSV. |
| `SCHEMA_MISMATCH` | The file capability returned an unexpected response shape. A platform problem, not an authoring error. |
| `INTERNAL_ERROR` | Unhandled exception; the message names the exception type. |

Row validation failures never raise; they accumulate in `errors[]`.

### Example

```yaml theme={null}
nodes:
  - id: parse-tickets
    type: procedure
    procedureId: core-parse-csv
    version: 1.0.0
    inputs:
      inputFile: "{{ steps.fetch-tickets.outputs.csvFile }}"
      schema:
        ticketId:    { type: integer, required: true }
        title:       { type: string,  required: true }
        priority:    { type: string }
        completedAt: { type: date }
```

The downstream node consumes `records` or `recordsFile` through the workflow's binding layer.

***

## core-filter-by-date-range

`core-filter-by-date-range` reads a JSON array of records and keeps the ones whose date field falls inside a closed `[from, to]` interval. Use it between a paginated source (Linear issues, Asana tasks, GitHub pull requests) and a step that only cares about one period.

| Field | Value |
| - | - |
| Runtime | Python, `procedure-base-python` image |
| Capabilities | `file_hosting` |
| Egress | None |
| Idempotent / deterministic | Yes / yes |
| Sandbox budget | 512 MB memory, 60 seconds |
| Errors | `INVALID_INPUT`, `SCHEMA_MISMATCH`, `INTERNAL_ERROR` |

### Inputs

| Field | Type | Required | Description |
| - | - | - | - |
| `inputFile` | fileId | Yes | A JSON file whose root is an **array of record objects**. |
| `dateField` | string | Yes | The field holding the date, for example `"completedAt"`. |
| `from` | string (ISO 8601) | Yes | Lower bound, **inclusive**. For example `2026-04-01T00:00:00Z` or `2026-04-01`. |
| `to` | string (ISO 8601) | Yes | Upper bound, **inclusive**. Must not be earlier than `from`. |

### Outputs

| Field | Type | Description |
| - | - | - |
| `outputFile` | fileId | A new file with the filtered JSON array, in the input file's mime type. |
| `matchedCount` | integer | Records inside the range. |
| `skippedCount` | integer | Records that could not be evaluated. |

Record order is preserved; the procedure filters, it does not sort.

### Skipped and filtered records

A record is **skipped** (counted in `skippedCount`) when it is not a JSON object, lacks the `dateField` key, or holds a value that is not a parseable ISO 8601 string. A record is **filtered out** (counted in neither) when its date is well-formed but outside the range. The input count minus `matchedCount + skippedCount` is the number of well-formed, out-of-range records.

### Time zones

Dates and bounds are parsed as ISO 8601 and normalized to UTC before comparison:

* A date such as `2026-04-15` is midnight UTC.
* A naive datetime such as `2026-04-15T12:00:00` is UTC.
* An aware datetime such as `2026-04-15T08:00:00-04:00` keeps its offset.

Arrays that mix time zones compare correctly.

### Size and determinism

The procedure loads the whole input into memory; there is no streaming path. The input, the decoded array and the serialized output must fit in 512 MB together, and the run must finish in 60 seconds. For larger inputs, split upstream. The filter is linear in record count.

Identical inputs produce byte-identical output: order is preserved, JSON is serialized without whitespace and without sorting keys, and the procedure reads no clock, random seed or network state. That makes it safe for runs that need replay equivalence, such as evals.

### Error codes

| Code | When |
| - | - |
| `INVALID_INPUT` | A required field is missing or the wrong type; `from` or `to` does not parse; `from` is later than `to`; the file is not valid JSON or not a JSON array. |
| `SCHEMA_MISMATCH` | The file capability returned an unexpected shape, for example no `fileId`. A platform problem, not an authoring error. |
| `INTERNAL_ERROR` | Anything else. |

### Example

Keep only the Linear issues completed in April 2026:

```yaml theme={null}
nodes:
  - id: paginate
    type: procedure
    procedureId: linear-paginate-issues
    version: 1.2.0
    inputs:
      period: "2026-04"
    outputs:
      ticketsFile: file
  - id: filter
    type: procedure
    procedureId: core-filter-by-date-range
    version: 0.1.0
    inputs:
      inputFile: { from: paginate.ticketsFile }
      dateField: "completedAt"
      from: "2026-04-01T00:00:00Z"
      to: "2026-04-30T23:59:59Z"
    outputs:
      outputFile: file
```

The executor resolves `paginate.ticketsFile` to a fileId before it starts the `filter` sandbox.

***

## core-build-xlsx-workbook

`core-build-xlsx-workbook` builds an `.xlsx` workbook from a JSON file of sheets. Use it whenever a downstream consumer — a report email, a Slack post, a human reviewer — needs a spreadsheet instead of inline records. It builds the workbook entirely in the sandbox, so compute time is its only cost.

| Field | Value |
| - | - |
| Runtime | Python 3.12, `procedure-base-python-data` image |
| Capabilities | `file_hosting` |
| Egress | None |
| Idempotent / deterministic | Yes / yes — identical inputs produce byte-identical workbooks |
| Errors | `INVALID_INPUT`, `INTERNAL_ERROR` |

### Inputs

The procedure takes one input, `sheetsFile`: the file ID of a JSON file that holds the ordered list
of sheets. Write the file with `file_put` (or take it from an upstream step) and pass its ID.

```yaml theme={null}
sheetsFile: file   # file ID of a JSON array of sheets
```

The file's content is an array; sheet order in the workbook matches array order:

```json theme={null}
[
  { "name": "Issues",  "columns": ["id", "title"],   "rows": [{ "id": 1, "title": "..." }] },
  { "name": "Summary", "columns": ["metric", "value"], "rows": [] }
]
```

* `name`: 1 to 31 characters, none of `\ / ? * [ ] :`, unique across the array.
* `columns`: the ordered header row.
* `rows`: records keyed by header name.

**Sheet names.** Excel reserves `\ / ? * [ ] :` in worksheet names and caps them at 31 characters. The procedure rejects a violating name with `INVALID_INPUT` rather than truncating it. Names are unique case-insensitively, as in Excel: `Issues` and `ISSUES` collide.

**Columns and rows.** Cells are written in `columns` order. Row keys not listed in `columns` are dropped, and missing keys produce empty cells: `columns` is the schema and `rows` is the data.

### Output

```yaml theme={null}
workbookFile:
  type: file
  mimeType: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
```

The workbook is bound as a workflow output under the key `workbookFile`. Downstream nodes (publish, email, chat attachment) reference its `fileId`; no raw bytes flow through workflow state.

### Formula injection prevention

A cell whose first character is `=`, `+`, `-`, `@`, or a leading tab, carriage return or line feed is treated as a formula by Excel, Google Sheets and LibreOffice when the cell type is unspecified. A malicious upstream value such as `=HYPERLINK(...)` can exfiltrate data, and in older Excel builds a crafted value can run a command when the file opens.

The CSV mitigation — prepending an apostrophe — does not work for XLSX: the apostrophe is written verbatim and shows up in the cell, corrupting values like phone numbers (`-555-1234`) and `@username` handles. Instead, the procedure forces every cell that starts with a dangerous prefix to the text type. Excel, Google Sheets and LibreOffice all render it as literal text, and the value is preserved exactly. Numbers, booleans, empty values and dates pass through unchanged, because they cannot be interpreted as formulas.

This addresses the threat model in the [OWASP CSV Injection](https://owasp.org/www-community/attacks/CSV_Injection) guidance, with the XLSX-specific mitigation.

### Column widths

Columns are sized to their longest displayed value, capped at 50 characters so one long cell does not stretch a column across the screen. If you need wider columns, split the field or post-process the file.

### Example: workflow node

```yaml theme={null}
- id: build-report
  type: procedure
  procedureId: core-build-xlsx-workbook
  version: 1.1.0
  inputs:
    sheetsFile: ${{ steps.summarise.outputs.sheetsFile }}
  outputs:
    workbookFile: workbookFile
```

The orchestrator validates the upstream binding against the procedure's input schema before it starts the sandbox; a mismatch surfaces as an `INVALID_INPUT` branch.

### Example: agent tool

Any agent whose permissions grant `file_hosting` and include this procedure can call it as a tool with a `sheetsFile` file ID. It returns a `fileId` the agent can pass to a publish or attachment tool:

```text theme={null}
build_xlsx_workbook({
  "sheetsFile": "file_sheets123"
})
→ { "workbookFile": "file_abc123" }
```

### Error codes

| Condition | Error code |
| - | - |
| `sheetsFile` is missing, or its content is not a non-empty JSON array | `INVALID_INPUT` |
| A sheet name breaks the length, reserved-character or uniqueness rules | `INVALID_INPUT` |
| `columns` is not a list of strings, or `rows` is not a list of objects | `INVALID_INPUT` |
| Writing the file through `file_hosting` fails | Propagated from the capability |
| Anything else | `INTERNAL_ERROR` |

***

## linear-paginate-issues

`linear-paginate-issues` pages through every team in a Linear workspace and keeps the issues whose date field falls in one calendar month, with no agent in the loop. An agent driving pagination itself can exhaust its step budget and stop early; this procedure keeps going until Linear says there are no more pages.

It is idempotent but **not deterministic**: the algorithm repeats exactly for the same Linear state, but live issues change between invocations, so cached results are not interchangeable.

### When to use it

Use it when:

* You need every issue across every team, not one team or one page.
* You filter by `completedAt`, `createdAt` or `updatedAt` within a calendar month.
* You want filtering done before any model sees the data, so token cost scales with the filtered count.

Use something else when:

* You query a single team once — call the `project_management` capability from an agent.
* You filter by a non-date field such as assignee, label or priority — author a filter procedure or do it in an agent.
* Your source is not Linear.

### Inputs

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `period` | string | Yes | — | Reporting month as `YYYY-MM`, in UTC. |
| `dateField` | string | No | `completedAt` | One of `completedAt`, `createdAt`, `updatedAt`. |
| `teamFilter` | string\[] | No | `[]` (all teams) | Optional allowlist of Linear team keys, for example `["ENG", "DESIGN"]`. |

A `teamFilter` key that does not exist in the workspace fails immediately with `INVALID_INPUT`; a typo would otherwise produce a silently empty report.

### Output

| Field | Type | Description |
| - | - | - |
| `ticketsFile` | file (`application/json`) | JSON array of normalized ticket objects. |

```json theme={null}
{
  "id": "issue-uuid",
  "identifier": "ENG-1234",
  "title": "Ship the thing",
  "url": "https://linear.app/issue/issue-uuid",
  "completedAt": "2026-04-15T18:22:01.000Z",
  "createdAt": "2026-03-02T09:11:00.000Z",
  "updatedAt": "2026-04-15T18:22:01.000Z",
  "priority": 2,
  "priorityLabel": "High",
  "estimate": 3.0,
  "labels": ["capitalizable"],
  "team":     { "id": "team-uuid", "key": "ENG", "name": "Engineering" },
  "state":    { "id": "state-uuid", "name": "Done", "type": "completed" },
  "assignee": { "id": "user-uuid",  "name": "Alice", "email": "alice@example.com" },
  "project":  { "id": "proj-uuid",  "name": "Q2 Platform" }
}
```

Assignee, project and state are resolved before the file is written, so a downstream agent needs no Linear access. **An archived assignee, project or state resolves to `null`**; the rest of the row stays intact.

### Termination

The loop stops **only** when Linear reports `pageInfo.hasNextPage == false`. A page on which the date filter rejected every issue does **not** stop it: Linear interleaves issues from many periods, so page 12 can still hold matches after an empty page 11.

```text theme={null}
for each team in workspace (filtered by teamFilter):
  cursor = None
  while True:
    page = paginateTeamIssues(teamId, after=cursor, first=100, ...)
    for issue in page.nodes:
      if periodStart <= issue[dateField] <= periodEnd:
        emit normalized(issue)
    if not page.pageInfo.hasNextPage:
      break               # ← only valid termination
    cursor = page.pageInfo.endCursor
```

### Date filter

Bounds are **inclusive on both ends**. For `period: "2026-04"` the window is `2026-04-01T00:00:00.000Z` to `2026-04-30T23:59:59.999Z` — the last millisecond of the month, not midnight, so an issue closed at 23:59:42 on the last day is included. Issues whose `dateField` is `null`, such as open issues filtered by `completedAt`, are excluded.

### Connection and authority

The procedure calls Linear GraphQL through the **`linear/api` vendor connection**. Forge's egress firewall injects the connection's Authorization header for `api.linear.app`; the procedure never reads a raw secret. Provision the connection at the scope the dispatch uses before invoking it. The procedure requires the `vendors:read` permission and uses `file_hosting` to write its output. Reading the resulting file still requires authority over its file binding.

### Error codes

| Code | When |
| - | - |
| `INVALID_INPUT` | `period` does not parse, `dateField` is not one of the allowed values, or `teamFilter` names an unknown team. |
| `RATE_LIMITED` | Linear still rate-limited the request after the retry budget. Backoff has jitter and honors a bounded `Retry-After`. |
| `AUTH_FAILED` | Linear rejected the connection's credentials. Never retried. |
| `SCHEMA_MISMATCH` | Linear reported `hasNextPage=true` without an `endCursor`, or a page was malformed. |
| `TIMEOUT` | An HTTP timeout or the execution budget expired. Inspect the failure stage, and narrow the team set if needed. |
| `INTERNAL_ERROR` | An unexpected failure. Keep the run and error evidence before retrying. |

### Resource profile

| Setting | Value |
| - | - |
| Image | `procedure-base-python-data` |
| Memory | 1,024 MB |
| Timeout | 600 seconds |
| Page size | 100 issues per request |
| Rate-limit retries | 5 attempts, exponential backoff with jitter (base 1.5 s, cap 30 s) |

Runtime and cost depend on team count, issue count, Linear latency, throttling and sandbox placement. Inspect the actual invocation rather than assuming a fixed time or cost.

***

## Related

* [Procedures](https://docs.gloo.com/forge/concepts/procedures.md) — what a procedure is and how it is governed
* [Author a procedure](https://docs.gloo.com/forge/build/author-a-procedure.md) — write your own
* [Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — how procedures pass files between steps


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