1.6.9 listtasks (outputting the list of tasks and the detailed task information)

Description

The functionality of the listtasks command is as follows:

Outputting the list of tasks or task histories

If you execute the listtasks command by specifying tasks for the output option, you can output the task information displayed in the list of tasks in the Tasks window in a CSV-formatted file. Alternatively, if you execute the command by specifying histories for the output option, you can output the task information displayed in the list of histories in the Tasks window in a CSV-formatted file. Note that debug tasks are not output to either of the CSV files.

In addition, you can specify a period to filter the task information to be output.

Outputting the detailed task information

If you execute the listtasks command by specifying taskdetails for the output option, the detailed task information including input property and output property values is output to the detailed task information storage folder. Note that the detailed information on the debug tasks is not output.

If you execute the submittask command based on the detailed task information^# output by the listtasks command, you can re-register the scheduled tasks and recurring tasks with the same setting in a batch.

#

This detailed task information does not include the definition information (service, service template, user, user group, service group, connection destinations, service share properties) and the definition file. Use the backupsystem command to back up those pieces of information.

Syntax

listtasks
     [/startrange {yyyy-mm-dd|,yyyy-mm-dd|yyyy-mm-dd,yyyy-mm-dd}]
     /output {tasks | histories | taskdetails}
      {/file output-file-path |/taskdetaildir detailed-task-information-storage-folder-path}
     [/encoding {UTF-8 | Shift_JIS}]
     /user user-ID
     {/password password | /passwordfile password-file-path}

Arguments

/startrange {yyyy-mm-dd|,yyyy-mm-dd|yyyy-mm-dd,yyyy-mm-dd}

This option specifies the start date or scheduled start date of tasks to filter the tasks to be output.

yyyy must have a four-digit year in half-width numeric characters. mm must have a month from 1 (or 01) to 12 in half-width numeric characters. dd must have a day from 1 (or 01) to 31 in half-width numeric characters.

• yyyy-mm-dd

  This option causes the command to output the tasks that started or are scheduled to start on and after the specified date.

• ,yyyy-mm-dd

  This option causes the command to output the tasks that started or are scheduled to start on and before the specified date.

• yyyy-mm-dd,yyyy-mm-dd

  This option causes the command to output the tasks that started or are scheduled to start within the specified period. The date on the right side of , can accept any date on and after the date specified on the left side.

For recurring tasks, tasks scheduled to start up to the next time are output, and any tasks scheduled to start subsequently are not output.

If you want to output waiting tasks, specify a scheduled date and time instead of a start data and time if the tasks are recurring and scheduled tasks. If they are immediate tasks, specify a submitted data and time. You can check the submitted date and time in the Task Details window.

If this option is omitted, all the tasks viewable to users are output.

Note that an error occurs if you specify the startrange option when taskdetails is specified for the output option.

/output {tasks | histories | taskdetails}

This option specifies which one of the following information is output in the list:

• tasks

  Outputs the list of tasks from the Tasks window.

• histories

  Outputs the list of histories from the Tasks window.

• taskdetails

  Outputs the detailed task information including the input property and output property values.

{/file output-file-path |/taskdetaildir detailed-task-information-storage-folder-path}

• /file output-file-path

  This option specifies the absolute or relative path to the file in which the list is output. An error occurs if the specified file exists.

  This option is required if tasks or histories is specified for the output option. An error occurs if this option is specified when taskdetails is specified for the output option.

• /taskdetaildir detailed-task-information-storage-folder-path

  This option specifies the absolute or relative path to an empty folder to which the detailed task information is output. Note that only a folder on the local disk can be specified. The number of characters that can be specified is no more than 180 characters for the absolute path. If the relative path is used, the path being converted to the absolute path must be no more than 180 characters.

  An error occurs if the specified folder does not exist, or the specified folder already contains a file or folder.

  This option is required if taskdetails is specified for the output option. An error occurs if this option is specified when tasks or histories is specified for the output option.

/encoding {UTF-8 | Shift_JIS}

This option specifies the encoding of the output file. If this option is omitted, the default encoding of the OS is used.

If taskdetails is specified for the output option, the encoding specified here is applied only to the task list file (listtasks.csv) located directly under the detailed task information storage folder. The detailed task information, property file (input property file), and output property file are always output in UTF-8.

/user user-ID

This option specifies the user ID for JP1/AO.

The number of possible characters is in the range from 1 to 256 characters.

The possible characters are half-width alphanumeric characters, !, #, $, %, &, ', (, ), *, +, -, ., =, @, \, ^, _, and |.

This option is not case sensitive.

/password password

This option specifies the password of the user indicated by the user option.

You must specify either this option or the passwordfile option. If both options are specified, or if neither are specified, then you will get an error.

The number of possible characters is in the range from 1 to 256 characters.

The possible characters are the same as those for the user option.

/passwordfile password-file-path

This option specifies the absolute or relative path to the password file for the user specified in the user option. You can create a password file by using the encryptpassword command.

You must specify either this option or the password option. If both options are specified, or if neither are specified, then you will get an error.

Output format

The format of output from the listtasks command is as follows:

When outputting the list of tasks and histories (when tasks or histories is specified for the output option)

The output items are output in a single line per task in CSV format.

The values for each output item are enclosed in double quotation marks ("). Any double quotation mark (") contained in the value is escaped with another one added in front of the mark.

#

The configuration type is output only if the Admin or Develop role has been set for the target resource groups from the user group that the user belongs to.

The following list shows some examples of file outputs.

"Task Name","To Do","Status","Scheduled Time","Start Time","Completion Time","Schedule Type",
"Task ID","Description","Service","Service Group","Tags","Submitted By","Submit Time","Schedule Interval",
"Recurrence Time","Schedule Start Date","Notes","Step Start Time","Supported Action Type","Service Status"
"Remote command execution_20150828130932","FALSE","Failed","","2015/8/28 13:09","2015/8/28 13:09","immediate","4015",
"","Remote command execution","DefaultServiceGroup","Basic,OS_Operations","System","2015/8/28 13:09","","","","","","forciblyStop,retry","Release"

When outputting the detailed task information (when taskdetails is specified for the output option)

The following shows the data that is output to the detailed task information storage folder.

The following lists the contents of the detailed task information storage folder:

• Detailed task information storage folder

  Folder name: Arbitrary name

  The folder you specify in the taskdetaildir option.

• Task list file

  File name: listtasks.csv

  The file you can use to check the list of tasks contained in the detailed task information, and the tasks in that list to be re-registered by the submittask command.

  A flag is added at the end of each line of the task list that is output by specifying tasks for the output option to indicate whether the task is to be re-registered by the submittask in a batch.

  The following shows an output example of the task list.

  Figure 1‒3: Output example of the task list

  The following describes the contents of the header part and data part:

  Header part (first line)

  Unexecuted Schedule

  Data part (second or subsequent lines)

  true: The task is to be re-registered in a batch.

  false: The task is not to be re-registered in a batch.

  A flag in the data part (second line or subsequent lines) becomes true if the task is a planned task (scheduled task or recurring task) and has not been executed yet, including the following:

  • A scheduled task of which execution has not been started when the listtasks command is executed

  • A recurring task that has not been canceled when the listtasks command is executed

  • A scheduled task and recurring task that are being held when the listtasks command is executed

  Note that the task list file is used for checking the tasks to be re-registered by the submittask in a batch. Do not edit this file.

• Individual detailed task information storage folders

  Folder name: task-ID

  This folder stores the definition information, property file (input property file), and output property file for individual tasks. The task ID becomes the folder name, and the number of folders that matches the number of output tasks are generated.

• Task definition information file

  File name: taskdef.xml

  The file in which task definition information is output in XML. Do not edit this file.

• Property file (input property file)

  File name: input.properties

  The input property information set for the task is output in key=value format. For details on the format of the property file (input property file), see the JP1/Automatic Operation Administration Guide. Note that only input properties with their visibility set to Edit and Submit Window are output. If no such input property exists, an empty file is created.

  When you perform batch re-registration of the tasks, do not edit the input property file before executing the submittask command. If the file is edited, the command execution result is not supported by this product. However, if you want to register the tasks with settings different from the original settings, create a copy of this file and use the copy. After copying the file, specify items such as the scheduled date and time and task name that can be specified when executing the service, and then execute the service separately. If you want to change the input property value, edit the copied file as required, and execute the submittask command with the propertyfile option.

  Note that information items (such as the host name, IP address, and user name) included in the input property values are output without processing. However, if the data type of the property is password, the obfuscated value is output.

• Output property file

  File name: output.properties

  The output property information set for the task is output in key=value format. If no applicable output property exists, an empty file is created.

  Note that information items (such as the host name, IP address, and user name) included in the output property values are output without processing. However, if the data type of the property is password, the obfuscated value is output.

• Property value file storage folder

  Folder name: value_files

  This folder stores property value files.

• Property value file

  • Name of a property value file for input properties

    input_number^#.txt

  • Name of a property value file for output properties

    output_number^#.txt

  #

  number is a sequential number starting with 0001, and it is obtained for each property type (input or output property).

  If the input or output properties for the service include a composite type property, the value of the property is output as a text file. For details on the property value file format, see the JP1/Automatic Operation Administration Guide.

Located in

In Windows:

JP1/AO-installation-folder\bin

In Linux:

/opt/jp1ao/bin

Execute permission

Execute the command as a user with Administrator or root permissions for the OS. If a user without Administrator or root permissions executes the command, a message appears asking the user to elevate the permission level.

Permission required for the user specified for the user option depends on the argument specified for the output option.

When tasks or histories is specified for the output option (when outputting the list of tasks or histories)

The Admin, Develop, Modify, or Submit role must be set for the target service group from the user group that the user specified for the user option belongs to. The command does not output a list of tasks for any service groups for which none of these roles are set.

When taskdetails is specified for the output option (when outputting the detailed task information)

Specify the user who has the Admin role for the user option. The Admin role which allows access to the entire resource is required because the information on the entire tasks registered in JP1/AO are output, and the information is output without processing even if the input property or output property values include information such as the host name, IP address, user name, and password. Store the output detailed task information in a properly access-controlled location.

Return code

The following table lists the return codes from the command.

Example

The following examples show how to use the command for each case.

• To output, in Windows, the list of registered tasks to a file in default encoding of the OS:

  listtasks /output tasks /file list01.csv /user user01 /password pass01

• To output, in Windows, the tasks in the list of tasks that started or are scheduled to start from January 1, 2012 to March 31, 2012 to a file in UTF-8 encoding:

  listtasks /startrange 2012-01-01,2012-03-31 /output histories /file list02.csv /encoding UTF-8 /user user02 /password pass02

• To output, in Windows, the detailed task information:

  listtasks /output taskdetails /taskdetaildir "C:\data\taskdetail" /user user03 /password pass03