- URL:https://<root>/system/tasks/<taskID>/update
- Required Capability:Default administrator role
- Version Introduced:10.9
Description
This operation allows you to edit and update the properties of a preexisting task (CleanGPJobs, BackupRetentionCleaner at 10.9.1, and CreateBackup at 10.9.1). Updates that have been made to a task will go into effect during its next scheduled execution.
Request parameters
Parameter | Details |
---|---|
title | The task's title. Example
|
type | The type of task. At 10.9, the only task supported was the CleanGPJobs task type. At 10.9.1, the CreateBackup and BackupRetentionCleaner tasks were added. Values: CleanGPJobs | CreateBackup | BackupRetentionCleaner |
parameters | A JSON object of additional parameters that will be added to the task run request. For CreateBackup, parameters must include the name of the backup, the storeName of the backup store in which the backup will reside, and the passcode that will be used to encrypt and restore the backup (the passcode must be at least eight characters). This operation can be used to change the passcode for a backup by passing in a new, plaintext value that will be reencrypted once the edit operation is complete. The backup description is optional. Example
|
itemId | The task item ID the scheduled task will be run against. This parameter is not required for CreateBackup. Example
|
startDate | The date, defined in Epoch milliseconds (Unix), of when the scheduled task will begin running. Example
|
endDate | The date, defined in Epoch milliseconds (Unix), of when the scheduled task will stop running. Example
|
minute | A valid CRON expression (, - * /) that specifies the minute value for the task's schedule. For examples of sample schedules, see the CRON expressions section below. Example
|
hour | A valid CRON expression (, - * /) that specifies the hour value for the task's schedule. For examples of sample schedules, see the CRON expressions section below. Example
|
dayOfMonth | A valid CRON expression (, - * ? / L W LW) that specifies the day of the month for the task's schedule. For examples of sample schedules, see the CRON expressions section below. Example
|
month | A valid CRON expression (, - * /) that specifies the month for the task's schedule. For examples of sample schedules, see the CRON expressions section below. Example
|
dayOfWeek | A valid CRON expression (, - * ? / L #) that specifies the day of the week for the task's schedule. For examples of sample schedules, see the CRON expressions section below. Example
|
maxOccurences | The maximum number of occurrences this task should execute. Example
|
f | The response format. The default format is html. Values: html | json | pjson |
CRON expressions
Special characters and wildcards can be used to customize your scheduled jobs. The following table lists the supported characters:
Character | Details |
---|---|
* | Specifies all values. |
? | No specific value for dayOfMonth and dayOfWeek expressions. |
- | A range. |
, | List of additional values. |
/ | Specifies increments. |
# | The nth day name of the month. |
L | Last day of the week or month. |
W | The weekday (Monday-Friday) nearest the given day (applies only to dayOfMonth). |
LW | Last weekday of the month. |
The following table demonstrates sample schedules and how they translate to CRON values for the minute, hour, dayOfMonth, month, and dayOfWeek parameters:
Schedule | minute | hour | dayOfMonth | month | dayOfWeek |
---|---|---|---|---|---|
Hourly at 15 minutes past the hour | 15 | * | * | * | ? |
Every four hours during weekdays | 0 | */4 | ? | * | 1-5 |
Weekly on Sundays at 12 p.m. | 0 | 12 | ? | * | 7 |
Twice a month on the 1st and 15th at 12 a.m. | 0 | 0 | 1,15 | * | ? |
Last Friday of every month at 10 p.m. | 0 | 22 | ? | * | 6L |
Last day of the month at 10 p.m. | 0 | 22 | L | * | ? |
Last weekday of the month at 6 p.m. | 0 | 18 | LW | * | ? |
Closest weekday to the 15th of each month at midnight | 0 | 0 | 15W | * | ? |
Example usage
The following is a sample POST request for the update operation:
POST /context/admin/system/tasks/87b8a97828e647e8af5d634774b2b8a7/update HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
title=gpCleanerTask&type=CleanGPJobs¶meters=&itemId=d68b96a1-4c39-4914-8d97-d82842a71bed&startDate=1589428800000&endDate=1589428800000&minute=0&hour=*&dayOfMonth=*&month=*&dayOfWeek=?&maxOccurences=30&f=pjson&token=m7zGSezM7znt6ZuIwr827imJxOTSDsjYujVdd7SiAQLYG1HmesG8EbSnTwCbiekEh0QwRdmeyp1hP63M60TPrdZQ2NzIg5G7qFaQh40MdiOCfh60-6oPKC2MNoqwdVDZ3srzreVZb66QofWXws8GMrKWkgP45A-2an5crKvReUo-pwvkzm68W87Q0yPJFA2Kww39UnMYNw-5qd2-Bt04VmkrqKI-lCbA-jFZY_UGzeGzNqnBGrjKuVB_q17HogMw
The following sample POST request demonstrates using the update operation on a CreateBackup task that changes the passcode value:
POST /context/admin/system/tasks/5f0cdc50cf36460990bb6edfe9b60e08/update HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
title=backups&type=CreateBackup¶meters={"storeName": "backups","passcode": "myNewPasscode","description": "Automated Backups from Task Scheduler","name": "schedule1"}&startDate=1589428800000&endDate=1589428800000&minute=0&hour=0&dayOfMonth=?&month=*&dayOfWeek=7&maxOccurrences=1&f=pjson&token=HRozb6bnTL6gfA-SJO-IxhfLgJrioK1KJdMLWmCE5HjHWz9U3fOiFv3-HkgPZqsLljTkk2WDENGt5fjho5s39e_mZL5At60UvJPoNnC5O2sv2HTlumG7TsYfbtnokpWmS6-lf8XoQpSKusZwmxIkEMP-yE0Wxrj8o9sWKi29J-pxzkoCDhoUfdLt6NnBWxhESpegh8BzNcEruqxuDQD-JRmaTsbRDaBHTQTePMzQePhXl7KcEG9Cfkw2sa7P1W1e
JSON Response example
{
"generation": 5,
"created": "Apr 21, 2021, 10:42:17 PM",
"active": true,
"ownerId": "c076e404cec9497488f008fc5b83e6fa",
"type": "GP_JOBS_CLEANER_TASK_TYPE",
"orgId": "0123456789ABCDEF",
"cronSchedule": {
"dayOfWeek": "?",
"hour": "*",
"month": "*",
"dayOfMonth": "*",
"minute": "0"
},
"cronExpression": "0 0 * * * ?",
"itemId": "0a78247d-0d0d-4b69-a658-03104e15bd66",
"runIntervalSeconds": 3600,
"taskType": "CleanGPJobs",
"taskState": "active",
"taskTitle": "gpCleanerTask",
"maxOccurrences": -1,
"id": "2a1ba86743414f929c0c1f38b32f1c9c",
"lastStart": "Apr 22, 2021, 3:00:00 AM",
"updated": "Apr 21, 2021, 10:42:17 PM",
"taskId": "2a1ba86743414f929c0c1f38b32f1c9c"
}