Master
Versions: Euwe / Fine / Latest /

Service Management

Service management is provided via the following collections:

Path Description

/api/service_catalogs

Service Catalogs

/api/service_templates

Service Templates

/api/services

Services

/api/service_requests

Service Requests

Service Catalogs

Full CRUD is available on service catalogs.

Creating Service Catalogs

/api/service_catalogs

Creating service catalog is provided via the following actions:

Method Versions Comment

create

2.0.0

Preferred

add

since v1.0

Example of creating service catalog with create method:

POST /api/service_catalogs
{
   "action" : "create",
   "resource" : {
     "name" : "Sample Service Catalog",
     "description" : "Description of Sample Service Catalog",
     "service_templates" : [
       { "href" : "http://localhost:3000/api/service_templates/3" },
       { "href" : "http://localhost:3000/api/service_templates/4" }
     ]
   }
}

Optionally without the create action signature:

{
  "name" : "Sample Service Catalog",
  "description" : "Description of Sample Service Catalog",
  "service_templates" : [
    { "href" : "http://localhost:3000/api/service_templates/3" },
    { "href" : "http://localhost:3000/api/service_templates/4" }
  ]
}

Please refer to the Resource Attributes page for a list of available attributes when creating Service Catalogs.

Editing Service Catalogs

Editing a service catalog via the edit action as follows:

POST /api/service_catalogs/:id
{
  "action" : "edit",
  "resource" : {
    "description" : "Updated Description of Third Service Catalog"
   }
}

Assigning Service Templates

Assign and Unassigning service templates to service catalogs is done via the assign and unassign actions as follows:

POST /api/service_catalogs/:id
{
  "action" : "assign",
  "resources" : [
    { "href" : "http://localhost:3000/api/service_templates/5" },
    { "href" : "http://localhost:3000/api/service_templates/6" }
  ]
}
POST /api/service_catalogs/:id
{
  "action" : "unassign",
  "resources" : [
    { "href" : "http://localhost:3000/api/service_templates/1" },
    { "href" : "http://localhost:3000/api/service_templates/2" }
  ]
}

Ordering Services Service Templates

Ordering services is done by triggering an order action on service templates in a service catalog as follows:

POST /api/service_catalogs/:id/service_templates
{
  "action" : "order",
  "resource" : {
    "href" : "http://localhost:3000/api/service_templates/3",
    "option_0_vm_target_name" : "test-vm-0001",
    "option_0_vm_target_hostname" : "test-vm-0001"
  }
}

Refresh Service Dialog Fields

Refreshing dialog fields is done via a refresh_dialog_fields action as shown in the following cases:

Refresh Dialog Fields of Service Templates Service Dialogs

Refreshing dialog fields for a service template service dialogs is done as follows:

POST /api/service_catalogs/:id/service_templates
{
  "action" : "refresh_dialog_fields",
  "resource" : {
    "href" : "http://localhost:3000/api/service_templates/3",
    "dialog_fields" : {
      "my_field1" : "my field1 value",
      "my_field2" : "my field2 value",
      "my_field3" : "my field3 value",
      ...
    },
    "fields" : [ "my_field1", "my_field3" ]
  }
}
Refresh Dialog Fields of Service Dialogs

Refreshing dialog fields for a service dialog is done as follows:

POST /api/service_dialogs/:id
{
  "action" : "refresh_dialog_fields",
  "resource" : {
    "dialog_fields" : {
      "my_field1" : "my field1 value",
      "my_field2" : "my field2 value",
      "my_field3" : "my field3 value",
      ...
    },
    "fields" : [ "my_field1", "my_field3" ]
  }
}

Deleting Service Catalogs

Single service catalogs can simply be deleted via the DELETE method as follows:

DELETE /api/service_catalogs/:id

Multiple service catalogs can also be deleted with a single request as follows:

POST /api/service_catalogs
{
  "action" : "delete",
  "resources" : [
    { "href" : "http://localhost:3000/api/service_catalogs/11" },
    { "href" : "http://localhost:3000/api/service_catalogs/12" },
    { "href" : "http://localhost:3000/api/service_catalogs/13" }
  ]
}

Service Templates

Management of Service Templates is available via the following collection:

/api/service_templates

Full CRUD is available on service templates.

Creating Service Templates

Service Templates can be created via a POST to the /api/service_templates collection:

/api/service_templates
{
  "name" : "Atomic Service Template",
  "service_type" : "atomic",
  "prov_type"    : "amazon",
  "display"      : "false",
  "config_info"  : {
    "miq_request_dialog_name" : "Dialog_Name",
    "placement_auto"          : [true, 1],
    "number_of_vms"           : [1, "1"],
    "src_vm_id"               : [11, "test_vm"],
    "vm_name"                 : "AtomicVMName",
    "schedule_type"           : ["immediately", "Immediately on Approval"],
    "instance_type"           : [21, "instance_flavor"],
    "src_ems_id"              : [5, "test_provider"],
    "provision"               : {
      "fqname"    : "/Sample/System/ProvisionEndpoint",
      "dialog_id" : 21
    },
    "retirement"              : {
      "fqname"    : "/Sample/System/RetirementEndpoint",
      "dialog_id" : 22
    }
  }
}

Editing Service Templates

Editing a single service template as follows:

POST /api/service_templates/:id
{
  "action" : "edit",
  "resource" : {
    "name" : "svc_template_01",
    "description" : "This is a sample service template"
  }
}

Deleting Service Templates

Deleting single service template via the DELETE method:

DELETE /api/service_templates/:id

or via the delete action as follows:

POST /api/service_templates/:id
{
  "action" : "delete"
}

Multiple service templates can also be deleted in bulk as follows:

POST /api/service_templates
{
  "action" : "delete",
  "resources" : [
    { "href" : "http://localhost:3000/api/service_templates/11" },
    { "href" : "http://localhost:3000/api/service_templates/12" }
  ]
}

Services

Accessing services is via the services collection as follows:

/api/services

or addressing an individual Service via the services resource:

/api/services/:id

Creating Services

In general, services are created once ordered from service catalogs.

Service resources can also be created as follows:

POST /api/services
{
  "action" : "create",
  "resource" : {
    "name" : "test_service_name",
    "description" : "Test Service",
    "parent_service" : { "href" : "http://localhost:3000/api/services/15" }
  }
}

In the above example parent_service is an href or id reference to an existing service.

Please refer to the Resource Attributes page for a list of available attributes when creating Services.

Service Actions

Once services are ordered from a catalog, they can be:

Resources can also be added or removed from services as shown here:

Other than service creates and edits, service actions return the action response as in the following example:

Request:

POST /api/services/12
{
  "action" : "start"
}

Response:

{
  "success": true,
  "message": "Service id:12 name:'SampleService' starting",
  "task_id": 62,
  "task_href": "http://localhost:3000/api/tasks/62",
  "href": "http://localhost:3000/api/services/12"
}

Service Editing

POST /api/services/:id
{
   "action" : "edit",
   "resource" : {
     "name" : "Updated Service Name",
     "description" : "Updated Service Description"
   }
}

Adding and Removing Resources from Services

Adding and removing resources from services is made available with the following actions:

Action

add_resource

remove_resource

remove_all_resources

The following example adds a single resource to a service:

POST /api/services/:id
{
  "action" : "add_resource",
  "resource" : {
    { "resource" : { "href" : "http://localhost:3000/api/vms/11" } }
  }
}

The following example bulk adds resources to multiple services:

POST /api/services
{
   "action" : "add_resource",
   "resources" : [
      {
        "href" : "http://localhost:3000/api/services/3",
        "resource" : { "href" : "http://localhost:3000/api/vms/11" }
      },
      {
        "href" : "http://localhost:3000/api/services/3",
        "resource" : { "href" : "http://localhot:3000/api/vms/12" }
      },
      {
        "href" : "http://localhost:3000/api/services/4",
        "resource" : { "href" : "http://localhost:3000/api/vms/21" }
      },
      {
        "href" : "http://localhost:3000/api/services/5",
        "resource" : { "href" : "http://localhost:3000/api/vms/22" }
      }
   ]
}

The following example removes a single resource from a service:

POST /api/services/:id
{
  "action" : "remove_resource",
  "resource" : {
     { "resource" : { "href" : "http://localhost:3000/api/vms/11" } }
  }
}

The following example removes resources in bulk from multiple services:

POST /api/services
{
  "action" : "remove_resource",
  "resources" : [
    {
      "href" : "http://localhost:3000/api/services/3",
      "resource" : { "href" : "http://localhost:3000/api/vms/11" }
    },
    {
      "href" : "http://localhost:3000/api/services/3",
      "resource" : { "href" : "http://localhot:3000/api/vms/12" }
    },
    {
      "href" : "http://localhost:3000/api/services/4",
      "resource" : { "href" : "http://localhost:3000/api/vms/21" }
    },
    {
      "href" : "http://localhost:3000/api/services/5",
      "resource" : { "href" : "http://localhost:3000/api/vms/22" }
    }
  ]
}

The following example removes all resources from a single service:

POST /api/services/:id
{
  "action" : "remove_all_resources"
}

The following example removes all resources in bulk from multiple services:

POST /api/services
{
  "action" : "remove_all_resources",
  "resources" : [
    { "href" : "http://localhost:3000/api/services/11" },
    { "href" : "http://localhost:3000/api/services/12" },
    { "href" : "http://localhost:3000/api/services/13" }
  ]
}

Service Retiring (now)

POST /api/services/:id
{
  "action" : "retire"
}

Service Retiring (future)

POST /api/services/:id
{
  "action" : "retire",
  "resource" : { "date" : "10/30/2015", "warn" : "5" }
}

Service Reconfiguring

When a service is defined with a Reconfigure Automation Entrypoint, the reconfigure action is shown as a valid action for that service.

This action takes any of the dialog fields the service supports during reconfiguration.

POST /api/services/:id
{
  "action" : "reconfigure",
  "resource" : {
    "field1" : "updated field1 value",
    "field2" : "updated field2 value",
    ...
  }
}

Starting Services

POST /api/services/:id
{
  "action" : "start"
}

Stopping Services

POST /api/services/:id
{
  "action" : "stop"
}

Suspending Services

POST /api/services/:id
{
  "action" : "suspend"
}

Deleting Services

DELETE /api/services/:id

Or via the delete action for deleting multiple services:

POST /api/services
{
  "action" : "delete",
  "resources" : [
    { "href" : "http://localhost:3000/api/services/101",
    { "href" : "http://localhost:3000/api/services/102",
    { "href" : "http://localhost:3000/api/services/103"
    ...
  ]
}

Service Requests

Querying Service Requests

Once services are ordered from a catalog, service requests can be monitored as follows:

GET /api/service_requests/:id

Additionally, tasks of the specific requests can be queried:

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

or optionally via the tasks alias:

GET /api/service_requests/:id?expand=tasks

Approving or Denying Service Requests

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

Approving a Service Request
POST /api/service_requests/:id
{
  "action" : "approve",
  "reason" : "reason for approval"
}

Denying a Service Request

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

Adding Approvers to Service Requests

Approvers can be added to service requests with the add_approver action. Approvers can be specified by user_id or user reference including an href or id of the approver.

POST /api/service_requests/:id
{
  "action" : "add_approver",
  "resource" : {
    "user_id" : 11
  }
}

Or one of the following signatures:

{
  "action" : "add_approver",
  "resource" : {
    "user" : { "id" : 11  }
  }
}
{
  "action" : "add_approver",
  "resource" : {
    "user" : { "href" : "http://localhost:3000/api/users/11" }
  }
}

Approvers can also be added in bulk as follows:

POST /api/service_requests
{
  "action" : "add_approver",
  "resources" : [
    {
      "href" : "http://localhost:3000/api/service_requests/101",
      "user_id" : 11
    },
    {
      "href" : "http://localhost:3000/api/service_requests/102",
      "user" : { "id" : 11 }
    },
    {
      "href" : "http://localhost:3000/api/service_requests/103",
      "user" : { "href" : "http://localhost:3000/api/users/11" }
    }
  ]
}

Removing Approvers from Service Requests

Approvers can be removed from service requests with the remove_approver action. Approvers can be specified by user_id or user reference including an href or id of the approver.

POST /api/service_requests/:id
{
  "action" : "remove_approver",
  "resource" : {
    "user_id" : 11
  }
}

Approvers can also be removed in bulk as follows:

POST /api/service_requests
{
  "action" : "remove_approver",
  "resources" : [
    {
      "href" : "http://localhost:3000/api/service_requests/101",
      "user_id" : 11
    },
    {
      "href" : "http://localhost:3000/api/service_requests/102",
      "user" : { "id" : 11 }
    },
    {
      "href" : "http://localhost:3000/api/service_requests/103",
      "user" : { "href" : "http://localhost:3000/api/users/11" }
    }
  ]
}