ManageIQ

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" }
  ]
}

Note:

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"
  }
}

Note: If you need to include a password in the call to the Ordering Services, you can use the password::dialog_password field to supply the password as a parameter. This password is passed as a string datatype.

{
  "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",
    "password::dialog_password" : "password"
  }
}

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.

Note:

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:

Additional Service actions include:

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" }
  ]
}

Adding Provider VMs to Services

For cases where VMs are created externally, i.e. via Ansible Playbooks, this action allows the system to identify the VMs created and link those VMs back to the service.

POST /api/services/:id

{
  "action" : "add_provider_vms",
  "resource" : {
    "provider" : { "href" : "http://localhot:3000/api/providers/11" }
    "uid_ems" : [
      "provider_vm_id1",
      "provider_vm_id2",
      ...
    ]
  }
}

Requesting a Chargeback Report for a Service

This action will request a chargeback report for the service.

POST /api/services/:id

{
  "action" : "queue_chargeback_report"
}

The queue_chargeback_report action will return an action response which includes the task reference as shown here:

{
  "success": true,
  "message": "Queued chargeback report generation for Service id:1 name:'test_service1'",
  "task_id": "39",
  "task_href": "http://localhost:3000/api/tasks/39"
}

The task_href can be queried and upon completion of the task, the chargeback report for the service can be queried as follows:

GET /api/services/:id?attributes=chargeback_report

Service Retiring (now)

POST /api/services/:id

{
  "action" : "request_retire"
}

Service Retiring (future)

POST /api/services/:id

{
  "action" : "request_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

Note:

The request tasks of service requests can be queried by expanding the request_tasks as follows:

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

or by fetching them directly as follows:

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

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" }
    }
  ]
}

Editing Request Tasks

Request tasks of Service Requests can be updated as follows:

POST /api/service_requests/:id/request_tasks/:request_task_id

{
  "action" : "edit",
  "resource" : {
    "options" : {
      "request_param_a" : "value_a",
      "request_param_b" : "value_b"
    }
  }
}