8.6.7 listtasks (outputting the list of tasks and the detailed task information)
Description
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 Tasks view 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 Task Histories view 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, resource 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} {/fileoutput-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 see the submitted date and time in the Task Details dialog box.
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 the tasks from the Tasks view.
-
histories
Outputs the list of the histories from the Task Histories view.
-
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 190 characters for the absolute path. If the relative path is used, the path being converted to the absolute path must be no more than 190 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, this option is applied only to the task list file located directly under the detailed task information storage folder (listtasks.csv). The detailed task information and the property files 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
When outputting the list from the Tasks and Task Histories views (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.
Output item |
Description |
---|---|
Task |
Task name |
Status |
Status |
Scheduled Time |
Scheduled start date and time |
Start Time |
Start date and time |
End Time |
End date and time |
Type |
Task type |
ID |
Task ID |
Description |
Task description |
Service |
Service name |
Resource Group |
Resource group |
Category |
Service category |
Submitted By |
User who executed the task |
Submitted At |
Submitted date and time |
Recurrence Pattern |
Recurrence pattern |
Recurrence Time |
Recurrence time |
Recurrence Start |
Start date of recurrence |
Configuration Type# |
Configuration type |
- #
-
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","Status","Scheduled Time","Start Time","End Time","Type","ID","Description","Service","Resource Group","Category","Submitted By","Submitted At","Recurrence Pattern","Recurrence Time","Recurrence Start","Configuration Type" "Remote command execution_20131031190605","Waiting","2013-11-01 00:00:00","","","Recurring task","3327","","Remote command execution","All Resources","OS_Operations/Basic","user","2013-10-31 19:06:37","Weekly Monday,Wednesday,Friday","00:00:00","2013-10-31","Release" "Remote command execution_20131031194429","Waiting","2013-11-01 09:00:00","","","Scheduled task","3355","","Remote command execution","All Resources","OS_Operations/Basic","user","2013-10-31 19:44:52","","","","Release" "Get list of OS users_20131031194524","Waiting","2013-11-01 20:00:00","","","Recurring task","3385","","Get list of OS users","All Resources","OS_Operations/Management","user","2013-10-31 19:45:44","Daily","20:00:00","2013-10-31","Release" "Remote command execution_20131031194500","Waiting","2013-11-30 00:00:00","","","Scheduled task","3361","","Remote command execution","All Resources","OS_Operations/Basic","user","2013-10-31 19:45:17","","","","Release" "Get list of OS users_20131031194524","Completed","2013-10-31 20:00:00","2013-10-31 20:00:00","2013-10-31 20:00:19","Recurring task","3375","","Get list of OS users","All Resources","OS_Operations/Management","user","2013-10-31 19:45:44","Daily","20:00:00","2013-10-31","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 8‒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 and the property files 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.
-
Input property file
File name: input.properties
The input property information set for the task is output. The data format is the same as the property file specified in the /propertyfile option of the submittask command. For details on the file format, see the description on the /propertyfile option in 8.6.9 submittask (executing a service and re-registering the tasks in a batch). Note that only the input property with its visibility set to exec is 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 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 that file specified for the /propertyfile option.
Note that the information is output without processing even if the input property values include information such as the host name, IP address, user name, and password.
-
Output property file
File name: output.properties
The output property information set for the task is output. The data format is the same as the input property file. For details on the file format, see the description of the /propertyfile option in 8.6.9 submittask (executing a service and re-registering the tasks in a batch). If no applicable input property exists, an empty file is created.
Note that the information is output without processing even if the output property values include information such as the host name, IP address, user name, and password.
Located in
JP1/AO-installation-folder\bin
Execute permission
Execute the command as a user with Administrator permissions for the OS. If a user without Administrator 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 resource 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 resource 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.
Return code |
Description |
---|---|
0 |
The command succeeded. |
1 |
The argument is invalid. |
2 |
The command execution has been interrupted. |
3 |
The service status is invalid. |
4 |
One of the other commands is running. |
5 |
Communication failed. |
6 |
Authentication failed. |
7 |
An invalid path is specified. |
8 |
The file with the same name already exists in the output path. |
9 |
The specified path does not exist. |
10 |
The specified path is not accessible. |
11 |
The specified folder is not empty. |
12 |
An invalid encoding is specified. |
13 |
Outputting the file failed. |
14 |
You do not have permission to execute the command. |
150 |
Obtaining the list of tasks failed. |
151 |
Obtaining the list of histories failed. |
152 |
Obtaining the detailed task information failed. |
255 |
The command execution has been interrupted due to an error other than the above. |
Example
The following commands show examples of how to use the command for each case.
-
To output 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 the tasks in the Task Histories view 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 the detailed task information:
listtasks /output taskdetails /taskdetaildir "C:\data\taskdetail" /user user03 /password pass03
Related topic