Method

job.update

Change a job; `active: false` deactivates it.

Changes a job's name, ID, reference, rate or active state. Fields you leave out stay as they are.

Once a job has invoices, bills or orders its owner cannot change, and the call is refused with conflict. GnuCash allows it, and silently moves the job's documents, posted ones included, to the new owner.

Examples

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"job.update","params":{"job":"3048f991c36143769571bcc833015d53","owner":"9697710198334d558a9bfde219bb1e41"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2003,
    "message": "the job has invoices, bills or orders, so its owner cannot change",
    "data": {
      "help": "error/conflict"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"job.update","params":{"job":"3048f991c36143769571bcc833015d53","active":false}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "guid": "3048f991c36143769571bcc833015d53",
    "active": false,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
job.update {"job":"3048f991c36143769571bcc833015d53","owner":"9697710198334d558a9bfde219bb1e41"}
job.update {"job":"3048f991c36143769571bcc833015d53","active":false}
EOF

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

{
  "error": {
    "code": 2003,
    "message": "the job has invoices, bills or orders, so its owner cannot change",
    "data": {
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"job.update","arguments":{"job":"3048f991c36143769571bcc833015d53","owner":"9697710198334d558a9bfde219bb1e41"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "the job has invoices, bills or orders, so its owner cannot change",
      "data": {
        "help": "error/conflict"
      }
    }
  }
}

Tool call:

{"name":"job.update","arguments":{"job":"3048f991c36143769571bcc833015d53","active":false}}

Result:

{
  "structuredContent": {
    "guid": "3048f991c36143769571bcc833015d53",
    "active": false,
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of job.update: the fields to change.

  • job (Guid, required): The job.
  • name (string or null): Job name.
  • id (string or null): Job number. On create, absent or empty takes the next number from the book's gncJob counter.
  • owner (Guid or null): The customer or vendor the job is for. It cannot change once the job has documents.
  • reference (string or null): Reference (GnuCash's job description).
  • rate (Amount or null): Rate: the default price of new lines on the job's documents. Zero removes it.
  • active (boolean or null): Active; false deactivates.

Result

A job.

  • guid (Guid, required): A GUID: 32 hexadecimal digits.
  • id (string, required)
  • name (string, required)
  • owner (OwnerInfo, required): An owner: a customer, vendor, employee or job.
  • reference (string, required)
  • rate (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number.
  • active (boolean, required)