Moab Web Services > Resources > Services

Services

This section describes the behavior of a Service (an interdependent collection of workflows). It is possible for a Service to be composed of multiple Services. This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services for each approach.

Services are tenant objects. If you have implemented a multi-tenant environment (see About Tenants for more information) and are logged in with an application account, you must include a proxy-user with each service call to limit the results to information that the user has permission to see. If you are logged in with an LDAP account, MWS will automatically limit the results to information that the LDAP user has permission to see. For more information, see Roles.

Moab Web Services reports a service's lifecycle, or a series of phases that a service goes through. The lifecycle allows you to follow the service's tracking job(s) in Moab as certain events occur. Services change phases as Moab enforces policies and as users request changes. For instance, you can choose to migrate, unblock, or terminate a service and trigger a phase change. Knowing a service's current phase lets you determine not only when a service has failed, but what might have caused it. For more information, see "" in the Moab Cloud Suite 7.5.0 Installation Guide.

The events that cause phase transitions to occur have a feature called phase hooks that you can use to run scripts during phase transitions. For instance, if you want to receive an email alert when a service becomes blocked, you can write a script that will send the email and attach it to an individual service, a service template, or globally on all services that will be created. You would then set the hook on the "block" event so that it runs whenever the service experiences this event. For more information, see the "Creating Service Lifecycle Phase Hooks" section of this page.

The Fields: Services reference section contains the type and description of all fields in the Service object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported methods

Resource	GET	PUT	POST	DELETE
/rest/services	Services	--	Create Custom Service Create Service from Service Template	--
/rest/services/<id>	Get Single Service	Modify Service	--	Delete Service

Resource

GET

PUT

POST

DELETE

/rest/services

Services

Create Custom Service

Create Service from Service Template

/rest/services/<id>

Get Single Service

Modify Service

Delete Service

This topic contains these sections:

Getting Service Information
Creating Services
Modifying or Moving Services
Deleting Services
- Delete Service
Getting Service Lifecycle Phase Hook Information
Creating Service Lifecycle Phase Hooks
- Create a Service Lifecycle Phase Hook
Modifying Service Lifecycle Phase Hooks
- Modify a Service Lifecycle Phase Hook
- Changing the Status of a Running Service Hook
Deleting Service Lifecycle Phase Hooks
- Delete a Service Lifecycle Phase Hook
Getting stepsCompleted Information
- Get Steps Completed Information
Modifying stepsCompleted
- Modify stepsCompleted

Getting Service Information

The HTTP GET method is used to retrieve Service information. Queries for all objects and a single object are available.

Quick reference

GET http://localhost:8080/mws/rest/services?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]
GET http://localhost:8080/mws/rest/services/<id>?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]
GET http://localhost:8080/mws/rest/services/<name>?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]
GET http://localhost:8080/mws/rest/services/<id>/root?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]
GET http://localhost:8080/mws/rest/services/<name>/root?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]
GET http://localhost:8080/mws/rest/services/vms/<vmId>?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]

Get All Services

URLs and parameters

GET http://localhost:8080/mws/rest/services?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]

Parameter	Required	Type	Valid values	Description	Example
query	No	JSON	--	Query for specific results. It is possible to query services by one or more fields based on MongoDB query syntax.	query={"type":"storage","label":"exlabel"}
sort	No	JSON	--	Sort the results. Use 1 for ascending and -1 for descending.	sort={"account":-1}
show-recursive-vc	No	Boolean	true or false	true shows extended details about the service's virtual container including nested virtual containers and nested jobs. Default is false.	show-recursive-vc=true
show-vc	No	Boolean	true or false	true shows details about the service's virtual container. Default is false.	show-vc=true

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/services?api-version=3&query={user:"bob"}
------------------------------------

{
   "totalCount":9,
   "resultCount":3,
   "results":[
      {
         "tenant": {
            "id":1234567890abcdef12345678",
            "name": "Research"
         },
         "dateCreated":"2011-12-07 16:03:40 UTC",
         "lastUpdated":"2011-12-07 16:03:40 UTC",
         "dateDeleted":null,
         "name":"bobService.1",

         "phase":"Analyzing",

          "version":1,
         "type":"container",
         "label":null,
         "user":"bob",
         "account":"bamboo",
         "startDateRequested":"2012-14-10 20:51:07 UTC",
         "startDateScheduled":"2012-14-10 20:51:07 UTC",
         "status":"A custom status message",
         "statusCode":0,
         "includedServices":[
            "machine0.1",
            "OSStoremachine0.1"
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "parent":null,
         "serviceTemplate":{
            "id":"4fbd42cfc4aa4c444cc54112",
            "name":"CentosVmPlusStorage"
         },
         "attributes":{
            "moab":{
               "vc":{
                  "id":"vc56"
               },
               "dependencies":[
                  {
                     "service":"machine0.1",
                     "dependency":[
                        "OSStoremachine0.1"
                     ]
                  }
               ],
               "jobRequested":{
                  "nodeSet": {
                    "selection": "FIRSTOF",
                    "type": "VARATTR",
                    "name": "MOAB_DATACENTER",
                    "values": ["vcenter-datacenter-416"]
                  }
                  "rules":{
                     "MOAB_DATACENTER":[
                        {
                           "value":"datacenter3",
                           "restriction":"must",
                           "comparator":"%=",
                           "displayValue":null
                        }
                     ]
                  }
               }
            }
         },
         "id":"4edff0cc6852f709fa777826"
      },
      {
         "tenant": {
            "id":1234567890abcdef12345678",
            "name": "Research"
         },
         "dateCreated":"2011-12-07 16:03:40 UTC",
         "lastUpdated":"2011-12-07 16:03:40 UTC",
         "dateDeleted":null,
         "name":"machine0.1",

         "phase":"Analyzing", 
         "version":1,
         "type":"vm",
         "label":"bobs machine",
         "user":"bob",
         "account":"bamboo",
         "startDateRequested":"2012-14-10 20:51:07 UTC",
         "startDateScheduled":"2012-14-10 20:51:07 UTC",
         "status":"A custom status message",
         "statusCode":0,
         "includedServices":[
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "parent":"bobService.1",
         "serviceTemplate":{
            "id":"4fbd42cfc4aa4c444cc54113",
            "name":"CentosVm"
         },
         "attributes":{
            "moab":{
               "vc":{
                  "id":"vc57"
               },
               "jobRequested":{
                  "id":"Moab.24",
                  "template":"genericVM",
                  "image":"centos5.5-stateless",
                  "features":[
                     "vlan3"
                  ],
                  "variables":{
                     "QOS":"High"
                  },
                  "resources":{
                     "mem":2,
                     "procs":2,
                     "disk":2
                  },
                  "nodeSet": {
                    "selection": "FIRSTOF",
                    "type": "VARATTR",
                    "name": "MOAB_DATACENTER",
                    "values": ["vcenter-datacenter-416"]
                  }
                  "rules":{
                     "MOAB_DATACENTER":[
                        {
                           "value":"datacenter3",
                           "restriction":"must",
                           "comparator":"%=",
                           "displayValue":null
                        }
                     ]
                  }
               }
            }
         },
         "id":"4edff0cc6852f709fa777827"
      },
      {
         "tenant": {
            "id":1234567890abcdef12345678",
             "name": "Research"
         },
         "dateCreated":"2011-12-07 16:03:40 UTC",
         "lastUpdated":"2011-12-07 16:03:40 UTC",
         "dateDeleted":null,
         "name":"OSStoremachine0.1",

         "phase":"Analyzing",
         "version":1,
         "type":"storage",
         "label":null,
         "user":"bob",
         "account":"bamboo",
         "startDateRequested":"2012-14-10 20:51:07 UTC",
         "startDateScheduled":"2012-14-10 20:51:07 UTC",
         "status":"A custom status message",
         "statusCode":0,
         "includedServices":[

         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "parent":"bobService.1",
         "serviceTemplate":{
            "id":"4fbd42cfc4aa4c444cc54114",
            "name":"OpSysStorage"
         },
         "attributes":{
            "moab":{
               "vc":{
                  "id":"vc58"
               },
               "jobRequested":{
                  "id":"Moab.23",
                  "template":"OSStorage",
                  "resources":{
                     "OS":200
                  },
                  "nodeSet": {
                    "selection": "FIRSTOF",
                    "type": "VARATTR",
                    "name": "MOAB_DATACENTER",
                    "values": ["vcenter-datacenter-416"]
                  }
                  "rules":{
                     "MOAB_DATACENTER":[
                        {
                           "value":"datacenter3",
                           "restriction":"must",
                           "comparator":"%=",
                           "displayValue":null
                        }
                     ]
                  }
               }
            }
         },
         "id":"4edff0cc6852f709fa777828"
      }
   ]
}

Querying services

It is possible to query services by one or more fields based on MongoDB query syntax.

Simple queries

To see only services that are associated with the user "bob" you can use a query such as the following:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob"}

To see only services that are of type "vm":

http://localhost:8080/mws/rest/services?api-version=3&query={"type":"vm"}

To see only bob's vm services:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob","type":"vm"}

To see only services that are NOT associated with bob:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":{"$ne":"bob"}}

More complex queries

When the field values of the desired services are a finite set, you can use the $in operator. For example, to see services that belong to either bob, alice, or charlie, you can do the following:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":{"$in":["alice","bob","charlie"]}}

You can also query on embedded JSON objects within the service JSON. For example, to see services requesting 3 processors you can use:

http://localhost:8080/mws/rest/services?api-version=3&query={"attributes.moab.jobRequested.resources.procs":3}

Conditional operators

You can perform <, <=, >, >= comparisons using the $lt, $lte, $gt, $gte operators.

Operator	Comparison
$lt	<
$lte	<=
$gt	>
$gte	>=

To see services requesting < 2 processors:

http://localhost:8080/mws/rest/services?api-version=3&query={"attributes.moab.jobRequested.resources.procs":{"$lt":2}}

To see services requesting >= 1024 memory:

http://localhost:8080/mws/rest/services?api-version=3&query={"attributes.moab.jobRequested.resources.mem":{"$gte":1024}}

Querying services by date

To see all services created after February 8, 2012 at 1:00 PM Mountain Standard Time (MST):

http://localhost:8080/mws/rest/services?api-version=3&query={"dateCreated":{"$gt":"2012-02-08 13:00:00 MST"}}

To see services created before or on February 8, 2012 at 1:00 PM Pacific Standard Time (PST):

http://localhost:8080/mws/rest/services?api-version=3&query={"dateCreated":{"$lte":"2012-02-08 13:00:00 PST"}}

To see services created between 12:00 PM and 1:00 PM Eastern Standard Time (EST) on February 8, 2012:

http://localhost:8080/mws/rest/services?api-version=3&query={"dateCreated":{"$lte":"2012-02-08 13:00:00 EST","$gte":"2012-02-08 12:00:00 EST"}}

Querying services by containing service

Services can contain other services. When a service is contained within another service, you can find out what its container is by looking at the parent field. A service that is not contained in any other service is called a top level service. If you want to see only top level services you need to query for services with a null parent.

In MongoDB syntax you query for services whose parent field have a $type of 10 (with 10 representing null). The following query shows all of bob's top level services:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob","parent":{"$type":10}}

Once you have the top level service, you can find the direct child services:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob","parent":"bobService.1"}

Once you have the direct children, you can find the children of those children with a similar query.

Sorting

See the sorting section of Global URL Parameters.

Limiting the number of results

If you want to limit the number of results of services you can use the max parameter. For example, to see only 10 of bob's services:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob"}&sort={"name":1}&max=10

To see bob's services 91-100 when sorted by name in ascending order you can combine max with offset as follows:

http://localhost:8080/mws/rest/services?api-version=3&query={"user":"bob"}&sort={"name":1}&max=10&offset=90

Retrieving a subset of fields

To cause only certain fields to return for each service, use the fields parameter. For example, to show only the name field for each service:

http://localhost:8080/mws/rest/services?api-version=3&fields=name

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {"name": "aliceService.1"},
    {"name": "machine0.1"},
    {"name": "OSStoremachine0.1"}
  ]
}

To show the name, type, and user:

http://localhost:8080/mws/rest/services?api-version=3&fields=name,type,user

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {
      "name": "aliceService.1",
      "type": "container",
      "user": "alice"
    },
        {
      "name": "machine0.1",
      "type": "vm",
      "user": "alice"
    },
        {
      "name": "OSStoremachine0.1",
      "type": "storage",
      "user": "alice"
    }
  ]
}

Get Single Service

URLs and parameters

GET http://localhost:8080/mws/rest/services/<id>?api-version=3[&[show-recursive-vc|show-vc]=true]
GET http://localhost:8080/mws/rest/services/<name>?api-version=3[&[show-recursive-vc|show-vc]=true]

Parameter	Required	Type	Valid values	Description	Example
id	Yes	String	--	The unique identifier of the service. Must contain exactly 24 alphanumeric characters.	--
name	Yes	String	--	The name of the service.	--
show-recursive-vc	No	Boolean	true or false	true shows extended details about the service's virtual container including nested virtual containers and nested jobs. Default is false.	show-recursive-vc=true
show-vc	No	Boolean	true or false	true shows details about the service's virtual container. Default is false.	show-vc=true
recursive	No	Boolean	true or false	true shows details about all included services, including nested services. Default is false.	recursive=true

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

If the service requested is a VM service and API version 2 is used, the full job and VM details will be returned in the output in the jobDetails and virtualMachineDetails fields. The format of these fields match the full output of Get Single Job and Get Single Virtual Machine. If Moab is not configured correctly to use API version 2, the request will fail just as it would with the Job and Virtual Machine resources if they were called directly.

These fields are also returned if a parent of a VM service is requested with the recursive flag set to true. This means that children services will also contain job and VM details if available.

Samples

Typical service:

GET http://localhost:8080/mws/rest/services/bobService.1?api-version=3
------------------------------------

{
   "tenant": {
      "id":1234567890abcdef12345678",
      "name": "Research"
   },
   "dateCreated":"2011-12-07 16:03:40 UTC",
   "lastUpdated":"2011-12-07 16:03:40 UTC",
   "dateDeleted": null,
   "name":"bobService.1",

   "phase":"Analyzing",   
   "version":1,
   "type":"container",
   "label":null,
   "user":"bob",
   "account":"bamboo",
   "startDateRequested":"2012-14-10 20:51:07 UTC",
   "startDateScheduled":"2012-14-10 20:51:07 UTC",
   "durationRequested":86400,
   "status":"A custom status message",
   "statusCode":0,
   "includedServices":[
      "machine0.1",
      "OSStoremachine0.1"
   ],

   "stepsCompleted": [],

   "hookDefinitions": [{

     "id": "51f9395484aeed592c4d658e",

     "name": "myHook",

     "type": "after",

     "currentPhase": "analyzing",

     "transition": "accept",

     "nextPhase": "deploying",

     "url": "exec:///opt/mws/spool/hooks/approval.pl",

     "timeoutInSeconds": 3000

},

     "id": "62g1416595bffe613d5e769f",

     "name": "emailOnBlock"

     "type": "after"

     "currentPhase": "deploying",

     "transition": "block",

     "nextPhase": "blocked",

     "url": "exec:///opt/mws/spool/hooks/blockEmail.pl",

   "parent":null,
   "serviceTemplate":{
      "id":"4fbd42cfc4aa4c444cc54112",
      "name":"CentosVmPlusStorage"
   },
   "attributes":{
      "moab":{
         "vc":{
            "id":"vc56"
         },
         "dependencies":[
            {
               "service":"machine0.1",
               "dependency":[
                  "OSStoremachine0.1"
               ]
            }
         ],
         "jobRequested":{
           "nodeSet": {
              "selection": "FIRSTOF",
               "type": "VARATTR",
               "name": "MOAB_DATACENTER",
                "values": ["vcenter-datacenter-416"],
                "displayValues": ["Data Center 416"]
             },
            "rules":{
               "MOAB_DATACENTER":[
                  {
                     "value":"datacenter3",
                     "restriction":"must",
                     "comparator":"%=",
                     "displayValue":null
                  }
               ]
            }
         }
      }
   },
   "id":"4edff0cc6852f709fa777826"
}

Service with children (recursive=true). This example uses some field selection to restrict the full output while still demonstrating that the job and VM details are returned for applicable child services.

GET http://localhost:8080/mws/rest/services/bobService.1?api-version=3&recursive=true&api-version=3&fields=...
------------------------------------

{
   "tenant": {
      "id":1234567890abcdef12345678",
      "name": "Research"
   },
   "name":"TestService1.1",

   "phase:"Deployed",
   "dateCreated":"2013-01-15 17:15:25 UTC",
   "lastUpdated":"2013-01-15 17:15:25 UTC",
   "dateDeleted": null,
   "type":"container",
   "label":null,
   "user":"moab-admin",
   "account":null,
   "includedServices":[
      "Virtual Machine 2 container",
      "Virtual Machine 3 container"
   ],

   "stepsCompleted": [],

   "hookDefinitions": [],

   "parent":null,
   "startDateRequested":"2013-01-15 17:15:25 UTC",
   "startDateScheduled":"2013-01-15 17:15:25 UTC",
   "durationRequested":null,
   "version":0,
   "status":"Service waiting to be scheduled at 2013-01-15 17:15:25 UTC",
   "statusCode":null,
   "attributes":{
      "moab":{
         "vc":{
            "id":"vc6"
         },
         "dependencies":[
         ],
         "jobRequested":{
           "nodeSet": {
              "selection": "FIRSTOF",
               "type": "VARATTR",
               "name": "MOAB_DATACENTER",
                "values": ["vcenter-datacenter-416"],
                "displayValues": ["Data Center 416"]
             },
            "rules":{
               "MOAB_DATACENTER":[
                  {
                     "value":"datacenter3",
                     "restriction":"must",
                     "comparator":"%=",
                     "displayValue":null
                  }
               ]
            }
         }
      }
   },
   "children":[
      {
         "tenant": {
            "id":1234567890abcdef12345678",
            "name": "Research"
         },
		 "name":"Virtual Machine 2 container",
         "dateCreated":"2013-01-15 17:15:25 UTC",
         "lastUpdated":"2013-01-15 17:15:25 UTC",
         "dateDeleted": null,
         "type":"container",
         "label":null,
         "user":"moab-admin",
         "account":null,
         "includedServices":[
            "vm 2",
            "Virtual Machine 2 container OS Storage"
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "parent":"TestService1.1",
         "startDateRequested":"2013-01-15 17:15:25 UTC",
         "startDateScheduled":"2013-01-15 17:15:25 UTC",
         "durationRequested":null,
         "version":0,
         "status":"Service waiting to be scheduled at 2013-01-15 17:15:25 UTC",
         "statusCode":null,
         "attributes":{
            "moab":{
               "vc":{
                  "id":"vc7"
               },
               "dependencies":[

               ],
               "jobRequested":{
                  "nodeSet": {
                    "selection": "FIRSTOF",
                     "type": "VARATTR",
                     "name": "MOAB_DATACENTER",
                     "values": ["vcenter-datacenter-416"],
                     "displayValues": ["Data Center 416"]
                  },
                  "rules":{
                     "MOAB_DATACENTER":[
                        {
                           "value":"datacenter3",
                           "restriction":"must",
                           "comparator":"%=",
                           "displayValue":null
                        }
                     ]
                  }
               }
            }
         },
         "children":[
            {
               "tenant": {
                  "id":1234567890abcdef12345678",
                  "name": "Research"
               },
               "name":"vm 2",

               "phase":"Deployed",               
               "dateCreated":"2013-01-15 17:15:25 UTC",
               "lastUpdated":"2013-01-15 17:15:25 UTC",
               "dateDeleted": null,
               "type":"vm",
               "label":null,
               "user":"moab-admin",
               "account":null,
               "includedServices":[

               ],

               "stepsCompleted": [],

               "hookDefinitions": [],

               "parent":"Virtual Machine 2 container",
               "startDateRequested":"2013-01-15 17:15:25 UTC",
               "startDateScheduled":"2013-01-15 17:15:25 UTC",
               "durationRequested":null,
               "version":6,
               "status":"VM successfully provisioned",
               "statusCode":null,
               "attributes":{
                  "moab":{
                     "vc":{
                        "id":"vc8"
                     },
                     "jobRequested":{
                        "id":"Moab.9",
                        "template":"genericVM",
                        "image":"centos5.5-stateless",
                        "resources":{
                           "mem":1024,
                           "procs":1
                        },
                        "nodeSet": {
                          "selection": "FIRSTOF",
                           "type": "VARATTR",
                           "name": "MOAB_DATACENTER",
                           "values": ["vcenter-datacenter-416"],
                           "displayValues": ["Data Center 416"]
                        },
                        "rules":{
                           "MOAB_DATACENTER":[
                              {
                                 "value":"datacenter3",
                                 "restriction":"must",
                                 "comparator":"%=",
                                 "displayValue":null
                              }
                           ]
                        }
                     }
                  },
                  "vmId":"vm3",
                  "hypervisor":"i04"
               },
               "virtualMachineDetails":{
                 "name":"vm3"
               },
               "jobDetails":{
                 "name":"Moab.9"
               },
               "id":"50f58eade4b03bfe59ca30c4"
            },
            {
               "tenant": {
                  "id":1234567890abcdef12345678",
                  "name": "Research"
               },
               "name":"Virtual Machine 2 container OS Storage",

               "phase":"Deployed",
               "dateCreated":"2013-01-15 17:15:25 UTC",
               "lastUpdated":"2013-01-15 17:15:25 UTC",
               "dateDeleted": null,
               "type":"storage",
               "label":null,
               "user":"moab-admin",
               "account":null,
               "includedServices":[

               ],

               "stepsCompleted": [],

               "hookDefinitions": [],

               "parent":"Virtual Machine 2 container",
               "startDateRequested":"2013-01-15 17:15:25 UTC",
               "startDateScheduled":"2013-01-15 17:15:25 UTC",
               "durationRequested":null,
               "version":2,
               "status":"Storage successfully provisioned",
               "statusCode":null,
               "attributes":{
                  "moab":{
                     "vc":{
                        "id":"vc9"
                     },
                     "jobRequested":{
                        "id":"Moab.8",
                        "template":"OSStorage",
                        "resources":{
                           "gold":100
                        },
                       "nodeSet": {
                         "selection": "FIRSTOF",
                         "type": "VARATTR",
                         "name": "MOAB_DATACENTER",
                         "values": ["vcenter-datacenter-416"],
                         "displayValues": ["Data Center 416"]
                        },
                        "rules":{
                           "MOAB_DATACENTER":[
                              {
                                 "value":"datacenter3",
                                 "restriction":"must",
                                 "comparator":"%=",
                                 "displayValue":null
                              }
                           ]
                        }
                     }
                  },
                  "mount":"nfs://simulatedMount8",
                  "server":"vlan3-gold",
                  "size":"100"
               },
               "id":"50f58eade4b03bfe59ca30c5"
            }
         ],
         "id":"50f58eade4b03bfe59ca30c3"
      },
      {
         "tenant": {
            "id":1234567890abcdef12345678",
            "name": "Research"
         },
		 "name":"Virtual Machine 3 container",
         "dateCreated":"2013-01-15 17:15:25 UTC",
         "lastUpdated":"2013-01-15 17:15:25 UTC",
         "dateDeleted": null,
         "type":"container",
         "label":null,
         "user":"moab-admin",
         "account":null,
         "includedServices":[

         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "parent":"TestService1.1",
         "startDateRequested":"2013-01-15 17:15:25 UTC",
         "startDateScheduled":"2013-01-15 17:15:25 UTC",
         "durationRequested":null,
         "version":0,
         "status":"Service waiting to be scheduled at 2013-01-15 17:15:25 UTC",
         "statusCode":null,
         "attributes":{
            "moab":{
               "vc":{
                  "id":"vc10"
               },
               "dependencies":[

               ],
               "jobRequested":{
                  "nodeSet": {
                    "selection": "FIRSTOF",
                    "type": "VARATTR",
                    "name": "MOAB_DATACENTER",
                    "values": ["vcenter-datacenter-416"],
                    "displayValues": ["Data Center 416"]
                  },
                  "rules":{
                     "MOAB_DATACENTER":[
                        {
                           "value":"datacenter3",
                           "restriction":"must",
                           "comparator":"%=",
                           "displayValue":null
                        }
                     ]
                  }
               }
            }
         },
         "children":[

         ],
         "id":"50f58eade4b03bfe59ca30b6"
      }
   ],
   "id":"50f58eade4b03bfe59ca30c2"
}

VM Service using API version 2:

This output is using field selection for id, name, attributes.moab.jobRequested.id, attributes.vmId, jobDetails.name,and virtualMachineDetails.name—meaning not all of the output is shown. This example is simply to show the behavior of API version 2 with a VM service.

GET http://localhost:8080/mws/rest/services/vm3service.1?api-version=3&fields=...
------------------------------------

{
  "name": "vm3service",
  "attributes": {
    "moab": {
      "jobRequested": {
        "id": "Moab.9"
      }
    },
    "vmId": "vm3"
  },
  "id": "50f58eade4b03bfe59ca30c4",
  "jobDetails":{
    "name": "Moab.9"
  },
  "virtualMachineDetails":{
    "name": "vm3"
  }
}

Get Root Service

URLs and parameters

GET http://localhost:8080/mws/rest/services/<id>/root?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]
GET http://localhost:8080/mws/rest/services/<name>/root?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]

To see available URL parameters, see Get Single Service and Global URL Parameters.

Response

Returns the root service container for a specific service. The root service, sometimes referred to as the top level service, either directly or indirectly contains all other services in a service hierarchy.

For example, assume there are services A, B, C, D, E, F, and G. A contains B and C. B contains D and E. C contains F and G:

Click to enlarge

The root service of A, B, C, D, E, F, and G is A.

In this example A is the root service of A.

Samples

GET http://localhost:8080/mws/rest/services/centos6Vm/root?api-version=3&fields=name,type,includedServices
------------------------------------

{
  "name": "centos6VmPlusStorage"
  "type": "container",
  "includedServices":   [
    "centos6Vm",
    "centos6Storage"
  ]

Get Service for Virtual Machine

URLs and parameters

GET http://localhost:8080/mws/rest/services/vms/<vmId>?api-version=3[&[show-recursive-vc|show-vc]=true&recursive=true]

To see available URL parameters, see Get Single Service and Global URL Parameters.

Response

Returns the service associated with a specific virtual machine. The service's type must be vm and the service's attributes.vmId must match the virtual machine's identifier (e.g "vm1").

A maximum of one service should be associated with a virtual machine. If more than one service is associated with a virtual machine only one service will be displayed.

Samples

GET http://localhost:8080/mws/rest/services/vms/vm12?api-version=3&fields=name,type,attributes.vmId
------------------------------------

{
  "name": "centos6Vm.12",
  "type": "vm",
  "attributes": {"vmId": "vm12"}
}

Creating Services

The HTTP POST method is used to create a Service.

Quick reference

POST http://localhost:8080/mws/rest/services?api-version=3

If you are logged in as an application account or LDAP user and submit a service without specifying the user, MWS considers the user as which you are logged in the user of the service.

Create Service from Service Template

URLs and parameters

POST http://localhost:8080/mws/rest/services?api-version=3

See Global URL Parameters for available URL parameters.

Simple case

The tenant field is required and must contain only letters, digits, periods, dashes, and underscores. For POST and PUT actions, the tenant name or ID, or both the name and ID must be specified; if both the name and ID are specified, they must both refer to the same tenant or MWS returns an error.

To create a service from the template named "Rhel54VmPlusStorage":

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
  "tenant": {
     "id":1234567890abcdef12345678",
     "name": "Research"
  },
  "user": "steve",
  "account": "cloud",
  "startDateRequested": "2013-07-19 13:18:47 MST",
  "durationRequested": 86400,
  "data":   [
    {
      "label": "My RHEL 5.4 VM Plus Storage",
      "serviceTemplate": "Rhel54VmPlusStorage",
    }
  ]
}

Alternatively you can submit:

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
  "tenant": {
     "id":1234567890abcdef12345678",
     "name": "Research"
  },
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "label": "My RHEL 5.4 VM Plus Storage",
      "serviceTemplate": {
        "name":"Rhel54VmPlusStorage"
      } 
    }
  ]
}

To create a service based on the service template with id "4fbd2d90c4aa4996400bsa5m":

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
  "tenant": {
     "id":1234567890abcdef12345678",
     "name": "Research"
  },
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "label": "My RHEL 5.4 VM Plus Storage",
      "serviceTemplate": {
        "id":"4fbd2d90c4aa4996400bsa5m"
      } 
    }
  ]
}

"name" and "label" fields

The name field is deprecated in version 8.1.0. If it is set, it must be unique. However, if the name field is not set, a new UUID will be automatically generated for each service without a name value.
The label field is required and must not be blank. However, if the name field is already specified by the client, it will be automatically used as the label.
If neither name or label field is set during service creation, an error will occur.
If the label field is not specified for a service, the label field from the service template will be inherited.

Note that the name field must still be used for extending service templates and defining "included services."

Extending a service template

If you want to create a service from a service template, but wish to extend the service template with some additional variables or generic resources, you can use the extends field. Extending a service template is also helpful when you wish to override certain values, such as the amount of memory or processors the service requires.

To extend a service template, you will need to determine the extends path for the service you wish to override. The extends path is the name of the top level service, followed by one or more localNames as described in the includedServices field. All but the last <localName> are nested containers inside the top level container. For example:

<top level service name>::<localName>[:<localName>]+

For example, suppose you want to create a new service from the "Rhel54VmPlusStorage" service template, and you want to name this new service "MyRhel54VmPlusStorage". In this example, "Rhel54VmPlusStorage" contains a service template named "SubContainer1". The localName for "SubContainer1" in the "Rhel54VmPlusStorage" includedServices field is "sc1".

Rhel54VmPlusStorage service template
------------------------------------

{
   "name":"Rhel54VmPlusStorage",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"sc1",
         "serviceTemplate":"SubContainer1"
      }
   ]

The extends path for the instance of "SubContainer1" in your "MyRhel54VmPlusStorage" is:

MyRhel54VmPlusStorage::sc1

Let's say inside "SubContainer1" is another service template called "SubContainer2". The localName for "SubContainer2" as defined in the includedServices field for "SubContainer1" is "sc2".

SubContainer1 service template
------------------------------------

{
   "name":"SubContainer1",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"sc2",
         "serviceTemplate":"SubContainer2"
      }
   ]

The extends path for the instance of "SubContainer2" in "MyRhel54VmPlusStorage" is:

MyRhel54VmPlusStorage::sc1:sc2

Now let's say that "SubContainer2" contains two service templates, "Rhel54Vm" and "OpsysStorage" with localNames "rvm" and "oss" respectively.

SubContainer1 service template
------------------------------------

{
   "name":"SubContainer2",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"rvm",
         "serviceTemplate":"Rhel54Vm"
      },
      {
         "localName":"oss",
         "serviceTemplate":"OpSysStorage"
      }
   ]

The extends paths for the instances of "Rhel54VM" and "OpSysStorage" in "MyRhel54VmPlusStorage" are:

MyRhel54VmPlusStorage::sc1:sc2:rvm
MyRhel54VmPlusStorage::sc1:sc2:oss

Now that we have the extends paths for all the services that will be created from the "Rhel54VmPlusStorage" template, we can add variables to these services that were not in the service templates.

In the following example, the specified tenant must match the tenant in the corresponding service template.

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
  "tenant": {
     "id":1234567890abcdef12345678",
     "name": "Research"
  },
  "user": "steve",
  "account": "cloud",
  "data":   [
        {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": "Rhel54VmPlusStorage",
      "attributes": {
         "sharedData":{ "extraAttribute":"some attribute not in the Rhel54VmPlusStorage template" }
      }
    },
    {
      "name": "MyRhel54Vm",
      "extends": "MyRhel54VmPlusStorage::sc1:sc2:rvm",
      "attributes": {
          "moab": {"job": {"variables": {"extraVar": "An additional variable not in the Rhel54Vm template"}}},
          "sharedData":{ "extraAttribute":"some attribute not in the Rhel54Vm template" }          
      }
    },
    {
      "name": "MyOsStorage",
      "extends": "MyRhel54VmPlusStorage::sc1:sc2:oss",
      "attributes": {
          "moab": {"job": {"variables": {"extraVar2": "An additional variable not in the OpSysStorage template"}}},
          "sharedData":{ "extraAttribute":"some attribute not in the OpSysStorage template" }          
      }
    }
  ]
}

When the "MyRhel54Vm" service is created, it will have a variable named "extraVar" even though this variable was not defined in the "Rhel54Vm" service template. Likewise, when the "MyOsStorage" service is created, it will have a variable named "extraVar2", even though no such variable was defined in the "OsStorage" service template. All three services will have an attribute named "extraAttribute" in their attributes.sharedData sections though "extraAttribute" does not appear in any service template.

Extending services and dependencies in a container service

To add a services to a container service that were not in the container's service template you first define the new services in the service request. Then you extend the includedServices field of the container with the newly defined services. This will add the new services to any that are already in the container as defined in the service template. It is only possible to add services to a container. It is not possible to remove services from a container that were defined in the container's service template.

For example, say the CentosVmPlusStorage service template contains an OpSysStorage service template and a CentosVm service template.

CentosVmPlusStorage service template
------------------------------------

{
   "name":"CentosVmPlusStorage",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"oss",
         "serviceTemplate":"OpSysStorage"
      },
      {
         "localName":"cvm",
         "serviceTemplate":"CentosVm"
      }
   ]

To add two storage services to the service created from the CentosVmPlusStorage service template submit the following service request:

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
   "tenant": {
     "id":1234567890abcdef12345678",
     "name": "Research"
   },
   "user":"bob",
   "account":"cloud",
   "data":[
      {
         "name":"BobsCentosVmPlusStorage",
         "serviceTemplate":"CentosVmPlusStorage",
         "includedServices":[
            "NewStorageToAdd1",
            "NewStorageToAdd2"
         ]

       },
      {
         "name":"NewStorageToAdd1",
         "serviceTemplate":"ExtraStorage"
      },
      {
         "name":"NewStorageToAdd2",
         "serviceTemplate":"ExtraStorage"
      }
   ]
}

The resulting service BobsCentosVmPlusStorage will contain NewStorageToAdd1, NewStorageToAdd2, a service created from the OpSysStorage template, and a service created from the CentosVm template. To add a dependency such that the CentosVm service will not be able to start until both NewStorageToAdd1 and NewStorageToAdd2 have been set up:

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
   "tenant": {
      "id":1234567890abcdef12345678",
      "name": "Research"
   },
   "user":"bob",
   "account":"cloud",
   "data":[
      {
         "name":"BobsCentosVmPlusStorage",
         "serviceTemplate":"CentosVmPlusStorage",
         "includedServices":[
            "NewStorageToAdd1",
            "NewStorageToAdd2"
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "service":"BobsCentosVm",
                     "dependency":[
                        "NewStorageToAdd1",
                        "NewStorageToAdd2"
                     ]
                  }
               ]
            }
         }
      },
      {
         "name":"BobsCentosVm",
         "extends":"CentosVmPlusStorage:cvm"
      },
      {
         "name":"NewStorageToAdd1",
         "serviceTemplate":"ExtraStorage"
      },
      {
         "name":"NewStorageToAdd2",
         "serviceTemplate":"ExtraStorage"
      }
   ]
}

Extendable fields

You can only extend certain fields. Below is a table of fields that can be extended:

Extendable fields	Notes
attributes.moab.dependencies	Dependencies can be added but not removed. Only applicable to containers.
attributes.moab.job.features	Features can be added but not removed.
attributes.moab.job.nodeSet	Overrides the nodeSet from the service template.
attributes.moab.job.requestedHosts	Hosts can be added but not removed.
attributes.moab.job.resources	Including procs, mem, disk, and any generic resource.
attributes.moab.job.rules	Overrides all rules from the service template.
attributes.moab.job.variables	Can either change the value of variables in the template or add new variables.
attributes.sharedData	A place for arbitrary, site-specific data.
image
includedServices	Services can be added but not removed. Only applicable to containers.
label

Sample response

If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.

JSON response
------------------------------------

{"name":"MyRhel54VmPlusStorage.1"}

Create Custom Service

URLs and parameters

POST http://localhost:8080/mws/rest/services

See Global URL Parameters for available URL parameters.

Request body

The tenant field is required and must contain only letters, digits, periods, dashes, and underscores.

The payload below shows all the fields that are available during service submission.

POST http://localhost:8080/mws/rest/services?api-version=3
------------------------------------

{
   "tenant": {
      "id":1234567890abcdef12345678",
      "name": "Research"
   },
   "user":"adaptive",
   "account":"cloud",
   "startDateRequested":"2011-11-08 13:18:47 MST",
   "durationRequested":86400,
   "data":[
      {
         "name":"myNewService",
         "type":"container",
         "label":"My New Service",
         "includedServices":[
            "myVmContainer",
            "myNetworkStorageWorkflow",
            "myPmContainer"
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myNetworkStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ],
               "job":{
                  "nodeSet":{
                     "selection":"FIRSTOF",
                     "type":"VARATTR",
                     "name":"MOAB_DATACENTER",
                     "values":[
                        "datacenter4"
                     ]
                  },
                  "rules":{
                     "ATTRIBUTE_1":[
                        {
                           "value":"value_1",
                           "restriction":"must",
                           "comparator":"%="
                        }
                     ]
                  }
               }
            },
            "sharedData":{
               "extraAttribute":"Some arbitrary value",
               "extraAttribute2":"Another arbitrary value"
            }
         }
      },
      {
         "name":"myVmContainer",
         "label":"My VM Container",
         "type":"container",
         "includedServices":[
            "myVmWorkflow",
            "myOsStorageWorkflow"
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myOsStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ]
            }
         }
      },
      {
         "name":"myVmWorkflow",
         "label":"My VM Workflow",
         "type":"vm",
         "includedServices":[
         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,
                     "mem":2048,
                     "disk":80
                  },
                  "variables":{
                     "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericVM",
                  "requestedHosts":[
                     "i16"
                  ],
                  "features":[
                     "vlan3"
                  ],
                  "flags":[
                     "novmmigrate"
                  ]
               }
            }
         }
      },
      {
         "name":"myOsStorageWorkflow",
         "label":"My OS Storage Workflow",
         "type":"storage",
         "includedServices":[

         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "job":{
                  "template":"OSStorage",
                  "resources":{
                     "OS":2500
                  }
               }
            }
         }
      },
      {
         "name":"myNetworkStorageWorkflow",
         "label":"My VM Container",
         "type":"storage",
         "includedServices":[

         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "job":{
                  "template":"extraStorage",
                  "resources":{
                     "gold":500
                  },
                  "variables":{
                     "mount":"/path/to/mount"
                  }
               }
            }
         }
      },
      {
         "name":"myPmContainer",
         "label":"My PM Container",
         "type":"container",
         "includedServices":[
            "myPmWorkflow"
         ],

         "stepsCompleted": [],

         "hookDefinitions": []

       },
      {
         "name":"myPmWorkflow",
         "label":"My PM Workflow",
         "type":"pm",
         "includedServices":[

         ],

         "stepsCompleted": [],

         "hookDefinitions": [],

         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,
                     "mem":2048,
                     "disk":100
                  },
                  "variables":{
                     "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericPM"
               }
            }
         }
      }
   ]
}

The name field must still be used when extending service templates and defining "included services." For more information, see "name" and "label" fields.

Sample response

If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.

JSON response
------------------------------------

{"name":"myNewService.1"}

Service Inheritance

Child services can inherit certain attributes from parent (or grandparent) services. Inheritance happens when a child service’s attribute is a null value and when one of its parent service’s attribute is a non-null value. When a service is created from a service template, inheritance happens after any extensions. In other words, fields from the service template are overridden by corresponding fields in the service before inheritance occurs.

Currently, attributes.moab.job.nodeSet and attributes.moab.job.rules are the only attributes that support inheritance.

NodeSet inheritance

If a child service’s attributes.moab.job.nodeSet field is null, it inherits the nodeSet values from its nearest parent that has a nodeSet value (anything non-null). This means that a child service will inherit a nodeSet value from its parent if, and only if, its nodeSet value is null, and the parent’s nodeSet value is not null. If the parent service’s value is also null, the child service will inherit the nodeSet value from the grandparent service; if the grandparent’s service value is null, the child service will inherit the nodeSet value from the great-grandparent service, and so on.

If all parent services have a null value, then the child service retains its null value (as there is nothing it can possibly inherit).

It is possible for a nodeSet field to be an empty object. Even though the object is empty, it is considered to be a non-null value, and any child services with a null value will inherit the empty rules object from its parent service.

The following diagram shows a service hierarchy before any nodeSet values are inherited. Note that service A, the top-level or “grandparent” service, has a null nodeSet value.

Click to enlarge

Once nodeSet values are inherited, the services will change as follows:

Click to enlarge

Services B and D remain unchanged, because they have no parent services with a non-null nodeSet value. However, note that service F has inherited service C’s nodeSet value. This is because service F previously had a null value, but its parent service, service C, had a non-null value (ONEOF:FEATURE:C).

Let’s look at another example.

Click to enlarge

In this example, note that service A—the grandparent service—has a non-null nodeSet value (ONEOF:FEATURE:A).

Click to enlarge

Note that two things happened after inheritance occurred:

Service B inherited service A’s nodeSet value (ONEOF:FEATURE:A). Service D then inherited the same nodeSet value from service B.
Service F inherited service C’s nodeSet value (ONEOF:FEATURE:C). Note that it did not inherit service A’s nodeSet value. This is because a child service inherits the non-null nodeSet value from its nearest parent.

Rules inheritance

Similar to the way child services inherit nodeSet values, child services also inherit rules values. If a service’s attributes.moab.job.rules field is null, it inherits the rules values from its nearest parent that has a rules value (i.e. a non-null value). This means that a child service will inherit a rules value from its parent if, and only if, its rules value is null, and the parent’s rules value is not null.

If all parent services have a null value, then the child service retains its null value (as there is nothing it can possibly inherit).

It is possible for a rules field to be an empty object. Even though the object is empty, it is considered to be a non-null value, and any child services with a null value will inherit the empty rules object from its parent service.

The following diagram shows a service hierarchy before any rules values are inherited. Empty brackets ([]) indicate an empty rules object. Remember that an empty rules object is considered to be a non-null value.

Click to enlarge

Once the rules values are inherited, the services change, as follows:

Click to enlarge

Three things of note occurred with inheritance:

Services B and E remain unchanged, because their parent (service A), has a null value.
Service K inherited the rules value from its parent, service D, ([d must %= 1]).
Service H inherited the empty list value from its parent, service C. This is because an empty object is still considered a non-null value.

Let’s look at another example.

Click to enlarge

In this example, service A has a non-null rules value ([a must %= 0]). Once the rules values are inherited, the services change, as follows:

Click to enlarge

Two things of note occurred with inheritance:

Services B and E both inherit service A’s rules value.
Service H still inherited service C’s value, and service K still inherited service D’s value. This is because a child service inherits the non-null rules value from its nearest parent.

Modifying or Moving Services

The HTTP PUT method is used to modify Services.

Quick reference

PUT http://localhost:8080/mws/rest/services/<id>?api-version=3&change-mode=<add|remove|set>
PUT http://localhost:8080/mws/rest/services/<name>?api-version=3&change-mode=<add|remove|set>

PUT http://localhost:8080/mws/rest/services/<id|name>/unblock?api-version=3

PUT http://localhost:8080/mws/rest/services/<id|name>/terminate?api-version=3

Modify Service

URLs and parameters

PUT http://localhost:8080/mws/rest/services/<id>?api-version=3&change-mode=<add|remove|set>
PUT http://localhost:8080/mws/rest/services/<name>?api-version=3&change-mode=<add|remove|set>

Parameter	Required	Type	Valid values	Description
id	Yes	String	--	The unique identifier of the Service.
name	Yes	String	--	The name of the Service.
change-mode	No	String	add remove set	If add, add the specified steps or hook definitions to existing ones. If remove, remove the specified steps or hook definitions from existing ones. If set, replace all steps or hook definitions with the ones specified.

Parameter

Required

Type

Valid values

Description

Yes

String

The unique identifier of the Service.

name

Yes

String

The name of the Service.

change-mode

String

add

remove

set

If add, add the specified steps or hook definitions to existing ones.

If remove, remove the specified steps or hook definitions from existing ones.

If set, replace all steps or hook definitions with the ones specified.

Only one of id or name is required.

The change-mode parameter only applies to the stepsCompleted and hookDefinitions fields.

See Global URL Parameters for available URL parameters.

Example request

Only the attributes, status, statusCode, and label fields may be modified in services. Note that the status and label fields must be a valid string, and the statusCode field must be a valid number (long). Any arbitrary string and number may be used to represent the current state of the service through status and statusCode respectively.

PUT http://localhost:8080/mws/rest/services/myStorageService?api-version=3
------------------------------------

{
    "label": "My Service",
    "status": "Done provisioning!",
    "statusCode": 200,
    "attributes": {
        "mount": "/mnt/myMount",
        "size": "2500",
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"      
        }
    }
}

The moab element of attributes cannot be modified. An error will be returned if this is attempted.

Sample response

JSON response
------------------------------------

{
    "tenant": {
        "id":1234567890abcdef12345678",
        "name": "ResearchGroup"
    },
    "name": "myStorageService",
    "dateCreated": "2012-02-01 14:54:52 UTC",
    "lastUpdated": "2012-02-01 14:54:52 UTC",
    "type": "storage",
    "label": "My Service",
    "user": "john",
    "account": "corp",
    "status": "Done provisioning!",
    "statusCode": 200,
    "includedServices": [],

    "stepsCompleted": [],

    "hookDefinitions": [],

    "parent": "myVmWithStorage",
    "attributes": {
        "moab": {
            "vc    ": {
                "id": "vc3"
            },
            "jobRequested": {
                "id": "Moab.1",
                "template": "extraStorage",
                "resources": {
                    "gold": 2500
                }
            }
        },
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"        
        },
        "mount": "/mnt/myMount",
        "size": "2500"
    },
    "id": "4f29b4abe4b03c2f8e3a1a40"
}

Move Service

Moving a service is a matter of updating an existing service. The following requirements must be met to move a service:

The specified service must be a container service.
The destination tenant must exist.
The user requesting the move must have global update service permission or update service permissions for both the current tenant and the new tenant.

Moving a service moves that service and all its child services, plus all associated jobs and VMs. Jobs and VMs should automatically migrate to the new tenant's node(s) but may not due to resource availability, policies, and so forth.

Services that contain storage or physical machines as part of the service will not move as intended and your service will not work as intended. Do not use this option on services that contain storage or physical machines.

Sample request

PUT http://localhost:8080/mws/rest/services/<serviced-id-or-name>?api-version=3
------------------------------------
{
   "tenant": {
      "id":1234567890abcdef12345678",
      "name": "ResearchGroup"
   }
}

Unblock a Service

URLs and parameters

PUT http://localhost:8080/mws/rest/services/<id|name>/unblock?api-version=3

Response

Returns a list of actions Moab took to unblock the service.

Sample response

PUT http://localhost:8080/mws/rest/services/genericVM/unblock?api-version=3
----------------------------------

   "requeued completed job 'Moab.3.genericVM-setup'"

If a job in the service workflow cannot be requeued, MWS will return an error message to explain why it failed. If the service is not blocked when this call is made, MWS returns an error that says there is nothing to unblock.

Terminate a Service

URLs and parameters

PUT http://localhost:8080/mws/rest/services/<id|name>/terminate?api-version=3

Response

Ends a service's normal lifecycle but does not delete it.

Sample response

PUT http://localhost:8080/mws/rest/services/genericVM/terminate?api-version=3
----------------------------------

   "terminated job 'Moab.1.genericVM-setup'",

   "terminated job 'Moab.2.genericVM-setup'",

   "terminated job 'Moab.4.genericVM-destroy'"

   "terminated job 'Moab.3.genericVM-setup'"

Deleting Services

The HTTP DELETE method is used to delete Services.

Quick reference

DELETE http://localhost:8080/mws/rest/services/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/services/<name>?api-version=3

If you delete a service without specifying who deleted it, MWS considers the deleter of the service the user as which you are logged in

Delete Service

URLs and parameters

DELETE http://localhost:8080/mws/rest/services/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/services/<name>?api-version=3

Parameter	Required	Type	Valid values	Description	Example
force-delete	No	Boolean	true or false	If true MWS will not check service dependencies before deleting it.	--
id	Yes	String	--	The unique identifier of the Service.	--
name	Yes	String	--	The name of the Service.	--

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{}

Getting Service Lifecycle Phase Hook Information

The HTTP GET method is used to retrieve information about all global service hooks and all running service hooks (global-definitions, and running, respectively.). You may also query for all hooks on a single service (definitions).

Quick reference

GET http://localhost:8080/mws/rest/services/hooks/global-definitions?api-version=3

GET http://localhost:8080/mws/rest/services/hooks/running?api-version=3

GET http://localhost:8080/mws/rest/services/<id>|<name>/hooks/definitions?api-version=3

Get All Global Hook Definitions

URLs and parameters

See Global URL Parameters for available URL parameters.

Response

Returns all configured global hook definitions.

Sample response

GET http://localhost:8080/mws/rest/services/hooks/global-definitions?api-version=3
----------------------------------
{
    "totalCount": 1,
    "resultCount": 1,
    "results": [
        {
	     "id": "51f9395484aeed592c4d658e",
	     "name": "auditHook",
	     "type": "after",

             "includeServiceAsBody": true,
	     "currentPhase": "analyzing",
	     "transition": "accept",
	     "nextPhase": "deploying",
	     "url": "exec:///opt/mws/spool/hooks/audit.pl",
             "timeoutInSeconds": 3000
	 },
	 {
	      "id": "12a8284373zddc481b3c547d",
	      "name": "email",
	      "type": "after",

              "includeServiceAsBody": false,
	      "currentPhase": "analyzing",
	      "transition": "accept",
	      "nextPhase": "deploying",
	      "url": "exec:///opt/mws/spool/hooks/serviceEmail.pl"
	  }
     ]
}

Get All Hook Definitions on a Single Service

URLs and parameters

GET http://localhost:8080/mws/rest/services/<id>|<name>/hooks/definitions?api-version=3

Parameter	Required	Type	Valid values	Description	Example
id	Yes	String	---	The unique identifier of the service .	--
name	Yes	String	--	The unique name of the service.	--

Only one of id or name is required.

To see available URL parameters, see Global URL Parameters.

Response

Returns a combination of all global (global-definitions) and service hook definitions.

Samples

    "totalCount": 1,
    "resultCount": 1,
    "results": [

        {
	     "id": "51f9395484aeed592c4d658e",
             "global": true,
	     "name": "hookDefinitionName",
	     "type": "after",

             "includeServiceAsBody": true,
	     "currentPhase": "analyzing",
	     "transition": "accept",
	     "nextPhase": "deploying",
	     "url": "exec:///opt/mws/spool/hooks/script.pl",
	     "timeoutInSeconds": 3000

        },
	 {
	     "id": "62g1416595ffe613d5e769f",
	     "global":  false,
	     "name": "hookDefinitionName2",
	     "type": "after",

             "includeServiceAsBody": false,
	     "currentPhase": "",
	     "transition": "migrate",
	     "nextPhase": "",
	     "url": "exec:///opt/mws/spool/hooks/script2.pl",
	     "timeoutInSeconds": 900

        },
	 {
	     "id": "49e8284373zddc481b3c547d",
	     "global": true,
	     "name": "hookDefinitionName3",
	     "type": "after",

             "includeServiceAsBody": true,
	     "currentPhase": "",
	     "transition": "",
	     "nextPhase": "deployed",
	     "url": "exec:///opt/mws/spool/hooks/script3.pl",
	     "timeoutInSeconds": 900
        }

]
}

Get All Running Service Hooks

URLs and parameters

GET http://localhost:8080/mws/rest/services/hooks/running?api-version=3

To see available URL parameters, see Global URL Parameters.

Response

Returns all running service hooks.

Samples

GET http://localhost:8080/mws/rest/services/hooks/running?api-version=3
------------------------------------
{

    totalCount: 3,

    resultCount: 3,

    results:

            definitionId: "52cc461c6eab428c05104a15",

            endDate: "2014-01-07 18:23:25 UTC",

            exitCode: 0,

            globalHook: false,

            processId: 18368,

            serviceId: "52cc461c6eab428c05104a2a",

            standardError: "",

            standardOutput:

                status: "Succeeded",

                outcome: "On transition 'Submit' beforeSync and afterSync was Analyzing"

},

            startDate: "2014-01-07 18:23:24 UTC",

            status: "SUCCEEDED",

            timeoutInSeconds: 900,

            version: 2,

            id: "52cc461c6eab428c05104a2b

},

            definitionId: "52cc461c6eab428c05104a1f",

            endDate: "2014-01-07 18:23:26 UTC",

            exitCode: 0,

            globalHook: false,

            processId: null,

            serviceId: "52cc461c6eab428c05104a2a",

            standardError: "Can't remove /opt/moab/tools/cloud/VM/setup.vm.pl: Permission denied, skipping file.",

            standardOutput:

                status: "Failed",

                action: "Make Setup Script Fail",

                transition: "Submit"

},

            startDate: "2014-01-07 18:23:26 UTC",

            status: "FAILED",

            timeoutInSeconds: 900,

            version: 1,

            id: "52cc461e6eab428c05104a2e"

},

            definitionId: "52cc461c6eab428c05104a16",

            endDate: "2014-01-07 18:23:40 UTC",

            exitCode: 0,

            globalHook: false,

            processId: 18416,

            serviceId: "52cc461c6eab428c05104a2a",

            standardError: "",

            standardOutput:

                status: "Succeeded",

                outcome: "On transition 'Accept' beforeSync and afterSync was Deploying"

},

            startDate: "2014-01-07 18:23:39 UTC",

            status: "SUCCEEDED",

            timeoutInSeconds: 900,

            version: 2,

            id: "52cc462b6eab428c05104a73"

Creating Service Lifecycle Phase Hooks

The HTTP POST method is used to create a global-definition and service lifecycle phase hook on a service. The HTTP PUT method can also be used to create a service lifecycle phase hook on a service.

The Fields: Service Global Hook Definitions, Fields: Service Running Hooks reference sections contain the type and description of all fields in the definitions, global-definitions, and running objects. It also contains details regarding which fields are valid during PUT and POST actions.

Quick reference

POST http://localhost:8080/mws/rest/services/hooks/global-definitions?api-version=3

POST http://localhost:8080/mws/rest/services?api-version=3

PUT http://localhost:8080/mws/rest/services/<id|name>?api-version=3&change-mode=add

Create a Service Lifecycle Phase Hook

Service phase hooks execute scripts you have configured to run during transitional events between service lifecycle phases. For more information about the service lifecycle and its phases, see "" in the Moab Cloud Suite Administrator Guide. You can configure global hooks that will exist on all services and service hooks that only exist on a single service or on any service that derived from a template with the hook(s). Configuration options allow you to be as vague or specific as you want when you specify when the hook should execute; for instance, you might have the script run when the service leaves the Analyzing phase for any reason, or you might have the script run only when the service leaving Analyzing is entering the Blocked phase.

URLs and parameters

Service phase hook attributes

Parameter	Required	Type	Valid values	Description	Example
id	No	String	--	The unique identifier of the service, generated on POST.	--
currentPhase	Yes	String	analyzing, blocked, cleaning, defining, deploying, deployed, migrating, rejected, reserved, terminated See Services for more information about each phase.	When your service transitions from this phase to another, the hook executes. currentPhase can be used with nextPhase or with both nextPhase and transition to attach the hook to a more specific event.	currentPhase=submit
global	No	Boolean	--	Indicates whether the phase hook is global or belongs to a specific service. It is false by default.	`global=true`
includeServiceAsBody	Yes	Boolean	--	If true, MWS passes the full service JSON into the service's stdin.	includeServiceAsBody=true
name	Yes	String	--	The name of the hook. Because hooks run alphabetically, the name determines the run order in relation to other scripts. When you give a service hook the same name as a global hook, the service hook overrides the global hook.	`name=myHook`
nextPhase	Yes	String	analyzing, blocked, cleaning, deleted, deploying, deployed, migrating, rejected, reserved, terminated See Services for more information about each service lifecycle phase.	When your service transitions to this phase from another, the hook runs. nextPhase can be used with currentPhase or with both currentPhase and transition to attach the hook to a specific event.	nextPhase=analyzing
timeoutInSeconds	No	Integer	--	The number of seconds that the hook will run before it times out. When a service hook times out, the service continues to run, but an error message is generated. The default is 900 seconds.	timeoutInSeconds=3000
transition	Yes	String	accept, automigrate, block, clean, deploy, expire, migrate, migrateaccept, migratefail, migratesuccess, purge, reject, reserve, submit, terminate, unblock See Services for more information about each service lifecycle phase transitions.	The event that causes the hook to execute. The services will not pause its transition to wait for the hooks to run, so the scripts must be short-run executions. transition can be used with currentPhase and nextPhase to attach the hook to a specific event.	transition=submit
type	Yes	String	"after"	The type of hook you are creating. The only valid type at present is after.	type=after
url	Yes	Path	exec:///<path>[?<field>=$<variable>[&<field>=<variable>]...]	The location of the script that will run when the hook executes. You can include a list of variables from the service or hook to pass into the script. Because MWS does not pause the service transition for the hook, your script should be simple. If the script takes too long to run, the service could become unsynchronized with the associated Moab job.	url=exec:///myScript.pl

Only one of currentPhase, nextPhase, or transition is required; however, you can also choose to use both currentPhase and nextPhase together or all three parameters.

See Global URL Parameters for available URL parameters.

Service hook status

If you would like to view the status of script after its execution, make sure that your script prints the following statuses to stdout. See step 3 in the instructions below for an example.

Status	Description
failed	The script failed. This could be due to a corrupt script, an improperly configured status, the script's running past the specified timeoutInSeconds, or other reasons. If the hook fails, MWS generates an error message and the service continues to run normally.
succeeded	The script executed and completed successfully without exceeding the specified timeoutInSeconds.
waiting	The script is currently running. The status will change to either failed or succeeded once the script finishes, but you may also change the status manually. When you manually change a running hook's status from waiting to succeeded, MWS assumes the script succeeded, regardless of what actually happened or if the script has finished running.

To create a service with a service hook

Verify that the /opt/mws/spool directory exists in your system and that tomcat has read and write access to it.
Create a new directory inside /opt/mws/spool for your scripts.
```
> mkdir /opt/mws/spool/hooks
```
Write a script executable by tomcat called /opt/mws/spool/hooks/helloWorld.sh that performs the action that should occur when the hook's service phase transition begins.
```
1 #!/bin/sh
```
```
2
```
```
3 is_succeeded=true
```
```
4 if $is_succeeded ; then
```
```
5   echo '{"output":"hello world!", "status":"succeeded"}' 
```
```
6 else
```
```
7   echo '{"status":"failed"}'
```
```
8 fi
```

Create a service with the hook definition, making sure that the URL references the script you made.

http://localhost:8080/mws/rest/services?api-version=3

-----------------------
{
  "name": "vm1",
  "type": "vm",

  "tenant": {
    "name": "Gryffindor"
  },

  "hookDefinitions": [
    {

      "name": "myHook",
      "transition": "submit",
      "type": "after",
      "url": "exec:///opt/mws/spool/hooks/helloWorld.sh"
    }
  ],
  "attributes": {
    "moab": {
      "job": {
        "resources": {
          "procs": "2",
          "mem": "1028"
        },
        "image": "centos5.5-stateless",

        "template": "genericVM"
      }
    }
  }

Create a container service that will hold the new VM.

http://localhost:8080/mws/rest/services?api-version=3
-----------------------

    "includedServices": [

        "localName": "vm1"

],

    "type": "container",

    "user": "rweasley",

    "account": "cloud",

    "tenant": {"name":"Gryffindor"},

    "data":   [

        "name": "vmGreat",

    "hookDefinitions":[]

Query /services/<id>/hooks/definitions to see both your global and local hooks for the service.
You can override global hook descriptions by giving a service hook definition the same name as the global hook.
Once your service runs, you can find it when you query the running hooks (/services/hooks/running).

Sample response

------------------------------------

Modifying Service Lifecycle Phase Hooks

The HTTP PUT method is used to modify service lifecycle phase hooks on Services.

Quick reference

PUT http://localhost:8080/mws/rest/services/<id>?api-version=3&change-mode=<add|remove|set>
PUT http://localhost:8080/mws/rest/services/<name>?api-version=3&change-mode=<add|remove|set>

Modify a Service Lifecycle Phase Hook

URLs and parameters

PUT http://localhost:8080/mws/rest/services/hooks/<id>/global-definitions?api-version=3

PUT http://localhost:8080/mws/rest/services/hooks/<name>/global-definitions?api-version=3

Parameter	Required	Type	Valid values	Description	Example
id	Yes	String		The unique identifier of the hook.	--
name	Yes	String		The name of the hook.	--
change-mode	Yes	String	One of add, remove, or set.	Whether you are replacing certain settings of the hook (add), removing certain settings of the hook (remove), or replacing the hook entirely (set). The change-mode parameter is used to delete a service phase hook. See Delete a Service Lifecycle Phase Hook for more information.	change-mode=set

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

------------------------------------

Changing the Status of a Running Service Hook

URLs and parameters

PUT http://localhost:8080/mws/rest/services/hooks/running/<id>/?change-mode=set?api-version=3

Parameter	Required	Type	Valid values	Description	Example
change-mode	Yes	String	set	Lets you change the current status of the service hook (see Service hook status for valid statuses). When you manually change a hook from waiting to succeeded, MWS assumes that the script did succeed, regardless of what actually happened or whether the script is still running. You can only modify the status field of a running hook.	change-mode=set
id	Yes	String	--	The unique identifier of the service hook.
name	Yes	String	--	The name of the service hook.

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

PUT http://localhost:8080/mws/rest/services/hooks/running?change-mode=set?api-version=3

------------------------------------

    "status": "succeeded"

Deleting Service Lifecycle Phase Hooks

The HTTP DELETE method is used to delete service lifecycle phase hooks from Services. Deleting a service (see Deleting Services for more information) deletes all hooks attached to it.

Quick reference

DELETE http://localhost:8080/mws/rest/services/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/services/<name>?api-version=3

Delete a Service Lifecycle Phase Hook

URLs and parameters

DELETE http://localhost:8080/mws/rest/services/hooks/global-definitions/<id>?api-version=3

DELETE http://localhost:8080/mws/rest/services/hooks/global-definitions/<name>?api-version=3

PUT http://localhost:8080/mws/rest/services?api-version=3&change-mode=remove

Parameter	Required	Type	Valid values	Description	Example
id	Yes	String		The unique identifier of the hook.
name	Yes	String		The name of the hook.

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

PUT http://localhost:8080/mws/rest/services?api-version=3&change-mode=remove

    "hookDefinitions":

            "id": "23423h2l32kl23kkl2"

Getting stepsCompleted Information

The HTTP GET method is used to get stepsCompleted information.

Quick reference

GET http://localhost:8080/mws/rest/services/<id|name>?api-version=3&fields=stepsCompleted

For information about using the stepsCompleted field in the Moab Cloud Suite, see "" in the Moab Cloud Suite Installation Guide.

Get Steps Completed Information

URLs and parameters

GET http://localhost:8080/mws/rest/services/<id|name>?api-version=3&fields=stepsCompleted

Parameter	Required	Type	Valid values	Description	Example
id	Yes	String	--	The unique identifier of the Service.	--
name	Yes	String	--	The name of the Service.	--

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

stepsCompleted:["step1,step2"]

Modifying stepsCompleted

The HTTP GET method is used to modify the stepsCompleted.

Quick reference

PUT http://localhost:8080/mws/rest/services/<id|name>?api-version=3&change-mode=add

For information about using the stepsCompleted field in the Moab Cloud Suite, see "" in the Moab Cloud Suite Installation Guide.

Modify stepsCompleted

URLs and parameters

PUT http://localhost:8080/mws/rest/services/<id|name>?api-version=3&change-mode=add

Parameter	Required	Type	Valid values	Description	Example
change-mode	Yes	String	One of add, remove, or set.	Whether you are adding steps (add), removing steps (remove), or replacing the steps entirely (set).	change-mode=set
id	Yes	String	--	The unique identifier of the Service.	--
name	Yes	String	--	The name of the Service.	--

Only one of id or name is required.

See Global URL Parameters for available URL parameters.

Sample response

PUT http://localhost:8080/mws/rest/services/<id|name>?api-version=3&change-mode=add

{stepsCompleted=>["step1"]}

------------------------------------

{
    "tenant": {
        "id":1234567890abcdef12345678",
        "name": "ResearchGroup"
    },
    "name": "myService",
    "dateCreated": "2012-02-01 14:54:52 UTC",
    "lastUpdated": "2012-02-01 14:54:52 UTC",
    "type": "storage",
    "label": "My Service",
    "user": "john",
    "account": "corp",
    "status": "Done provisioning!",
    "statusCode": 200,
    "includedServices": [],

    "stepsCompleted": [step0,step1],

    "hookDefinitions": [],

    "parent": "myVmWithStorage",
    "attributes": {
        "moab": {
            "vc    ": {
                "id": "vc3"
            },
            "jobRequested": {
                "id": "Moab.1",
                "template": "extraStorage",
                "resources": {
                    "gold": 2500
                }
            }
        },
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"        
        },
        "mount": "/mnt/myMount",
        "size": "2500"
    },
    "id": "4f29b4abe4b03c2f8e3a1a40"
}