Method

book.setOptions

Set the num field source, the auto read-only threshold, trading accounts, the default budget, the business options or the default invoice report, as GnuCash's book options dialog does.

Changes any of the book's options; an option you leave out is left alone. autoReadOnlyDays (0 to 3650) makes transactions older than that many days read-only, as GnuCash's red line does, and the result's readOnlyThreshold is the date it works out to today. useTradingAccounts switches the book to trading accounts, which changes how transactions in several currencies are recorded.

Pitfall: once a threshold is set, posting a transaction dated before it is refused with invalid, and changing or deleting an existing one with conflict; both carry data.reason auto-read-only. Set it to 0 to lift it.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-07-01T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.setOptions","params":{"autoReadOnlyDays":30}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "splitActionForNum": false,
    "autoReadOnlyDays": 30,
    "readOnlyThreshold": "2024-06-01",
    "useTradingAccounts": false,
    "defaultBudget": null,
    "companyName": "",
    "companyAddress": "",
    "companyContactPerson": "",
    "companyPhoneNumber": "",
    "companyFaxNumber": "",
    "companyEmailAddress": "",
    "companyWebsiteUrl": "",
    "companyId": "",
    "taxNumber": "",
    "defaultInvoiceReport": null
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"transaction.post","params":{"datePosted":"2024-03-01","description":"Too old","splits":[{"account":"Root:Asset:Bank","value":"5.00"},{"account":"Root:Expenses","value":"-5.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "reason": "auto-read-only",
      "date": "2024-03-01",
      "threshold": "2024-06-01",
      "help": "error/invalid"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"transaction.delete","params":{"guid":"c0000000000000000000000000000000"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "reason": "auto-read-only",
      "date": "1970-01-01",
      "threshold": "2024-06-01",
      "help": "error/conflict"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
book.setOptions {"autoReadOnlyDays":30}
transaction.post {"datePosted":"2024-03-01","description":"Too old","splits":[{"account":"Root:Asset:Bank","value":"5.00"},{"account":"Root:Expenses","value":"-5.00"}]}
transaction.delete {"guid":"c0000000000000000000000000000000"}
EOF

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

{
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "reason": "auto-read-only",
      "date": "2024-03-01",
      "threshold": "2024-06-01",
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"book.setOptions","arguments":{"autoReadOnlyDays":30}}

Result:

{
  "structuredContent": {
    "splitActionForNum": false,
    "autoReadOnlyDays": 30,
    "readOnlyThreshold": "2024-06-01",
    "useTradingAccounts": false,
    "defaultBudget": null,
    "companyName": "",
    "companyAddress": "",
    "companyContactPerson": "",
    "companyPhoneNumber": "",
    "companyFaxNumber": "",
    "companyEmailAddress": "",
    "companyWebsiteUrl": "",
    "companyId": "",
    "taxNumber": "",
    "defaultInvoiceReport": null
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-03-01","description":"Too old","splits":[{"account":"Root:Asset:Bank","value":"5.00"},{"account":"Root:Expenses","value":"-5.00"}]}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "…",
      "data": {
        "reason": "auto-read-only",
        "date": "2024-03-01",
        "threshold": "2024-06-01",
        "help": "error/invalid"
      }
    }
  }
}

Tool call:

{"name":"transaction.delete","arguments":{"guid":"c0000000000000000000000000000000"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "…",
      "data": {
        "reason": "auto-read-only",
        "date": "1970-01-01",
        "threshold": "2024-06-01",
        "help": "error/conflict"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of book.setOptions; an absent option is left as it is.

  • splitActionForNum (boolean or null): Use the split action as the Number. Turning it on also sets the Book feature Number Field Source.
  • autoReadOnlyDays (integer (int64) or null): Days after which transactions become read-only: 0 (off) to 3650.
  • useTradingAccounts (boolean or null): Balance multi-commodity transactions through trading accounts. No existing transaction changes.
  • defaultBudget (Guid or null): The default budget: a budget of the book. It cannot be unset.
  • companyName (string or null): "Company Name"; "" clears it (v0.6).
  • companyAddress (string or null): "Company Address", lines separated by newlines (v0.6).
  • companyContactPerson (string or null): "Company Contact Person" (v0.6).
  • companyPhoneNumber (string or null): "Company Phone Number" (v0.6).
  • companyFaxNumber (string or null): "Company Fax Number" (v0.6).
  • companyEmailAddress (string or null): "Company Email Address" (v0.6).
  • companyWebsiteUrl (string or null): "Company Website URL" (v0.6).
  • companyId (string or null): "Company ID" (v0.6).
  • taxNumber (string or null): The Tax tab's "Tax Number" (v0.6).
  • defaultInvoiceReport (InvoiceReportParam or null): "Default Invoice Report": { guid, name }, or null to clear it (v0.6).

Result

The book options, as book.options and book.setOptions return them.

  • splitActionForNum (boolean, required): "Use Split Action Field for Number": a split's Number is its action, and the transaction's num is the T-Num.
  • autoReadOnlyDays (integer (int64), required): "Day Threshold for Read-Only Transactions (red line)": 0 when off.
  • readOnlyThreshold (Date or null): Today minus the threshold's days: transactions posted before it are read-only. Absent when the threshold is off.
  • useTradingAccounts (boolean, required): "Use Trading Accounts": every commit keeps the trading splits of multi-commodity transactions.
  • defaultBudget (Guid or null): "Default Budget": the GUID the option holds, or null when it is unset. A GUID naming no budget is returned as stored; budget.list gives the default in effect.
  • companyName (string, required): The Business tab's "Company Name"; "" when unset (v0.6).
  • companyAddress (string, required): "Company Address": lines separated by newlines (v0.6).
  • companyContactPerson (string, required): "Company Contact Person" (v0.6).
  • companyPhoneNumber (string, required): "Company Phone Number" (v0.6).
  • companyFaxNumber (string, required): "Company Fax Number" (v0.6).
  • companyEmailAddress (string, required): "Company Email Address" (v0.6).
  • companyWebsiteUrl (string, required): "Company Website URL" (v0.6).
  • companyId (string, required): "Company ID", such as a tax ID (v0.6).
  • taxNumber (string, required): The Tax tab's "Tax Number" (v0.6).
  • defaultInvoiceReport (InvoiceReport or null): "Default Invoice Report": the report GnuCash's Print Invoice runs, as GnuCash parses the slot; null when unset or unreadable. The GUID is returned as stored and may name no report red-ale has (v0.6).