KSC Open API  13.1
Kaspersky Security Center API description
Task settings format
Parameter nameTypeOptionalityDescription
"TASKID_COMPONENT_NAME"paramStringRequiredName of component.
"TASKID_PRODUCT_NAME"paramStringRequiredName of product.
"TASKID_VERSION"paramStringRequiredVersion of product.
"TASK_NAME"paramStringRequiredName of task type. See Tasks of Administration Server and Network Agent.
"DisplayName"paramStringRequiredTask display name. Contained in "TASK_INFO_PARAMS". 100 characters max.
"TASK_ADDITIONAL_PARAMS"paramParamsRequiredContainer (paramParams) with task type-dependent settings. See Tasks of Administration Server and Network Agent.
"KLPRCI_TASK_INVISIBLE"paramBoolOptionalThe parameter accepts true if the task is invisible in Administration Console.
Contained in "TASK_ADDITIONAL_PARAMS".
"KLPRTS_START_CONDITION"paramParamsOptionalContainer (paramParams) with additional conditions to start the task for specific custom schedules. See Task start conditions.
"TASK_INFO_PARAMS"paramParamsRequiredContainer (paramParams) with task type-independent settings.
"TASKSCH_TYPE"paramIntRequiredType of schedule. See Schedule types
"klprts-TaskScheduleSubtype"paramIntRequiredSubtype of schedule. Contained in "TASK_INFO_PARAMS".
"TASK_DEL_AFTER_RUN_FLAG"paramBoolOptionalThe parameter accepts true if a task will be deleted from the scheduler (not from disk) after run.
"PRTS_TASK_ENABLED"paramBoolOptional

Task "enabled" flag.

Warning:
This parameter is obsolete. We do not recommend to use it.
"PRTS_TASK_GROUPID"paramIntOptionalID of the administration group (see HostGroup interface) for a group task.
This attribute is absent or equal to -1 for a computer-set task.
Contained in "TASK_INFO_PARAMS".
"PRTS_EXCEPT_GROUPIDS"paramArrayOptional

Contains integer ID of administration groups to exclude from the task scope. Contained in "TASK_INFO_PARAMS".

"KLHST_WKS_CTYPE"paramIntOptional

Target computer types. May have the following values:

  • 1 Add workstations to the task scope.
  • 2 Add servers to the task scope.
  • 3 Add both servers and workstations to the task scope.

Contained in "TASK_INFO_PARAMS".

".HstQueryId"paramIntOptionalHosts query identity (for a task based on a hosts query; group identity "PRTS_TASK_GROUPID" for this task should be -1).
Should be 0 or absent for other tasks.
Contained in "TASK_INFO_PARAMS".
"HostList"paramArrayOptionalList of hosts (in case of task for set of computers; group identity "PRTS_TASK_GROUPID" for such task should be -1, ".HstQueryId" should absent or be equal to 0).
Every entry should contain either the "HostName" parameter (to identify an existing host, see KLHST_WKS_HOSTNAME attribute, in priority) or "HostDispName" parameter (to identify the host by its display name, see KLHST_WKS_DN attribute). An additional entry may contain the "Preliminary" parameter, which should be set to true if this target host should be used for a preliminary start; otherwise, it should be false. Sample:
            +---0 (paramParams)
                +---HostName = (paramString)"295ce3ac-f4b7-47e9-a7a5-b6aa7cb74e66"
            +---1 (paramParams)
                +---HostName = (paramString)"638168dc-735d-40af-88a5-b2f28eea6e99"
            +---2 (paramParams)
                +---HostDispName = (paramString)"Host3"
                +---Preliminary = (paramBool)true
            +---3 (paramParams)
                +---HostDispName = (paramString)"Host4"
                +---Preliminary = (paramBool)false
Contained in "TASK_INFO_PARAMS".
"KLPRSS_EVPNotifications"paramParamsOptionalNotification settings for changing the state of a task. See KLPRSS_EVPNotifications description.
Contained in "TASK_INFO_PARAMS".
"KLTSK_ALLOW_AUTO_RANDOMIZATION"paramBoolOptional

The parameter accepts true if Administration Server calculates the task randomization period by itself. Contained in "TASK_INFO_PARAMS".

Option is disabled in UI in the following cases:

  • Task product name == "1093".
  • Task is local, and "TASKSCH_TYPE" == 0x100.
  • "TASKSCH_TYPE" == 0x800.
"TASK_START_DELTA"paramIntOptional

Randomization value. Contained in "TASK_INFO_PARAMS".

Option is disabled in UI in the following cases:

  • "KLTSK_ALLOW_AUTO_RANDOMIZATION" == true.
  • Task product name == "1093".
"TASKSCH_RUN_MISSED_FLAG"paramBoolOptional

Option to execute the task if the time to run is missed. Contained in "TASK_INFO_PARAMS".

Option is disabled in UI in the following cases:

  • Task product name == "1093".
  • Task is local, and one of the following conditions is met:
    • "TASKSCH_TYPE" == 0x100.
    • "TASKSCH_TYPE" == 0x80.
    • "TASKSCH_TYPE" == 0x1000.
    • "TASKSCH_TYPE" == 0x200.
    • "TASKSCH_TYPE" == 0x800.
    • "TASKSCH_TYPE" == 0x40000.
"klprts-WakeOnLAN"paramIntOptionalNumber of milliseconds from Wake remote computer on LAN until starting the task. Valid range 60000-59940000 (1-999 min), or 0 when function is disabled. Contained in "TASK_INFO_PARAMS". Option is disabled in UI when:
  • Plug-in registry key KLCSR_SERVER_SIDE_TASK is 0 OR
  • "TASKSCH_TYPE" == 0x80 OR "TASKSCH_TYPE" == 0x1000 OR "TASKSCH_TYPE" == 0x200 OR "TASKSCH_TYPE" == 0x800
"klprts-ShutdownSystemAfterRun"paramBoolOptionalThe computer must be shut down after task execution. Contained in "TASK_INFO_PARAMS". Option is disabled in UI when:
  • Plug-in registry key KLCSR_SERVER_SIDE_TASK is 0 OR
  • "TASK_NAME" == "Remote Installation" OR "TASK_NAME" == "Remote Deinstallation"
"klprts-TaskMaxRunningTime"paramIntOptionalMaximum duration of a task execution in milliseconds. Valid range 60000-59940000 (1-999 min), or 0 when function is disabled. Contained in "TASK_INFO_PARAMS". Option is disabled in UI when:
  • Plug-in registry key (KLCSR_PRODUCT_CTRL_BUTTONS & 2) == 0 OR
  • Plug-in registry key KLCSR_RESIDENT_TASK is 1
"klprts-TaskCannotBeDeleted"paramBoolOptionalIf the value is 'true', the user cannot delete the task. Contained in "TASK_INFO_PARAMS".
"TASKSCH_FIRST_EXECUTION_TIME"paramDateTimeOptionalTime when the task must be executed for the first time, in UTC.
"TASKSCH_FIRST_EXECUTION_TIME_SEC"paramIntOptionalMilliseconds of TASKSCH_FIRST_EXECUTION_TIME.
"TASK_PRIORITY"paramIntOptionalPriority of thread of task execution.
"TASKSCH_LIFETIME"paramDateTimeOptionalValidity period of schedule, in UTC.
"TASK_MAX_EXEC_TIME"paramIntOptional

Limit for execution time, in milliseconds.

"TASK_LAST_EXEC_TIME"paramDateTimeOptionalLast execution time, in UTC.
"TASK_LAST_EXEC_TIME_SEC"paramIntOptional

Last execution time, in milliseconds.

"TASK_PREP_START"paramIntOptionalStart preparing for N milliseconds before the main start.
"TASKSCH_MS_PERIOD"paramIntOptionalUsed for setting schedule. Task execution period, in seconds.
"TASKSCH_ED_HOURS"paramIntOptionalHours. Used in daily schedule.
"TASKSCH_ED_MINS"paramIntOptionalMinutes. Used in daily schedule.
"TASKSCH_ED_SECS"paramIntOptionalSeconds. Used in daily schedule.
"TASKSCH_EW_DAY"paramIntOptionalDays. Used in weekly schedule. A week day: 0->Sunday, ... 6->Saturday.
"TASKSCH_EW_HOURS"paramIntOptionalHours. Used in weekly schedule.
"TASKSCH_EW_MINS"paramIntOptionalMinutes. Used in weekly schedule.
"TASKSCH_EW_SECS"paramIntOptionalSeconds. Used in weekly schedule.
"TASKSCH_EM_DAY"paramIntOptionalDays. Used in monthly schedule. Day of the month when the task should be run (1-31).
"TASKSCH_EM_HOURS"paramIntOptionalHours. Used in monthly schedule.
"TASKSCH_EM_MINS"paramIntOptionalMinutes. Used in monthly schedule.
"TASKSCH_EM_SECS"paramIntOptionalSeconds. Used in monthly schedule.
"PRTS_TASK_TARGET_COMPUTERS_TYPE"paramIntOptional

Type of managed devices. Auxiliary parameter used in GUI only. Contained in "TASK_INFO_PARAMS". Possible values:

  • 0 - Managed devices scanned by KSC
  • 1 - Managed devices addresses provided by the user
  • 2 - KSC's device query
  • 3 - Administration group

Defaults: If PRTS_TASK_GROUPID == -1 then default value is 0, otherwise - 3

"PRTS_TASK_GROUPNAME"paramStringOptionalDisplay name of an administration group. It's a part of 'TASK_INFO_PARAMS' (filled only if the task data is received from the server implementations of TasksStorage, for optimization purposes only).
"klprts-DontApplyToSlaveServers"paramBoolOptionalMeans that a task cannot be spread over secondary servers. It's a part of 'TASK_INFO_PARAMS'.
"klprts-TaskAccountUser"paramStringOptionalAccount name. For some tasks, it can be in the klprts-TaskAccounts array. See List of deployment task attributes.
"klprts-TaskAccountPassword"paramBinaryOptional

Password for encrypted account. See How sensitive data must be protected.

For some tasks, it can be in the klprts-TaskAccounts array. See List of deployment task attributes.

Task settings example: 

    +---TASK_NAME
    +---TASKID_COMPONENT_NAME
    +---TASKID_PRODUCT_NAME
    +---TASKID_VERSION
    +---TASK_DEL_AFTER_RUN_FLAG
    +---TASK_ADDITIONAL_PARAMS
        +---KLPRTS_START_CONDITION
            +---KLPRTS_START_CONDITION_TYPE
            +---... <depending on the KLPRTS_START_CONDITION_TYPE value>
        +---... <depending on the task type>
    +---TASK_INFO_PARAMS
        +---DisplayName
        +---PRTS_TASK_ENABLED
        +---PRTS_TASK_GROUPID
        +---KLPRSS_EVPNotifications
        +---KLTSK_ALLOW_AUTO_RANDOMIZATION
        +---PRTS_EXCEPT_GROUPIDS
        +---KLHST_WKS_CTYPE
        +---...
    +---TASKSCH_FIRST_EXECUTION_TIME
    +---TASK_MAX_EXEC_TIME
    +---...
    


 Types of schedule. 

 





Launch type"TASKSCH_TYPE""klprts-TaskScheduleSubtype""klprts-TaskScheduleSubtypeEx"Required Parameters 



Manual00x100-



Immediately50x200-Flag TASK_DEL_AFTER_RUN_FLAG must be set to "true". 



Once50x40-"TASKSCH_FIRST_EXECUTION_TIME" - Time of first execution of task. Flag TASK_DEL_AFTER_RUN_FLAG must be set to "true". 



Every N hours50x1-"TASKSCH_FIRST_EXECUTION_TIME" - Time of first execution of task.

 "TASKSCH_MS_PERIOD" - Count of seconds, divisible on 3600.

  



Every N days, beginning from a day and time20x2-"TASKSCH_ED_HOURS" - Start hour.

 "TASKSCH_ED_MINS" - Start minute.

 "TASKSCH_ED_SECS" - Start second.

 "TASKSCH_MS_PERIOD" - Execution period, in days.

  



Every N days, beginning from a date and time20x100000-"TASKSCH_ED_HOURS" - Start hour.

 "TASKSCH_ED_MINS" - Start minute.

 "TASKSCH_ED_SECS" - Start second.

 "TASKSCH_FIRST_EXECUTION_TIME" - Date of first execution of task, in UTC.

 "TASKSCH_MS_PERIOD" - Execution period, in days.

  



Every N weeks, beginning from a date30x4-"TASKSCH_FIRST_EXECUTION_TIME" - Time of first task execution.

 "TASKSCH_MS_PERIOD" - Weeks.

  



Daily50x8-"TASKSCH_FIRST_EXECUTION_TIME"

 "TASKSCH_MS_PERIOD" - Task execution period, in seconds. Displayed in the UI in days (divided by 24*60*60)

  



Weekly30x10-"TASKSCH_EW_DAY" - Day of the week: 0->Sunday, ... 6->Saturday.

 "TASKSCH_EW_HOURS"

 "TASKSCH_EW_MINS"

 "TASKSCH_EW_SECS"

  



Monthly40x20-"TASKSCH_EM_DAY" - Day of the month when the task should be run (1-31).

 "TASKSCH_EM_HOURS"

 "TASKSCH_EM_MINS"

 "TASKSCH_EM_SECS"

  



On start of a component00x80-"EVENT_TYPE" = "KLBLAG_EV_ONAPPSTART"  



Every N minutes, beginning from a date50x400-"TASKSCH_FIRST_EXECUTION_TIME" - Time of first execution of task.

 "TASKSCH_MS_PERIOD" = Execution period, in seconds.

  



Start task after client's Update task is completed.00x800-



Start after N seconds after the product starts00x1000-"klprts-DelayOnAppTaskStart" = Execution delay in minutes.

  



No user-editable schedule00x2000-



After the Administration Server's update retranslation task completes00x1000x4000
+---"KLPRTS_START_CONDITION" - See Task start conditions
    +---"KLPRTS_START_CONDITION_TYPE" = 1
        
  



On virus outbreak event00x1000x8000
+---"KLPRTS_START_CONDITION" - See Task start conditions
    +---"KLPRTS_START_CONDITION_TYPE" = 2
    +---"KLPRTS_START_CONDITION_VALUE" = See virus outbreak source in Task start conditions
        
  



After another task completes00x1000x10000
There are two options, depending of the following conditions:


Controlled task - Task that is scheduled to start after the execution of the controlling task.


bServerExecutedTask = (ProductNameOf_ControlledTask == KLCS_PRODUCT_ADMSERVER && !GetRegFlag(TS_SERVERSIDETASK))


If (bServerExecutedTask == TRUE || ProdNameOf_ControllingTask == "1093"), then use the format for server's tasks. Otherwise, use the format for the client's tasks.


    

  • For server's tasks 
        +---"KLPRTS_START_CONDITION" - See Task start conditions
        +---"KLPRTS_START_CONDITION_TYPE" = 3
        +---"KLPRTS_START_CONDITION_VALUE_EX" - See Task states
        +---"KLPRTS_START_CONDITION_VALUE" - Group task ID
        +---"KLPRTS_START_CONDITION_VALUE2" - Task ID in KLPRTS::TasksStorage
    
    • 

  • For client's tasks
    
 
        +---"EVENT_TYPE" = "KLPRCI_TaskState"
    +---"EVENT_BODY_FILTER" - Parameters
        +---"KLPRCI_TASK_TS_ID" - Task ID in KLPRTS::TasksStorage
        +---"KLPRCI_newState" - See Task states
        
      
    • 






Weekly, at a certain day and time.00x1000x20000
If "TASKSCH_WEEKSDAYS" exists and "TASKSCH_WD_DAYS" <> is 0, we have a weekly execution schedule
+---"TASKSCH_WEEKSDAYS" - Parameters in parTaskInfo
    +---"TASKSCH_WD_DAYS" - Days when task should be run. This is a bitmask, meaningful bits 1-7. Sunday is 1, Monday (1 << 1) = 2, Tuesday (1 << 2) = 4. Bits may be OR-ed.
    +---"TASKSCH_WD_HOURS" - Time when the task should be run - hour   (0-23).
    +---"TASKSCH_WD_MINS" - Time when the task should be run - minute (0-59).
    +---"TASKSCH_WD_SECS" - Time when the task should be run - second (0-59).
        
  



Controlled by application00x1000x40000



Months Days Schedule. see KLSCH::MonthsDaysSchedule70x1000x80000
"TASKSCH_MD_DAYS" - Days when the task should be run.
    This is a bitmask of first four weeks of a month (4*7=28 bits total),
    first bit is Sunday of first week, second bit is Monday of first week, etc.
    Bits may be OR-ed.
    Some examples:
    First Sunday of a month                 0000000 0000000 0000000 0000001 = 1
    Second Monday of a month                0000000 0000000 0000010 0000000 = 256
    First Sunday and second Monday of month 0000000 0000000 0000010 0000001 = 257
"TASKSCH_MD_LAST_WEEK" - Days of last week of a month. Bitmask with 7 meaningful bits.
    First bit means last Sunday of a month, second bit means last Monday of a month, etc.
    Example:


    Last Thursday of a month                0010000 = 16


"TASKSCH_MD_HOURS" - Time when the task should be run - hour (0-23).


"TASKSCH_MD_MINS" - Time when the task should be run - minute (0-59).


"TASKSCH_MD_SECS" - Time when the task should be run - second (0-59).


        
  






 Notification settings for changing the state of the task (see KLPRSS_EVPNotifications description). 

 


    +---TASK_INFO_PARAMS
        +---...
        +---KLPRSS_EVPNotifications
            +---ERR
                +---0
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLPRCI_TaskState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
            +---INF
                +---0
                    +---KLEVP_ND_BODY_FILTER
                       +---KLPRCI_newState = 2
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLPRCI_TaskState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
                +---1
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLEVP_GroupTaskSyncState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
                +---2
                    +---KLEVP_ND_BODY_FILTER
                    |   +---KLPRCI_newState = 4
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLPRCI_TaskState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
                +---3
                    +---KLEVP_ND_BODY_FILTER
                    |   +---KLPRCI_newState = 1
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLPRCI_TaskState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
        +---WRN
                +---0
                    +---KLEVP_ND_DAYS_TO_STORE_EVENT = 7
                    +---KLEVP_ND_EVETN_TYPE = "KLPRCI_TaskState"
                    +---KLEVP_ND_STORE_AT_CLIENT_LOG = false
                    +---KLEVP_ND_STORE_AT_CLIENT_PRES = false
                    +---KLEVP_ND_STORE_AT_SERVER_LOG = false
        
 The above snippet describes the rules for processing two types of events: KLPRCI_TaskState and KLEVP_GroupTaskSyncState. The processing method depends on the severity (ERR, INF, WRN) of a specific event and its content (KLPRCI_newState). See Events notification settings. 

 





Parameter nameTypeDescription 



"KLEVP_ND_DAYS_TO_STORE_EVENT"paramIntTime limit (in days) for storing in database. 



"KLEVP_ND_EVETN_TYPE"paramStringType of event. 



"KLEVP_ND_STORE_AT_CLIENT_LOG"paramBoolStore event in event log on a host. 



"KLEVP_ND_STORE_AT_CLIENT_PRES"paramBoolMust be set to false. 



"KLEVP_ND_STORE_AT_SERVER_LOG"paramBoolStore event in event log on the server. 



"KLEVP_ND_BODY_FILTER"paramParamsFilter on content of event.