scheduledTransaction.create

Create a scheduled transaction with its template transactions.

Creates a scheduled transaction: a name, a Schedule (one or more recurrences, such as every month) and template transactions, the transactions to enter each time it falls due. It enters nothing itself: transactions are made by Since Last Run, when you ask for it.

A template split names a real account and a debit or credit formula: a number (750), or an expression using variables such as i, the number of the occurrence, or the loan functions pmt, ipmt and ppmt. Arguments are separated by :, not by commas. A formula with no variable and accounts of one commodity must balance, or the call is refused with unbalanced. Template splits cannot use placeholder or root accounts.

The recurrences you give are normalised as GnuCash does, and the result shows what was stored; warnings carries what GnuCash's editor would ask about, such as a name already in use. Auto-create is refused when a formula has a variable other than i, or the splits span commodities, as GnuCash's editor refuses it.

Examples

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": {
    "guid": "…",
    "name": "Monthly rent",
    "enabled": true,
    "startDate": "2024-05-01",
    "end": {
      "never": true
    },
    "lastOccurrence": null,
    "instanceCount": 1,
    "nextOccurrence": "2024-05-01",
    "schedule": [
      {
        "mult": 1,
        "periodType": "month",
        "start": "2024-05-01",
        "weekendAdjust": "none"
      }
    ],
    "warnings": [],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":4,"method":"scheduledTransaction.create","params":{"name":"","schedule":[{"mult":1,"periodType":"month"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": 2001,
    "message": "please name the scheduled transaction",
    "data": {
      "reason": "name",
      "help": "error/invalid"
    }
  }
}

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.create {"name":"","schedule":[{"mult":1,"periodType":"month"}]}
EOF

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

{
  "error": {
    "code": 2001,
    "message": "please name the scheduled transaction",
    "data": {
      "reason": "name",
      "help": "error/invalid"
    }
  }
}

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:

{
  "structuredContent": {
    "guid": "…",
    "name": "Monthly rent",
    "enabled": true,
    "startDate": "2024-05-01",
    "end": {
      "never": true
    },
    "lastOccurrence": null,
    "instanceCount": 1,
    "nextOccurrence": "2024-05-01",
    "schedule": [
      {
        "mult": 1,
        "periodType": "month",
        "start": "2024-05-01",
        "weekendAdjust": "none"
      }
    ],
    "warnings": [],
    "…": "…"
  }
}

Tool call:

{"name":"scheduledTransaction.create","arguments":{"name":"","schedule":[{"mult":1,"periodType":"month"}]}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "please name the scheduled transaction",
      "data": {
        "reason": "name",
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of scheduledTransaction.create; absent fields take the editor's defaults.

name (string, required): The name, not empty.
schedule (array of RecurrenceParam, required): The Schedule: at least one Recurrence, each starting on startDate unless it says otherwise.
templateTransactions (array of TemplateTransactionParam): The template transactions; default none.
enabled (boolean or null): Since Last Run leaves out a disabled one; default true.
startDate (Date or null): The first possible occurrence; default today.
end (End or null): The end; default never. Setting one kind of end clears the other.
autoCreate (boolean or null): Create due instances without asking; default false. Refused with variables other than i, with more than one commodity, or with no template split.
notify (boolean or null): And say so; default true with autoCreate, refused without it.
advanceCreateDays (integer (int32) or null): Days ahead to create; default 0.
advanceRemindDays (integer (int32) or null): Days ahead to remind, after that; default 0.

Result

A scheduled transaction, with every field GnuCash's file holds.

guid (Guid, required): Identity.
name (string, required): The name; names need not be unique.
enabled (boolean, required): Disabled ones are left out of Since Last Run and the forecasts.
startDate (Date, required): The first possible occurrence.
end (End, required): The end, as stored.
lastOccurrence (Date or null): The last occurrence acted on (created, ignored or postponed), or null if never run.
instanceCount (integer (int32), required): The Instance count: the value of i for the next instance.
autoCreate (boolean, required): Create due instances without asking.
notify (boolean, required): And say so.
advanceCreateDays (integer (int32), required): Days ahead to create.
advanceRemindDays (integer (int32), required): Days ahead to remind, after that.
schedule (array of Recurrence, required): The Schedule, as stored.
nextOccurrence (Date or null): The next occurrence after the last (or the first), or null when it has ended or never occurs.
deferredInstances (array of DeferredInstance, required): The state saved before each postponed instance, in file order.
templateAccount (Guid or null): The template account's GUID, or null when there is none.
templateTransactions (array of TemplateTransaction or null): The template transactions, in the template account's split order; absent in scheduledTransaction.list.
variables (array of string, required): Every variable the formulas name, i and the exchange-rate variables, sorted bytewise.
warnings (array of WarningInfo or null): What GnuCash's editor would have asked to confirm; only from methods that write.