Update (Task)

URL:: https://<root>/system/tasks/<taskID>/update
Methods:: POST
Required Capability:: Access allowed only with the default administrator role
Version Introduced:: 10.9

Description

The update 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 Use dark colors for code blocksCopy `1 title=gpCleanerTask`
`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 Use dark colors for code blocksCopy `1 parameters={}`
`itemId`	The task item ID the scheduled task will be run against. This parameter is not required for `CreateBackup`. Example Use dark colors for code blocksCopy `1 itemId=d68b96a1-4c39-4914-8d97-d82842a71bed`
`startDate`	The date, defined in Epoch milliseconds (Unix), of when the scheduled task will begin running. Example Use dark colors for code blocksCopy `1 startDate=1589428800000`
`endDate`	The date, defined in Epoch milliseconds (Unix), of when the scheduled task will stop running. Example Use dark colors for code blocksCopy `1 endDate=1589428800000`
`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 Use dark colors for code blocksCopy `1 minute=0`
`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 Use dark colors for code blocksCopy `1 hour=`
`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 Use dark colors for code blocksCopy `1 dayOfMonth=`
`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 Use dark colors for code blocksCopy `1 month=`
`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 Use dark colors for code blocksCopy `1 dayOfWeek=?`
`maxOccurences`	The maximum number of occurrences this task should execute. Example Use dark colors for code blocksCopy `1 maxOccurences=-1`
`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:

Use dark colors for code blocksCopy
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&parameters=&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:

Use dark colors for code blocksCopy
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&parameters={"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

Use dark colors for code blocksCopy
{
  "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"
}