5.6.2. TaskStart¶

Description¶

Adding and starting new tasks.

When starting a task, the uri field is required, other settings are optionally specified.

Monitoring settings are transferred in two parts …

The Boro architecture implies that some settings are specified to a task directly and individually, and other part is included in the Thresholds profiles. It allows to select one of the preset profiles for a typical task. Thresholds described in the ProfileInfo method should be set by selecting the appropriate profile, not by direct value assignment. All possible task settings are described in the Task Configuration chapter.

If settings are not specified, the server sets the values in accordance with the following rules:

profiles of notifications, thresholds, record, and service availability are set in accordance with the type or analyzed service. A user can set settings by default in the web interface. To learn more, go to the User Guide;
Settings not included in the Thresholds profile are assigned in accordance with default values described in the Task Configuration chapter.

To avoid automatic assignment and disable the profile, send the empty array for the required types of settings in the request:

{
          "profiles":{
            "email":[],
            "record":[],
            "kpi":[],
            ...
          },
}

Important

The threshold profile cannot be disabled, this is a required profile.

Important

The following profiles can be set just in amount of one: Alarm notifications, probe thresholds, service availability for a task.

Request¶

{
  "user_id":(number),
  "methods":[
    {
      "method":"TaskStart",
      "params":{
        "project_id":(number),
        "app_id":(number),
        "tasks":[
          {
            "uri":(string),
            "name":(string),
            "service":(string),
            "tags":(string),
            "profiles":{
              "alarm":[(number)],
              "email":[(number)],
              "threshold":[(number)],
              "pagerduty":[(number)],
              "record":[(number)],
              "snmp":[(number)],
              "webhook":[(number)],
              "telegram":[(number)],
              "kpi":[(number)]
            },
            "task_config":{
              ...
            }
          }
        ]
      }
    }
  ]
}

user_id - an integer value, a user identifier;
project_id - an integer value, a user project identifier;
app_id - an integer value, a probe identifier;
uri - a string, a path to an analysed stream (a service, a file);
name - a string, a stream name (e.g. a channel name);
service - a string, a service (channel) identification name used to consolidate service states and errors from different monitoring points. This field binds the project tasks from different probes to be displayed in MosaicView;
tags - a string, a list of tags separated by commas. Tags are used to filter displaying on different views;
profiles - an object, a list of profile identifiers of the notification system, record settings and service availability:
- alarm - an array of integer values, an identifier of the Alarm notification triggers profile. The current implementation supports using only one profile of this type;
- email - an array of integer values, identifiers of the E-mail notification triggers profiles;
- threshold - an array of integer values, an identifier of a settings profile and thresholds. The current implementation supports using only one profile of this type;
- pagerduty - an array of integer values, profile identifiers of notification triggers to the PagerDuty system;
- record - an array of integer values, identifiers of record settings profiles;
- snmp - an array of integer values, identifiers of the SNMP notification triggers profiles;
- webhook - an array of integer values, identifiers of the Webhook notification triggers profiles;
- telegram - an array of integer values, profile identifiers of notification triggers to the Telegram messenger;
- kpi - an array of integer values, a profile identifier of service availability profile. The current implementation supports using only one profile of this type.
task_config - an object, additional information about a task and task settings. The structure is described in more detail in the section Task Configuration. Some settings should be specified through selecting thresholds profiles (see the description of the ProfileInfo method).

Reply¶

{
  "reply":[
    {
      "method":"TaskStart",
      "result":[
        {
          "task_id":(number),
          "app_id":(number),
          "uri":(string),
          "name":(string),
          "status":(string),
          "start":(string),
          "start_f":(number),
          "service":(string),
          "tags":(string),
          "profiles":{
            "alarm":[(number)],
            "email":[(number)],
            "threshold":[(number)],
            "pagerduty":[(number)],
            "record":[(number)],
            "snmp":[(number)],
            "webhook":[(number)],
            "telegram":[(number)],
            "kpi":[(number)]
          },
          "task_config":{
            ...
          }
        }
      ]
    }
  ]
}

task_id - an integer value, a task identifier;
app_id - an integer value, a probe identifier;
uri - a string, a path to an analysed stream (a service, a file);
name - a string, a stream name (e.g. a channel name);
status - a string, a task status: Scheduled - start of a task is planned. The state is assigned to tasks set using API. Further, the state changes depending on the success of a task starting;
start - a string, a task creation date and time;
start_f - a real number, a task creation date in the format of Unix time with a fractional part (to increase the accuracy);
service - a string, a service (channel) identification name used to consolidate service states and errors from different monitoring points. This field binds the project tasks from different probes to be displayed in MosaicView;
tags - a string, a list of tags separated by commas. Tags are used to filter displaying on different views;
profiles - an object, a list of profile identifiers of the notification system, record settings and service availability:
- alarm - an array of integer values, an identifier of the Alarm notification triggers profile. The current implementation supports using only one profile of this type;
- email - an array of integer values, the identifiers of the E-mail notification triggers profiles;
- threshold - an array of integer values, an identifier of a settings profile and thresholds. The current implementation supports using only one profile of this type;
- pagerduty - an array of integer values, profile identifiers of notification triggers to the PagerDuty system;
- record - an array of integer values, the identifiers of a record settings profiles;
- snmp - an array of integer values, the identifiers of the SNMP notification triggers profiles;
- webhook - an array of integer values, the identifiers of the Webhook notification triggers profiles;
- telegram - an array of integer values, profile identifiers of notification triggers to the Telegram messenger;
- kpi - an array of integer values, a profile identifier of service availability profile. The current implementation supports using only one profile of this type.
task_config - an object, additional information about a task and task settings. The structure is described in more detail in the section Task Configuration.

Example¶

Request by the cURL utility¶

#1. A simple example in which a task name and its URI are specified.
  curl http://172.16.11.111/ctrl_api/v1/json \
   -H "Content-Type: application/json" \
   --data '{"user_id":4,"methods":[{"method":"TaskStart", "params":{"project_id":23,"app_id":702,"tasks":[{"uri":"udp://239.1.1.3:1234","name":"CtrlAPI test1"}]}}]}'

#2. An example in which the following data is additionally specified: thumbnails capture options, notifications and thresholds profiles, a service name and tags. The network interface is also specified.
  curl http://172.16.11.111/ctrl_api/v1/json \
   -H "Content-Type: application/json" \
   --data '{"user_id":4,"methods":[{"method":"TaskStart","params":{"project_id":23,"app_id":702,"tasks":[{"uri":"udp://239.1.1.3:1234","name":"CtrlAPI test2","service":"Channel1","tags":"IPTV,HD,TV35","profiles":{"alarm":[79],"threshold":[96],"snmp":[263],"webhook":[265]},"task_config":{"iface":{"ip":"10.10.30.202"},"thumbnail":{"enable":true,"default_period":10,"scte35_period":1}}}]}}]}'

Part of a reply to the request #2¶

 {
   "reply":[
     {
       "method":"TaskStart",
       "result":[
         {
           "task_id":236918,
           "app_id":702,
           "uri":"udp://239.1.1.3:1234",
           "name":"CtrlAPI test2",
           "status":"Scheduled",
           "start":"2020-03-09 20:30:40 +0700",
           "start_f":1583760640.8342988,
           "service":"Channel1",
           "tags":"IPTV,HD,TV35",
           "profiles":{
             "webhook":[
               265
             ],
             "snmp":[
               263
             ],
             "threshold":[
               96
             ],
             "alarm":[
               79
             ]
           },
           "task_config":{
             "uri":"udp://239.1.1.3:1234",
             "name":"CtrlAPI test2",
             "iface":{
               "ip":"10.10.30.202"
             },
             "thumbnail":{
               "enable":true,
               "default_period":10,
               "scte35_period":1
             },
               ...
           }
         }
       ]
     }
   ]
 }