Report response formats

There are two response levels: raw HTTP responses from the Agent API and the objects assembled by its JavaScript helpers. Field names are case-sensitive. The examples below illustrate structure; report IDs, parameters, columns, and values depend on your report.

HTTP query envelopes

Information Query returns an envelope:

{
  "ok": true,
  "Stanza": {
    "nodeInfos": {
      "nodeInfo": {
        "id": "Client Reports\\Monthly usage.rpx",
        "parentId": "Client Reports",
        "hasCommands": "true",
        "hasChildren": "false"
      }
    }
  }
}

This discovery example omits XML metadata and other node attributes. Always inspect ok, even after HTTP success. Failed queries can include errorText, errorType, errorCode, and ErrorElement. XML is represented as JSON using these conventions:

Representation	Meaning
`__name`, `__ns`	XML element name and namespace.
Named properties such as `field`	Child elements. One child is an object; repeated children are an array. A missing child can be absent.
`value`	Text content. A `<value>` child can itself have a `value` text property.
Attribute properties	Usually strings, including values such as `"true"`, `"false"`, and sequence numbers.
`__ordered`	Ordered child elements when different child names occur together. Use this to preserve mixed table-cell order.

Normalize absent, single, and repeated elements before iteration:

const asArray = value => value == null ? [] : Array.isArray(value) ? value : [value];

The GetReports helper reduces the matching report nodes to a string array. The raw HTTP envelope is not itself that array.

Parameter forms

Parameter retrieval returns an XMPP data form in Stanza.x. The JavaScript helper returns that form directly. Illustrative form, with XML metadata omitted:

{
  "type": "form",
  "title": { "value": "Monthly usage" },
  "field": [
    {
      "var": "Month",
      "type": "text-single",
      "label": "Month",
      "desc": { "value": "Month to include, in YYYY-MM format." },
      "required": {},
      "value": { "value": "2026-08" }
    },
    {
      "var": "Format",
      "type": "list-single",
      "label": "Format",
      "value": { "value": "summary" },
      "option": [
        { "label": "Summary", "value": { "value": "summary" } },
        { "label": "Details", "value": { "value": "details" } }
      ]
    }
  ]
}

Field property	How to use it
`var`	Exact submission key. Do not replace it with the displayed label.
`type`	Input type, such as `text-single`, `boolean`, `list-single`, `list-multi`, `hidden`, or `fixed`.
`label`, `desc`	Text for the person supplying parameters.
`required`	Presence of this element marks a required field. It need not be a JSON boolean.
`value`	Default or supplied value, normally nested as `{ "value": "text" }`. Repeated values can be an array.
`option`	Allowed options; submit their values rather than their display labels.

Honor any validation information in the form. Do not assume every report accepts dates, the same date format, or the same field names. Preserve hidden fields. Fixed fields describe the form rather than requesting user input. An actual empty form can be submitted with no fields; a missing form should be investigated.

Assembled JavaScript results

ExecuteReport returns a completed query record assembled from progress events. This illustrative result contains one section and one table. A report can contain multiple tables, nested sections, and generated objects.

{
  "Sections": [
    {
      "Type": "Section",
      "Header": "Usage",
      "Items": [
        {
          "Type": "Table",
          "Id": "usage",
          "Name": "Monthly usage",
          "Columns": [
            { "Id": "month", "Header": "Month" },
            { "Id": "total", "Header": "Total", "NrDecimals": "2" }
          ],
          "Records": [
            ["2026-08", { "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }]
          ],
          "Done": true
        }
      ]
    }
  ],
  "Objects": [],
  "Tables": {
    "usage": {
      "Type": "Table",
      "Id": "usage",
      "Name": "Monthly usage",
      "Columns": [
        { "Id": "month", "Header": "Month" },
        { "Id": "total", "Header": "Total", "NrDecimals": "2" }
      ],
      "Records": [
        ["2026-08", { "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }]
      ],
      "Done": true
    }
  },
  "Ok": true,
  "Errors": [],
  "HasErrors": false,
  "Started": true,
  "Done": true,
  "Title": "Monthly usage"
}

Property	Meaning
`Tables`	Object keyed by table ID, not an array. Iterate with `Object.values(result.Tables)`.
`Sections`	Hierarchical presentation. Sections have `Type: "Section"`, `Header`, and `Items`.
`Objects`	Generated objects with `Type: "Object"`, `ContentType`, and `Base64`.
`Title`	Report title, if supplied.
`Started`, `Done`	Execution lifecycle flags. `Done` alone does not distinguish successful completion from an abort.
`HasErrors`, `Errors`	Errors recorded by the helper. An abort adds `"Aborted."`.
`Ok`	Initialized to true by the current helper. Do not use it alone to determine success.

Section Items can contain nested sections, tables, objects, and messages. A table can appear in a section and in Tables; these are two ways to access the same output, not two separate tables. Messages have Type: "Message", Level, and Text. Inspect their levels and text; they are not all copied into Errors. The helper removes Status when the query ends. Do not require it in a completed result. An HTTP execution acknowledgment never contains this assembled object.

Read tables and cells

Columns defines display order. Each entry in Records is a row array in that same order: Records[rowIndex][columnIndex] belongs to Columns[columnIndex]. Columns contain Id and may include Header, SourceId, Partition, ForegroundColor, BackgroundColor, Alignment, and NrDecimals. Do not assume a particular table ID, column count, or column name unless your provider defines that contract for your report.

Cell shape	Meaning
String or other scalar	Text or a scalar value. Numeric, date, and boolean XML values can remain strings.
`{ "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }`	Value with a unit.
`{ "Type": "Measurement", "Magnitude": "20.1", "Unit": "°C", "Error": "0.2" }`	Value, unit, and measurement error.
`{ "Type": "EncodedObject", "ContentType": "image/png", "Base64": "..." }`	Encoded content within a table cell.
Missing or null value	Empty cell. Preserve its position instead of shifting later cells.

For raw newRecords progress, cells retain their XML names, such as string, double, quantity, or measurement. Read record.__ordered when present; grouping by cell type would scramble column order. For quantities and measurements, the raw attributes are m (magnitude), u (unit), and e (measurement error). Convert values according to the report’s contract. Avoid converting large integers to JavaScript numbers if precision matters. Render labels and text as text. Decode objects according to an allowed content type rather than inserting arbitrary output as HTML.

Handle partial or failed results

Reject HTTP failures and Information Query responses with ok: false before consuming success data.
Wait for query completion, not just the first table or its Done flag.
Treat aborted queries, missing progress, and client deadlines as incomplete results.
Inspect helper HasErrors, Errors, and section messages before displaying a result as successful.

See Reports troubleshooting for the next check for each symptom.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Reports

HTTP query envelopes

Parameter forms

Assembled JavaScript results

Read tables and cells

Handle partial or failed results

​HTTP query envelopes

​Parameter forms

​Assembled JavaScript results

​Read tables and cells

​Handle partial or failed results

HTTP query envelopes

Parameter forms

Assembled JavaScript results

Read tables and cells

Handle partial or failed results