Preview a calc rule
const url = 'https://example.com/api/v1/calc-rules:preview';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"inputs":[{"alias":"example","key":"example"}],"name":"example","output_key":"example","owner_kind":"component","reduce":{"expr":"example"},"selector":{"component_types":["example"],"components":["example"],"system_types":["example"],"systems":["example"]}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/calc-rules:preview \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ { "alias": "example", "key": "example" } ], "name": "example", "output_key": "example", "owner_kind": "component", "reduce": { "expr": "example" }, "selector": { "component_types": [ "example" ], "components": [ "example" ], "system_types": [ "example" ], "systems": [ "example" ] } }'Computes a candidate calc rule now, on each owner it selects that the caller may read, with the reduce the tick runs, and writes nothing (a read-only transaction). For each owner it answers the value the rule would write, the output’s current value and whether they differ, the inputs with no value, the members skipped and the instances left out as stale (named when the caller may read the component, else counted). An expression that reads one member’s value by position (members[1].value.t, or an element of an input’s list) over a system with a member the caller may not read is withheld on that system, its error counting the members out of scope; one that folds each input’s list whole (avg(t), max(t)) shows the aggregate. A component rule previews the selected components holding one of its inputs, as the tick would mark them. The owners holding a current value of the output are computed first, so the cap never hides one, and the answer lists the owners holding a value or that the rule would write one on first, each by name. At most owner_cap owners are computed, and a bound on total input reads stops a preview over large systems early, a whole owner at a time (owners_judged of owners_total, truncated past either). The candidate is checked as a save would check it: a reduce that does not compile, a cycle in the key graph, an output another enabled rule or a collection writes, or health are each a 422, so the author learns before saving; given a saved rule’s name it is judged as an edit of that rule. The selector’s names resolve in the caller’s read scope: a name that does not exist and one the caller may not read are the same 422, and a name shared in and out of scope means the one in scope. A preview takes no lock a save waits on. Gated by rule:read.
Request Body required
Section titled “Request Body required ”object
A URL to the JSON Schema for this object.
The keys the rule reads, each by a unique alias its reduce uses
object
The name the reduce’s expression binds the input by: an identifier of at most 64, not a keyword, a builtin or list function’s name, or one of the calc site’s own bindings (component, has, members, system, value); unique in the rule
The property or metric the input reads, by name or uuid; the rule holds it by uuid, so a rename changes nothing
A saved rule’s name, to preview an edit of it (its stored version is then not a second writer of its key); absent for a new rule
The property or metric the rule would write
What the rule derives a value on
An expression over the inputs by alias
object
An expression over the inputs by alias, each bound as the list of its current values (one per instance on a component, every member’s on a system), yielding the output key’s type: max(tcp), avg(temp), any(call) || max(people) > 0
The owners the rule derives for; absent is every owner of its kind
object
A component rule: derive on components whose type falls within one of these component types
A component rule: derive on these components (by name or id on write; ids on read)
A system rule: derive on systems whose type falls within one of these system types (subtypes included)
A system rule: derive on these systems (by name or id on write; ids on read)
Responses
Section titled “ Responses ”OK
object
A URL to the JSON Schema for this object.
The most owners one preview computes
What the rule would do on each owner it selects that the caller may read, by owner id
object
The output key’s current value on the owner; absent when it has none
Whether the value differs from the current one, so the rule would write a sample
Why the rule could not compute on the owner
The input keys no value was found for
A system with no role-bound members: the rule would write nothing
The owner, by name
The owner’s uuid
What the owner is
A system rule’s members that held no value of an input, those the caller may read
object
The member component, by name
The member component’s uuid
The input key the member held no value of
How many more skipped members the caller may not read
The instances an input’s list would leave out as stale, on components the caller may read
object
The component the instance is on, by name
The component’s uuid
The instance left out as stale
The input key
How many more stale instances the caller may not read
The value the rule would write now; absent when it would write nothing
How many owners were computed
How many owners the rule selects that the caller may read
The cap stopped the preview short of every owner
Example
{ "$schema": "/api/v1/schemas/CalcPreviewOutputBody.json", "owners": [ { "owner_kind": "component" } ]}default
Section titled “default ”Error
object
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
object
Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{ "$schema": "/api/v1/schemas/ErrorModel.json", "detail": "Property foo is required but is missing.", "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "about:blank"}