start_action.adoc 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  1. [#api-start-action]
  2. = Starting Actions from the API
  3. There are two API methods for starting actions: `StartAction`, which returns straight away, and `StartActionAndWait`, which waits for the action to finish.
  4. include::partial$api/start_action_methods.adoc[]
  5. 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.
  6. [#api-ids]
  7. == Action IDs vs Binding IDs
  8. * `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.
  9. * `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`).
  10. 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`.
  11. [#api-request-startaction]
  12. == Request type: StartAction request object
  13. Used by:
  14. *** xref:api/method_StartAction.adoc[StartAction]
  15. This is the request the OliveTin web UI uses, and gives you the most control over the execution.
  16. [source,json]
  17. .`StartActionRequest`
  18. ----
  19. {
  20. "bindingId": "string",
  21. "arguments": [
  22. {
  23. "name": "string",
  24. "value": "string"
  25. }
  26. ],
  27. "uniqueTrackingId": "string",
  28. "justification": "string"
  29. }
  30. ----
  31. * `bindingId` (required) - see <<api-ids>>.
  32. * `arguments` (optional) - values for the action's xref:args/intro.adoc[arguments].
  33. * `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.
  34. * `justification` (optional) - the reason for running the action, for actions that require a justification.
  35. [source,json]
  36. .Example
  37. ----
  38. {
  39. "bindingId": "generate_cryptocurrency",
  40. "arguments": [],
  41. "uniqueTrackingId": "0f8b1c2e-6d3a-4e5f-9a7b-1c2d3e4f5a6b"
  42. }
  43. ----
  44. [#api-request-startactionandwait]
  45. == Request type: StartActionAndWait request object
  46. Used by:
  47. *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
  48. [source,json]
  49. .`StartActionAndWaitRequest`
  50. ----
  51. {
  52. "actionId": "string",
  53. "arguments": [
  54. {
  55. "name": "string",
  56. "value": "string"
  57. }
  58. ],
  59. "justification": "string"
  60. }
  61. ----
  62. Note that this request selects the action with `actionId` (not `bindingId`), and does not accept a `uniqueTrackingId`.
  63. [#api-response-trackingid]
  64. == Response type: Execution Tracking ID
  65. Used by:
  66. *** xref:api/method_StartAction.adoc[StartAction]
  67. .Example Execution Tracking ID response
  68. [source,json]
  69. ----
  70. {"executionTrackingId":"5bb4860c-bbd0-4bc9-a7d6-42240551500c"}
  71. ----
  72. [#api-response-logentry]
  73. == Response type: LogEntry
  74. Used by:
  75. *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
  76. The `output` field contains the combined stdout and stderr of the action.
  77. .Example log entry
  78. [source,json]
  79. ----
  80. {
  81. "logEntry": {
  82. "datetimeStarted": "2026-11-12 11:56:29",
  83. "actionTitle": "Restart httpd on server1",
  84. "output": "Restarting httpd...\n",
  85. "timedOut": false,
  86. "exitCode": 0,
  87. "user": "guest",
  88. "userClass": "",
  89. "actionIcon": "&#128260;",
  90. "tags": [],
  91. "executionTrackingId": "56588051-80da-4b31-8cd8-461a4566e3a9",
  92. "datetimeFinished": "2026-11-12 11:56:31",
  93. "executionStarted": true,
  94. "executionFinished": true,
  95. "blocked": false,
  96. "datetimeIndex": "4",
  97. "canKill": false,
  98. "datetimeRateLimitExpires": "",
  99. "bindingId": "restart_httpd",
  100. "queued": false,
  101. "queuedForGroup": "",
  102. "justification": "",
  103. "arguments": [
  104. {
  105. "name": "server",
  106. "value": "server1"
  107. }
  108. ]
  109. }
  110. }
  111. ----
  112. [#api-deprecated-byget]
  113. == Deprecated: StartActionByGet and StartActionByGetAndWait
  114. `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`.
  115. 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.
  116. [%header]
  117. |===
  118. | Deprecated method | Use instead | Change
  119. | xref:api/method_StartActionByGet.adoc[StartActionByGet]
  120. | xref:api/method_StartAction.adoc[StartAction]
  121. | Send `{"bindingId": "..."}` instead of `{"actionId": "..."}`
  122. | xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
  123. | xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
  124. | Change the method name only - the request is the same
  125. |===