Create Task

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

Description

The createTask operation creates scheduled tasks for a deployment that run automatically. Once the task has been created, it can be updated using the Update operation. In addition, scheduled tasks can be disabled, reenabled, and deleted using other operations in the ArcGIS Enterprise Administrator API. This operation supports the following tasks:

Creating scheduled tasks to create backups of your deployment of ArcGIS Enterprise on Kubernetes
Creating scheduled tasks to perform and generate health check reports for your organization

Request parameters

Parameter	Details
`title` (Optional)	The title of the task. Example Use dark colors for code blocksCopy `1 title=backups`
`type` (Required)	The task type. Starting at 11.4, this parameter can specify either `CreateBackup` or `CreateHealthCheckReports` as the scheduled task type. Prior to 11.4, this parameter only supported `CreateBackup`. Example Use dark colors for code blocksCopy `1 type=CreateBackup`
`parameters` (Required)	A JSON object of additional parameters that will be added to the task run request. For more information on the required properties for `parameters` see the [Task parameters] section below. Example Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 //Create a backup at midnight, local time, with each backup getting deleted after 14 days parameters={ "name": "myBackup", "passcode": "myPassword", "storeName": "backups", "metaData": { "recurring": false, "startTime": "04:00", "retention": { "type": "day", "value": 14 } }, "retentionOffset": 1209600000 }`
`startDate` (Optional)	The date, defined in epoch milliseconds (Unix time), the task will begin running. Example Use dark colors for code blocksCopy `1 startDate=1589428800000`
`endDate` (Optional)	The date, defined in epoch milliseconds (Unix time), the task will stop running. Example Use dark colors for code blocksCopy `1 endDate=1589428800000`
`minute` (Required)	A valid CRON expression (`,` `-` `*` `/`) that specifies the minute value for the task's schedule. For sample schedules, see the CRON expressions section below. Example Use dark colors for code blocksCopy `1 minute=0`
`hour` (Required)	A valid CRON expression (`,` `-` `*` `/`) that specifies the hour value for the backup task's schedule. For sample schedules, see the CRON expressions section below. Example Use dark colors for code blocksCopy `1 hour=0`
`dayOfMonth` (Required)	A valid CRON expression (`,` `-` `*` `?` `/` `L` `W` `LW`) that specifies the day of the month value for the backup task's schedule. For sample schedules, see the CRON expressions section below. Example Use dark colors for code blocksCopy `1 dayOfMonth=?`
`month` (Required)	A valid CRON expression (`,` `-` `` `/`) that specifies the month value for the task's schedule. For sample schedules, see the CRON expressions section below. Example Use dark colors for code blocksCopy `1 month=`
`dayOfWeek` (Required)	A valid CRON expression (`,` `-` `*` `?` `/` `L` `#`) that specifies the day of the week value for the backup task's schedule. For sample schedules, see the CRON expressions section below. Example Use dark colors for code blocksCopy `1 dayOfWeek=7`
`maxOccurrences` (Optional)	The maximum number of occurrences the task will execute. Example Use dark colors for code blocksCopy `1 maxOccurrences=1`
`f`	The response format. The default format is `html`. Values: `html` \| `json` \| `pjson`

Task parameters

The table below outlines the required properties for parameters and which task type (either CreateBackup or CreateHealthCheckReports) the properties are required for.

Property	Details
`name`	The prefix of the backup or health check report name, which is appended with the date the backup or health check report was created.
`passcode`	This property only applies when a scheduled task's type is `CreateBackup`. The value that will be used to encrypt the backup when it is created and decrypt the backup when it is restored. The passcode must be at least eight characters.
`storeName`	This property only applies when a scheduled task's type is `CreateBackup`. The backup store in which the backup will reside.
`suiteIds`	This property only applies when a scheduled task's type is `CreateHealthCheckReports`. The type of health check report being performed. At 11.4, only basic health check reports (`BSHC-001`) are supported.
`itemId`	This property only applies when a scheduled task's type is `CreateHealthCheckReports`. A placeholder property that does not need to be included in the request.
`metaData`	JSON array that determines when the scheduled task starts, if it is recurring, and the retention information for the backup or health check report. The following properties are required for both `CreateBackup` and `CreateHealthCheckReports` tasks: `recurring`: A Boolean (`true` and `false`) value that determines whether a backup or health check report is created once or is recurring. `startTime`: A string representation of the time the backup will be created in Greenwich mean time, using 24-hour notation. `retention`: A JSON object that specifies the retention information for a backup or health check report. The JSON object includes a `type` property that sets the time units (`day`, `week`, or `month`) of how long the backup or health check will be retained, as well as a `value` property that specifies the length of time as it relates to the time unites (for example, 14 weeks, where `14` is set as the value for the `value` property and `week` is set as the value for `type`). `retentionOffset`: The milliseconds calculation of the retention value. This should match the information in the `retention` JSON array for the `metaData` property.

CRON expressions

Special characters and wildcards can be used to customize scheduled jobs. The following table lists the supported characters:

Character	Details
`*`	Specifies all values.
`?`	No specific value for `dayOfMonth` and `dayOfWeek` expressions.
`-`	A range.
`,`	A list of additional values.
`/`	Specifies increments.
`#`	The nth day name of the month (applies only to `dayOfWeek`).
`L`	The last day of the week or month.
`W`	The weekday (Monday-Friday) nearest the given day (applies only to `dayOfMonth`).
`LW`	The last weekday of the month.

The following table shows 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:00 p.m.	0	12	?	*	7
Twice a month on the 1st and 15th at 12:00 a.m.	0	0	1,15	*	?
Last Friday of every month at 10:00 p.m.	0	22	?	*	6L
Last day of the month at 10:00 p.m.	0	22	L	*	?
Last weekday of the month at 6:00 p.m.	0	18	LW	*	?
Closest weekday to the 15th of each month at midnight	0	0	15W	*	?

Example usages

The following is a sample POST request for the createTask operation that demonstrates scheduling a CreateBackup task that will run weekly on Sundays at 12:00 a.m.:

Use dark colors for code blocksCopy
POST /context/admin/system/tasks/createTask HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

title=backups&type=CreateBackup&parameters={"name": "myBackup","passcode": "myPassword","storeName": "backups","metaData": {"recurring": false,"startTime": "04:00","retention": {"type": "day","value": 14}},"retentionOffset": 1209600000}&startDate=1589428800000&endDate=1589428800000&minute=0&hour=0&dayOfMonth=?&month=*&dayOfWeek=7&maxOccurrences=1&f=pjson&token=<token>

The following is a sample POST request for the createTask operation that demonstrates scheduling a CreateHealthCheckReports task that will run daily at 11:02 PM:

Use dark colors for code blocksCopy
POST /context/admin/system/tasks/createTask HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

title=DailyReport&type=CreateHealthCheckReports&startDate=1731087120000&minute=32&hour=17&dayOfMonth=*/1&month=*&dayOfWeek=?&dayOffset=0&parameters={"name": "DailyReport","suiteIds": "BSHC-001","itemId": "","metaData": {"recurring": true,"startTime": "17:32","retention": {"type": "day","value": 14}},"retentionOffset": 1209600000}&maxOccurrences=&f=pjson&token=<token>

JSON Response examples

The sample response below is returned for a CreateBackup task:

Use dark colors for code blocksCopy
{
  "name": "schedule1",
  "passcode": "{crypt}3ngE7lQuQGDfaiab4uogjg==",
  "storeName": "default",
  "itemId": "",
  "metaData": {
    "recurring": true,
    "startTime":" 20:00",
    "retention": {
      "type": "day",
      "value": 14
    }
  },
  "retentionOffset": 1209600000
}

The sample response below is returned for a CreateHealthCheckReports task:

Use dark colors for code blocksCopy
{
  "task": {
    "generation": 0,
    "active": true,
    "ownerId": "0db8f0e0b5cd474e838bf45b9ad5d741",
    "type": "CREATE_HEALTHCHECK_REPORT_TASK_TYPE",
    "orgId": "0123456789ABCDEF",
    "cronSchedule": {
      "dayOfWeek": "?",
      "hour": "17",
      "month": "*",
      "dayOfMonth": "*/1",
      "minute": "32"
    },
    "cronExpression": "0 32 17 */1 * ?",
    "runIntervalSeconds": 0,
    "taskType": "CreateHealthCheckReports",
    "taskTitle": "DailyReport",
    "maxOccurrences": -1,
    "id": "961d54be9fe14500be6c0b573d33f011",
    "parameters": {
      "itemId": "",
      "metaData": {
        "recurring": true,
        "startTime": "17:32",
        "retention": {
          "type": "day",
          "value": 14
        }
      },
      "retentionOffset": 1209600000,
      "name": "DailyReport",
      "suiteIds": "BSHC-001"
    },
    "taskId": "961d54be9fe14500be6c0b573d33f011",
    "startDate": 1731087120000
  },
  "status": "success"
}