scheduledTransaction.apply

Apply a held Since Last Run proposal with the caller's choices, as one Mutation.

Applies a held Since Last Run proposal as one change: it creates the transactions of the instances in state toCreate and moves each scheduled transaction on, or does nothing. choices change an instance by its index: a new state (toCreate, reminder, postponed, ignored) and values for its variables. Instances you do not name keep the proposed state.

Everything is checked first and nothing is created if anything fails: a variable without a value, a formula that cannot be worked out, a template account that is a placeholder, a reminder placed before another state in one schedule, or an instance before the read-only date that you did not choose by name. GnuCash would create the transaction with zero amounts and try again next run. Postponing is refused in an SQLite book. A proposal made at an earlier revision of the book is refused with conflict: ask again.

If rounding leaves a created transaction unbalanced, an Imbalance-<CUR> split is added, as GnuCash's commit does, and reported in imbalanceSplits.

Examples

A proposal that is not held, because it was applied, discarded, pushed out or made before the book was opened, is refused:

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"scheduledTransaction.apply","params":{"proposal":"slr-999999"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2000,
    "message": "…",
    "data": {
      "kind": "sinceLastRunProposal",
      "id": "slr-999999",
      "help": "error/not-found"
    }
  }
}

Command line

red-ale exec --book book.gnucash scheduledTransaction.apply '{"proposal":"slr-999999"}'

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

{
  "error": {
    "code": 2000,
    "message": "…",
    "data": {
      "kind": "sinceLastRunProposal",
      "id": "slr-999999",
      "help": "error/not-found"
    }
  }
}

MCP tool call

Tool call:

{"name":"scheduledTransaction.apply","arguments":{"proposal":"slr-999999"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2000,
      "name": "not-found",
      "message": "…",
      "data": {
        "kind": "sinceLastRunProposal",
        "id": "slr-999999",
        "help": "error/not-found"
      }
    }
  }
}

A run with a monthly rent scheduled since May, ignoring May's instance. Proposal IDs count up from slr-1 in each server:

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"scheduledTransaction.create","params":{"name":"Monthly rent","startDate":"2024-05-01","schedule":[{"mult":1,"periodType":"month"}],"templateTransactions":[{"description":"Rent","splits":[{"account":"Rent","debitFormula":"750"},{"account":"Checking","creditFormula":"750"}]}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"scheduledTransaction.sinceLastRun","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "id": "slr-1",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"scheduledTransaction.apply","params":{"proposal":"slr-1","choices":[{"index":0,"state":"ignored"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "created": [
      {
        "index": 1,
        "date": "2024-06-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      },
      {
        "index": 2,
        "date": "2024-07-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      }
    ],
    "ignored": [
      0
    ],
    "postponed": [],
    "reminders": [],
    "schedules": [
      {
        "lastOccurrence": "2024-07-01",
        "instanceCount": 4,
        "…": "…"
      }
    ],
    "imbalanceSplits": [],
    "warnings": []
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Checking","type":"BANK","commodity":"USD"}
account.create {"name":"Rent","type":"EXPENSE","commodity":"USD"}
scheduledTransaction.create {"name":"Monthly rent","startDate":"2024-05-01","schedule":[{"mult":1,"periodType":"month"}],"templateTransactions":[{"description":"Rent","splits":[{"account":"Rent","debitFormula":"750"},{"account":"Checking","creditFormula":"750"}]}]}
scheduledTransaction.sinceLastRun {}
scheduledTransaction.apply {"proposal":"slr-1","choices":[{"index":0,"state":"ignored"}]}
EOF

It prints:

[
  "…",
  "…",
  "…",
  {
    "id": "slr-1",
    "…": "…"
  },
  {
    "created": [
      {
        "index": 1,
        "date": "2024-06-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      },
      {
        "index": 2,
        "date": "2024-07-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      }
    ],
    "ignored": [
      0
    ],
    "postponed": [],
    "reminders": [],
    "schedules": [
      {
        "lastOccurrence": "2024-07-01",
        "instanceCount": 4,
        "…": "…"
      }
    ],
    "imbalanceSplits": [],
    "warnings": []
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"scheduledTransaction.create","arguments":{"name":"Monthly rent","startDate":"2024-05-01","schedule":[{"mult":1,"periodType":"month"}],"templateTransactions":[{"description":"Rent","splits":[{"account":"Rent","debitFormula":"750"},{"account":"Checking","creditFormula":"750"}]}]}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"scheduledTransaction.sinceLastRun","arguments":{}}

Result:

{
  "structuredContent": {
    "id": "slr-1",
    "…": "…"
  }
}

Tool call:

{"name":"scheduledTransaction.apply","arguments":{"proposal":"slr-1","choices":[{"index":0,"state":"ignored"}]}}

Result:

{
  "structuredContent": {
    "created": [
      {
        "index": 1,
        "date": "2024-06-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      },
      {
        "index": 2,
        "date": "2024-07-01",
        "transactions": [
          "…"
        ],
        "…": "…"
      }
    ],
    "ignored": [
      0
    ],
    "postponed": [],
    "reminders": [],
    "schedules": [
      {
        "lastOccurrence": "2024-07-01",
        "instanceCount": 4,
        "…": "…"
      }
    ],
    "imbalanceSplits": [],
    "warnings": []
  }
}

Effect: write, on the Book.

Params

The params of scheduledTransaction.apply.

proposal (string, required): The proposal's ID.
choices (array of ChoiceParam): The caller's changes, by instance index. Instances not named keep the proposed state and bindings.
autoCreateOnly (boolean): Apply only the instances of auto-create scheduled transactions, as GnuCash does before it shows its dialog.

Result

The result of scheduledTransaction.apply.

created (array of CreatedWire, required): Instances created.
postponed (array of integer (uint), required): Instances postponed, newly or still.
ignored (array of integer (uint), required): Instances ignored.
reminders (array of integer (uint), required): Instances left as reminders.
schedules (array of ScheduleState, required): The scheduled transactions whose state changed, after the apply, in book order.
imbalanceSplits (array of RunImbalanceSplit, required): Every Imbalance-<CUR> split made.
warnings (array of RunWarning, required): Every Imbalance split again, and every transaction created read-only by date.