| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158 |
- [#api-start-action]
- = Starting Actions from the API
- There are two API methods for starting actions: `StartAction`, which returns straight away, and `StartActionAndWait`, which waits for the action to finish.
- include::partial$api/start_action_methods.adoc[]
- All request and response field names below are the protobuf JSON names (lowerCamelCase) from the link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[OliveTin Protobuf definition], which is the source of truth for the API.
- [#api-ids]
- == Action IDs vs Binding IDs
- * `actionId` is the `id` you set on the action in your `config.yaml`. To find your Action ID, and understand how Action IDs work, see the xref:action_customization/ids.adoc[Action ID] documentation.
- * `bindingId` identifies one button/instance of an action. For a normal action this is the same as the action ID. For actions generated from xref:entities/intro.adoc[entities], each entity gets its own binding ID. Binding IDs are returned by `GetDashboard` (as `action.bindingId`).
- NOTE: Despite its name, the `actionId` field used by `StartActionAndWait` is looked up as a binding ID. For normal actions this makes no difference, but for entity-generated actions you must send the entity's binding ID - sending the configured action `id` returns `not_found`.
- [#api-request-startaction]
- == Request type: StartAction request object
- Used by:
- *** xref:api/method_StartAction.adoc[StartAction]
- This is the request the OliveTin web UI uses, and gives you the most control over the execution.
- [source,json]
- .`StartActionRequest`
- ----
- {
- "bindingId": "string",
- "arguments": [
- {
- "name": "string",
- "value": "string"
- }
- ],
- "uniqueTrackingId": "string",
- "justification": "string"
- }
- ----
- * `bindingId` (required) - see <<api-ids>>.
- * `arguments` (optional) - values for the action's xref:args/intro.adoc[arguments].
- * `uniqueTrackingId` (optional) - if you set this, it is used as the execution tracking ID, otherwise one is generated for you. It must be up to 36 characters of hex digits and dashes (eg: a UUID), and must not already have been used. An invalid or previously used ID is silently replaced with a generated UUID, so always track the execution using the `executionTrackingId` returned in the response.
- * `justification` (optional) - the reason for running the action, for actions that require a justification.
- [source,json]
- .Example
- ----
- {
- "bindingId": "generate_cryptocurrency",
- "arguments": [],
- "uniqueTrackingId": "0f8b1c2e-6d3a-4e5f-9a7b-1c2d3e4f5a6b"
- }
- ----
- [#api-request-startactionandwait]
- == Request type: StartActionAndWait request object
- Used by:
- *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
- [source,json]
- .`StartActionAndWaitRequest`
- ----
- {
- "actionId": "string",
- "arguments": [
- {
- "name": "string",
- "value": "string"
- }
- ],
- "justification": "string"
- }
- ----
- Note that this request selects the action with `actionId` (not `bindingId`), and does not accept a `uniqueTrackingId`.
- [#api-response-trackingid]
- == Response type: Execution Tracking ID
- Used by:
- *** xref:api/method_StartAction.adoc[StartAction]
- .Example Execution Tracking ID response
- [source,json]
- ----
- {"executionTrackingId":"5bb4860c-bbd0-4bc9-a7d6-42240551500c"}
- ----
- [#api-response-logentry]
- == Response type: LogEntry
- Used by:
- *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
- The `output` field contains the combined stdout and stderr of the action.
- .Example log entry
- [source,json]
- ----
- {
- "logEntry": {
- "datetimeStarted": "2026-11-12 11:56:29",
- "actionTitle": "Restart httpd on server1",
- "output": "Restarting httpd...\n",
- "timedOut": false,
- "exitCode": 0,
- "user": "guest",
- "userClass": "",
- "actionIcon": "🔄",
- "tags": [],
- "executionTrackingId": "56588051-80da-4b31-8cd8-461a4566e3a9",
- "datetimeFinished": "2026-11-12 11:56:31",
- "executionStarted": true,
- "executionFinished": true,
- "blocked": false,
- "datetimeIndex": "4",
- "canKill": false,
- "datetimeRateLimitExpires": "",
- "bindingId": "restart_httpd",
- "queued": false,
- "queuedForGroup": "",
- "justification": "",
- "arguments": [
- {
- "name": "server",
- "value": "server1"
- }
- ]
- }
- }
- ----
- [#api-deprecated-byget]
- == Deprecated: StartActionByGet and StartActionByGetAndWait
- `StartActionByGet` and `StartActionByGetAndWait` are deprecated, and will be removed in a future version of OliveTin. They only accept an `actionId` (no arguments), and despite their names they no longer support `GET` requests - the OliveTin 2k style of putting the action ID in the URL returns `404`.
- When either method is called, OliveTin shows a warning on the xref:advanced_configuration/diagnostics.adoc[Diagnostics] page (code `deprecated_api_call`), so you can find integrations that still need updating. The warning is cleared when OliveTin restarts.
- [%header]
- |===
- | Deprecated method | Use instead | Change
- | xref:api/method_StartActionByGet.adoc[StartActionByGet]
- | xref:api/method_StartAction.adoc[StartAction]
- | Send `{"bindingId": "..."}` instead of `{"actionId": "..."}`
- | xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
- | xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
- | Change the method name only - the request is the same
- |===
|