report.saveConfiguration

Save a report's options under a new name in red-ale's configuration.

Saves a report's options under a name, as GnuCash's Save Report Configuration does, so that you can run it again by that name. Only the options that differ from the template's defaults are stored. Saved configurations live in red-ale's Configuration, not in the book, and this works with no book open; an account you give by full name needs an open book to resolve, a GUID does not.

A name already taken is refused with conflict, where GnuCash appends a number. Run a saved configuration with report.run using its name or GUID.

Examples

Example: with no book.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.saveConfiguration","params":{"name":"March balance sheet","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"2024-03-31"}}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "name": "March balance sheet",
    "kind": "saved",
    "template": "c4173ac99b2b448289bf4d11c731af13",
    "inMenu": false,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"report.saveConfiguration","params":{"name":"March balance sheet","report":"Balance Sheet"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2003,
    "message": "a saved report configuration is already called \"March balance sheet\"",
    "data": {
      "kind": "configuration",
      "name": "March balance sheet",
      "help": "error/conflict"
    }
  }
}

Command line

red-ale exec --script - <<'EOF'
report.saveConfiguration {"name":"March balance sheet","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"2024-03-31"}}}}
report.saveConfiguration {"name":"March balance sheet","report":"Balance Sheet"}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2003,
    "message": "a saved report configuration is already called \"March balance sheet\"",
    "data": {
      "kind": "configuration",
      "name": "March balance sheet",
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"report.saveConfiguration","arguments":{"name":"March balance sheet","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"2024-03-31"}}}}}

Result:

{
  "structuredContent": {
    "guid": "…",
    "name": "March balance sheet",
    "kind": "saved",
    "template": "c4173ac99b2b448289bf4d11c731af13",
    "inMenu": false,
    "…": "…"
  }
}

Tool call:

{"name":"report.saveConfiguration","arguments":{"name":"March balance sheet","report":"Balance Sheet"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "a saved report configuration is already called \"March balance sheet\"",
      "data": {
        "kind": "configuration",
        "name": "March balance sheet",
        "help": "error/conflict"
      }
    }
  }
}

Effect: write, on the Configuration only.

Params

Params of report.saveConfiguration.

name (string, required): The new configuration's name, unique among saved configurations.
report (ReportRef, required): The report whose options to save: a template, or a saved configuration, whose template the new one then configures.
options (ReportOptions or null): Changes over the report's options before saving.

Result

A report template or saved report configuration, as report.list lists it.

guid (Guid, required): The template's GUID (GnuCash's, for a built-in report), or the saved configuration's.
name (string, required): The template's name, or the saved configuration's.
kind (ReportKind, required): builtin, user or saved.
template (Guid or null): For a saved configuration: the GUID of the template it configures.
script (string or null): The script defining the template: standard/balance-sheet.rhai, or ./ and a user script's path in the report directory. null for a saved configuration whose template is not loaded.
menuPath (array of string, required): GnuCash's menu path. Empty for a saved configuration, which GnuCash lists in its own dialog.
menuName (string or null): The menu entry when it differs from the name.
menuTip (string or null): The menu tip.
inMenu (boolean, required): Whether the template shows in menus; false for a saved configuration.
exportTypes (array of string, required): The exports offered besides HTML: ["csv"] for the net and category charts (report.exportCsv), and for a saved configuration of one.
readOnly (boolean): true for a built-in saved configuration (v0.6), which cannot be changed, renamed or deleted, only copied with report.saveConfiguration; absent otherwise.