8.6.9 submittask (executing a service and re-registering the tasks in a batch)

Description

Executing a service

This command executes a specified service based on user-specified information such as the service name, resource group name, and property values. When the task is executed normally, a message reporting the task ID is output. This command cannot execute debug services. By specifying the options, you can execute a service recursively or at a specified execution date and time. If you do not specify any options, the command executes the service immediately.

Re-registering the tasks in a batch

This command re-registers the scheduled tasks and recurring tasks in a batch based on the contents of the detailed task information output by the listtasks command. The re-registered task inherits the settings and conditions from the original task. This command is a functionality for executing a scheduled or recurring service with the same settings by referring to the information stored in the detailed task information storage folder. Note that this command is not a functionality for restoring the same task. The re-registered task is, therefore, a task different from the original task and has a different task ID. Debug tasks cannot be re-registered.

Procedures before re-registering the tasks in a batch

Perform the following before re-registering the tasks in a batch:

The detailed task information storage folder must be the folder output by JP1/AO whose version and revision is the same as those of JP1/AO you use to re-register the tasks in a batch. Batch re-registration of tasks fails if the detailed task information storage folder output by JP1/AO whose version or revision is different is specified.
Check that the detailed task information storage folder output by the listtasks command exists.
Set up the definition information (service, service template, user, user group, resource group, connection destinations, and service share properties) and definition file separately. Restore those settings by using the backupsystem and restoresystem commands if necessary. Do not change those settings or delete any service after outputting the detailed task information storage folder by the listtasks command. If the service settings have been changed, batch re-registration is performed according to the changed settings. If the service settings have been deleted, re-registration of the corresponding task fails.
For a scheduled task, confirm that the specified time has not been passed at the time of task re-registration. An error occurs if the specified time has passed, and you cannot directly re-register the task.

Condition of the tasks that are re-registered in a batch: The tasks that are re-registered in a batch are the unexecuted scheduled tasks and recurring tasks that are in the task list (listtasks.csv) in the detailed task information storage folder. In the task list, the Unexecuted Schedule column of the unexecuted scheduled tasks and recurring tasks is true.

Re-registering a scheduled task of which scheduled time has passed: You cannot directly re-register a task of which scheduled time has passed. If you re-register the task in a batch, re-registration fails with a message indicating that the specified date and time has passed. To check the settings of the tasks of which re-registration failed, refer to the task list file (listtasks.csv) in the detailed task information storage folder and the property files in the individual detailed task information storage folders. If you want to register a task of which scheduled time has passed, check the original date and time in the task list (listtasks.csv) in the detailed task information storage folder, and then execute each service by specifying a new date and time using the Service window or the submittask command of JP1/AO. Note that the start time must be equal to or after the current date and time.

Measures to take when there is a task of which re-registration failed: If batch re-registration of tasks fails, a message indicating that task registration failed, and task IDs of the tasks of which registration failed are displayed. These task IDs are the ones output by the listtasks command. If some tasks are successfully re-registered, move the individual detailed task information storage folder for the relevant tasks to another location. Then eliminate the causes of the failure, and execute the command again. Moving the folders is to prevent duplicate registration of the successful tasks. If the same error occurs after taking the above measures, contact the system administrator.

Syntax

When executing a service immediately

submittask
     /servicename service-name
     [/resourcegroup resource-group-name]
     [/taskname task-name]
     [/taskdescription task-description]
     [/property property-key property-value |
      /propertyfile property-file-path]
      /user user-ID
      {/password password | /passwordfile password-file-path}
     [/wait]

When executing a service at a specified date and time

submittask
     /servicename service-name
     [/resourcegroup resource-group-name]
     [/taskname task-name]
     [/taskdescription task-description]
     [/property property-key property-value |
      /propertyfile property-file-path]
      /user user-ID
      {/password password | /passwordfile password-file-path}
      /scheduledate yyyy-mm-dd /scheduletime hh:mm

When executing a service recursively

submittask
      /servicename service-name
     [/resourcegroup resource-group-name]
     [/taskname task-name]
     [/taskdescription task-description]
     [/property property-key property-value |
      /propertyfile property-file-path]
      /user user-ID
      {/password password | /passwordfile password-file-path}
      /recurrencepattern {daily | weekly:sun,mon,...,sat | monthly:{dd,dd,...,dd | endofmonth}}
      /recurrencetime hh:mm /recurrencestart yyyy-mm-dd

When re-registering the tasks in a batch

submittask
     /reregister
     /taskdetaildir detailed-task-information-storage-folder 
     [/setoriginalsubmitter]
     /user user-ID
     {/password password | /passwordfile password-file-path}

Arguments

/servicename service-name

This option specifies the name of the service to be performed.

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

/resourcegroup resource-group-name

This option specifies the name of the resource group that the service to be performed belongs to.

If this option is omitted, the resource group associated with the user specified in the argument is used. However, if more than one resource group is associated with that user, an error occurs.

The number of possible characters is in the range from 1 to 63 characters. The possible characters are half-width alphanumeric characters and _.

However, a space character is allowed only if you specify the built-in resource group All Resources.

/taskname task-name

This option specifies the name of the task.

If this option is omitted, the system uses service-name_YYYYMMDDhhmmss (where YYYYMMDDhhmmss is the time when the service is performed) as a default name.

The number of possible characters is in the range from 1 to 128 characters. The possible characters are any characters other than the control characters (from \u0000 to \u001F and from \u007F to \u009F).

/taskdescription task-description

This option specifies the description of the task.

If this option is omitted, the value is not set.

The number of possible characters is in the range from 1 to 256 characters. The possible characters are any characters other than the control characters (from \u0000 to \u001F and from \u007F to \u009F).

/property property-key property-value

This option specifies the property key and value that the service to be performed uses. The system verifies whether the specified property value is valid according to the service template specifications.

For property keys that are not set by this option, the values specified in the Service Definition dialog box will be used. If values for required properties are specified in neither the Service Definition dialog box nor by this option, an error occurs.

You can use multiple instances of this option to specify multiple property key and value combinations (format: /property key-1 value-1 /property key-2 value-2 ...). You can specify a maximum of 100 instances of this option.

property-key

This option specifies the property key for the service.

The number of possible characters is in the range from 1 to 128 characters. The possible characters are half-width alphanumeric characters, -, _, and ..

If the same property key is specified more than once, then an error occurs.
property-value

This option specifies the property value for the property key.

Any value containing a space or special character must be enclosed in double quotation marks (").

/propertyfile property-file-path

This option specifies the absolute or relative path to the property file, which defines the input property settings that the service to be performed uses.

For property keys that are not set in the property file specified by this option, the values specified in the Service Definition dialog box will be used. If values for required properties are specified in neither the Service Definition dialog box nor in the file specified by this option, an error occurs.

The following table shows the format of the property file.

Table 8‒8: Property file format
Item	Rule
Location	Anywhere (However, the user who executes the command must be able to access it.)
File name	Any file name
Definition format	`property-key=property-value` `property-key=property-value` ... (Each entry must be specified on a separate line.)
Definition example ^#	`common.targetHost=ajsagthost` `jp1base.jp1BaseLHostName=lohost` `common.foreachIPaddress=192.168.1.xx,192.168.1.yy`

#: The property value delimiter varies depending on the service template to be used. The above examples use , as their delimiter.

The property keys and values must be defined in a single line per property key. The maximum number of definable combinations of property keys and values is 100 pairs.

The string until the first appearance of = is considered as a property key. The string from the character subsequent to the first = to the line break code (CR+LF) at the end of a line is considered as a property value. It is not considered whether the property file has a line break code at the end of the file.

/reregister

Specify this option if you re-register the tasks in a batch. Make sure that you also specify the /taskdetaildir option when you specify the /reregister option.

/taskdetaildir detailed-task-information-storage-folder

This option is required if the /reregister option is specified. This option specifies the absolute or relative path to the detailed task information storage folder that stores the scheduled or recurring task information you want to re-register. Note that only a folder on the local disk can be specified. The number of characters that can be specified for the absolute path is no more than 190 characters.

/setoriginalsubmitter

If you specify this option when re-registering the tasks in a batch, the task submitter after re-registration displays the name of the user who submitted the original task, not the user who re-registered the task. The user who submitted the original task is the user who was executing the task at the time when the listtasks command was used to output the detailed task information. You can check the task submitter after re-registration from the user ID displayed in the Submitted By column in the Tasks window. You can check the user who was executing the task at the time when the listtasks command was used to output the detailed task information in the Submitted By column in the listtasks.csv file that is output in the detailed task information storage folder.

If you omit this option, the user ID specified for the /user option of the submittask command becomes the task submitter after re-registration.

Note that an error does not occur even if "the user who was executing the task at the time when the listtasks command is used to output the detailed task information" does not exist when re-registering the task. In this case, the task submitter becomes "the user who is executing the task at the time when the listtasks command is used to output the detailed task information".

/user user-ID

This option specifies the user ID for JP1/AO. Make sure that you specify the ID of a user that is associated with a resource group that the service specified by the /servicename option belongs to.

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.

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.

/wait

If this option is specified, the command outputs the task execution result (Completed or Failed), and then terminates. If the /wait option is not specified, the command terminates without waiting for the task to terminate. In this case, a message reporting the task ID is output only when the task execution has started normally. Do not specify the /wait option together with the /scheduledate and /scheduletime options. If you do so, command execution will fail.

/scheduledate

If you want to execute the service according to a schedule, specify the date (year, month, and day) that the service will be executed in the YYYY-MM-DD format. In YYYY, specify a four-digit year. In MM, specify a month number from 1 (or 01) to 12. In DD, specify a day number from 1 (or 01) to 31. Note that when you specify the /scheduledate option, you must also specify the /scheduletime option. The command execution will fail if:

The combination of arguments is invalid.

For details on the combination of arguments, see Table 8‒9: Argument combination of the submittask command.
The date is specified in an incorrect format.
The execution time determined by the combination of this option and the /scheduletime option is earlier than the current time.
The specified date is not within the range from 1994-01-01 to 2036-12-31.

/scheduletime

If you want to execute the service according to a schedule, specify the time (hour and minute) in the hh:mm format. In hh, specify the hour from 00 to 23. In mm, specify the minute from 00 to 59. When you specify the /scheduletime option, you must also specify the /scheduledate option. The command execution will fail if:

The combination of arguments is invalid.

For details on the combination of arguments, see Table 8‒9: Argument combination of the submittask command.
The time is specified in an incorrect format.
The execution time determined by the combination of this option and the /scheduledate option is earlier than the current time.

/recurrencepattern {daily | weekly:sun,mon,...,sat | monthly:{dd,dd,...,dd | endofmonth}}

This option specifies the recurrence pattern of the service execution. When you specify the /recurrencepattern option, you must also specify the /recurrencetime and /recurrencestart options. Note that the command execution fails if either of the following conditions applies:

The combination of arguments is invalid.

For details on the combination of arguments, see Table 8‒9: Argument combination of the submittask command.
The specified recurrence pattern is in an invalid format.

There are three types of recurrence pattern: daily, weekly, and monthly. The format of the recurrence pattern differs by the recurrence pattern type.

Daily

Specify daily.

Weekly

Specify the pattern in the weekly:sun,mon,...,sat format.

Preceded by weekly:, specify one or more days on which you want to execute the service, delimiting them by a comma (,). To specify days in the abbreviated form, use sun, mon, tue, wed, thu, fri, and sat. The order of the specified days does not matter. An invalid argument error occurs if the same day is specified for multiple times.

Monthly

Specify the pattern in the monthly:{dd,dd,...,dd | endofmonth} format.

Preceded by monthly:, specify one or more dates on which you want to execute the service, delimiting them by a comma (,). To execute the service at the end of the month, specify just endofmonth, without specifying any dates. The order of the specified dates does not matter. The specifiable dates are from 1 (or 01) to 31. An invalid argument error occurs if the same date is specified multiple times or for a nonexistent date, such as 0 or below, or 32 or above. Note that the command skips execution of a recurring task on a date that is specified but does not exist in a particular month. For example, if the task is scheduled to be executed on 30th or 31th every month, recursive execution is skipped in February.

/recurrencetime hh:mm

This option specifies the time (hour and minute) at which to execute the service in hh:mm. For hh, specify the hour from 00 to 23. For mm, specify the minute from 00 to 59. When you specify the /recurrencetime option, you must also specify the /recurrencepattern and /recurrencestart options. Note that the command execution fails if either of the following conditions applies:

The combination of arguments is invalid.

For details on the combination of arguments, see Table 8‒9: Argument combination of the submittask command.
The specified time is in an invalid format.

/recurrencestart yyyy-mm-dd

This option specifies the date on which to start executing the recurring service in yyyy-mm-dd. For yyyy, specify the year in four digits. For mm, specify the month from 1 (or 01) to 12. For dd, specify the date from 1 (or 01) to 31. When you specify the /recurrencestart option, you must also specify the /recurrencepattern and /recurrencetime options. Note that the command execution fails if one of the following conditions applies:

The combination of arguments is invalid.

For details on the combination of arguments, see Table 8‒9: Argument combination of the submittask command.
The specified date is in an invalid format.
The specified date is out of the following range: from 1/1/1994 to 12/31/2036.

Argument combination of the submittask command

Table 8‒9: Argument combination of the `submittask` command
Option	Immediate execution of the service	Scheduled execution of the service	Recurring execution of the service	Re-registration of the scheduled tasks in a batch
`/servicename`	Required	Required	Required	--
`/resourcegroup`	Optional	Optional	Optional	--
`/taskname`	Optional	Optional	Optional	--
`/taskdescription`	Optional	Optional	Optional	--
`/property`^#1	Optional	Optional	Optional	--
`/propertyfile`^#1	Optional	Optional	Optional	--
`/reregister`	--	--	--	Required
`/taskdetaildir`	--	--	--	Required
`/setoriginalsubmitter`	--	--	--	Optional
`/user`	Required	Required	Required	Required
`/password`^#2	Required	Required	Required	Required
`/passwordfile`^#2	Required	Required	Required	Required
`/wait`	Optional	--	--	--
`/scheduledate`	--	Required	--	--
`/scheduletime`	--	Required	--	--
`/recurrencepattern`	--	--	Required	--
`/recurrencetime`	--	--	Required	--
`/recurrencestart`	--	--	Required	--

Legend:

Required: Required. An argument error occurs if omitted.

Optional: Can be omitted.

--: Cannot be specified. An argument error occurs if specified.

#1

Specify either the /property option or /propertyfile option. An error occurs if you specify both options at the same time.

#2

Specify either the /password option or /passwordfile option. An error occurs if you specify both options at the same time.

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.

Before the service can be executed, make sure that the Admin, Develop, Modify, or Submit role is set for the resource group of that service from the user group that the user who executes the command belongs to. The command cannot execute a service in a resource group for which none of these roles are set.

The following describes the permission required for the user specified for the /user option.

When executing a service

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 user can only execute a service for which he or she has the execute permission.

When re-registering a task in a batch

The Admin role must be set for the user specified for the /user option.

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.
5	Communication failed.
6	Authentication failed.
7	An invalid path is specified.
9	The specified path does not exist.
10	The specified path is not accessible.
14	You do not have permission to execute the command.
130	Starting the service failed.
131	The property file does not exist.
132	The property file has an invalid format.
133	The status of the task could not be obtained (when the `/wait` option is specified).
134	The task could not be executed (when the `/wait` option is specified).
136	The data format of the detailed task information storage folder is invalid.
137	Re-registering the planned tasks in a batch partially failed.
138	Re-registering the planned tasks in a batch failed entirely.
139	The version or revision of JP1/AO that was used to output the detailed task information storage folder is different from the currently installed JP1/AO.
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 execute a service specified by the service name with the property keys and values:

submittask /servicename service01 /user user01 /password pass01 /property keyA valueA /property keyB "value B" /property keyC valueC,valueD
To execute a service specified by the resource group and the service name, with the task name, task description, and property file:

submittask /servicename service02 /resourcegroup resourceA /taskname task02 /taskdescription testtask /propertyfile C:\properties.txt /user user02 /password pass02
To output the task execution result before the command terminates:

submittask /servicename service03 /user user03 /password pass03 /wait
To execute a service at the specified time:

submittask /servicename service04 /user user04 /password pass04 /scheduledate 2014-01-01 /scheduletime 15:30
To execute a service recursively:

submittask /servicename service05 /user user05 /password pass05 /recurrencepattern weekly:sun,mon,fri /recurrencetime 15:30 /recurrencestart 2013-06-17
To re-register planned tasks in a batch:

submittask /reregister /taskdetaildir "C:\data\taskdetail" /user user06 /password pass06

Related topic

To Page Top