tasks

This command retrieves information about, cancels, deletes, or updates properties for one or more tasks (jobs).

Attention: Currently, tasks can be used only as an API in Python scripts. It cannot be used from the command line in a Python or interactive shell.

Syntax

tasks  -h

tasks  [-j <task_ID_list] [-c <Boolean>]

tasks  -a cancel -j <task_ID_list> 

tasks  -a create -u <properties_JSON>

tasks  -a delete -j <task_ID_list> 

tasks  -a update -u <properties_JSON>

tasks  -t <template>

Options

If no parameters are specified, this command retrieves information about all jobs.

{-h | --help}
Displays the syntax and brief usage information for this command.
{-a | --action} <action>
Specifies the action to take. This can be one of the following values. If no action is specified, this command returns information about the task.
  • cancel. Cancels the specified tasks.

  • create. Creates a task.

  • delete. Cancels the specified tasks.

  • update. Updates the job state and percent complete for the specified task.

{-j | --jobUID} <task_ID_list>
The ID of one or more tasks, separated by a comma. If no task ID is specified, information about all tasks is returned
{-c | --children} <Boolean>
Indicates whether to return information about subtasks. This can be one of the following values.
  • true. (default). Returns information about subtasks.

  • false. Does not return information about subtasks.

{-t | --template} <template>
Specifies the properties for a new task, in JSON format.
Attributes Required / Optional Type Description
args Optional Array of strings List of arguments to include in the job title
cancelRESTBody Required when cancelRESTMethod is PUT or POST Object JSON formatted request body that is required to cancel the job, specified as a key-value pairs
cancelRESTMethod Required when cancelURL is specified String REST method to cancel the job. This can be one of the following values.
  • GET

  • POST

  • PUT

  • DELETE

cancelURL Optional String URL to cancel the job
children Required Array of objects Information about each subtask in the job (task)

The attributes in this object are the same as the top-level attributes.

createdBy Required String ID of the user that created the subtask. To obtain the user ID, see the GET /userAccounts REST API.
createDate Required String Date and time that the job was created
customUid Optional String User-defined job ID

The response body associates the user-defined job ID with the job UID that is assigned by XClarity Administrator.

endDate Optional String Date and time that the job completed
expirationTimeOut Required when cancelURL is specified Integer Number of seconds after which the job expires. Use -1 for jobs that do not expire.
jobCategory Required String Subtask category. This can be one of the following values.
  • Backup
  • Configuration
  • Custom
  • Firmware
  • Health
  • Inventory
  • Management
  • OsDeployment
  • OsDriverUpdates
  • OsImport
  • OsProfileExport
  • Power
  • RemoteAccess
  • SelfMaintenance
  • Service
  • SwitchConfiguration
  • SystemID
  • Unknown
jobState Required String State of the job. This can be one of the following values.
  • Aborted
  • Blocked
  • Cancelled
  • CancelledWithError
  • CancelledWithWarning
  • Cancelling
  • Complete
  • CompleteWithError
  • CompleteWithWarning
  • Expired
  • Initializing
  • Interrupted
  • InterruptedWithError
  • InterruptedWithWarning
  • Investigating
  • Pending
  • Resolved
  • Running
  • RunningWithError
  • RunningWithWarning
  • Skipped
  • Stopped
  • StoppedWithError
  • StoppedWithWarning
  • Unknown
  • Uploading
  • Validating
  • Waiting
jobSummary Required Object Information about the job summary
A job summary consists of the following attributes:
  • Description. Describes the problem (message) in a small phrase.
  • User action. Provides details about the problem and the steps to perform to recover from the problem. Provide as much detail as possible to help the user resolve the problem without contacting Lenovo Support.
  • Severity. The severity of the job.

The job summary is optional for a job that completes successfully; however, it is good practice to set the summary, even when the severity is informational.

  actionArgs Optional Array of strings List of arguments (variables) to include the recovery actions
  actionBundleKey Required String Key for the recovery actions in the translated message.properties file
  actionBundleName Required String Name of the translated message.properties file that contains the recovery actions
  actionText Required String Recovery actions to use if there is no translation
The actions can be simple text or formatted text (such as paragraphs, ordered lists, and bold text) using an array of JSON objects with the following attributes.
  • format. (Array of strings) List of formats for the text. This can be one of the following values.

    • bold. Corresponds to the <b> HTML tag.
    • italic. Corresponds to the <i> HTML tag.
    • underline. Corresponds to the <u> HTML tag.
    • link. Corresponds to the <a> HTML tag.
    • newline. Corresponds to the <br> HTML tag.
    • paragraph. Corresponds to the <p> HTML tag.
    • quotation. Corresponds to the <q> HTML tag.
    • orderedList. Corresponds to the <ol> HTML tag.
    • bulletList. Corresponds to the <ul> HTML tag.
    • listElement. Corresponds to the <li> HTML tag.
  • link. (String) URL to be linked to

  • text. (String or Array of strings) Text to be formatted

For example:
['{' 
  "text": "A simple paragraph.", 
   "format": [] 
'}', 
'{' 
  "text": [], 
  "format": ["newline"] 
'}', 
'{' 
  "text": ['{' 
    "text": "Segment pieces to format.", 
    "format": ["listElement"] 
  '}',  
  '{' 
    "text": ['{' 
      "text": "If the segmented text contains ", 
      "format": [] 
    '}', 
    '{' 
      "text": "multiple tags", 
      "format": ["bold"] 
    '}',   
    '{' 
      "text": ", segment them as well.", 
      "format": [] 
    '}' ], 
    "format": ["listElement"] 
  '}', 
  "format": ["orderedList"]
'}']
  descriptionArgs Required Array of strings List of arguments (variables) to include the message description
  descriptionBundleKey Required String Key for the message description in the translated message.properties file
  descriptionBundleName Required String Name of the translated message.properties file that contains the message description
  descriptionText Required String Message description to use if there is no translation
The description can be simple text or formatted text (such as paragraphs, ordered lists, and bold text) using an array of JSON objects with the following attributes.
  • format. (Array of strings) List of formats for the text. This can be one of the following values.

    • bold. Corresponds to the <b> HTML tag.
    • italic. Corresponds to the <i> HTML tag.
    • underline. Corresponds to the <u> HTML tag.
    • link. Corresponds to the <a> HTML tag.
    • newline. Corresponds to the <br> HTML tag.
    • paragraph. Corresponds to the <p> HTML tag.
    • quotation. Corresponds to the <q> HTML tag.
    • orderedList. Corresponds to the <ol> HTML tag.
    • bulletList. Corresponds to the <ul> HTML tag.
    • listElement. Corresponds to the <li> HTML tag.
  • link. (String) URL to be linked to

  • text. (String or Array of strings) Text to be formatted

For example:
['{' 
  "text": "A simple paragraph.", 
   "format": [] 
'}', 
'{' 
  "text": [], 
  "format": ["newline"] 
'}', 
'{' 
  "text": ['{' 
    "text": "Segment pieces to format.", 
    "format": ["listElement"] 
  '}',  
  '{' 
    "text": ['{' 
      "text": "If the segmented text contains ", 
      "format": [] 
    '}', 
    '{' 
      "text": "multiple tags", 
      "format": ["bold"] 
    '}',   
    '{' 
      "text": ", segment them as well.", 
      "format": [] 
    '}' ], 
    "format": ["listElement"] 
  '}', 
  "format": ["orderedList"]
'}']
  severity Required String Severity of the job. This can be one of the following values.
  • Unknown. The severity is unknown.
  • Informational. The activity started or ended successfully.
  • Warning. The activity completed, but there are some problems that the user must be aware of (for example, Windows was deployed but failed to set the IP addresses successfully). The user can decide if action is needed.
  • Minor. Action is needed, but the situation is not serious at this time.
  • Major. Action is needed now.
  • Critical. The activity failed. Action is needed now and the scope is broad (perhaps an imminent outage to a critical resource will result).
  • Fatal. The activity failed. A non-recoverable error has occurred.
jobTitle Required String Job title to use if there is no translation
jobTitleBundle Required String Location of the message.properties file where the job title can be found if it is not located in the default task-management properties file.

The key that identifies the job title in the properties file.

jobTitleKey Required String Key that identifies the job title in the message.properties file
logs Required Array of objects Information about each log entry
  args Optional Array of strings Arguments of the message
  logBundleName Required String Location where messages.properties can be found if it is not located in the default task-management properties file
  logBundleKey Required String Key that identifies the job title in the message.properties file
  logDate Optional String Log date
  logText Required String User-defined log text
  severity Required String Severity of this log. This can be one of the following values.
  • Unknown. The severity is unknown.
  • Informational. The activity started or ended successfully.
  • Warning. The activity completed, but there are some problems that the user must be aware of (for example, Windows was deployed but failed to set the IP addresses successfully). The user can decide if action is needed.
  • Minor. Action is needed, but the situation is not serious at this time.
  • Major. Action is needed now.
  • Critical. The activity failed. Action is needed now and the scope is broad (perhaps an imminent outage to a critical resource will result).
  • Fatal. The activity failed. A non-recoverable error has occurred.
percentage Optional String Percentage complete of the subtask. This can be an integer from 0 - 100.
predefinedUid Optional String Job ID that is defined by the component that requested the job
rebootPersistet Optional Boolean Indicates whether an active job persists after a reboot. This can be one of the following values.
  • true. (default) The state of the job is not changed after a reboot.

  • false. The job state changes to Interrupted after a reboot.

startDate Optional String Date and time that the job started
stoppedBy Optional String ID of the user that stopped the job
targetUUID Required String ID of the device that is the target for the job.
uid Optional String Job ID
weight Optional String Weight of the job, which is used to update the percent complete

Jobs that take a long time to complete have a higher weight than fast jobs.

The following example creates a task with no subtasks.
{
   "children": [],
   "createdBy": "ADMIN",
   "createDate": "2019-02-27T16:26:01Z",
   "jobCategory": "Configuration",
   "jobState": "Running",
   "jobSummary": {
      "actionBundleKey": "",
      "actionBundleName": "",
      "actionText": "",
      "descriptionArgs": [],
      "descriptionBundleKey": "",
      "descriptionBundleName": "",
      "severity": ""
   },
   "jobTitle": "",
   "jobTitleBundle": "com.lenovo.lxca.profile.mri.ConfigurationPatternsMRI",
   "jobTitleKey": "SERVER_PROFILE_JOB_NAME",
   "logs": [{
      "logBundleKey": "",
      "logBundleName": "",
      "logText": "",
      "severity": ""
   }],
   "targetUUID": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"
}
{-u | --updateList} <properties_JSON>
Specifies the properties and tasks to update, in JSON format.
Parameter Required / Optional Type Description
jobUID Required String Job ID
jobState Optional String Job state. This can be one of the following values.
  • Aborted
  • Blocked
  • Cancelled
  • CancelledWithError
  • CancelledWithWarning
  • Cancelling
  • Complete
  • CompleteWithError
  • CompleteWithWarning
  • Expired
  • Initializing
  • Interrupted
  • InterruptedWithError
  • InterruptedWithWarning
  • Investigating
  • Pending
  • Resolved
  • Running
  • RunningWithError
  • RunningWithWarning
  • Skipped
  • Stopped
  • StoppedWithError
  • StoppedWithWarning
  • Unknown
  • Uploading
  • Validating
  • Waiting
percentage Optional Integer Percentage complete
For example:
[{
   "jobUID": "127"
   "jobState": "Validating",
   "percentage": 95
}]

Examples

The following example returns information about a specific task and also its subtasks.
connect --url https://192.0.2.0 --user ADMIN -noverify 
tasks –j 127
The following example returns information about a specific task but not the subtasks.
connect --url https://192.0.2.0 --user ADMIN -noverify 
tasks –j 127 –c false
The following example cancels multiple tasks.
connect --url https://192.0.2.0 --user ADMIN -noverify 
tasks –a cancel –j 127, 140
The following example deletes a specific task.
connect --url https://192.0.2.0 --user ADMIN -noverify 
tasks –a cancel –j 127
The following example updates the job state and percent complete for multiple tasks.
connect --url https://192.0.2.0 --user ADMIN -noverify 
tasks –a update –u '[{"jobUID":"127","jobState":"Validating","percentage":50}, {"jobUID":"140", 
                      "jobState":"Complete","percentage":100}]'

Related links