List cost roll-ups
Read what a node of the job hierarchy costs, and what everything beneath it costs.
A roll-up is derived and read-only — there is no create, update or delete. It is keyed on the cost centre rather than on a cost sheet, so a contract nobody has costed directly still returns a real total from the work orders beneath it, without an empty sheet having to exist for it.
Filter by organisation, cost_centre and cost_centre_type together for the
node you want rolled up. All three are required as a set; supplying some but
not all of them is rejected rather than answered.
By default this returns exactly one element: the roll-up for the node named
by the filter. Add eq(depth,all) to the filter to get one element per node
in the subtree beneath and including that node instead, so a client can see
which scheme, work order or operation is holding the money rather than only
how much is below in total. Any other depth value is rejected rather than
answered.
Every element, in either mode, also carries parent_cost_centre_id and
parent_cost_centre_type (both null on the subtree’s root), name, code
and has_cost_sheet — enough on its own to rebuild the shape of the subtree
and label each node, since a depth=all response is otherwise just a bag of
totals with no relationships between them.
Each roll-up returns the node’s own direct total, the rolled total that
includes every descendant, and by_status — rolled split by the status of
the sheet each line sits on, so a client can sum only the statuses it cares
about without asking again. Soft-deleted nodes are left out of the walk.
Totals are sums of the snapshots stored on the cost lines themselves, so revising a rate or a margin in the cost register never moves a roll-up.
This read is gated on permission to view cost lines rather than cost sheets: a roll-up returns nothing but money.
Authorizations
Session token for authentication.
Query Parameters
Filters the response data based on the value provided.
Available filters:
organisation: Filter by the ID of the organisation the node belongs tocost_centre: Filter by the ID of the node to roll upcost_centre_type: Filter by the type of the node to roll up (scheme-contracts,schemes,work-orders,operations)depth: Optional. How much of the subtree to return:self(the default, and the same as omitting the term) returns one element, the roll-up for the filtered node;allreturns one element per node in the subtree beneath and including it, so a client can see which scheme, work order or operation is holding the money rather than only the total beneath it. Matching is exact lowercase; any other value is rejected withCH.004.211.
A roll-up is derived from a cost centre, so organisation, cost_centre
and cost_centre_type must be given together — they identify the node
whose subtree is summed. Supplying some but not all of them is rejected
with CH.004.211 rather than answered, because a partly-filtered roll-up
would return a total for the wrong scope. Supplying none of them returns
an empty collection, as any unfiltered collection read does.
Wrap them in and(), as in
and(eq(organisation,c000c344-8847-47da-a091-32e75902d3b1),eq(cost_centre,7f3a2c18-64bd-4f0e-9a52-c8d1b73e0f45),eq(cost_centre_type,work-orders),eq(depth,all));
filters after a bare top-level comma are dropped.
For more information on using named filters, see the docs
Limit the number of resources returned by the API
x >= 1Offset the resources returned by the API
x >= 0