Creating VM Schedules with the API

Lets say want to make a VM Schedule that powers on VMs at 8 AM and powers off VMs at 7PM every day. This guide will walk through all the API calls in order create an automation schedule to do this.

To create a VM Schedule, you first need to create a VM Group. Start with a GET request to the /virtual-machines API to see the VMs available to make a group from. From this response we can see that we have 2 virtual machines available to us. We will use the Virtual Machines with the resource identifiers of 596fffcf937c950011f56951 and 596fffcf937c950011f56952 to create a VM Group.

Sample Request:

GET /virtual-machines

Sample Response:

{
    "links": {
        "self": "http://api-dev.vmpower.io/virtual-machines"
    },
    "data": [
        {
            "id": "596fffcf937c950011f56951",
            "type": "virtual-machines",
            "attributes": {
                "instance-id": "vmpower2classic/vmpower2classic/vmpower",
                "power-state": "off",
                "provider": "azureasm",
                "instance-name": "vmpower",
                "iops": 4500,
                "instance-type": "Standard_A1_v2",
                "pub-ip": "13.92.177.224",
                "since-idle-time": null,
                "price-per-hour": 0.065,
                "memory-gi-b": 2,
                "off-since": "2017-07-23T04:03:54.793Z",
                "iops-average": 0,
                "iops-max": 0,
                "iops-rec": "nochange",
                "memory-rec": "nochange",
                "cpu-rec": 0,
                "memory-utilized-max": 0,
                "memory-utilized-average": 0,
                "cpu-max": 0,
                "cpu-average": 0,
                "disk-read-max": 0,
                "disk-write-max": 0,
                "disk-write-average": 0,
                "disk-read-average": 0,
                "network-in-max": 0,
                "network-in-average": 0,
                "network-out-max": 0,
                "network-out-average": 0,
                "estimated-iops-size": 16000,
                "auto-off-warning-sent": false,
                "idle-reason": "",
                "is-idle": false,
                "cpus": 1,
                "unstoppable": false,
                "os-type": "windows",
                "plan-enabled": true
            },
            "links": {
                "self": "https://api-dev.vmpower.io/virtual-machines/596fffcf937c950011f56951"
            },
            "relationships": {
                "cloud-subscription": {
                    "data": {
                        "type": "cloud-subscriptions",
                        "id": "596fffcd937c950011f56950"
                    },
                    "links": {
                        "self": "https://api-dev.vmpower.io/cloud-subscriptions/596fffcd937c950011f56950"
                    }
                },
                "resizable-types": {
                    "data": [
                        {
                            "type": "vm-types",
                            "id": "596d867be87f61d849253734"
                        }
                    ],
                    "links": {
                        "self": "https://api-dev.vmpower.io/vm-types/596d867be87f61d849253734"
                    }
                },
                "recommended-resize-types": {
                    "data": [],
                    "links": {
                        "self": "https://api-dev.vmpower.io//"
                    }
                }
            }
        },
        {
            "id": "596fffcf937c950011f56952",
            "type": "virtual-machines",
            "attributes": {
                "instance-id": "vmpower2classic/vmpower2classic/vmpower2classic",
                "power-state": "on",
                "provider": "azureasm",
                "instance-name": "vmpower2classic",
                "iops": 4500,
                "instance-type": "Standard_A1_v2",
                "pub-ip": "13.92.177.224",
                "since-idle-time": null,
                "resize-recommendations": true,
                "price-per-hour": 0.065,
                "memory-gi-b": 2,
                "off-since": null,
                "iops-average": 0,
                "iops-max": 0,
                "iops-rec": "scaledown",
                "memory-rec": "nochange",
                "cpu-rec": 1,
                "memory-utilized-max": 62.463191,
                "memory-utilized-average": 52.45,
                "cpu-max": 0,
                "cpu-average": 0,
                "disk-read-max": 0,
                "disk-write-max": 0,
                "disk-write-average": 0,
                "disk-read-average": 0,
                "network-in-max": 0,
                "network-in-average": 0,
                "network-out-max": 0,
                "network-out-average": 0,
                "estimated-iops-size": 16000,
                "auto-off-warning-sent": false,
                "idle-reason": "",
                "is-idle": false,
                "cpus": 1,
                "unstoppable": false,
                "os-type": "windows",
                "plan-enabled": true
            },
            "links": {
                "self": "https://api-dev.vmpower.io/virtual-machines/596fffcf937c950011f56952"
            },
            "relationships": {
                "cloud-subscription": {
                    "data": {
                        "type": "cloud-subscriptions",
                        "id": "596fffcd937c950011f56950"
                    },
                    "links": {
                        "self": "https://api-dev.vmpower.io/cloud-subscriptions/596fffcd937c950011f56950"
                    }
                },
                "resizable-types": {
                    "data": [
                        {
                            "type": "vm-types",
                            "id": "596d867be87f61d849253734"
                        }
                    ],
                    "links": {
                        "self": "https://api-dev.vmpower.io/vm-types/596d867be87f61d849253734"
                    }
                },
                "recommended-resize-types": {
                    "data": [],
                    "links": {
                        "self": "https://api-dev.vmpower.io//"
                    }
                }
            }
        }
    ]
}

Now make a POST request to the /vm-groups API which will create a VM Group. You only need to provide a VM Group name and the associated VMs:

Sample Request

POST /vm-groups

{
    "data": {
        "type": "vm-groups",
        "attributes": {
            "name": "API Group"
        },
        "relationships": {
            "vms": {
                "data": [
                    {
                        "id": "596fffcf937c950011f56951",
                        "type": "virtual-machines"
                    },
                    {
                        "id": "596fffcf937c950011f56952",
                        "type": "virtual-machines"
                    }
                ]
            }
        }
    }
}

A successful group creation returns a 200 OK response with the generated resource identifier.

Sample Response:

{
    "links": {
        "self": "http://api-dev.vmpower.io/vm-groups/59d4f47b0521460012c3675d"
    },
    "data": {
        "id": "59d4f47b0521460012c3675d",
        "type": "vm-groups",
        "attributes": {
            "name": "API Group",
            "include-disk-write-max": true,
            "include-disk-write-average": true,
            "include-disk-read-average": true,
            "include-disk-read-max": true,
            "include-cpu-average": true,
            "include-cpu-max": true,
            "include-network-in-average": true,
            "include-network-out-average": true,
            "include-network-in-max": true,
            "include-network-out-max": true,
            "ignore-hours-enabled": false,
            "ignore-hours-end": 17,
            "ignore-hours-start": 9,
            "auto-off-warning-sent": false,
            "auto-off-hours": 3,
            "auto-off-warning-hours": 1,
            "auto-off-enabled": false
        },
        "links": {
            "self": "https://api-dev.vmpower.io/vm-groups/59d4f47b0521460012c3675d"
        },
        "relationships": {
            "vms": {
                "data": [
                    {
                        "type": "virtual-machines",
                        "id": "596fffcf937c950011f56951"
                    },
                    {
                        "type": "virtual-machines",
                        "id": "596fffcf937c950011f56952"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io/virtual-machines/596fffcf937c950011f56951"
                }
            }
        }
    }
}

Now that the VM Group is created, you can create a VM Schedule by performing a POST to the /vm-schedules API.

Sample Request:

POST /vm-schedules

{
    "data": {
        "type": "vm-schedules",
        "attributes": {
            "name": "API Group Schedule 2",
        },
        "relationships": {
            "vm-group": {
                "data": {
                    "type": "vm-groups",
                    "id": "59d4f47b0521460012c3675d"
                }
            }
        }
    }
}

Sample Response:

{
    "data": {
        "id": "59d4fb3410d6e30012065bd5",
        "type": "vm-schedules",
        "attributes": {
            "frequency": 1,
            "start-time": "2017-10-03T05:15:10.587Z",
            "normally": "on",
            "name": "API Group Schedule 2",
            "enabled": false,
            "notifications": true,
            "timezone": "US/Pacific",
            "warning-secs": 1800
        },
        "links": {
            "self": "https://api-dev.vmpower.io/vm-schedules/59d4fb3410d6e30012065bd5"
        },
        "relationships": {
            "weekly-schedule": {
                "data": null,
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "vm-group": {
                "data": {
                    "type": "vm-groups",
                    "id": "59d4f47b0521460012c3675d"
                },
                "links": {
                    "self": "https://api-dev.vmpower.io/vm-groups/59d4f47b0521460012c3675d"
                }
            }
        }
    }
}

You'll now need to associate a Weekly Schedule to your VM Schedule. Make a POST request to the /weekly-schedules API to create a new Weekly Schedule:

{
    "data": {
        "type": "weekly-schedules",
        "attributes": {}
    }
}

A successful response will be a 200 status code with a response body like this:

{
    "links": {
        "self": "http://api-dev.vmpower.io/weekly-schedules"
    },
    "data": {
        "id": "59d4fe5ba0f921001148432f",
        "type": "weekly-schedules",
        "attributes": {},
        "links": {
            "self": "https://api-dev.vmpower.io/weekly-schedules/59d4fe5ba0f921001148432f"
        },
        "relationships": {
            "monday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "tuesday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "wednesday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "thursday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "friday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "saturday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "sunday": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            }
        }
    }
}

Make note of this Weekly Schedule resource identifier. You'll need it to attach it to your VM Schedule.

Now associate the Weekly Schedule to your VM Schedule by sending a PATCH request to /vm-schedules/[:vm-schedule-id] API like so:

Sample Request:

PATCH /vm-schedules/59d4fb3410d6e30012065bd5

{
    "data": [
        {
            "id": "59d4fb3410d6e30012065bd5",
            "type": "vm-schedules",
            "attributes": {
                "frequency": 1,
                "start-time": "2017-10-03T05:15:10.587Z",
                "normally": "on",
                "name": "API Group Schedule 2",
                "enabled": true,
                "notifications": true,
                "timezone": "US/Pacific",
                "warning-secs": 1800
            },
            "links": {
                "self": "https://api-dev.vmpower.io/vm-schedules/59d4fb3410d6e30012065bd5"
            },
            "relationships": {
                "weekly-schedule": {
                    "data": {
                        "type": "weekly-schedules",
                        "id": "59d4fe5ba0f921001148432f"
                    }
                },
                "vm-group": {
                    "data": {
                        "type": "vm-groups",
                        "id": "59d4f47b0521460012c3675d"
                    },
                    "links": {
                        "self": "https://api-dev.vmpower.io/vm-groups/59d4f47b0521460012c3675d"
                    }
                }
            }
        }
    ]
}

Now your VM Schedule is associated with a Weekly Schedule. We now need to create Timespan resources and associate them with the Weekly Schedule in order to instruct the VM Schedule on how to execute against the VM Groups. In our case we will make a schedule to turn on our machines at 8:00 AM every day and turn off our machines at 7:00 PM (19:00) every day.

First make a POST request to the /timespans API to create a POWER ON event. The start-milis is the number of milliseconds from midnight to 8:00 AM. The end-milis is the amount of time the automation engine will attempt to execute the event. We recommend that end-milis - start-milis = 1800000 milliseconds (or 30 minutes) to ensure optimal execution reliability.

Sample Request:

POST /timespans

{
    "data": {
        "type": "timespans",
        "attributes": {
            "action-type": "POWER ON",
            "start-milis": 28800000,
            "end-milis": 30600000
        }
    }
}

A successful response will return a similar resource object including a generated id field:

Sample Response Body:

{
    "links": {
        "self": "http://api-dev.vmpower.io/timespans"
    },
    "data": {
        "id": "59d5028f9241eb00124e6320",
        "type": "timespans",
        "attributes": {
            "backup-retention-days": 7,
            "action-type": "POWER ON",
            "start-milis": 28800000,
            "end-milis": 30600000
        },
        "links": {
            "self": "https://api-dev.vmpower.io/timespans/59d5028f9241eb00124e6320"
        },
        "relationships": {
            "resize-actions": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            }
        }
    }
}

We will create another POWER OFF timespan event as well

Sample Request:

POST /timespans

{
    "data": {
        "type": "timespans",
        "attributes": {
            "action-type": "POWER OFF",
            "start-milis": 68400000,
            "end-milis": 70200000
        }
    }
}

Sample Response:

{
    "links": {
        "self": "http://api-dev.vmpower.io/timespans"
    },
    "data": {
        "id": "59d50534a0f9210011484330",
        "type": "timespans",
        "attributes": {
            "start-milis": 68400000,
            "end-milis": 70200000,
            "backup-retention-days": 7,
            "action-type": "POWER OFF"
        },
        "links": {
            "self": "https://api-dev.vmpower.io/timespans/59d50534a0f9210011484330"
        },
        "relationships": {
            "resize-actions": {
                "data": [],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            }
        }
    }
}

In this case start-milis represents the time 7:00PM (19:00) in milliseconds since midnight (00:00) and end-milis represents the time 7:30PM (19:30).

Finally to set these events to execute every day, set these timespans to each day on the Weekly Schedule you created.

Sample Request:

PATCH /weekly-schedules/59d4fe5ba0f921001148432f

{
    "links": {
        "self": "http://api-dev.vmpower.io/weekly-schedules"
    },
    "data": {
        "id": "59d4fe5ba0f921001148432f",
        "type": "weekly-schedules",
        "attributes": {},
        "links": {
            "self": "https://api-dev.vmpower.io/weekly-schedules/59d4fe5ba0f921001148432f"
        },
        "relationships": {
            "monday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "tuesday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "wednesday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "thursday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "friday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "saturday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            },
            "sunday": {
                "data": [
                    {
                        "id": "59d50534a0f9210011484330",
                        "type": "timespans"
                    },
                    {
                        "id": "59d5028f9241eb00124e6320",
                        "type": "timespans"
                    }
                ],
                "links": {
                    "self": "https://api-dev.vmpower.io//"
                }
            }
        }
    }
}

Finally to start the schedule ensure that the enabled field is set to true on the VM Schedule resource to start execution of your schedule by sending a PATCH request to the /vm-schedules API.

Because Timespan resources themselves are not specifically tied to a certain date, they may be used on any day of the week. It is important to know that the VMPower Dashboard creates a unique Timespan resource for each day, even if they are duplicates of each other.