OliveTin/docs/modules/ROOT/pages/api/start_action.adoc

[#api-start-action]
= Starting Actions from the API

There are several variants of this API call available which might be easier for scripts (or humans) to work with!

include::partial$api/start_action_methods.adoc[]

[#api-request-idurl]
== Request type: Action ID in the URL

Used by:

*** xref:api/method_StartActionByGet.adoc[StartActionByGet]
*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]

If you are trying to integrate OliveTin with your own scripts or processes, it's probably easiest to start actions by using an ID directly in the URL, <<api-eg-startIdUrl,see the example>>.

[#api-request-obj]
== Request type: OliveTin request object

Used by:

*** xref:api/method_StartAction.adoc[StartAction]
*** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]

[source,json]
.OliveTin request object structure
----
{
  "actionId": "string",
  "arguments": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "uniqueTrackingId": "string"
}
----

To find your Action ID, and understand how Action IDs work, see the xref:action_customization/ids.adoc[Action ID] documentation

If you need more control over the execution, then the only other option is to submit a `OliveTin reqjest object`, which is just a very simple JSON structure like this;

[source,json]
----
{
    "actionId": "Generate cryptocurrency",
    "arguments": [],
    "uniqueTrackingId": "my-tracking-id",
}
----

More detailed examples can be seen below.

[#api-response-trackingid]
== Response type: Execution Tracking ID

Used by:

*** xref:api/method_StartAction.adoc[StartAction]
*** xref:api/method_StartActionByGet.adoc[StartActionByGet]

.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]
*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]

.Example log entry
[source,json]
----
{
    "logEntry": {
        "datetimeStarted": "2024-02-27 14:14:49",
        "actionTitle": "Restart httpd on server1",
        "stdout": "",
        "stderr": "",
        "timedOut": true,
        "exitCode": -1,
        "user": "",
        "userClass": "",
        "actionIcon": "&#128260;",
        "tags": [

        ],
        "executionTrackingId": "b04b1e90-d457-4158-b7dc-da9e81f21568",
        "datetimeFinished": "2024-02-27 14:14:52",
        "actionId": "restart_httpd",
        "executionStarted": true,
        "executionFinished": true,
        "blocked": false
    }
}
----