API Reference

Open the interactive OpenAPI reference:

POST /sf_tools/{tool}

Run a Snippet Framework tool, queued on a collector or on this host

Runs one of the platform’s Dynamic Application toolbox tools. These are the jobs the platform’s Dynamic Application editor queues, with the same tool ids and the same command lines.

By default the run is queued for the Remote Toolbox on a Data Collector, so this endpoint returns a receipt rather than the result. The queued run reaches the collector through a database update, so nothing is available immediately; read the log and result back from GET /sf_tools/{tool}/{request_id}. The run happens on the collector its devices are assigned to. A collector named in the body has to be that one, and is required when a job uses a device wildcard.

With run_local true, the same command runs on the host this service runs on, an All-In-One or a Database Server, the way the collector’s Remote Toolbox would run it, and the log and result are returned directly with status 200, as the read back of a finished run returns them. No collector is resolved, so a device wildcard needs no collector, and one that is named is ignored. A local run uses the configuration and credentials this host holds, so it only finds the devices this host collects for. It is stopped after 90 seconds. Every response says which happened in mode.

Requires the DYN_APP_VIEW, DEV_COLLECTIONS_VIEW and DEV_TOOLS_RUN access hooks.

Parameters:

tool (string) – The tool to run, by name. dynamic_single is Dynamic App Collection (tool 13), detailed_collection is Snippet Framework Detailed Collection (tool 20), collection_object_graph is Snippet Framework Collection Object Graph (tool 21) and dynamic_multi is Snippet Framework Dynamic App Multi Collection (tool 22).

Query Parameters:

combine_streams (boolean) – Local runs only. Return the output as one stream, output.combined, as the read back does. Accepts true, false, 1 or 0. Defaults to false.

Response JSON Object:

app_id (integer) – The application to run on did, instead of jobs.
cobj_id (integer) – detailed_collection only. A collection object id, or a list of at most 1000 of them, to restrict the run to. Each is a whole number or a string of digits. Swagger 2.0 cannot express “one or a list”; both are accepted. Defaults to every collection object.
collector (string) – The id or name of the collector to run on. The collector each device is assigned to decides where the run happens; a collector named here has to be that one. Required when any job uses a device wildcard, and then also limits the wildcard to the devices that collector holds. Accepts a number as well as a string. Ignored when run_local is true, since a local run always runs on this host.
dark_mode (boolean) – collection_object_graph only. true for the dark theme, false for the light theme. Defaults to the CLI’s own default, which is dark.
debug (boolean) – Whether the tool logs at debug level. Like every flag, accepts true or false, or 1 or 0 as the platform’s editor sends them. Defaults to what the platform’s editor uses: on for dynamic_single, detailed_collection and dynamic_multi, off for collection_object_graph. Off unsets the debug variables rather than setting them to 0, which dynamic_single.py would read as on.
did (integer) – A single device to run on, with app_id, instead of jobs. This is the form the platform’s editor uses when it has no list of pairs.
disable_cache (boolean) – detailed_collection only. Skip cache fast-forwarding, so every step executes.
graph_type (string) – collection_object_graph only. The format to render the graph in. Defaults to mermaid, which the platform’s editor renders; the CLI’s own default is dot.
jobs[][] (string)
result_format (string) – detailed_collection only. web_ui, the format the platform’s editor uses, pretty prints each step’s data and the processed result for display and cuts them to 4096 characters. standard reports them as the values the collection produced.
run_local (boolean) – Run the tool on the host this service runs on and answer with its log and result, rather than queueing it for a collector. Accepts true or false, or 1 or 0. The command is the one a queued run sends, run the way the Remote Toolbox runs it. Left out, it is true on an All-In-One and false otherwise.

Status Codes:

200 OK – The run was made on this host, because run_local was true or was left out on an All-In-One. Holds its log, and its result for the tools that write one.
202 Accepted – The run was queued. Read its output with the returned request_id.
400 Bad Request – The body is invalid: a malformed job, a wildcard the tool does not allow, a field the tool does not accept, an invalid run_local, a malformed collector, a device wildcard with no collector, a device that is not assigned to any collector, or a request too large for the platform’s spool table.
401 Unauthorized – Unauthenticated
403 Forbidden – Forbidden (insufficient access hooks)
404 Not Found – The tool, a device, or the named collector does not exist.
409 Conflict – The devices are assigned to different collectors, or not to the one named. A collector only holds the configuration of its own devices, so the run would find nothing to do.
429 Too Many Requests – A local run was refused because five are already in progress, the most that may run at once. Try again once one has finished.
500 Internal Server Error – The run could not be audited, queued or run
504 Gateway Timeout – A local run did not finish within 90 seconds and was stopped. Holds what it wrote before then, and no result.

Request JSON Object:

extracted.collections (object) – detailed_collection only. Keyed <did>_<aid>, then by collection object id, each entry {"processed_result": ..., "error": ...}: the value the collection object produced, or null, and the error it reported, or null. With result_format web_ui the processed result is the editor’s display string, cut to 4096 characters; with standard it is the value itself. The snapshots of every step and the logs, the bulk of a detailed result, are not repeated here; they stay only in result.
extracted.dev_app_pairs[][] (integer)
extracted.graphs (object) – collection_object_graph only. Each Execution Environment’s graph, in the requested graph_type.
extracted.message (string) – Why the run failed when success is false, such as “No jobs scheduled”.
extracted.success (boolean) – Whether the jobs were scheduled and run. It does not say that any collection object produced data; collections does.
jobs[][] (string)
last_id (integer) – The number of the run’s last log row.
line_counts (object)
mode (string) – How the tool was run. Always local.
output (object) – The run’s whole log, one text per stream, or only combined when combine_streams is requested, exactly as the read back returns it.
result (object) – For every tool but dynamic_single. The JSON result exactly as the tool wrote it, or null when there is none.
result_error (string) – Present with result. Why there is no result, as the read back reports it. A local run has finished, so the reason is final.
terminated (boolean) – True, since the run finished.
tool (string)
tool_id (integer)
toolbox.phase (string) – There is no stuck phase: a run the collector never picks up stays queued and one the Remote Toolbox abandons stays running, so judge from the two ages when to stop waiting.
toolbox.returncode (integer) – The exit status of the backend script as stored. The Snippet Framework wrappers exit 0 whatever happened, and a script killed by a signal is stored as 0 too, so this says only that the run ended.
toolbox.seconds_since_last_output (integer)
toolbox.seconds_since_queued (integer)
toolbox.state (integer) – The spool row’s state as found: 1 scheduled, 2 launched, 3 running, 0 complete, 4 failed, 5 canceled. The updates can land out of order, so a finished run can still read 2.
truncated (boolean) – True when the tool wrote more than the 32 MiB of output a local run keeps. Every line past the limit was discarded, and any result is withheld. A local run is not paged, so it is otherwise false.
collector.id (integer)
collector.ip (string)
collector.name (string)
jobs[][]
mode – How the tool was run. Always remote for a queued run.
note (string)
request_id (integer) – The id to read the run’s output with.
tool – The tool’s name.
tool_id – The platform’s Remote Toolbox tool id.

GET /sf_tools/{tool}/{request_id}

Read a Snippet Framework tool run’s log and result

Reads back a page of a queued run’s log, and its result once the run has finished.

The log comes back as text per stream, in output, with the result chunks and the toolbox’s own marker rows left out, or with combine_streams as one text in the order written, the marker rows included. A page ends on a line, so append each stream’s text from each page to what you have. An empty page with terminated false means the collector has not written more yet. Call again with last_id as after_id until terminated is true.

Once terminated is true, every poll carries result, extracted and result_error for the tools that write a result, including a poll from the final last_id that returns no more log. There is no separate request for the result.

A run is only readable by the user who queued it, and only through the tool it was queued as.

Requires the DYN_APP_VIEW, DEV_COLLECTIONS_VIEW and DEV_TOOLS_RUN access hooks.

Parameters:

tool (string) – The tool to run, by name. dynamic_single is Dynamic App Collection (tool 13), detailed_collection is Snippet Framework Detailed Collection (tool 20), collection_object_graph is Snippet Framework Collection Object Graph (tool 21) and dynamic_multi is Snippet Framework Dynamic App Multi Collection (tool 22).
request_id (integer) – The request_id returned when the run was queued.

Query Parameters:

after_id (integer) – Return only output written after this cursor. A whole number.
page_size (integer) – The maximum number of log lines to return. Larger values are reduced.
wait_seconds (number) – Wait up to this long for the run to finish before returning, reading again every second on a fresh database connection. Defaults to no wait. Capped at 90 seconds.
combine_streams (boolean) – Return the output as one stream, output.combined, holding every row in the order the collector wrote it, the toolbox’s started and completed rows included, instead of one text per stream. Accepts true, false, 1 or 0. Defaults to false.

Status Codes:

200 OK – One page of the run’s log, with its result once it has terminated.
400 Bad Request – A query parameter is invalid.
401 Unauthorized – Unauthenticated
403 Forbidden – Forbidden (insufficient access hooks)
404 Not Found – The tool is unknown, or the request id is not a run of that tool belonging to this user. Every reason reads the same.
500 Internal Server Error – The output could not be read

Request JSON Object:

extracted.collections (object) – detailed_collection only. Keyed <did>_<aid>, then by collection object id, each entry {"processed_result": ..., "error": ...}: the value the collection object produced, or null, and the error it reported, or null. With result_format web_ui the processed result is the editor’s display string, cut to 4096 characters; with standard it is the value itself. The snapshots of every step and the logs, the bulk of a detailed result, are not repeated here; they stay only in result.
extracted.dev_app_pairs[][] (integer)
extracted.graphs (object) – collection_object_graph only. Each Execution Environment’s graph, in the requested graph_type.
extracted.message (string) – Why the run failed when success is false, such as “No jobs scheduled”.
extracted.success (boolean) – Whether the jobs were scheduled and run. It does not say that any collection object produced data; collections does.
last_id (integer) – The cursor to resume from. Pass it back as after_id.
line_counts (object) – A count of this page’s rows per stream, including the toolbox’s started and completed marker rows, which are left out of output unless combine_streams is set.
mode (string) – How the tool was run. Always remote, since only a queued run is read back.
output (object) – This page’s output, one text per stream. Has stdout and stderr at least; a stream the toolbox does not normally write appears under its own name. Each record is one line ending in a newline; one that had none, such as a record cut to 4096 characters with ... [truncated] appended, is given one. When combine_streams is requested, holds only combined: every row in the order written, the toolbox’s started and completed rows included.
request_id (integer)
result (object) – Present once terminated is true, for every tool but dynamic_single. The JSON result exactly as the tool wrote it, reassembled from its chunks, or null when there is none.
result_error (string) – Present with result. Why there is no result: the tool wrote none (its log says why), the result was larger than 16 MiB, it did not parse, or a chunk arrived at a length the tool could not have written, which means part of it was lost in transit. Such a result is withheld even if what remains parses. A result that is irregular or does not parse is only reported once the run has written nothing for 90 seconds; until then terminated stays false, since the rest may still be arriving.
terminated (boolean) – True once the run has finished and every line of its log has been returned. Stop polling. This reports termination only, not success. A run whose completion marker was lost terminates only after 90 seconds without output, so a batch still in transit from the collector is not cut off.
tool (string)
toolbox.phase (string) – There is no stuck phase: a run the collector never picks up stays queued and one the Remote Toolbox abandons stays running, so judge from the two ages when to stop waiting.
toolbox.returncode (integer) – The exit status of the backend script as stored. The Snippet Framework wrappers exit 0 whatever happened, and a script killed by a signal is stored as 0 too, so this says only that the run ended.
toolbox.seconds_since_last_output (integer)
toolbox.seconds_since_queued (integer)
toolbox.state (integer) – The spool row’s state as found: 1 scheduled, 2 launched, 3 running, 0 complete, 4 failed, 5 canceled. The updates can land out of order, so a finished run can still read 2.
truncated (boolean) – True when more output was waiting than the page could hold. Request the next page from last_id.