Skip to content

script_start

Tech

Starts a script instance execution.

Note

A script instance is a script configuration defining start / stop triggers and a specific set of flags and arguments for it to be started with. Each script instance can only run in at most one instance at any given time.

The script instance can only run in one instance at any given time. If the script instance is already running (state = running|terminating) an error must be returned.

Params

attribute description
script_name*
string		 The name of the script whose instance is to be started
instance_name*
string		 The name of the instance to be started

Example

{
  "script_name": "hello_world",
  "instance_name": "manual"
}

Return

attribute description
scripts*
[Script]		 The scripts present in device

Script

attribute description
name*
string		 The name of the script. Matches [-a-zA-Z0-9._]{1,100}
instances*
[Instance]		 The script instances

Instance

attribute description
name*
string		 The name of the script instance. Matches [-a-zA-Z0-9._]{1,100}
last_execution
Last Execution		 Information about the last execution of the script instance

Last Execution

attribute description
id*
unsigned int		 The ID of the execution
start_timestamp*
unsigned int		 The Unix timestamp of the start of the execution
start_trigger*
Start Trigger		 The trigger that started the execution.
state*
"running"|"terminating"|"finished"|"killed"		 The state of the execution
pid
unsigned int		 The process ID (PID) of the execution. It must be set for scripts where state is either running or terminating. It must not be set for scripts in other states.
stop_trigger
Stop Trigger		 The trigger that stopped the execution. If the script was not stopped by a trigger or it did not execution yet, this field must not be set.
is_outdated
bool		 Indicates whether executed with a script source version that has been changed since.

Start Trigger

attribute description
type*
"manual"|"xpath"|"scheduler"		 The type of the trigger
setting
string		 The configuration of the trigger: the xpath for xpath triggers or the crontab expression for scheduler triggers. Not applicable if the type is manual.
username
string		 The username of the user that started the script manually, only applicable if the type is manual.

Stop Trigger

attribute description
type*
"manual"|"xpath"|"scheduler"|"system"		 The type of the trigger
setting
string		 The configuration of the trigger: the xpath for xpath triggers or the crontab expression for scheduler triggers. Not applicable if the type is manual or system.
username
string		 The username of the user that stopped the script manually, only applicable if the type is manual.

Scheduler trigger

A scheduler trigger's setting is a five-field crontab expression (minute hour day-of-month month day-of-week), evaluated in the device's local timezone. Example: 0 3 * * mon-fri.

Example

{
  "scripts": [
    {
      "name": "hello_world",
      "instances": [
        {
          "name": "manual",
          "last_execution": {
            "pid": 1234,
            "start_timestamp": 1743246430,
            "start_trigger": {
              "type": "manual",
              "username": "admin"
            },
            "state": "running"
          }
        },
        {
          "name": "daily"
        }
      ]
    }
  ]
}