Provision Requests

Provisioning requests are made available via the following entrypoint.

/api/provision_requests

Creating Requests

Either by specifying a create action or by posting the request directly to /api/provision_requests.

As an example:

{
  "version" : "1.1",
  "template_fields" : {
    "guid" : "afe6e8a0-89fd-11e3-b6ac-b8e85646e742"
  },
  "vm_fields" : {
    "number_of_cpus" : 1,
    "vm_name" : "aab_test_vm1",
    "vm_memory" : "1024",
    "vlan" : "nic1"
  },
  "requester" : {
    "user_name" : "jdoe",
    "owner_first_name" : "John",
    "owner_last_name" : "Doe",
    "owner_email" : "jdoe@sample.com",
    "auto_approve" : true
  },
  "tags" : {
    "network_location" : "Internal",
    "cc" : "001"
  },
  "additional_values" : {
    "request_id" : "1001"
  },
  "ems_custom_attributes" : { },
  "miq_custom_attributes" : { }
}

Provision Requests Attribute Groups

Attribute Group Type Description

version

string

Interface version. Defaults to 1.1

template_fields

hash

Fields used to find template virtual machine. Provide any or all fields. Supply a guid or ems_guid to protect against matching same-named templates on different Providers within the appliance.

Supported fields are: name=[VM Template Name] Example: template_1 guid=[guid value from vms resource] ems_guid=[uid_ems value from vms resource]

vm_fields

hash

Allows for the setting of properties on the Catalog, Hardware, Network, Customize, and Schedule tabs in the Provisioning dialog

requester

hash

Allows for the setting of properties on the Requester tab in the Provisioning dialog

tags

hash

Tags to apply to newly created VM

Example: network_location=Internal cc=001

additional_values

hash

Additional values are name-value pairs stored with a provision request, but not used by the core provisioning code. These values are usually referenced from automate methods for custom processing

Example: Store a request_id from an external system so the system can be notified during the provisioning process

ems_custom_attributes

hash

Custom attributes applied to the virtual machine through the Provider as part of provisioning

miq_custom_attributes

hash

Custom attributes applied to the virtual machine and stored in the database as part of provisioning

Editing Requests

Updating provision requests can be performed by posting an edit action as follows:

POST /api/provision_requests/11
{
  "action" : "edit",
  "resource" : {
    "options" : {
      "custom_var1" : "custom value1"
    }
  }
}

Response:

{
  "href": "http://localhost:3000/api/provision_requests/11",
  "id": "11",
  "description": "Provision from [template1] to [###]",
  "approval_state": "pending_approval",
  "type": "MiqProvisionRequest",
  "created_on": "2015-04-14T17:36:30Z",
  "updated_on": "2015-04-14T18:32:30Z",
  "requester_id": "88913",
  "requester_name": "API User",
  "request_type": "template",
  "request_state": "pending",
  "message": "VM Provisioning - Request Created",
  "status": "Ok"
  "options": {
    "use_pre_dialog": false,
    "request_type": "template",
    "miq_request_dialog_name": "miq_provision_dialogs",
    "src_vm_id": [
      109996,
      "template1"
    ],
    "src_vm_nics": [],
    "src_vm_lans": [],
    "src_ems_id": [
      59136,
      "ems_0000000000002"
    ],
    "placement_auto": [
      true,
      1
    ],
    "vm_tags": [],
    "ws_values": {
    },
    "ws_ems_custom_attributes": {
    },
    "ws_miq_custom_attributes": {
    },
    "tags": {
    }
    "userid": "admin",
    "source_id": "109996",
    "source_type": "VmOrTemplate",
    "custom_var1" : "custom value1"
  }
}

Approving or Denying Requests

If a provision is not auto approved, it can be approved or denied via the actions approve and deny on the provision request resource.

Approving a Request

POST /api/provision_requests/:id
{
  "action" : "approve",
  "reason" : "reason for approval"
}

Denying a Request

POST /api/provision_requests/:id
{
  "action" : "deny",
  "reason" : "reason for denial"
}

Monitoring Requests

Once a provision request is created, the response result will include the queryable provision request itself, i.e. /api/provision_requests/:id

Response:

{
  "results": [
    {
      "id": "3068",
      "description": "Provision from [template1] to [###]",
      "approval_state": "pending_approval",
      "type": "MiqProvisionRequest",
      "created_on": "2015-04-14T17:36:30Z",
      "updated_on": "2015-04-14T17:36:30Z",
      "requester_id": "88913",
      "requester_name": "API User",
      "request_type": "template",
      "request_state": "pending",
      "message": "VM Provisioning - Request Created",
      "status": "Ok"
      "options": {
        "use_pre_dialog": false,
        "request_type": "template",
        "miq_request_dialog_name": "miq_provision_dialogs",
        "src_vm_id": [
          109996,
          "template1"
        ],
        "src_vm_nics": [],
        "src_vm_lans": [],
        "src_ems_id": [
          59136,
          "ems_0000000000002"
        ],
        "placement_auto": [
          true,
          1
        ],
        "vm_tags": [],
        "ws_values": {
        },
        "ws_ems_custom_attributes": {
        },
        "ws_miq_custom_attributes": {
        },
        "tags": {
        }
      },
      "userid": "admin",
      "source_id": "109996",
      "source_type": "VmOrTemplate"
    }
  ]
}

In the above example, the request could be queried periodically until the request_state reaches the finished state. Specifically,

GET /api/provision_requests/3068

Note:

The requests tasks of a provisioning request can also be queried by expanding the request_tasks subcollection as follows:

GET /api/provision_requests/:id?expand=request_tasks

or by fetching them directly as follows:

GET /api/provision_requests/:id/request_tasks?expand=resources

Editing Request Tasks

Request tasks for Provision Requests can be updated as follows:

POST /api/provision_requests/:id/request_tasks/:request_task_id
{
  "action" : "edit",
  "resource" : {
    "options" : {
      "request_param_a" : "value_a",
      "request_param_b" : "value_b"
    }
  }
}

For a list of attributes available for the provision request attribute groups please refer to the Provision Request Supported Attributes in the appendices section.