Scheduled tasks

Edit online

The scheduled tasks APIs can be executed by using curl commands. These APIs can be used for scheduling start, stop, restart, deploy VMs, and deploy VMs using deploy templates. You can also choose to fetch list of tasks that are scheduled by users who are assigned to different roles.

Before you use GraphQL APIs

The scheduled tasks APIs are based on GraphQL APIs. You must obtain a token before you use the GraphQL APIs to schedule a task. For more information about GraphQL APIs, see Apollo GraphQL Docs.

Example code to obtain a token.

Request : 
curl \
  -H "Content-Type: application/json" \
  -D - \
  -d '{ "query": "mutation { loginToKeystone(username: \"root\" password: \"passw0rd\" project: \"ibm-default\") { status msg user { token } } }" }' \
  http://localhost:8002/graphql
  
Response : 

HTTP/1.1 200 OK
X-DNS-Prefetch-Control: off
X-Frame-Options: SAMEORIGIN
Strict-Transport-Security: max-age=15552000; includeSubDomains
X-Download-Options: noopen
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Origin: *
Vary: Origin
Access-Control-Allow-Credentials: true
Content-Type: application/json; charset=utf-8
Content-Length: 603
ETag: W/"25b-yn0uipQluko2CPupcBTSKgvFefs"
Date: Fri, 03 Dec 2021 04:09:01 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"data":{"loginToKeystone":{"status":"success","msg":"User authenticated successfully","user":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoicm9vdCIsIm9zVG9rZW4iOiJnQUFBQUFCaHFaaGRIalFXY3lHbURmTjNWMGxnbDJYMWtmaTJ0RTRZbkRaWGJvRUhKNmZ1cHpqdHo4TmVsT2tZQ0pQYnB5LUVJMHRzNy13bjNEVFQxdktiNUN6ZDA4N0VXaC05Z2VibnctaDFMSnRHTzV6SGhUbGF3N2hiVVhudzBsTDVYU1RXaGdhYjNEWlpVQk92a3ZFblhKZmI2ZTBieWRJXy1iREFlbWlJeDN3aEhON3pOWHhVbEFzck15ODgtWDYwaDJuREhfckNHVDhIR08tckN5M2ZSS05DMkFCM1cxWWNxQjkxWDlvY2NrTVhOZFcwLVBjIiwiaWF0IjoxNjM4NTA0NTQxLCJleHAiOjE2Mzg1MjYxNDB9.pv1eWI6fGSacutVzjkKzXclMxDN0x-F6UXUfeEPSVqQ"}}}}

The token received from the response can be used to execute schedule task APIs.

Schedule stop VMs
Schedule start VMs
Schedule restart VMs
Schedule deploy VMs
Schedule deploy VMs using deploy templates
View all scheduled tasks

Schedule stop VMs

Use this API to schedule stop operation on selected VMs. This API takes VM ID along with scheduled timestamp and whether to hard stop the VM in the request body. This API returns task ID and status in the response body. If invalid parameters are provided, the API does not return any response.

Response code

Status Code: Successful (200)

Request parameters

Table 1. Parameters in the request for scheduling stop VMs
Name	Style	Type	Description
`ids`	body	list	List of comma separated VM IDs.
`isImmediate`	body	Boolean	Whether to hard stop a VM. If you set this parameter to true, the VM is hard stopped.
`scheduledAt`	body	string	Specify date and time when the VM must be stopped.
`comment`	body	string	Optional. Provide any comments for scheduling the VM stop task.

Example curl request for scheduling stop VMs task:

curl \
  -H "Content-Type: application/json" \
  -H "token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoicm9vdCIsIm9zVG9rZW4iOiJnQUFBQUFCaHFaaGRIalFXY3lHbURmTjNWMGxnbDJYMWtmaTJ0RTRZbkRaWGJvRUhKNmZ1cHpqdHo4TmVsT2tZQ0pQYnB5LUVJMHRzNy13bjNEVFQxdktiNUN6ZDA4N0VXaC05Z2VibnctaDFMSnRHTzV6SGhUbGF3N2hiVVhudzBsTDVYU1RXaGdhYjNEWlpVQk92a3ZFblhKZmI2ZTBieWRJXy1iREFlbWlJeDN3aEhON3pOWHhVbEFzck15ODgtWDYwaDJuREhfckNHVDhIR08tckN5M2ZSS05DMkFCM1cxWWNxQjkxWDlvY2NrTVhOZFcwLVBjIiwiaWF0IjoxNjM4NTA0NTQxLCJleHAiOjE2Mzg1MjYxNDB9.pv1eWI6fGSacutVzjkKzXclMxDN0x-F6UXUfeEPSVqQ" \
  -D - \
  -d '{ "query": "mutation { stopVMs(ids: [\"5b2fedcd-8262-43a4-8973-a18ed462f23c\"] scheduledAt: \"Fri Dec 03 2021 10:58:00 GMT+0530 (India Standard Time)\") { taskId status name } }" }' \
  http://localhost:8002/graphql

Response body

Table 2. Parameters in the response for scheduling stop VMs
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.

Example response:

{
  "data": {
    "stopVMs": {      
      "taskId": "d9ff5bd4-31d3-469b-98fd-8b0f75016d63",
      "status": "Scheduled",
      "name": "Stop VMs"
    }
  }
}

Schedule start VMs

This API allows you to schedule start operation on selected VMs. This API takes VM IDs along with scheduled timestamp in the request body and returns task ID and task status in the response body. If invalid parameters are provided, the API does not return any response.

Response code

Status Code: Successful (200)

Request parameters

Table 3. Parameters in the request for scheduling start VMs
Name	Style	Type	Description
`ids`	body	list	List of comma separated VM IDs.
`scheduledAt`	body	string	Specify date and time when the VM must be started.
`comment`	body	string	Optional. Provide any comments for scheduling the VM start task.

Example:

curl \
  -H "Content-Type: application/json" \
  -H "token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoicm9vdCIsIm9zVG9rZW4iOiJnQUFBQUFCaHFaaGRIalFXY3lHbURmTjNWMGxnbDJYMWtmaTJ0RTRZbkRaWGJvRUhKNmZ1cHpqdHo4TmVsT2tZQ0pQYnB5LUVJMHRzNy13bjNEVFQxdktiNUN6ZDA4N0VXaC05Z2VibnctaDFMSnRHTzV6SGhUbGF3N2hiVVhudzBsTDVYU1RXaGdhYjNEWlpVQk92a3ZFblhKZmI2ZTBieWRJXy1iREFlbWlJeDN3aEhON3pOWHhVbEFzck15ODgtWDYwaDJuREhfckNHVDhIR08tckN5M2ZSS05DMkFCM1cxWWNxQjkxWDlvY2NrTVhOZFcwLVBjIiwiaWF0IjoxNjM4NTA0NTQxLCJleHAiOjE2Mzg1MjYxNDB9.pv1eWI6fGSacutVzjkKzXclMxDN0x-F6UXUfeEPSVqQ" \
  -D - \
  -d '{ "query": "mutation { startVMs(ids: [\"5b2fedcd-8262-43a4-8973-a18ed462f23c\", \"34fcb6f8-d0b6-4877-bab5-b306938bfd0f\"] scheduledAt: \"Fri Dec 03 2021 12:35:00 GMT+0530 (India Standard Time)\") { taskId status name } }" }' \
  http://localhost:8002/graphql

Response body

Table 4. Parameters in the response for scheduling start VMs
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.

Example response:

{
  "data": {
    "startVMs": {
      "taskId": "7a000fc9-6e73-4e56-8a55-b7c9b04a045a",
      "status": "Scheduled",
      "name": "Start VMs"
    }
  }
}

Schedule restart VMs

Use this API to schedule restart operation on selected VMs. This API takes VM IDs along with scheduled timestamp in the request body. You can also choose whether to soft or hard stop and restart a VM. This API returns task ID and task status in the response body. If invalid parameters are provided, the API does not return any response.

Response code

Status Code: Successful (200)

Request parameters

Table 5. Parameters in the request for scheduling restart VMs
Name	Style	Type	Description
`ids`	body	list	List of comma separated VM IDs.
`restartType`	body	string	Optional. Whether to hard stop and restart a VM. If you set this parameter to soft, the VM shuts down normally. When set to hard, the VM shuts down immediately without the operating system shutting down first. A hard restart might result in the loss of data.
`scheduledAt`	body	string	Specify date and time when the VM must be restarted.
`comment`	body	string	Optional. Provide any comments for scheduling the VM restart task.

Example:

curl \
  -H "Content-Type: application/json" \
  -H "token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoicm9vdCIsIm9zVG9rZW4iOiJnQUFBQUFCaHFaaGRIalFXY3lHbURmTjNWMGxnbDJYMWtmaTJ0RTRZbkRaWGJvRUhKNmZ1cHpqdHo4TmVsT2tZQ0pQYnB5LUVJMHRzNy13bjNEVFQxdktiNUN6ZDA4N0VXaC05Z2VibnctaDFMSnRHTzV6SGhUbGF3N2hiVVhudzBsTDVYU1RXaGdhYjNEWlpVQk92a3ZFblhKZmI2ZTBieWRJXy1iREFlbWlJeDN3aEhON3pOWHhVbEFzck15ODgtWDYwaDJuREhfckNHVDhIR08tckN5M2ZSS05DMkFCM1cxWWNxQjkxWDlvY2NrTVhOZFcwLVBjIiwiaWF0IjoxNjM4NTA0NTQxLCJleHAiOjE2Mzg1MjYxNDB9.pv1eWI6fGSacutVzjkKzXclMxDN0x-F6UXUfeEPSVqQ" \
  -D - \
  -d '{ "query": "mutation { restartVMs(ids: [\"5b2fedcd-8262-43a4-8973-a18ed462f23c\", \"34fcb6f8-d0b6-4877-bab5-b306938bfd0f\"] scheduledAt: \"Fri Dec 04 2021 12:35:00 GMT+0530 (India Standard Time)\") { taskId status name } }" }' \
  http://localhost:8002/graphql

Response body

Table 6. Parameters in the response for scheduling restart VMs
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.

Example response:

{
  "data": {
    "restartVMs": {
      "taskId": "e971ec3e-187b-4def-910a-9ebf4a02cbf2",
      "status": "Scheduled",
      "name": "Restart VMs"
    }
  }
}

Schedule deploy VMs

Use this API to schedule deploy operation on selected VMs. This API takes image IDs, deploy target, SCG ID, and Compute template ID, VM deploy count along with scheduled time stamp in the request body. This API returns task ID and status in the response body. If invalid parameters are provided, the API does not return any response.

Response code

Status Code: Successful (200)

Request parameters

Table 7. Parameters in the request for scheduling deploy VMs
Name	Style	Type	Description
`name`	body	string	Name of the VM.
`imageId`	body	string	OpenStack ID of the image.
`deployTargetHostGroupID`	body	string	OpenStack ID of the host group.
`deployTargetHostID`	body	string	OpenStack ID of the host.
`computeTemplateId`	body	string	ID of the Compute template.
`scgID`	body	string	OpenStack ID of the storage connectivity group.
`vcpus`	body	integer	Specify the number of vCPUs.
`procUnits`	body	float	Specify the number of processing units.
`memory`	body	integer	Specify the amount of memory space needed in MB.
`count`	body	integer	Number of VMs to deploy.
`scheduledAt`	body	string	Select time when the VMs must be deployed.
`networks`	body	list	Specify the network attributes such as IP address, whether it is a primary network and SR-IOV redundant, and vNIC capacity (multiple of 2, minimal of 2, up to a maximum of 100). Example network attributes: `[ { id: "0bbf0b55-e379-4524-a42e-672fd97454d4", isPrimary: true, ipAddress: x.x.x.x, sriovInputRedundantAdapter: true, sriovInputvNicCapacity: 2 } ]`

Example data to be passed in curl query:

mutation {
  deployVM(
    input: {
      name: "test-gql_2",     
      imageID: "b533a239-ea6e-4501-8bc6-c0b05f942e40",
      deployTargetHostGroupID: "1",
      computeTemplateId: "c6f8c804-7c71-4cd6-9a46-b60071b32931"
      scgID: "5341a5d4-b1dc-4d00-9ebb-9abfedf472f7",     
      vcpus: 1
      procUnits: 0.1
      memory: 2048     
      networks: {
        id: "0bbf0b55-e379-4524-a42e-672fd97454d4",       
      }
      count: 1
      scheduledAt: "Mon Nov 26 2021 06:00:00 GMT+0530 (India Standard Time)"
    }
  ) {
    taskId
    status
    name
  }
}

Response body

Table 8. Parameters in the response for scheduling deploy VMs
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.

Example response:

{
  "data": {
    "deployVM": {
      "taskId": "14336399-6f28-4d60-a200-191666fbceb9",
      "status": "Scheduled",
      "name": "Deploy VMs"
    }
  }
}

Schedule deploy VMs using deploy templates

Users that are assigned to roles admin, admin_assist, or self_service can use this API to schedule deploy operation using deploy templates. This API takes VM name, deploy template ID, VM deploy count along with scheduled time stamp in the request body. This API returns task ID, name, and status in the response body. If invalid parameters are provided, the API does not return any response.

Note: Email notifications related to scheduled deploy operation for users assigned to self_service role is planned for future releases.

Response code

Status Code: Successful (200)

Request parameters

Table 9. Parameters in the request for scheduling deploy VMs using deploy template
Name	Style	Type	Description
`name`	body	string	Name of the VM.
`deployTemplateId`	body	string	ID of the deploy template.
`count`	body	integer	Number of VMs to deploy.
`scheduledAt`	body	string	Select time when the VMs must be deployed.
`requestJustification` (for self_service role only)	body	string	An empty message or justification message.

Example data to be passed in curl query:

mutation {
	deployVMUsingDT(
    input: {
      name: "dt_test"
      count: 1,
      deployTemplateId: "d3a76392-44bc-4172-bff8-f4e1fc3ef7f7"      
      scheduledAt: "Tue Apr 12 2022 16:12:10 GMT+0530 (India Standard Time)"      
    }
  ) {
    taskId
    status
    name
  }
}

Response body

Table 10. Parameters in the response for scheduling deploy VMs using deploy template
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.

Example response:

{
  "data": {
    "deployVMUsingDT": {
      "taskId": "69767469-32fb-4d50-8f7e-d9be08775423",
      "status": "Scheduled",
      "name": "Deploy VMs Using Deploy Template"
    }
  }
}

View all scheduled tasks

Use this API to view all tasks that are scheduled by users who are assigned to different roles. This API returns task ID, task status, name of the scheduled task, scheduled task date and time, resource type and resource names in the response body. If invalid parameters are provided, the API does not return any response.

Example format for request:

curl \
  -H "Content-Type: application/json" \
  -H "token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoicm9vdCIsIm9zVG9rZW4iOiJnQUFBQUFCaHFaaGRIalFXY3lHbURmTjNWMGxnbDJYMWtmaTJ0RTRZbkRaWGJvRUhKNmZ1cHpqdHo4TmVsT2tZQ0pQYnB5LUVJMHRzNy13bjNEVFQxdktiNUN6ZDA4N0VXaC05Z2VibnctaDFMSnRHTzV6SGhUbGF3N2hiVVhudzBsTDVYU1RXaGdhYjNEWlpVQk92a3ZFblhKZmI2ZTBieWRJXy1iREFlbWlJeDN3aEhON3pOWHhVbEFzck15ODgtWDYwaDJuREhfckNHVDhIR08tckN5M2ZSS05DMkFCM1cxWWNxQjkxWDlvY2NrTVhOZFcwLVBjIiwiaWF0IjoxNjM4NTA0NTQxLCJleHAiOjE2Mzg1MjYxNDB9.pv1eWI6fGSacutVzjkKzXclMxDN0x-F6UXUfeEPSVqQ" \
  -d '{ "query": "query { getAllScheduledTasks { taskId name scheduledTimestamp status resourceType resourceNames } }" }' \
  http://localhost:8002/graphql

Response code

Status Code: Successful (200)

Response body

Table 11. Parameters in the response for fetching scheduled task details
Name	Style	Type	Description
`taskId`	body	string	ID of the scheduled task.
`status`	body	string	Current task status.
`name`	body	string	Name of the scheduled task.
`scheduledTimestamp`	body	string	Scheduled date and time of the task.
`resourceType`	body	string	Type of resource, which is a VM.
`resourceNames`	body	string	List of VM names in the scheduled task.

Example response:

{
   "data":{
      "getAllScheduledTasks":[
         {
            "taskId":"f5ebb0e3-9cd0-4d4e-a2f2-edef62904afd",
            "name":"Start VMs",
            "scheduledTimestamp":"2021-11-23T10:29:43.000Z",
            "status":"Scheduled",
            "resourceType":"VM",
            "resourceNames":[
               "gautpras-test-gql"
            ]
         },
         {
            "taskId":"e9e64080-03ad-4cfb-9032-041548b70a2b",
            "name":"Stop VMs",
            "scheduledTimestamp":"2021-10-22T12:10:20.000Z",
            "status":"Error",
            "resourceType":"VM",
            "resourceNames":[
               "vm4_demo"
            ]
         },
         {
            "taskId":"e971ec3e-187b-4def-910a-9ebf4a02cbf2",
            "name":"Restart VMs",
            "scheduledTimestamp":"2021-11-24T08:48:48.000Z",
            "status":"Processed",
            "resourceType":"VM",
            "resourceNames":[
               "vm_0240_test",
               "vm_nov16"
            ]
         },
         {
            "taskId":"62a1aa7d-d720-44a5-bd5b-a25c67ab532f",
            "name":"Deploy VMs",
            "scheduledTimestamp":"2021-10-21T12:29:30.000Z",
            "status":"Processed",
            "resourceType":"VM",
            "resourceNames":[
               "sch_dep1"
            ]
         }
      ]
   }
}