updateReport

mutation · in the family Report

What it does

Rename a saved report, change what it is for, or replace its spec wholesale — the words and family re-derive.

Edit a Report's mutable attributes. Requires the unrestricted capability + the record's CURRENT revision.

What happens

An ordinary edit.

Who may call it

Capability area: Work and notes — Tasks, notes, messages, dashboards and the everyday tools every staff member keeps.

Owner
System Administrator
Manager
Associate Manager
Warehouse Associate
Sales Associate
Cashier
An API key whose scope allows api:updateReport

Arguments

Name	Type	Required	Notes
`id`	ID `ID!`	yes	The id of the record.
`revision`	ID `ID!`	yes	The revision id you read on the record; the change is refused if an edit landed in the meantime.
`input`	EditReportInput `EditReportInput!`	yes	No further notes.

Returns

Report Report! — A Report (📊; THE REPORT ENGINE, program 3 of THE OFFICE FIX PROGRAM 2): a SAVED REPORT DEFINITION — a validated ReportSpec (the reportRun grammar VERBATIM: a plan + columns, or a plan + groupBy/measures, an optional sort) kept as JSON text (specJson, at most 12288 characters) with its words (describeReport, at most 4096 characters) and the family its rows or groups are made of (terminalFamily). It stores NO result: every run executes as THE RUNNER under the runner's own list rights through reportRun(reportId) (rows on screen, now) or startExportJob(reportId, format) (a file, in the background); the saved spec is RE-VALIDATED at every run (a roster that moved since the save refuses in the teaching voice — edit the spec); only an active definition runs. The definition is the question, never an answer. NOT searchable (no filter roster until the report builder lands).

Example request

mutation ExampleUpdateReport($id: ID!, $revision: ID!, $input: EditReportInput!) {
  updateReport(id: $id, revision: $revision, input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    specJson
    words
    terminalFamily
    description
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "input": {
    "caption": "Blue jeans"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "updateReport": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "RO-EXMP-0000-000F",
      "type": "Report",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "specJson": "<spec json>",
      "words": "<words>",
      "terminalFamily": "<terminal family>",
      "description": "Straight-cut, mid-rise, five pockets."
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer

VALIDATION/INVALID — Something in the request is not valid. (VALIDATION)
AUTHN/REQUIRED — Sign in to do this. (AUTHN)
AUTHZ/FORBIDDEN — Your role does not allow this action. (AUTHZ)
RATE_LIMIT/THROTTLED — Too many requests in a short time. (RATE_LIMIT)
NOT_FOUND/* — That record could not be found. (NOT_FOUND)
CONFLICT/* — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. (CONFLICT)
VALIDATION/VERSION_REQUIRED — The request did not say which app version it came from. (VALIDATION)

Dry run

Add dryRun: true to the request envelope (extensions.at) to rehearse this call: every check runs, the write is rehearsed against the current records and nothing is stored; the answer is the refusal a real call would give, or the record it would create. Every response to a rehearsal carries dryRun: true, so a rehearsed record is never mistaken for a saved one.