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

Description

The functionality of the submittask command is as follows:

Executing a service

This command executes a specified service based on user-specified information such as the service name, service 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, service 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 task of which re-registration failed, refer to the task list file (listtasks.csv) in the detailed task information storage folder, and the property file (input property file) and output property file in the individual detailed task information storage folder. 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

The syntax of the submittask command is as follows:

When executing a service immediately

submittask
     /servicename service-name
     [/servicegroup service-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
     [/servicegroup service-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
     [/servicegroup service-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[:{1h|2h|3h|4h|6h|8h|12h|24h}] | weekly:sun,mon,...,sat | monthly:{dd,dd,...,dd[,endofmonth]| 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 128 characters.

/servicegroup service-group-name

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

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

The number of possible characters is in the range from 1 to 80 characters. The possible characters are any characters other than the unicode characters from U+10000 to U+10FFFF.

Note that, instead of the servicegroup option, you can also specify the service group name by using the resourcegroup option, which was used in JP1/AO 10-52 and earlier. If you specify All Resources for the servicegroup option, the service will run as if DefaultServiceGroup is specified.

/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 in this option, the values specified in the Service Definition window will be used. If values for required properties are not specified in either the Service Definition window or 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 ...). By default, you can specify a maximum of 1,000 instances of this option. You can specify the maximum number of properties that can be specified by using the user-specified properties file (config_user.properties).

• property-key

  This option specifies the property key for the service.

  The number of possible characters is in the range from 1 to 1,024 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 and property values that are not set in the property file specified by this option, the values specified in the Service Definition window (Create, Edit, or Copy) or the Submit Service window will be used. If values for required properties are not specified in either the Service Definition window (Create, Edit, or Copy) or in the Submit Service window, and the values are not defined in the property file specified by this option, an error occurs.

For details on the format of the property file, see the JP1/Automatic Operation Administration Guide.

The following table shows the format of the property 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 service 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.

/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 1‒10: 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 1‒10: 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[:{1h|2h|3h|4h|6h|8h|12h|24h}] | weekly:sun,mon,...,sat | monthly:{dd,dd,...,dd[,endofmonth] | 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 1‒10: 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 to execute the command once a day.

To specify the recurrence interval in hours, specify in the following format: daily:{1h|2h|3h|4h|6h|8h|12h|24h}. Start with daily:, and then select the time interval from 1h, 2h, 3h, 4h, 6h, 8h, 12h, and 24h.

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] | endofmonth} format.

Specify monthly: followed by one or more dates on which to execute the services, with the dates delimited by commas. To execute the service at the end of the month, specify endofmonth. You can specify the dates in any order. If you want to specify execution at the end of the month in addition to specific dates, specify endofmonth at the end of the sequence. Specify dates as single-byte numerals in the range from 1 (or 01) to 31. In the following circumstances, an invalid argument error occurs:

• The same date is specified multiple times

• A nonexistent date such as 0 or below or 32 or above is specified

• endofmonth is specified but not at the end of the sequence

Note that the service will not be executed in a month that does not contain the specified date. For example, if the task is scheduled to be executed on the 30th or 31st of every month, recurring execution of that task will be 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 1‒10: 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 1‒10: 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

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

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.

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.

Example

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

• To execute, in Windows, 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, in Windows, a service specified by the service group and the service name, with the task name, task description, and property file:

  submittask /servicename service02 /servicegroup servicegroupA /taskname task02 /taskdescription testtask /propertyfile C:\properties.txt /user user02 /password pass02

• To output, in Windows, the task execution result before the command terminates:

  submittask /servicename service03 /user user03 /password pass03 /wait

• To execute, in Windows, a service at a specified time:

  submittask /servicename service04 /user user04 /password pass04 /scheduledate 2014-01-01 /scheduletime 15:30

• To execute, in Windows, 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, in Windows, planned tasks in a batch:

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