5.6.5. TaskChangeConfig

Description

Configuring running tasks.

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.

Settings changes are only passed by the method, the rest of the settings remain unchanged.

Important

Some task settings cannot be changed due to the probe architecture:
task_id - a task identifier;
uri or addr - a path to an analysed stream (a service, a file);
ottAllRenditions - the mode of OTT analysis (Player|AllRenditions).
Stop the current task and start a new task with correct settings.

Important

For OTT services analysis: configuration can be changed only for a parent task (the Master tab on a task page in the Boro interface). Settings for child tasks are updated automatically.

Request

{
  "user_id":(number),
  "methods":[
    {
      "method":"TaskChangeConfig",
      "params":{
        "project_id":(number),
        "task_ids":[(number)],
        "changes":{
          "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;

  • task_ids - task identifiers, the field can be specified in one of the following formats:
    id1 - an integer value, a task identifier;
    [id1,id2] - an array of integer values, task identifiers.

  • changes - an object, a list of new settings. Settings changes are only passed by the method, the rest of the settings remain unchanged;

  • 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, 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. Some settings should be specified through selecting thresholds profiles (see the description of the ProfileInfo method).

Reply

{
  "reply":[
    {
      "method":"TaskChangeConfig",
      "result":{
        "task_ids":[(number)],
        "description":"Config change request was sent to probe",
        "changes":{
          ...
        }
      }
    }
  ]
}

  • task_ids - an array of integer values, task identifiers;

  • changes - an object, a list of new settings that had been validated on the server and were sent to the probe. The object content description is similar to the description of the changes object in the Request section above.

Errors

{
  "reply":[
    {
      "method":"TaskChangeConfig",
      "errors":{
        ...
      }
    }
  ]
}

The errors object may contain the following errors:

  • immutable_fields - an array of strings, a list of settings that cannot be changed ['taskId', 'addr', 'allIndexHLS', 'ottAllRenditions']. Stop the current task and start a new task with correct settings;

  • change_with_threshold - an array of strings, a list of settings belonging to a threshold profile. These settings can be set only by selecting one of the preset thresholds profiles;

  • incorrect_value - an array of strings, a list of settings with incorrect values;

  • unable_change_tasks - an array of integers, a list of task identifiers for which a method cannot be executed (a task with the specified ID does not exist, has not been started or belongs to another project);

  • unable_change_subtasks - an array of integers, a list of subtask identifiers. While analysing OTT service, settings can be changed only in a parent task;

  • no_changes_for_tasks - an array of integers, a list of task identifiers. A method does not contain correct settings changes.

Example

Request by the cURL utility for changing a configuration
#1. Request for one task: changing a task name and a list of tags
  curl http://172.16.11.111/ctrl_api/v1/json \
   -H "Content-Type: application/json" \
   --data '{"user_id":4,"methods":[{"method":"TaskChangeConfig","params":{"project_id":23,"task_ids":241555,"changes":{"tags":"HD,IPTV","name":"NewTask"}}}]}'

#2. Request for several tasks: changing a list of tags; enabling Thumbnail Capture and Video Freeze Detection
  curl http://172.16.11.111/ctrl_api/v1/json \
   -H "Content-Type: application/json" \
   --data '{"user_id":4,"methods":[{"method":"TaskChangeConfig","params":{"project_id":23,"task_ids":[241555,241630],"changes":{"tags":"HD, IPTV","profiles":{"alarm":390},"task_config":{"thumbnail":{"enable":true,"default_period":5},"freeze":{"enable":true}}}}}]}'
Reply to the request #2
 {
   "reply":[
     {
       "method":"TaskChangeConfig",
       "result":{
         "task_ids":[
           241555,
           241630
         ],
         "description":"Config change request was sent to the probe",
         "changes":{
           "tags":"HD, IPTV",
           "profiles":{
             "alarm":390
           },
           "task_config":{
             "thumbnail":{
               "enable":true,
               "default_period":5
             },
             "freeze":{
               "enable":true
             }
           }
         }
       }
     }
   ]
 }