REST API - POST Create Task (Backup)

This operation runs a backup job for a subclient or a backup set.

Request

Syntax

 
POST <webservice>/CreateTask HTTP/1.1
 Host: <host name>
 Accept: application/xml
 Authtoken: <authentication token>
 Content-type: application/xml
 <create_task_template_backup.xml>

where <webservice> is the root path used to route the API requests to the Web Server.

For more information, see Available Web Services for REST API.

Request Headers

Name	Description
Host	The host name of the Web Server or Web Console used in the API request.
Accept	The format of the response. Valid values are: application/xml or application/json.
Authtoken	The authentication token received after successfully logging on. For details on receiving an authentication token, see Authentication.
Content-type	The media type contained in the request body.

XML

Download the create_task_template_backup.xml file required for this request. The following table displays the parameters for the create_task_template_backup.xml file.

Parameter	Description	Element	Parent Element
_type_	The entity where the backup is initiated. Valid values are: SUBCLIENT_ENTITY BACKUPSET_ENTITY	associations	taskInfo
appName	The name of the application. Valid values are: Active Directory DB2 DB2 MultiNode DB2 on UNIX Documentum Exchange Database File System Informix Database MySQL NAS Notes Database Oracle Oracle RAC PostgreSQL SAP HANA SAP for MAX DB SAP for Oracle Sharepoint Server SQL Server Sybase Database Virtual Server	associations	taskInfo
applicationId	The ID of the application. Valid values are: 53, for Exchange Database 33, for File System 104, for MySQL 13, for NAS 59, for Notes Database 22, for Oracle 80, for Oracle RAC 125, for PostgreSQL 79, for SAP for MAX DB 61, for SAP for Oracle 81, for SQL Server 5, for Sybase Database 106, Virtual Server	associations	taskInfo
backupsetName	The name of the backup set.	associations	taskInfo
backupsetId	The system-generated ID assigned to the backup set.	associations	taskInfo
clientName	The name of the client.	associations	taskInfo
clientId	The system-generated ID assigned to the client.	associations	taskInfo
commCellId	The CommCell ID of the CommServe.	associations	taskInfo
instanceName	The name of the instance, for example: DefaultInstanceName.	associations	taskInfo
instanceId	The system-generated ID assigned to the instance.	associations	taskInfo
subclientName	The name of the subclient. To update all of the subclients for a backup set, do not use the subclientName parameter.	associations	taskInfo
subclientId	The system-generated ID assigned to the subclient.	associations	taskInfo
backupLevel	The type of backup to perform. Valid values are: FULL INCREMENTAL DIFFERENTIAL SYNTHETIC_FULL	backupOpts	options
collectMetaInfo	The option to collect file and folder metadata to enable granular recovery. By default this is true for full and streaming backups and false for IntelliSnap and incremental backups. Valid values are True/False.	backupOpts	options
doNotTruncateLog	The option to not truncate the logs. Valid values are True/False.	backupOpts	options
incLevel	The option to run an incremental backup before or after a synthetic full backup. Use the incLevel parameter with the runIncrementalBackup parameter. Valid values are: BEFORE_SYNTH AFTER_SYNTH	backupOpts	options
isSpHasInLineCopy	Valid values are True/False.	backupOpts	options
runIncrementalBackup	The option to run an incremental backup with a synthetic full backup. Use the backupLevel parameter to define the type of backup. Use the incLevel parameter to define the order in which the incremental and synthetic full backups are run. Valid values are True/False.	backupOpts	options
runSILOBackup	The option to run a SILO backup. Valid values are True/False.	backupOpts	options
sybaseSkipFullafterLogBkp	The option to skip a full backup for new Sybase databases after a log backup. Valid values are True/False.	backupOpts	options
truncateLogsOnSource	The option to truncate logs on source. Valid values are True/False.	backupOpts	options
createNewIndex	SAP Oracle: The option to create a new index. Valid values are True/False.	dataOpt	backupOpts
enableIndexCheckPointing	The option to enable index check pointing. Valid values are True/False.	dataOpt	backupOpts
enforceTransactionLogUsage	The option to use the transaction logs for granular restarts. Valid values are True/False.	dataOpt	backupOpts
followMountPoints	The option to back up the data in the mount point. Valid values are True/False.	dataOpt	backupOpts
skipCatalogPhaseForSnapBackup	The option to skip the catalog phase for snap backups. Valid values are True/False.	dataOpt	backupOpts
skipConsistencyCheck	The option to skip the consistency check. Valid values are True/False.	dataOpt	backupOpts
spaceReclamation	The option to check for deleted stubs. Valid values are True/False.	dataOpt	backupOpts
verifySynthFull	The option to verify the synthetic full backup. Valid values are True/False.	dataOpt	backupOpts
backupFailedVMsOnly	The option to include only VMs that failed to back up in a previous job. Valid values are True/False.	vsaBackupOptions	backupOpts
driveId	The code for the drive used to perform the backup operation.	drive	dataPathOpt
drivePoolId	The code for the drive pool used to perform the backup operation.	drivePool	dataPathOpt
libraryId	The code for the library used to perform the backup operation.	library	dataPathOpt
mediaAgentId	The code for the MediaAgent used to perform the backup operation.	mediaAgent	dataPathOpt
spareMediaGroupId		spareGroup	dataPathOpt
allowOtherSchedulesToUseMediaSet	The option to allow jobs that are part of a schedule and that use a specific storage policy to start new media. This option prevents other jobs from writing to the media. Valid values are True/False.	mediaOpt	backupOpts
markMediaFullOnSuccess	The option to mark the media full two minutes after the completion of the backup operation. Valid values are True/False.	mediaOpt	backupOpts
numberofDays	The number of days to keep the job. Use this parameter when the retentionJobType parameter is set to "NO_OF_DAYS."	mediaOpt	backupOpts
reserveResourcesBeforeScan	The option to reserve the media before the scan phase instead of before the operation phase. Valid values are True/False.	mediaOpt	backupOpts
retentionJobType	The option to set job retention. Valid values are: INFINITE, to retain this job indefinitely NO_OF_DAYS, to prune the job after the number of days specified in the numberofDays parameter STORAGE_POLICY_DEFAULT, to apply the retention rules of the associated storage policy	mediaOpt	backupOpts
startNewMedia	The option to start the backup operation on new media. Valid values are True/False.	mediaOpt	backupOpts
excludeMediaNotCopied	The option to exclude media with jobs that need to be copied. Valid values are True/False.	vaultTrackerOpt	backupOpts
exportMediaAfterJobFinishes	The option to export the media after the job is complete. Valid values are True/False.	vaultTrackerOpt	backupOpts
filterMediaByRetention	The option to filter media by extended retention. Use this parameter with the mediaWithExtendedRetentionJobs parameter. Valid values are True/False.	vaultTrackerOpt	backupOpts
mediaWithExtendedRetentionJobs	The option to specify whether media with at least one extended retention job or media with no extended retention will be exported. Use this parameter when the filterMediaByRetention parameter is set to "true." Valid values are True/False.	vaultTrackerOpt	backupOpts
trackTransit	The option to track transit information. Valid values are True/False.	vaultTrackerOpt	backupOpts
useVirtualMailSlots	The option to store exported media in virtual mail slots. Valid values are True/False.	vaultTrackerOpt	backupOpts
exportLocation	The export location. Export locations are defined in Storage Resources > Locations.	vaultTrackerOpt	backupOpts
inTransitLocation		vaultTrackerOpt	backupOpts
active	The option to export and track media with an "active" status. Valid values are True/False.	mediaStatus	vaultTrackerOpt
all	The option to export and track all media. Valid values are True/False.	mediaStatus	vaultTrackerOpt
bad	The option to export and track media with a "bad" status. Valid values are True/False.	mediaStatus	vaultTrackerOpt
full	The option to export and track media with a "full" status. Valid values are True/False.	mediaStatus	vaultTrackerOpt
overwriteProtected	The option to export and track media with a "read-only" status. Valid values are True/False.	mediaStatus	vaultTrackerOpt
jobDescription		commonOpts	options
enableNumberOfRetries	The option to enable retrying the job. When this parameter is set to "true," use the numberOfRetries parameter to set the number of tries. Valid values are True/False.	jobRetryOpts	commonOpts
killRunningJobWhenTotalRunningTimeExpires	The option to kill the job when the total running time elapses, even if the job is in a "Running" state. The total running time is in the totalRunningTime parameter. Use this parameter with the enableTotalRunningTime parameter. Valid values are True/False.	jobRetryOpts	commonOpts
numberOfRetries	The number of times that Job Manager attempts to restart the job. Use this parameter when the enableNumberOfRetries parameter is set to "true."	jobRetryOpts	commonOpts
enableTotalRunningTime	The option to kill the job when the total running time elapses and the job is not in a "Running" state. Use this parameter with the totalRunningTime parameter. To override the "Running" state restriction, use this parameter with the killRunningJobWhenTotalRunningTimeExpires parameter. Valid values are True/False.	runningTime	jobRetryOpts
totalRunningTime	The maximum elapsed time, in hours and minutes, that the job should exist before it is killed. (Jobs in a "Running" state are not killed even after the time elapses unless the killRunningJobWhenTotalRunningTimeExpires parameter is set to "true.") Use this parameter when the enableTotalRunningTime parameter is set to "true." The format of the time is HH:MM:SS. For example, 01:05:00 is one hour, five minutes, and no seconds.	runningTime	jobRetryOpts
priority	The priority of the job. The highest priority is zero and the lowest priority is 999.	startUpOpts	commonOpts
startInSuspendedState	The option to start the job in a suspended state. The suspended job cannot run until it is manually resumed. Valid values are True/False.	startUpOpts	commonOpts
useDefaultPriority	The option to use the default priority for the job. Valid values are True/False.	startUpOpts	commonOpts
active_end_date	The end date of the schedule specified in the UNIX timestamp format. The timestamp is always the beginning of the day (00:00 hours) for the specified date.	pattern	subTasks
active_end_occurence	The number of times you want to repeat the schedule.	pattern	subTasks
active_end_time	The end time of the schedule specified in seconds.	pattern	subTasks
active_start_date	The start date of the schedule specified in UNIX timestamp format. The timestamp is always the beginning of the day (00:00 hours) for the specified date.	pattern	subTasks
active_start_time	The start time of the schedule specified in seconds.	pattern	subTasks
description	The description of the schedule pattern, for example, Every year on day 10 of January at 12:00 AM starting December 16, 2013 and repeats every 0 hr(s) 0 min(s) until 12:00 AM.	pattern	subTasks
flags		pattern	subTasks
freq_interval	The meaning of this parameter changes based on the value of the freq_type parameter: If freq_type equals One_Time or Automatic_Schedule, freq_interval is not used and is set to 0. If freq_type equals Daily, freq_interval is the number of days the schedule should repeat. For example, the parameters to run a schedule daily every 17 days are freq_type="Daily" and freq_interval="17". If freq_type equals Weekly, freq_interval is the sum of the bit form values assigned to the days of the week. The bit form values are: Sunday = 1 Monday = 2 Tuesday = 4 Wednesday = 8 Thursday = 16 Friday = 32 Saturday = 64 For example, the parameters to run a schedule weekly on Monday and Saturday are freq_type="Weekly" and freq_interval="66" and the parameters to run a schedule weekly on Sunday, Monday, Tuesday, Wednesday, and Thursday are freq_type="Weekly" and freq_interval="31". If freq_type equals Monthly, freq_interval is the day of the month the schedule runs. For example, the parameters to run a schedule monthly on the thirteenth of every month are freq_type="Monthly" and freq_interval="13". If freq_type equals Monthly_Relative, freq_interval is the day of the week the schedule runs. Valid values are: 1, for Sunday 2, for Monday 3, for Tuesday 4, for Wednesday 5, for Thursday 6, for Friday 7, for Saturday 8, for any day 9, for a weekday 10, for a weekend day If freq_type equals Yearly or Yearly_Relative, freq_interval is the day of the month the schedule runs.	pattern	subTasks
freq_recurrence_factor	The meaning of this parameter changes based on the value of the freq_type parameter: If freq_type equals Yearly or Yearly_Relative, freq_recurrence_factor is the month the schedule runs. For example, the parameters to run a yearly schedule every July are freq_type="Yearly" and freq_recurrence_factor="7". If freq_type equals Daily, Weekly, Monthly or Monthly_Relative, freq_recurrence_factor is set to 1. If freq_type equals One_Time or Automatic_Schedule, freq_recurrence_factor is set to 0.	pattern	subTasks
freq_relative_interval	The meaning of this parameter changes based on the value of the freq_type parameter: If freq_type equals Monthly_Relative or Yearly_Relative, freq_relative_interval is the ordinal numbers indicating when the schedule runs. Use with the freq_interval parameter. Valid values are: 1, if the exception occurs on the first n 2, if the exception occurs on the second n 3, if the exception occurs on the third n 4, if the exception occurs on the fourth n 5, if the exception occurs on the last n If freq_type equals any other value, freq_recurrence_factor is set to 0.	pattern	subTasks
freq_restart_interval		pattern	subTasks
freq_subday_interval	The time interval to repeat the schedule.	pattern	subTasks
freq_type	Indicates how often the schedule is run. Valid values are: One_Time Daily Weekly Monthly Monthly_Relative Yearly Yearly_Relative Automatic_Schedule	pattern	subTasks
name		pattern	subTasks
patternId	The system-generated ID assigned to the schedule pattern.	pattern	subTasks
calendarId	The code for the calendar, for example, 1.	calendar	pattern
calendarName	The name of the calendar, for example, Standard.	calendar	pattern
Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday	The days of the week defined for a weekly schedule. Valid values are True/False.	daysToRun	pattern
day	The day of the week defined for a monthly schedule. Use this parameter with the week parameter. Valid values are: Sunday Monday Tuesday Wednesday Thursday Friday Days Weekday Weekend_Day	daysToRun	pattern
week	The week defined for a monthly schedule. Use this parameter with the day parameter. Valid values are: first second third fourth last	daysToRun	pattern
onDayNumber	The specific day of the month defined for a monthly schedule. Valid values are 1 through 31.	daysToRun	pattern
exception	The option to set an exception for a repeating schedule. Multiple exceptions can be added for the repeating schedule: <repeatPattern exception="true" occurrence="1" onDay="1" onDayNumber="0"/> <repeatPattern exception="true" occurrence="0" onDay="0" onDayNumber="268435460"/> Use the occurrence and the onDay or the onDayNumber parameters to define the exception. Valid values are True/False.	repeatPattern	pattern
occurrence	The ordinal numbers indicating when the exception to a repeating schedule occurs. Use this parameter with the onDay parameter or the onDayNumber parameter. Valid values are: 0, if the exception occurs on specific days of the month 1, if the exception occurs on the first n 2, if the exception occurs on the second n 4, if the exception occurs on the third n 8, if the exception occurs on the fourth n 16, if the exception occurs on the last n For example, if a repeating schedule skips the fourth Friday of the month, then the parameter is occurrence="8". If a repeating schedule skips the last Friday of the month, then the parameter is occurrence="16".	repeatPattern	pattern
onDay	The day of the week indicating when the exception to a repeating schedule occurs. Use this parameter with the occurrence parameter. Valid values are: 0, to use the onDayNumber parameter 1, for Sunday 2, for Monday 4, for Tuesday 8, for Wednesday 16, for Thursday 32, for Friday 64, for Saturday 128, for any day 256, for a weekday 512, for a weekend day For example, if a repeating schedule skips the fourth Friday of the month, then the parameters are occurrence="8" and onDay="32". If a repeating schedule skips the last weekday of the month, then the parameters are occurrence="16" and onDay="256".	repeatPattern	pattern
onDayNumber	The days of the month indicating when the exception to a repeating schedule occurs. Use this parameter with the occurrence parameter. Valid values are the sum of the bit form values assigned to the days of the month. The bit form values are calculated as follows: first day = 1 second to thirty-first day = 2⁽n^-1) where n is the day of the month For example, if a repeating schedule skips the first day and thirty-first day of the month, then the parameter is onDayNumber="1073741825" using the formula 1+2^(31-1). If a repeating schedule skips the third day and twenty-ninth day of the month, then the parameter is onDayNumber="268435460" using the formula 2^(3-1)+2^(29-1).	repeatPattern	pattern
TimeZoneName	If the taskType parameter equals SCHEDULE, a schedule pattern must be set. The name of the time zone. Sample values: (UTC) Coordinated Universal Time (UTC-05:00) Eastern Time (US & Canada)	TimeZone	pattern
TimeZoneId	The ID of the time zone to associate with the schedule. For a list of valid values, see Time Zone IDs and Names.	TimeZone	pattern
subTaskName	The name of the schedule if the taskType parameter equals SCHEDULE.	subTask	subTasks
operationType	The type of operation. Valid value is BACKUP.	subTask	subTasks
subTaskType	The type of subtask. Valid value is BACKUP.	subTask	subTasks
initiatedFrom	Valid values are: GUI COMMANDLINE	task	taskInfo
policyType	Valid value is DATA_PROTECTION.	task	taskInfo
sequenceNumber	A user-defined number other than zero.	task	subTasks
taskId		task	taskInfo
taskType	The option to schedule the task or to run the task immediately. Valid values are: IMMEDIATE SCHEDULE Note: If the taskType parameter equals SCHEDULE, a schedule pattern must be set. Review the parameters in the <pattern> element.	task	taskInfo
alertId	The ID of the alert to associate with the schedule.	alert	task
alertName	The name of the alert to associate with the schedule.	alert	task
disabled	Valid values are True/False.	taskFlags	task

Response

Response Parameters

Parameter	Description	Element
taskId	The system-generated ID assigned to the task.	TMMsg_CreateTaskResp
val	The system-generated ID assigned to the job.	jobIds

Examples

Sample Request

This request starts an immediate backup job.

POST <webservice>/CreateTask HTTP/1.1
 Host: client.mydomain.com
 Accept: application/xml
 Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
 0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
 8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
 40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
 68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
 3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
 Content-type: application/xml
 <TMMsg_CreateTaskReq>
   <taskInfo>
     <associations _type_="SUBCLIENT_ENTITY" appName="File System" applicationId="33" backupsetName="defaultBackupSet" clientName="client001" commCellId="0" subbclientName="default" />
     <subTasks>
       <options>
         <backupOpts backupLevel="FULL" doNotTruncateLog="false" isSpHasInLineCopy="false" runIncrementalBackup="true" runSILOBackup="false" sybaseSkipFullafterLogBkp="false" truncateLogsOnSource="false">
           <dataOpt createNewIndex="false" enableIndexCheckPointing="false" enforceTransactionLogUsage="false" followMountPoints="true" skipCatalogPhaseForSnapBackup="false" skipConsistencyCheck="false" spaceReclamation="false" verifySynthFull="false" />
           <dataPathOpt>
             <drive driveId="0" />
             <drivePool drivePoolId="0" />
             <library libraryId="0" />
             <mediaAgent mediaAgentId="0" />
             <spareGroup spareMediaGroupId="0" />
           </dataPathOpt>
           <mediaOpt allowOtherSchedulesToUseMediaSet="true" markMediaFullOnSuccess="false" numberofDays="30" reserveResourcesBeforeScan="false" 
 retentionJobType="2" startNewMedia="true" />
         </backupOpts>
         <commonOpts jobDescription="">
           <jobRetryOpts enableNumberOfRetries="false" killRunningJobWhenTotalRunningTimeExpires="false" numberOfRetries="0">
             <runningTime enableTotalRunningTime="false" totalRunningTime="3600" />
           </jobRetryOpts>
           <startUpOpts priority="166" startInSuspendedState="false" useDefaultPriority="true" />
         </commonOpts>
       </options>
       <subTask operationType="2" subTaskType="2" />
     </subTasks>
     <task initiatedFrom="COMMANDLINE" policyType="DATA_PROTECTION" sequenceNumber="10" taskId="0" taskType="IMMEDIATE">
       <taskFlags disabled="false"/>
     </task>
   </taskInfo>
 </TMMsg_CreateTaskReq>

This request schedules a backup job.

<?xml version="1.0" encoding="utf-8" ?>
 <TMMsg_CreateTaskReq>
 <taskInfo>
     <associations _type_="" appName="Virtual Server" applicationId="106" backupsetName="defaultBackupSet" backupsetId="190" clientName="client001" clientId="89" commCellId="" instanceName="VMware" instanceId="100" subclientName="default" subclientId="11" />
     <subTasks>
       <options>
         <backupOpts backupLevel="Incremental" collectMetaInfo="true" doNotTruncateLog="false" incLevel="BEFORE_SYNTH" isSpHasInLineCopy="" runIncrementalBackup="true" runSILOBackup="" sybaseSkipFullafterLogBkp="false" truncateLogsOnSource="false">
           <dataOpt createNewIndex="true" enableIndexCheckPointing="" enforceTransactionLogUsage="false" followMountPoints="true" skipCatalogPhaseForSnapBackup="" skipConsistencyCheck="false" spaceReclamation="" verifySynthFull="" />
           <vsaBackupOptions>
             <backupFailedVMsOnly>false</backupFailedVMsOnly>
           </vsaBackupOptions>
         </backupOpts>
       </options>
       <pattern active_end_occurence="0" active_end_time="00:00:00" active_start_date="2016-05-03 00:00:00" active_start_time="21:00:00" description="Every week on Monday,Tuesday,Wednesday,Thursday,Friday at 9:00 PM starting May 2, 2016 " freq_interval="62" freq_recurrence_factor="1" freq_relative_interval="0" freq_subday_interval="0" freq_type="weekly">
         <calendar calendarId="1" calendarName="standard"/>
         <daysToRun Monday="true" Tuesday="true" Wednesday="true" Thursday="true" Friday="true" />
         <timeZone TimeZoneId="100" TimeZoneName="(UTC) Coordinated Universal Time"/>
       </pattern>
       <subTask operationType="2" subTaskType="2" subTaskName="test_schedule_1" />
     </subTasks>
     <task initiatedFrom="COMMANDLINE" policyType="DATA_PROTECTION" sequenceNumber="10" taskId="0" taskType="SCHEDULE">
       <taskFlags disabled="false"/>
     </task>
 </taskInfo>
 </TMMsg_CreateTaskReq>

Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 <TMMsg_CreateTaskResp taskId="6441">
   <jobIds val="40983" />
 </TMMsg_CreateTaskResp>