The sections below show the MWS resources and the HTTP methods defined on them. The prefix for these resources depends on how the mws.war file is deployed. A typical prefix would be http://localhost:8080/mws. Using this example, one absolute resource URI would be http://localhost:8080/mws/rest/jobs.

This section only contains documentation for the latest API version. Please see the table in the Requesting Specific API Versions section for links to documentation for previous versions.

4.1 Access Control Lists

This section describes behavior of the ACL Rules (Access Control List Rules) object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The ACL API contains the type and description of all fields in the ACL Rules object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

ACLs are not directly manipulated through a single URL, but with sub-URLs of the other objects such as Virtual Containers and Reservations.

Resource	GET	PUT	POST	DELETE
/rest/reservations/rsvId/acl-rules/aclId		Create or Update ACLs		Delete ACL
/rest/vcs/vcId/acl-rules/aclId		Create or Update ACLs		Delete ACL

4.1.1 Getting ACLs

Although ACL Rules cannot be retrieved directly using the GET method on any of the acl-rules resources, ACL Rules are attached to supported objects when querying for them. Each supported object contains a field named aclRules, which is a collection of the ACL Rules defined on that object.

Supported Objects

The following is a list of objects that will return ACL Rules when queried:

4.1.2 Creating or Updating ACLs

The HTTP PUT method is used to create or update ACL Rules. The request body can contain one or more ACL Rules. If an ACL Rule with the same type and value exists, then it will be overwritten.

Quick Reference

PUT http://localhost/mws/rest/reservations/<rsvId>/acl-rules
PUT http://localhost/mws/rest/vcs/<vcId>/acl-rules

4.1.2.1 Create or Update ACL

URLs and Parameters

PUT http://localhost/mws/rest/reservations/<objectId>/acl-rules
PUT http://localhost/mws/rest/vcs/<objectId>/acl-rules

Parameter	Required	Type	Valid Values	Description
objectId	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available for the PUT method, along with some sample values.

JSON Request Body

{"aclRules": [{
  "affinity": "POSITIVE",
  "comparator": "LEXIGRAPHIC_EQUAL",
  "type": "USER",
  "value": "ted"
}]}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["Virtual container 'vc1' successfully modified"]}

Samples

Create or update multiple ACLs on a single object:

PUT http://localhost/mws/rest/reservations/system.21/acl-rules

{"aclRules": [
    {
    "affinity": "POSITIVE",
    "comparator": "LESS_THAN_OR_EQUAL",
    "type": "DURATION",
    "value": "3600"
  },
    {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "ted"
  }
]}

Restrictions

ACL Rules cannot be added to or updated on Standing Reservations.
The affinity and comparator fields are ignored for Virtual Containers.

4.1.3 Deleting ACLs

The HTTP DELETE method is used to remove ACL Rules.

Quick Reference

ACL Rules cannot be removed from Standing Reservations.

DELETE http://localhost/mws/rest/reservations/<rsvId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<vcId>/acl-rules/<aclId>

4.1.3.1 Delete ACL

URLs and Parameters

DELETE http://localhost/mws/rest/reservations/<objectId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<objectId>/acl-rules/<aclId>

Parameter	Required	Type	Valid Values	Description
objectId	Yes	String	-	The unique identifier of the object from which to remove the ACL Rule.
aclId	Yes	String	-	A string representing the ACL Rule, with the format `type:value`.

See Global URL Parameters for available URL parameters.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["Successfully modified virtual container 'vc1'"]}

Restrictions

ACL Rules cannot be removed from Standing Reservations.

4.2 Accounts

This section describes behavior of the Accounts object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

This resource refers to Moab Accounting Manager accounts, not Moab Workload Manager accounts.

The Account API contains the type and description of fields that all Accounts have in common.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/accounts	Get all accounts
/rest/accounts/id	Get specified account

4.2.1 Getting Accounts

The HTTP GET method is used to retrieve Accounts information.

Quick Reference

GET http://localhost/mws/rest/accounts

4.2.1.1 Get All Accounts

URLs and Parameters

GET http://localhost/mws/rest/accounts?proxy-user=<USER>[&custom-fields=Department][&query={"deleted":false}][&sort={"requestId":-1}]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
custom-fields	No	Comma-Separated String	Includes custom MAM account attributes.	custom-fields=Department
query	No	JSON	Query for specific results.	query={"deleted":false}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"requestId":-1}

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/accounts?proxy-user=amy&fields=name,description

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
        {
      "id": "biology",
      "description": "Biology Dept."
    },
        {
      "id": "chemistry",
      "description": "Chemistry Dept."
    }
  ]
}

4.2.1.2 Get Single Account

URLs and Parameters

GET http://localhost/mws/rest/accounts/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Responses

GET http://localhost/mws/rest/accounts/chemistry?proxy-user=amy

{
  "id": "chemistry",
  "active": true,
  "organization": "",
  "description": "Chemistry Dept",
  "creationTime": "2012-04-11 06:56:11 UTC",
  "modificationTime": "2012-04-11 06:56:11 UTC",
  "deleted": false,
  "requestId": 94,
  "transactionId": 283,
  "users":   [
        {
      "id": "amy",
      "active": true,
      "admin": false
    },
        {
      "id": "bob",
      "active": true,
      "admin": false
    },
            {
      "id": "dave",
      "active": true,
      "admin": false
    }
   ]
}

4.3 Credentials

This section describes behavior of the Credential object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Credential API is new with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2.
See Requesting Specific API Versions for more information.

The Credential API contains the type and description of all fields in the Credential object.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/credentials/accounts	Get all account credentials
/rest/credentials/classes	Get all class credentials
/rest/credentials/groups	Get all group credentials
/rest/credentials/qoses	Get all QoS credentials
/rest/credentials/users	Get all user credentials

4.3.1 Getting Credentials

The HTTP GET method is used to retrieve Resource Type information.

Quick Reference

GET http://localhost/mws/rest/credentials/accounts
GET http://localhost/mws/rest/credentials/classes
GET http://localhost/mws/rest/credentials/groups
GET http://localhost/mws/rest/credentials/qoses
GET http://localhost/mws/rest/credentials/users

4.3.1.1 Get All Account Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/accounts

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/credentials/accounts?fields=name

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "account1"}
  ]
}

4.3.1.2 Get All Class Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/classes

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/credentials/classes?fields=name

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "class1"}
  ]
}

4.3.1.3 Get All Group Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/groups

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/credentials/groups?fields=name

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "group1"}
  ]
}

4.3.1.4 Get All QoS Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/qoses

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/credentials/qoses?fields=name

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "qos1"}
  ]
}

4.3.1.5 Get All User Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/users

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/credentials/users?fields=name

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "user1"}
  ]
}

4.4 Diagnostics

This section describes additional REST calls that are available for performing diagnostics on Moab Web Services.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/diag/about	Get version information
/rest/diag/auth	Diagnose authentication
/rest/diag/health/summary	Get health information summary
/rest/diag/health/detail	Get health information detail
/rest/diag/ldap	Get LDAP connection information

4.4.1 Version and Build Information

The HTTP GET method is used to retrieve version and build information.

Quick Reference

GET http://localhost/mws/rest/diag/about

URLs and Parameters

GET http://localhost/mws/rest/diag/about

Sample Response

The response contains the application version, build number, build date, and revision.

{
  "suite":"Cloud",
  "pluginCommonsVersion":"0.9.3",
  "version":"7.1",
  "build":"100",
  "buildDate":"2012-01-01_16-00-00",
  "revision":"1000"
}

4.4.2 Diagnose Authentication

The HTTP GET method is used to test for proper authentication. This resource is designed to be used as a simple validation of credentials and gives no output besides the response code.

Quick Reference

GET http://localhost/mws/rest/diag/auth

URLs and Parameters

GET http://localhost/mws/rest/diag/auth

Sample Response

A successful result is indicated by the 200 response code while a failure is indicated by a 401 response code.

{}

4.4.3 Connection Health Information

The HTTP GET method is used to retrieve health or status information for connections to external systems or software. There are two available resources for health, one that returns simple summary information and another that returns detailed information.

Quick Reference

GET http://localhost/mws/rest/diag/health
GET http://localhost/mws/rest/diag/health/detail

4.4.3.1 Get Health Summary

URLs and Parameters

GET http://localhost/mws/rest/diag/health/summary

If the MongoDB connection is down, authenticated resources are not available. While this resource does not possess much detail beyond that of simple connection information, it is still useful as it does not require authentication and therefore can be used to determine connection problems with MongoDB.

Sample Response

The response contains the connection health for Moab Workload Manager (MWM), Moab Accounting Manager (MAM), and MongoDB. A true response value indicates that the connection is healthy and available, and a false response indicates that the connection is currently down. Likewise, the mongoConnected property for MWM signifies the state of the MWM to MongoDB connection. The possible values of this state are UP, DOWN, NOT_CONFIGURED when the MongoDB server is not configured in MWM, NOT_SUPPORTED when MWM is not compiled with MongoDB support, and UNKNOWN when MWS cannot communicate with MWM.

{
  "mam": {
    "connected": true
  },
  "mongo": {
    "connected": false
  },
  "mwm": {
    "connected": true,
    "mongoConnected": "UP"
  }
}

4.4.3.2 Get Health Detail

URLs and Parameters

GET http://localhost/mws/rest/diag/health/detail

If the MongoDB connection is down, authenticated resources such as this are not available. In this case, using the Get Health Summary instead may be required.

Sample Response

The response contains the connection health and information for Moab Workload Manager (MWM), Moab Accounting Manager (MAM), and MongoDB. A "connected": true response value indicates that the connection is healthy and available, and a false response indicates that the connection is currently down. Likewise, the mongoConnected property for MWM signifies the state of the MWM to MongoDB connection. The possible values of this state are UP, DOWN, NOT_CONFIGURED when the MongoDB server is not configured in MWM, NOT_SUPPORTED when MWM is not compiled with MongoDB support, and UNKNOWN when MWS cannot communicate with MWM. A message is also present for all down connections except MWM to MongoDB giving a reason for the error state.

{
  "mam": {
    "connected": false,
    "host": "localhost",
    "message": "There was an error connecting to MAM at 'localhost', the secret key does not match.",
    "port": 7112,
    "version": null
  },
  "mongo": {
    "connected": true,
    "databaseName": "mws",
    "host": "127.0.0.1",
    "message": null,
    "port": 27017,
    "replicaSet": null,
    "username": "mws",
    "version":"2.0.1"
  },
  "mwm": {
    "connected": true,
    "host": "localhost",
    "message": null,
    "port": 42559,
    "licensedFeatures": ["vm", "provision"],
    "state":"RUNNING",
    "mongoConnected": "DOWN",
    "mongoCredentialsSet":false,
    "mongoHost":"localhost",
    "mongoPort":27017,
    "version": "7.2"
  }
}

4.4.4 LDAP Information

The HTTP GET method is used to retrieve LDAP information.

Quick Reference

GET http://localhost/mws/rest/diag/ldap

URLs and Parameters

GET http://localhost/mws/rest/diag/ldap

Sample Response

{
  "server": "openldapsambaserver",
  "port": 389,
  "securityType": "SSL",
  "baseDNs": ["dc=testldap,dc=ac"],
  "bindUser": "cn=admin,dc=testldap,dc=ac",
  "userObjectClass": "posixAccount",
  "userNameAttribute": "uid"
}

4.5 Events

This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services for handling events

The Event API contains the type and description of all fields in the Event object. It also contains details regarding which fields are valid during POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/events	Get all events		Create event
/rest/events/id	Get specified event

Configuration

Logging events to a flat file requires that you make a few changes to the configuration in the log4j section of the mws-config.groovy file so that events will be logged to the events.log file, and all other Moab Web Services logging information will be sent to the mws.log file.

Causing events.log to Roll Based on a Time Window

You can specify how often the events.log file rolls. The following example illustrates the configuration changes you will need make to mws-config.groovy to cause the events.log file to roll based on a time window. (In this example, mws-config.groovy is configured so that events.log rolls daily at midnight.)

Daily rolling events.log configuration in mws-config.groovy

log4j = {
  def eventAppender = new org.apache.log4j.rolling.RollingFileAppender(name: 'events', layout: pattern(conversionPattern: "%m%n"))
  def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd}', activeFileName: '/tmp/events.log')
  rollingPolicy.activateOptions()
  eventAppender.setRollingPolicy(rollingPolicy)  appenders {
      appender eventAppender
      rollingFile name: 'rootLog',
        file: '/tmp/mws.log',
        maxFileSize: '1GB'
  }
  root {
    warn 'rootLog'
  }
  trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter'
}

Note the RollingFileAppender and the TimeBasedRollingPolicy lines. These lines configure Moab Web Services to write the event log to the events.log file.

Rolled log files will have a date appended to their name in this format: 'yyyy-MM-dd' (for example, events.log.2012-02-28).

If you want the event log file to roll at the beginning of each month, change the TimeBasedRollingPolicy "fileNamePattern" date format to 'yyyy-MM'. For example:

Monthly event logs

def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM}', activeFileName: '/tmp/events.log')

If you want the event log file to roll at the beginning of each hour, change the date format to 'yyyy-MM-dd_HH:00'. For example:

Hourly event logs

def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd_HH:00}', activeFileName: '/tmp/events.log')

Configuring events.log to Roll Based on File Size Threshold

You can also configure the events.log file to roll when the log size exceeds a specified threshold. The following example illustrates the configuration changes you will need to make to mws-config.groovy to cause the events.log file to roll on a size threshold. (In this example, mws-config.groovy is configured so that events.log rolls when its size exceeds 50 MB.)

mws-config.groovy configuration that rolls events.log based on file size

log4j = { appenders { rollingFile name: 'events', file: '/tmp/events.log', maxFileSize: '50MB', maxBackupIndex:10

rollingFile name: 'rootLog', file: '/tmp/mws.log', maxFileSize: '1GB' }

root { warn 'rootLog' }

trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter' }

Note that maxFileSize is set to '50MB'. This means that when the events.log file exceeds 50 MB, it will roll.

The name for the rolled log will be "events.log.1". When the new events.log file exceeds 50 MB, it will roll and be named "events.log.1", while the old "events.log.1" file will be renamed "events.log.2". This process will continue until the optional maxBackupIndex value is met. In the example above, maxBackIndex is set to 10. This means that Moab Web Services will delete all but the ten most recent events.log files. Using this feature helps prevent hard drives from filling up.

Additivity

The additivity attribute of the EventFlatFileWriter logger can be either "true" or "false". If you specify "true", events will be logged to the events.log file and the mws.log file. If you specify "false", events will be logged to the events.log file only. (All other Moab Web Services logging information will be logged to the mws.log file, as configured by the rootLog appender.)

To log events to the mws.log file in addition to the events.log file, make this configuration: additivity:true. For example:

Logging events to both events.log and mws.log

trace additivity:true, events:'com.ace.mws.events.EventFlatFileWriter'

For more configuration options, see Apache Extras Companion for log4j.

Deleting Old Events

By default, MWS will hold event data in MongoDB indefinitely. However, if disk space is limited, you may want to regularly delete old, unneeded events from MongoDB. This section contains some examples of how you can do this.

Let's say that you want to delete events that are older than 90 days. You could run this script. (There are 86,400,000 milliseconds in a day, so in this example, 90*86400000 corresponds to 90 days in milliseconds.)

Delete events older than 90 days

$ mongo
MongoDB shell version: 2.0.1
connecting to: test
> use mws
> db.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})
> exit

To create a script to perform this task:

deleteOldEvents.sh

#!/bin/bash
printf 'use mws_dev\ndb.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})\nexit' | mongo

Now say that you want to set up a cron job ($crontab -e) so that old events are automatically deleted on a certain day of the week (for example, every Sunday at 2:00 a.m.), you would add an entry like this:

cron table entry to delete old events

00 02 * * 0 /root/deleteOldEvents.sh

4.5.1 Getting Events

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

Quick Reference

GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/events/<id>

4.5.1.1 Get All Events

URLs and Parameters

GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Query for specific results.	query={"status":"failure"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"id":-1}

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost:8080/mws/rest/events

{ "totalCount":3, "resultCount":3, "results":[ { "details":{

}, "errorMessage":{ "errorCode":"542", "message":"Cannot communicate with XCAT resource manager", "originator":"XCAT" }, "eventCategory":"failure", "eventTime":"2012-01-27 15:18:32 UTC", "eventType":"rmfailure", "facility":"rm", "primaryObject":{ "serialization":null, "type":"rm", "id":"xcat" }, "sourceComponent":"MWM", "status":"failure", "id":"4faddab8c4aa264506f8ac3d" }, { "details":{

}, "eventCategory":"start", "eventTime":"2012-01-27 15:18:31 UTC", "eventType":"schedcyclestart", "facility":"scheduler", "sourceComponent":"MWM", "status":"success", "id":"4faddab8c4aa264506f8ac3c" }, { "details":{ "alpha":"lorem ipsum dolor sit amet", "bravo":"2", "charlie":"consectetur adipisicing elit, sed do" }, "eventCategory":"start", "eventTime":"2012-01-27 15:18:30 UTC", "eventType":"jobstart", "facility":"job", "initiatedBy":{ "proxyUser":"bob", "user":"tomcat6" }, "primaryObject":{ "serialization":"\n <job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />\n ", "type":"job", "id":"moab.849" }, "relatedObjects":[ { "type":"vm", "id":"vm56" }, { "type":"service", "id":"lamp.211" } ], "sourceComponent":"MWM", "status":"success", "id":"4faddab8c4aa264506f8ac3b" } ] }

Querying Events

It is possible to query events by one or more fields based on MongoDB query syntax. The following contains examples of simple and complex event queries and event queries by date.

Simple Queries

To see only events that are of type "jobsubmit":

http://localhost/mws/rest/events?query={"eventType":"jobsubmit"}

To see only events of type "jobsubmit" with the status of "failure":

http://localhost/mws/rest/events?query={"eventType":"jobsubmit","status":"failure"}

To see only events with the "job" facility:

http://localhost/mws/rest/events?query={"facility":"job"}

To see only events in the "start" event category:

http://localhost/mws/rest/events?query={"eventCategory":"start"}

More Complex Queries

You can query on embedded JSON objects within the event JSON. For example, to see events associated with proxyUser bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob"}

To see only events that are NOT associated with bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$ne":"bob"}}

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

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$in":["alice","bob","charlie"]}}

Querying Events by Date

To see events created before January 27, 2012 at 12:08 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$lt":"2012-01-27 12:08:00 UTC"}}

To see events created before or on January 27, 2012 at 12:08 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$lte":"2012-01-27 12:08:00 UTC"}}

To see all events created after January 27, 2012 at 12:04 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$gt":"2012-01-27 12:04:00 UTC"}}

To see all events created after or on January 27, 2012 at 12:04 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive:

http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive that are associated with proxyUser bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive, that are associated with proxyUser bob, and that are of type "jobsubmit":

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventType":"jobsubmit","eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

Sorting

See the sorting section of Global URL Parameters

Limiting the Number of Results

If you want to limit the number of results of events, you can use the max parameter. For example, to see only 10 "vmmigrate" events:

http://localhost/mws/rest/events?query={"eventType":"vmmigrate"}&sort={"eventTime":1}&max=10

To see "vmcreate" events 51-60 when sorted by eventTime in descending order, you can combine max with offset, as follows:

http://localhost/mws/rest/events?query={"eventType":"vmcreate"}&sort={"eventTime":-1}&max=51&offset=60

Retrieving a Subset of Fields

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

http://localhost/mws/rest/events?max=3&fields=eventTime

This returns:

{
  "totalCount": 187,
  "resultCount": 3,
  "results":   [
    {"eventTime": "2012-03-05 10:01:59 UTC"},
    {"eventTime": "2012-03-05 10:02:00 UTC"},
    {"eventTime": "2012-03-05 10:02:01 UTC"}
  ]
}

To show the name, type, and status:

http://localhost/mws/rest/events?fields=name,type,status

This returns:

{
  "totalCount": 187,
  "resultCount": 3,
  "results":   [
        {
      "eventTime": "2012-03-05 10:01:59 UTC",
      "eventType": "jobsubmit",
      "status": "failure"
    },
        {
      "eventTime": "2012-03-05 10:02:00 UTC",
      "eventType": "jobstart",
      "status": "success"
    },
        {
      "eventTime": "2012-03-05 10:02:01 UTC",
      "eventType": "vmmigrate",
      "status": "success"
    }
  ]
}

4.5.1.2 Get Single Event

URLs and Parameters

GET http://localhost/mws/rest/events/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "details":   {
    "attribute": "walltime",
    "modifier": "increase",
    "value": "200000"
  },
  "eventCategory": "job",
  "eventTime": "2012-01-27 00:07:00 UTC",
  "eventType": "jobmodify",
  "facility": "baseline",
  "initiatedBy":   {
    "proxyUser": "bob",
    "user": "viewpoint"
  },
  "primaryObject":   {
    "serialization": null,
    "type": "job",
    "id": "moab.900"
  },
  "sourceComponent": "MWM",
  "status": "success",
  "id": "4fa46081c4aa5b896ac4b757"
}

4.5.2 Creating Events

The HTTP POST method is used to create an Event.

Quick Reference

POST http://localhost/mws/rest/events

4.5.2.1 Create Event

URLs and Parameters

POST http://localhost/mws/rest/events

Request Body

Unlike most other URLs, the events URL accepts both JSON and XML. Be sure to set the Content-Type HTTP header to either application/json or application/xml.

POST http://localhost/mws/rest/events Content-Type:application/json

[
   {
      "eventTime":"2012-01-27 15:18:30 UTC",
      "eventType":"jobstart",
      "eventCategory":"start",
      "sourceComponent":"MWM",
      "status":"success",
      "facility":"job",
      "initiatedBy":{
         "proxyUser":"bob",
         "user":"tomcat6"
      },
      "primaryObject":{
         "serialization":"<job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />",
         "type":"job",
         "id":"moab.849"
      },
      "relatedObjects":[
         {
            "type":"vm",
            "id":"vm56"
         },
         {
            "type":"service",
            "id":"lamp.211"
         }
      ],
      "details":{
         "alpha":"lorem ipsum dolor sit amet",
         "bravo":"2",
         "charlie":"consectetur adipisicing elit, sed do"
      }
   },
   {
      "eventTime":"2012-01-27 15:18:32 UTC",
      "eventType":"rmfailure",
      "eventCategory":"failure",
      "sourceComponent":"MWM",
      "status":"failure",
      "facility":"rm",
      "primaryObject":{
         "serialization":null,
         "type":"rm",
         "id":"xcat"
      },
      "errorMessage":{
         "errorCode":"542",
         "message":"Cannot communicate with XCAT resource manager",
         "originator":"XCAT"
      }
   },
   {
      "eventTime":"2012-01-27 15:18:31 UTC",
      "eventType":"schedcyclestart",
      "eventCategory":"start",
      "sourceComponent":"MWM",
      "status":"success",
      "facility":"scheduler"
   }
]

POST http://localhost/mws/rest/events Content-Type:application/xml

<Events>  <Event eventTime="2012-01-27T15:18:30.000-07:00" eventType="jobstart" eventCategory="start" sourceComponent="MWM" status="success" facility="job">
    <InitiatedBy user="tomcat6" proxyUser="bob"/>     
    <PrimaryObject objectType="job" objectID="moab.849">
      <Serialization>
         <![CDATA[<job JobID="moab.849" ReqAWDuration="100000" User="bob" />]]>
      </Serialization>  
    </PrimaryObject> 
    <RelatedObjects>
      <RelatedObject objectType="vm" objectID="vm56"/>
      <RelatedObject objectType="service" objectID="lamp.211"/>
    </RelatedObjects>
    <Details>
    	<Detail name="alpha">lorem ipsum dolor sit amet</Detail>
    	<Detail name="bravo">2</Detail>
    	<Detail name="charlie">consectetur adipisicing elit, sed do</Detail>    		
    </Details>
  </Event>
  <Event eventTime="2012-01-27T15:18:31.000-07:00" eventType="schedcyclestart" eventCategory="start" sourceComponent="MWM" status="success" facility="scheduler" />
  <Event eventTime="2012-01-27T15:18:32.000-07:00" eventType="rmfailure" eventCategory="failure" sourceComponent="MWM" status="failure" facility="rm">
    <PrimaryObject objectType="rm" objectID="xcat" />
    <ErrorMessage originator="XCAT" errorCode="542">Cannot communicate with XCAT resource manager</ErrorMessage> 
  </Event>
</Events>

Sample Response

If the request was successful, the response will be an object with an id property containing the ID of the newly created events. On failure, the response is an error message.

JSON Response

[{"id":"4fadd83bc4aa366464599e1a"},{"id":"4fadd83bc4aa366464599e1b"},{"id":"4fadd83bc4aa366464599e1c"}]

Below is an example of events.log output for a successful event request:

2012-01-27T15:18:30.000-07:00 type="jobstart" category="start" sourceComponent="MWM" status="success" facility="job" initiatedBy.user="tomcat6" initiatedBy.proxyUser="bob" primaryObject.type="job" primaryObject.id="moab.849" relatedObject.0.type="service" relatedObject.0.id="lamp.211" relatedObject.1.type="vm" relatedObject.1.id="vm56" detail.alpha="lorem ipsum dolor sit amet" detail.bravo="2" detail.charlie="consectetur adipisicing elit, sed do" primaryObject.serialization="<job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />"
2012-01-27T15:18:31.000-07:00 type="schedcyclestart" category="start" sourceComponent="MWM" status="success" facility="scheduler"
2012-01-27T15:18:32.000-07:00 type="rmfailure" category="failure" sourceComponent="MWM" status="failure" facility="rm" primaryObject.type="rm" primaryObject.id="xcat" error.originator="XCAT" error.code="542" error.message="Cannot communicate with XCAT resource manager"

Note that " (double quote) characters in the input have been replaced by \" characters in the output. (For other character restrictions, see the "Restrictions" section below.)

Restrictions

Special characters, such as newline, carriage return, and " (double quote) are encoded in the output of events.log to make events.log easy to parse with scripts and third party tools. For example, if the input XML contains:

<ErrorMessage>RM says, "Cannot provision vm21"</ErrorMessage>

Then the following will be output to events.log:

error.message="RM says, \"Cannot provision vm21\""

Notice that " has been replaced with \". This table contains the most common encodings.

Character	Escape Sequence
" (double quote)	\"
\ (backslash)	\\
newline	\n
carriage return	\r
tab	\t

(For more information see escape sequences for Java Strings.)

Other restrictions include:

Detail names can only contain alpha-numeric characters, colons (:), underscores (_), and dashes (-).
primaryObject.serialization, error.message, and detail values (for example detail.someName="some value") can contain any printable ASCII character. Single quotes (') and double quotes (") cannot be contained in any other field.
A single event cannot contain more than more than 50 details. If an event has more than 50 details, the excess details will be ignored.

4.6 Funds

This section describes behavior of the Fund object and all related objects in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Fund API, FundBalance API, FundStatement API, and FundStatementSummary API contain the type and description of all fields in the Fund object as well as related objects and reports given in the URLs below.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/funds	Get all funds
/rest/funds/id	Get specified fund
/rest/funds/balances	Get all fund balances
/rest/funds/reports/statement	Get fund statement
/rest/funds/reports/statement/summary	Get fund statement summary

4.6.1 Getting Funds

The HTTP GET method is used to retrieve Fund information.

Quick Reference

GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}]
GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]
GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]
GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>]
GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]

4.6.1.1 Get All Funds

URLs and Parameters

GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
active	No	Boolean	Lists only active or non-active allocations of the fund. The fund amount becomes the sum of the active/inactive allocations.	active=true
custom-fields	No	Comma-Separated String	Includes custom MAM fund attributes.	custom-fields=health
filter	No	JSON	Query funds based on defined MAM filter.	filter={"account":"chemistry"}
filter-type	No	String	Query funds based on defined MAM filter type.	filter-type=NonExclusive
query	No	JSON	Query for specific results.	query={"priority":"2","allocation.active":"false"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"id":-1}

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/funds?proxy-user=amy&fields=id,name,allocations,constraints

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": 2,
    "name": 1204,
    "allocations": [    {
      "id": 2,
      "startTime": "-infinity",
      "endTime": "2012-02-02 09:34:42 UTC",
      "amount": 9060000,
      "creditLimit": 0,
      "deposited": 9060000,
      "active": true,
      "description": ""
    }],
    "fundConstraints": [    {
      "id": 2,
      "name": "CostCenter",
      "value": 1204
    }]
  }]
}

4.6.1.2 Get Single Fund

URLs and Parameters

GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
active	No	Boolean	Lists only active or non-active allocations of the fund. The fund amount becomes the sum of the active/inactive allocations.	active=true
custom-fields	No	Comma-Separated String	Includes custom MAM fund attributes.	custom-fields=health
filter	No	JSON	Query funds based on defined MAM filter.	filter={"account":"chemistry"}
filter-type	No	String	Query funds based on defined MAM filter type.	filter-type=NonExclusive

See Global URL Parameters for available URL parameters.

Sample Responses

Fund sample response

{
  "id": 2,
  "name": 1204,
  "priority": 0,
  "description": "R&D for Manufacturing",
  "creationTime": "2012-02-02 09:34:42 UTC",
  "amount": 9060000,
  "deposited": 9060000,
  "creditLimit": 0,
  "allocations": [  {
    "id": 2,
    "startTime": "-infinity",
    "endTime": "infinity",
    "amount": 9060000,
    "creditLimit": 0,
    "deposited": 9060000,
    "active": true,
    "description": ""
  }],
  "fundConstraints": [  {
    "id": 2,
    "name": "CostCenter",
    "value": 1204
  }]
}

4.6.1.3 Get All Fund Balances

URLs and Parameters

GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
custom-fields	No	Comma-Separated String	Includes custom MAM fund attributes.	custom-fields=health
filter	No	JSON	Query funds based on defined MAM filter.	filter={"account":"chemistry"}
filter-type	No	String	Query funds based on defined MAM filter type.	filter-type=NonExclusive

See Global URL Parameters for available URL parameters.

Sample Response

The fund balances resource is an aggregation of fund data. See the FundBalance API page for more details.

GET http://localhost/mws/rest/funds/balances?proxy-user=amy

{
  "totalCount": 2,
  "resultCount": 2,
  "results": [
    {
      "id": 2,
      "name": 1204,
      "priority": 0,
      "description": "R&D for Manufacturing",
      "creationTime": "2012-02-02 09:34:42 UTC",
      "amount": 9060000,
      "deposited": 9060000,
      "creditLimit": 0,
      "reserved": 0,
      "allocations": [
        {
          "id": 2,
          "amount": 9060000,
          "creditLimit": 0,
          "deposited": 9060000
        }
      ],
      "fundConstraints": [
        {
          "id": 2,
          "name": "CostCenter",
          "value": 1204
        }
      ],
      "balance": 9060000,
      "available": 9060000,
      "allocated": 9060000,
      "used": 0,
      "percentRemaining": 100,
      "percentUsed": 0
    },
    {
      "id": 5,
      "name": "",
      "priority": 0,
      "description": "",
      "creationTime": "2012-04-03 09:25:47 UTC",
      "amount": 901290219001,
      "deposited": 901290219021,
      "creditLimit": 30,
      "reserved": 84018308897.68,
      "allocations": [
        {
          "id": 6,
          "amount": 901290219001,
          "creditLimit": 30,
          "deposited": 901290219021
        }
      ],
      "fundConstraints": [],
      "balance": 817271910103.32,
      "available": 817271910133.32,
      "allocated": 901290219051,
      "used": 20,
      "percentRemaining": 100,
      "percentUsed": 0
    }
  ]
}

4.6.1.4 Get Fund Statement

URLs and Parameters

GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
filter	No	JSON	Query funds based on defined MAM filter.	filter={"account":"chemistry"}
filter-type	No	String	Query funds based on defined MAM filter type.	filter-type=NonExclusive
start-time	No	Date, -infinity, or now	Filter allocations and transaction after a start time.	start-time=2012-04-03 15:24:39 UTC
end-time	No	Date, -infinity, or now	Filter allocations and transactions before an end time.	end-time=2012-04-03 15:24:39 UTC
context	No	hpc or cloud	The context to use in Moab Accounting Manager.	context=hpc

The context parameter overrides the default context set for MAM using the mam.context configuration parameter. See the Configuration page for more information on this parameter.

See Global URL Parameters for available URL parameters.

Sample Response

The fund statement report provides a snapshot of the current funds. See the FundStatement API for more details.

GET http://localhost/mws/rest/funds/reports/statement?proxy-user=amy&fields=startBalance,endBalance

{
  "startBalance":1234.01,
  "endBalance":1000
}

4.6.1.5 Get Fund Statement Summary

URLs and Parameters

GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
filter	No	JSON	Query funds based on defined MAM filter.	filter={"account":"chemistry"}
filter-type	No	String	Query funds based on defined MAM filter type.	filter-type=NonExclusive
start-time	No	Date, -infinity, or now	Filter allocations and transaction after a start time.	start-time=2012-04-03 15:24:39 UTC
end-time	No	Date, -infinity, or now	Filter allocations and transactions before an end time.	end-time=2012-04-03 15:24:39 UTC

See Global URL Parameters for available URL parameters.

Sample Response

The fund statement summary is slightly different from the typical fund statement in that the transactions are provided as summaries grouped by object and action. See the FundStatementSummary API for more details.

GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=amy&fields=totalCredits,totalDebits,transactions.action,transactions.amount,transactions.count

{
  "totalCredits":200.02,
  "totalDebits":-100,
  "transactions":[ {
      "action":"Deposit",
      "amount":200.02,
      "count":2
    }, {
      "action":"Charge",
      "amount":-100,
      "count":1
    }
  ]
}

4.7 Images

This section describes behavior of the Image resource in Moab Web Services. An image resource is used to track the different types of operating systems and hypervisors available in the data center. It also tracks which virtual machines are available on the hypervisors. This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Image API contains the type and description of all fields in the Image object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/images	Get All Images		Create Image
/rest/images/id	Get Specified Image	Modify Image		Delete Image
/rest/images/name	Get Specified Image	Modify Image		Delete Image

4.7.1 Getting Images

The HTTP GET method is used to retrieve Image information. You can query all objects or a single object.

Quick Reference

GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>

4.7.1.1 Get All Images

URLs and Parameters

GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"stateful","osType":"linux"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/images?fields=id,name

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "centos5-stateful"
  }]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.7.1.2 Get Single Image

URLs and Parameters

GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

Virtual machine image example:

GET http://localhost/mws/rest/images/centos5-compute-stateful

{
  "active":true,
  "extensions":{
    "xcat":{
      "os":"centos",
      "architecture":"x86_64",
      "profile":"compute"
    }
  },
  "features":[],
  "hypervisor":false,
  "hypervisorType": null,
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos5-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":false,
  "supportsVirtualMachine":true,
  "templateName":"",
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

Hypervisor image example:

GET http://localhost/mws/rest/images/esxi-4.1-stateful

{
  "active":true,
  "extensions":{
    "xcat":{
      "hvGroupName":"hvGroup",
      "vmGroupName":"vmGroup",
      "os":"esxi-4.1",
      "architecture":"x86_64",
      "profile":"hv"
    }
  },
  "features":[],
  "hypervisor":true,
  "hypervisorType":"ESX",
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos5-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "supportsVirtualMachine":false,
  "templateName":"",
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. See Modify Image for more information.

4.7.2 Creating Images

The HTTP POST method is used to submit Images.

Quick Reference

POST http://localhost/mws/rest/images

4.7.2.1 Create Single Image

URLs and Parameters

POST http://localhost/mws/rest/images

See Global URL Parameters for available URL parameters.

Request Body

Three fields are required to submit an image: name, hypervisor, and osType. Each image must also support provisioning to either a physical machine or a virtual machine by using the supportsPhysicalMachine or supportsVirtualMachine fields.

The name field must contain only letters, digits, periods, dashes, and underscores.

The array of virtualized images are themselves objects that contain image IDs or names. For more information on available fields and types, see the Image API.

The following is an example of the most basic image that can be created:

POST http://localhost/mws/rest/images

{
  "name": "centos5-stateful",
  "osType": "linux",
  "hypervisor": false,
  "supportsVirtualMachine":true
}

Note that this example does not provide any information for a provisioning manager (such as xCAT) to actually provision the machine. In order to provide this, you must add an entry to the extensions field that contains provisioning manager-specific information. Each key in the extensions field corresponds to the provisioning manager, and certain properties are required based on this key. For example, the xCAT extension key must be named xcat and must contain certain fields. These extension keys are documented in the Image API. See the following examples of creating images with xCAT-specific provisioning information below.

Sample Response

If the request was successful, the response body is the new image that was created exactly as shown in Get Single Image. On failure, the response is an error message.

Samples

The virtualizedImages field only accepts input when the image is a hypervisor and expects an array of image IDs or names, as shown in the following example:

Example payload of hypervisor with 2 vms

{
  "hypervisor":true,
  "name":"esx5-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "type":"stateful",
  "hypervisorType":"ESX",
  "virtualizedImages":   [
    {"id": "4fa197e68ca30fc605dd1cf0"},
    {"name": "centos5-stateful"}
  ]
}

The following example shows how to create an image that utilizes a cloned template for a virtual machine. (Note that the type must be set to linkedclone in order to set the templateName field.)

VM Utilizing a Cloned Template

{
  "active": true,
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "linkedclone",
  "supportsVirtualMachine":true,
  "templateName":"centos5-compute"
}

The following are samples of a virtual machine and a hypervisor image that can be provisioned with xCAT:

xCAT Virtual Machine Image

{
  "active": true,
  "features": [],
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "stateful",
  "supportsVirtualMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "centos",
        "architecture": "x86_64",
        "profile": "compute"
     }
  }
}

xCAT Hypervisor Image

{
  "active": true,
  "features": [],
  "hypervisor": true,
  "name": "esxi5-base-stateless",
  "osType": "linux",
  "virtualizedImages":   [
    {"name": "centos5-compute-stateless"}
  ],
  "type": "stateless",
  "hypervisorType": "ESX",
  "supportsPhysicalMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "esxi5",
        "architecture": "x86_64",
        "profile": "base",
        "hvType": "esx",
        "hvGroupName": "esx5hv",
        "vmGroupName": "esx5vm"
     }
  }
}

4.7.3 Modifying Images

The HTTP PUT method is used to modify Images.

Quick Reference

PUT http://localhost/mws/rest/images/<id>
PUT http://localhost/mws/rest/images/<name>

4.7.3.1 Modify Single Image

URLs and Parameters

PUT http://localhost/mws/rest/images/<id>
PUT http://localhost/mws/rest/images/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

The name field must contain only letters, digits, periods, dashes, and underscores.

Example Request

PUT http://locahost/mws/rest/images/centos5-stateful

{
  "name": "centos5-stateful",
  "type": "stateful",
  "hypervisor": false,
  "osType": "linux",
  "virtualizedImages": []
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object in between the time the data was retrieved and the modify request was delivered.

Sample Response

If the request was successful, the response body is the modified image as shown in Get Single Image. On failure, the response is an error message.

4.7.4 Deleting Images

The HTTP DELETE method is used to delete Images.

Quick Reference

DELETE http://localhost/mws/rest/images/<id>
DELETE http://localhost/mws/rest/images/<name>

4.7.4.1 Delete Single Image

URLs and Parameters

DELETE http://localhost/mws/rest/images/<id>
DELETE http://localhost/mws/rest/images/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{}

4.8 Jobs

This section describes behavior of the Job object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Job API has changed with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2 in order to behave as documented.
In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Job API contains the type and description of all fields in the Job object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/jobs	Get all jobs		Submit job
/rest/jobs/name	Get single job	Modify job		Cancel job

4.8.1 Getting Job Information

The HTTP GET method is used to retrieve Job information.

Quick Reference

GET http://localhost/mws/rest/jobs/<name>?api-version=2

4.8.1.1 Get All Jobs

URLs and Parameters

GET http://localhost/mws/rest/jobs?api-version=2

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"isActive":true}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

How to Get All Jobs

GET http://localhost/mws/rest/jobs?api-version=2&fields=name,flags&max=3

{
  "totalCount": 8,
  "resultCount": 3,
  "results":   [
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.1"
    },
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.2"
    },
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.4"
    }
  ]
}

How to Get a Subset of Jobs

Here are a few examples of how to query for jobs.

Get Active Jobs

http://localhost/mws/rest/jobs?api-version=2&query={"isActive":true}

Get Completed Jobs

http://localhost/mws/rest/jobs?api-version=2&query={"isActive":false}

Get Jobs Owned by a Particular User

http://localhost/mws/rest/jobs?api-version=2&query={"credentials.user":"fred"}

Known Issues

Some jobs are not returned if DisplayFlags UseBlocking is set in the moab.cfg file.

4.8.1.2 Get Single Job

URLs and Parameters

GET http://localhost/mws/rest/jobs/<name>?api-version=2

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "arrayIndex": null,
  "arrayMasterName": null,
  "attributes": [],
  "blocks": [  {
    "category": "jobBlock",
    "message": null,
    "type": null
  }],
  "bypassCount": 0,
  "cancelCount": 0,
  "commandFile": "/tmp/test.sh",
  "commandLineArgs": null,
  "completionCode": null,
  "cpuTime": 0,
  "credentials":   {
    "account": null,
    "group": "adaptive",
    "jobClass": null,
    "qos": "NONE",
    "qosRequested": null,
    "user": "adaptive"
  },
  "customName": null,
  "dates":   {
    "completedDate": null,
    "createdDate": "2012-10-11 17:58:16 UTC",
    "deadlineDate": "2037-10-24 12:26:40 UTC",
    "dispatchedDate": null,
    "earliestRequestedStartDate": null,
    "earliestStartDate": "2012-10-11 17:58:18 UTC",
    "eligibleDate": "2012-10-11 17:59:19 UTC",
    "lastCanceledDate": null,
    "lastChargedDate": null,
    "lastPreemptedDate": null,
    "lastUpdatedDate": "2012-10-11 17:59:19 UTC",
    "startDate": null,
    "submitDate": "2012-10-11 17:58:16 UTC",
    "terminationDate": "2037-10-24 12:26:40 UTC"
  },
  "deferCount": 0,
  "dependencies": [],
  "description": null,
  "duration": 8639999,
  "durationActive": 0,
  "durationQueued": 31,
  "durationRemaining": 0,
  "durationSuspended": 0,
  "emailNotifyAddresses": [],
  "emailNotifyTypes": [],
  "environmentRequested": false,
  "environmentVariables": {},
  "epilogScript": null,
  "flags": ["GLOBALQUEUE"],
  "holdDate": null,
  "holdReason": null,
  "holds": [],
  "initialWorkingDirectory": "/tmp",
  "isActive": true,
  "jobGroup": null,
  "masterNode": null,
  "memorySecondsDedicated": 0,
  "memorySecondsUtilized": 0,
  "messages": [],
  "migrateCount": 0,
  "minimumPreemptTime": 0,
  "mwmName": "Moab",
  "name": "Moab.15",
  "nodesExcluded": [],
  "nodesRequested": [],
  "nodesRequestedPolicy": null,
  "partitionAccessList":   [
    "msm",
    "SHARED"
  ],
  "partitionAccessListRequested":   [
    "msm",
    "SHARED"
  ],
  "preemptCount": 0,
  "priorities":   {
    "run": 0,
    "start": 1,
    "system": 0,
    "user": 0
  },
  "processorSecondsDedicated": 0,
  "processorSecondsLimit": 0,
  "processorSecondsUtilized": 0,
  "prologScript": null,
  "queueStatus": "blocked",
  "rejectPolicies": [],
  "requirements": [  {
    "architecture": null,
    "attributes": [],
    "features": [],
    "index": 0,
    "featuresRequested": [],
    "featuresRequestedMode": "AND",
    "featuresExcluded": [],
    "featuresExcludedMode": "AND",
    "metrics": {},
    "nodeAccessPolicy": null,
    "nodeAllocationPolicy": null,
    "nodeCount": 0,
    "nodes": [],
    "nodeSet": null,
    "image": null,
    "reservation": null,
    "resourcesPerTask":     {
      "processors":       {
        "dedicated": 1,
        "utilized": 0
      },
      "memory":       {
        "dedicated": 0,
        "utilized": 0
      },
      "disk":       {
        "dedicated": 0,
        "utilized": null
      },
      "swap":       {
        "dedicated": 0,
        "utilized": null
      }
    },
    "taskCount": 4,
    "tasksPerNode": 0
  }],
  "reservationRequested": null,
  "resourceFailPolicy": null,
  "resourceManagerExtension": null,
  "resourceManagers": [  {
    "isDestination": false,
    "isSource": true,
    "jobName": "Moab.15",
    "name": "internal"
  }],
  "rmStandardErrorFilePath": null,
  "rmStandardOutputFilePath": null,
  "standardErrorFilePath": null,
  "standardOutputFilePath": null,
  "startCount": 0,
  "states":   {
    "state": "Idle",
    "stateExpected": "Idle",
    "stateLastUpdatedDate": null,
    "subState": null
  },
  "submitHost": "0:0:0:0:0:0:0:1",
  "systemJobAction": null,
  "systemJobType": null,
  "targetedJobAction": null,
  "targetedJobName": null,
  "templates": [{"name": "DEFAULT"}],
  "triggers": [],
  "variables": {},
  "virtualContainers": [],
  "virtualMachines": [],
  "vmUsagePolicy": null
}

Job Arrays

If a job is the master of a job array, the response will have some additional fields set as shown in the following example. The name field is chosen by the Moab Workload Manager, and the customName field comes from the job array name field.

Job Array Master

{
  "name": "Moab.5",
  "customName": "myarray",
  "flags":   [
    "ARRAYMASTER",
    "GLOBALQUEUE",
    "CANCELONFIRSTFAILURE",
    "CANCELONANYSUCCESS"
  ]
}

If a job is a sub-job of an array, the response will have other fields set as shown in the following example.

Array Sub-Job

{
  "name": "Moab.5[21]",
  "customName": "myarray",
  "arrayIndex": 21,
  "arrayMasterName": "Moab.5",
  "flags":   [
    "ARRAYJOB",
    "GLOBALQUEUE",
    "CANCELONFIRSTFAILURE",
    "CANCELONANYSUCCESS"
  ]
}

4.8.2 Submitting Jobs

The HTTP POST method is used to submit Jobs.

Quick Reference

POST http://localhost/mws/rest/jobs?api-version=2[&proxy-user=<username>]

Restrictions

MWS must have read access to the file given in commandFile.
No more than one virtual container can be specified in the request. The virtual container must already exist.
The credentials.user and credentials.group properties are used to submit a job as the specified user belonging to the specified group.
Job variables have the following restrictions:

Variable names cannot contain equals (=), semicolon (;), colon (:), plus (+), question mark (?), caret (^), backslash (\), or white space.
Variable values cannot contain semicolon (;), colon (:), plus (+), or caret (^).

When submitting jobs, the only supported hold type is User.
The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.2.1 Submit Job

URLs and Parameters

POST http://localhost/mws/rest/jobs?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

To submit a job, only one field is required: commandFile.

The request body below shows all the fields that are available during job submission. This is a very contrived example; its purpose is simply to show sample values in the correct format.

JSON Request Body (specified host list)

{
  "attributes":   [
    "attr1",
    "attr2"
  ],
  "commandFile": "/tmp/test.sh",
  "commandLineArguments": "-x -v",
  "credentials":   {
    "account": "account",
    "group": "group",
    "jobClass": "BATCH",
    "qosRequested": "QOS1",
    "user": "saadmin"
  },
  "customName": "custom name for job",
  "dates":   {
    "earliestRequestedStartDate": "2012-11-08 13:18:47 UTC",
    "deadlineDate": "2014-02-17 14:00:00 UTC"
  },
  "dependencies":   [
        {
      "type": "set",
      "name": "vc1.varA"
    },
        {
      "type": "set",
      "name": "vc2.varB"
    },
        {
      "type": "set",
      "name": "vc3.varC"
    }
  ],
  "duration": 600,
  "emailNotifyAddresses":   [
    "[email protected]",
    "[email protected]"
  ],
  "emailNotifyTypes":   [
    "JobStart",
    "JobEnd"
  ],
  "environmentRequested": true,
  "environmentVariables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "epilogScript": "/tmp/epilog.sh",
  "flags":   [
    "RESTARTABLE",
    "SUSPENDABLE"
  ],
  "holds": ["User"],
  "initialWorkingDirectory": "/tmp",
  "jobGroup": "job_group",
  "nodesExcluded":   [
    {"name": "node07"},
    {"name": "node08"}
  ],
  "nodesRequested":   [
    {"name": "node01"},
    {"name": "node02"}
  ],
  "nodesRequestedPolicy": "SUBSET",
  "partitionAccessListRequested":   [
    "p1",
    "p2"
  ],
  "priorities": {"user": 5},
  "prologScript": "/tmp/prolog.sh",
  "requirements": [  {
    "architecture": "x86_64",
    "attributes":     [
            {
        "name": "matlab",
        "comparator": "<=",
        "value": "7.1"
      },
            {
        "name": "soffice",
        "comparator": "=",
        "value": "3.1"
      }
    ],
    "featuresRequested":     [
      "a",
      "b",
      "c"
    ],
    "featuresRequestedMode": "OR",
    "featuresExcluded":     [
      "d",
      "e",
      "f"
    ],
    "featuresExcludedMode": "AND",
    "nodeAccessPolicy": "SINGLEJOB",
    "nodeAllocationPolicy": "PRIORITY",
    "nodeCount": 6,
    "image": "linux",
    "resourcesPerTask":     {
      "disk": {"dedicated": 1024},
      "memory": {"dedicated": 512},
      "processors": {"dedicated": 2},
      "swap": {"dedicated": 4096},
      "matlab": {"dedicated": 6},
      "intellij": {"dedicated": 2}
    },
    "taskCount": 4,
    "tasksPerNode": 14
  }],
  "reservationRequested": {"name": "rsv.1"},
  "resourceFailPolicy": "RETRY",
  "resourceManagerExtension": "x=PROC=4",
  "standardErrorFilePath": "/tmp/error",
  "standardOutputFilePath": "/tmp/out",
  "submitHost": "admin-node",
  "templates":   [
    {"name": "template1"},
    {"name": "template2"}
  ],
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "virtualContainers": [{"name": "vc1"}],
  "vmUsagePolicy": "CREATEVM"
}

Sample Response

The response of this task is one of three possibilities:

An object with a single messages property containing a list of error messages on failure

{"messages":["Could not create job - invalid requirements"]}

An object with a name property containing the name of the newly created job

{"name":"Moab.1"}

An object with a name property and a virtualContainers list containing the name of the newly created virtual container

{ "name": "Moab.1", "virtualContainers": [{"name": "vc1"}] }

The virtual container will only be reported when a new virtual container has been created by Moab for the job.

4.8.2.2 Examples of Job Submission

This section includes some sample job submission requests.

Submit job to run on node2 and node3

POST http://localhost/mws/rest/jobs?api-version=2

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/tmp",
  "nodesRequested":   [
    {"name": "node2"},
    {"name": "node3"}
  ]
}

Submit job that requires 20 processors

POST http://localhost/mws/rest/jobs?api-version=2

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"taskCount": 20}]
}

Submit job to run after a certain time

POST http://localhost/mws/rest/jobs?api-version=2

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "dates": {"earliestRequestedStartDate": "2012-10-11 18:36:35 UTC"},
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"taskCount": 20}]
}

Submit job based on `msub` example

Given this msub command:

msub -l nodes=3:ppn=2,walltime=1:00:00,pmem=100 script2.pbs.cmd

Here is an equivalent MWS request:

POST http://localhost/mws/rest/jobs?api-version=2

{
  "duration": 3600,
  "commandFile": "/home/adaptive/script2.pbs.cmd",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/home/adaptive",
  "requirements": [  {
    "resourcesPerTask": {"memory": {"dedicated": 100}},
    "taskCount": 6,
    "tasksPerNode": 2
  }]
}

To emulate what msub does, make commandFile an absolute path, and add credentials.user, credentials.group, and initialWorkingDirectory.

As shown above, nodes=3:ppn=2 is equivalent to setting taskCount to 6 and tasksPerNode to 2.

Submit a Job Array

See the Submitting Job Arrays section for details on how to submit a job array.

4.8.3 Modifying Jobs

The HTTP PUT method is used to modify Jobs.

Quick Reference

PUT http://localhost/mws/rest/jobs/<name>[/<modifyAction>]?api-version=2[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.3.1 Modify Job Attributes

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Job, along with some sample values.

JSON Request Body

{
  "credentials":   {
    "account": "account",
    "jobClass": "BATCH",
    "qosRequested": "QOS1"
  },
  "customName": "custom name for job",
  "dates": {"earliestRequestedStartDate": "2012-11-08 13:18:47 UTC"},
  "duration": 600,
  "flags":   [
    "RESTARTABLE",
    "SUSPENDABLE"
  ],
  "holds": ["User"],
  "messages":   [
    {"message": "Message one"},
    {"message": "Message two"}
  ],
  "partitionAccessListRequested":   [
    "p1",
    "p2"
  ],
  "priorities": {"user": 5},
  "reservationRequested": {"name": "rsv.1"},
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

These messages may not match the messages returned from Moab exactly, but are given as an example of the structure of the response.

Not all messages are shown for the above request body.

JSON Response

{"messages": [
  "Account modified successfully",
  "Messages modified successfully",
  "Variables modified successfully"
]}

Restrictions

Old messages are not removed from jobs; only new messages are added.
Job variables have the restrictions documented in Submitting Jobs

4.8.3.2 Perform Actions on Job

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<name>/<modifyAction>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
modifyAction	Yes	String	cancel	Attempts to cancel the job.
			checkpoint	Attempts to checkpoint the job. Note that the OS must support checkpointing for this to work.
			execute	Executes the job if possible.
			hold	Attempts to hold the job using the holds set in the request body.
			requeue	Attempts to requeue the job.
			resume	Attemps to resume the job.
			suspend	Attempts to suspend the job.
			unhold	Attempts to release the holds set in the request body.
proxy-user	No	String	-	Perform the action as this user.

Performing a cancel function on a job is equivalent to deleting a job.

See Global URL Parameters for available URL parameters.

Request Body

Request bodies are only required for holding or unholding jobs. All other actions do not require request bodies of any kind.

JSON Request Body to Add Holds to a Job

{"holds": ["User"]}

JSON Request Body to Remove Holds from a Job

{"holds": ["User"]}

If no holds are specified when unholding a job, all holds will be removed. This is equivalent to specifying holds as a list with a single element of All.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages": ["Job modified successfully"]}

4.8.4 Deleting (Canceling) Jobs

The HTTP DELETE method is used to cancel Jobs.

Quick Reference

DELETE http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.4.1 Cancel Job

URLs and Parameters

DELETE http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

Additional information about the DELETE can be found in the HTTP response header X-MWS-Message.

4.9 Job Arrays

This section describes behavior of the Job Array object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The JobArray API contains the type and description of all fields in the Job Array object.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/job-arrays			Submit new job array

4.9.1 Submitting Job Arrays

The HTTP POST method is used to submit Job Arrays.

Quick Reference

POST http://localhost/mws/rest/job-arrays?api-version=2[&proxy-user=<username>]

While the Job Array resource only gives access to create job arrays, job arrays are retrieved using the operations in the Getting Job Information section.

Restrictions

All restrictions present for Submitting Jobs are present for job arrays. In addition, job arrays are only supported if the ENABLEJOBARRAYS parameter is set to TRUE in the moab.cfg file. Example:

ENABLEJOBARRAYS 	TRUE

4.9.1.1 Submit Job Array

URLs and Parameters

POST http://localhost/mws/rest/job-arrays?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

To submit a job array, only two fields are required: jobPrototype and one of indexValues or indexRanges. Both index ranges and values may be specified if desired.

The request body below shows all the fields that are available during job array submission, although the jobPrototype shown is a simple example and does not utilize all fields of a job submission.

The jobPrototype field has the same properties as a typical job submission. Examples of this can be seen in the Submitting Jobs section.

JSON Request Body

{
  "name": "myarray",
  "indexRanges": [  {
    "startIndex": 11,
    "endIndex": 25,
    "increment": 2
  }],
  "indexValues":   [ 2, 4, 6, 8, 10 ],
  "slotLimit": 2,
  "cancellationPolicy":   {
    "firstJob": "FAILURE",
    "anyJob": "SUCCESS"
  },
  "jobPrototype":   {
    "commandFile": "/tmp/test.sh",
    "initialWorkingDirectory": "/tmp",
    "requirements": [{"taskCount": 4}]
  }
}

Sample Response

The response of this task is the same as submitting a job.

4.10 Job Templates

This section describes behavior of the Job Template object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Job Template API contains the type and description of all fields in the Job Template object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/job-templates	Get all job templates
/rest/job-templates/id	Get specified job template

4.10.1 Getting Job Templates

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

Quick Reference

GET http://localhost/mws/rest/job-templates/<id>

4.10.1.1 Get All Job Templates

URLs and Parameters

GET http://localhost/mws/rest/job-templates

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/job-templates?fields=id

{
  "totalCount": 14,
  "resultCount": 14,
  "results":   [
    {"id": "DEFAULT"},
    {"id": "genericVM"},
    {"id": "genericVM-setup"},
    {"id": "genericVM-destroy"},
    {"id": "genericVM-migrate"},
    {"id": "genericPM"},
    {"id": "genericPM-setup"},
    {"id": "genericPM-destroy"},
    {"id": "OSStorage"},
    {"id": "OSStorage-setup"},
    {"id": "OSStorage-destroy"},
    {"id": "extraStorage"},
    {"id": "extraStorage-setup"},
    {"id": "extraStorage-destroy"}
  ]
}

4.10.1.2 Get Single Job Template

URLs and Parameters

GET http://localhost/mws/rest/job-templates/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "account": "account",
  "args": "arg1 arg2",
  "commandFile": "/tmp/script",
  "description": "description",
  "genericSystemJob": true,
  "id": "genericVM",
  "inheritResources": false,
  "jobDependencies": [  {
    "name": "genericVM-setup",
    "type": "JOBSUCCESSFULCOMPLETE"
  }],
  "jobFlags": ["VMTRACKING"],
  "jobTemplateFlags": ["SELECT"],
  "jobTemplateRequirements": [  {
    "architecture": "x86_64",
    "diskRequirement": 500,
    "genericResources": {"tape": 3},
    "nodeAccessPolicy": "SINGLEJOB",
    "operatingSystem": "Ubuntu 10.04.3",
    "requiredDiskPerTask": 200,
    "requiredFeatures": ["dvd"],
    "requiredMemoryPerTask": 1024,
    "requiredProcessorsPerTask": 2,
    "requiredSwapPerTask": 512,
    "taskCount": 4
  }],
  "priority": 20,
  "qos": "qos",
  "queue": "queue",
  "durationRequested": 600,
  "select": true,
  "trigger": null,
  "version": 0,
  "vmUsagePolicy": "REQUIREPM"
}

4.11 Metric Types

This section describes behavior of the Metric Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The MetricType API contains the type and description of all fields in the Metric Type object.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/metric-types	Get all metric types

4.11.1 Getting Metric Types

The HTTP GET method is used to retrieve Metric Type information.

Quick Reference

GET http://localhost/mws/rest/metric-types

4.11.1.1 Get All Metric Types

URLs and Parameters

GET http://localhost/mws/rest/metric-types

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/metric-types?fields=id

{
  "totalCount": 9,
  "resultCount": 9,
  "results":   [
    {"id": "vmcount"},
    {"id": "watts"},
    {"id": "pwatts"},
    {"id": "temp"},
    {"id": "cpu"},
    {"id": "mem"},
    {"id": "io"},
    {"id": "ccores"},
    {"id": "threads"}
  ]
}

4.12 Nodes

This section describes behavior of the Node object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Node API has changed with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2 in order to behave as documented.
In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Node API contains the type and description of all fields in the Node object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/nodes	Get all nodes
/rest/nodes/name	Get specified node	Modify node

4.12.1 Getting Nodes

The HTTP GET method is used to retrieve Node information.

Quick Reference

GET http://localhost/mws/rest/nodes/<name>?api-version=2

4.12.1.1 Get All Nodes

URLs and Parameters

GET http://localhost/mws/rest/nodes?api-version=2

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"compute"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

This query will not return the DEFAULT or GLOBAL nodes from Moab Workload Manager. However, the Get Single Node task may be used to retrieve them individually if desired.

Sample Response

GET http://localhost/mws/rest/nodes?api-version=2&fields=name

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"name": "node1"},
    {"name": "node2"},
    {"name": "node3"}
  ]
}

4.12.1.2 Get Single Node

URLs and Parameters

GET http://localhost/mws/rest/nodes/<name>?api-version=2

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "name": "hv2",
  "architecture": null,
  "classes": ["class1"],
  "featuresReported": [],
  "index": 2,
  "ipAddress": "10.0.0.4",
  "isHypervisor": true,
  "lastUpdatedDate": "2012-10-11 17:42:24 UTC",
  "migrationDisabled": false,
  "partition": "msm",
  "processorSpeed": null,
  "profilingEnabled": false,
  "rack": null,
  "slot": null,
  "type": "compute",
  "messages": [  {
    "count": 11,
    "createdDate": "2012-10-24 04:06:04 UTC",
    "expireDate": "2037-10-24 12:26:40 UTC",
    "message": "This is a message"
  }],
  "metrics":   {
    "watts": 200,
    "pwatts": 200,
    "temp": 103,
    "vmcount": 4
  },
  "variables": {},
  "states":   {
    "powerState": "On",
    "powerStateExpected": null,
    "state": "Idle",
    "stateExpected": "Idle",
    "stateLastUpdatedDate": "2012-10-11 17:15:01 UTC",
    "subState": null,
    "subStateLast": null,
    "subStateLastUpdatedDate": null
  },
  "operatingSystem":   {
    "hypervisorType": "KVM",
    "image": "hyper",
    "imageExpected": null,
    "imageLastUpdatedDate": null,
    "imagesAvailable": ["hyper"],
    "virtualMachineImages":     [
      "stateless1",
      "stateless2"
    ]
  },
  "resources":   {
    "processors":     {
      "configured": 8,
      "real": 8,
      "dedicated": 0,
      "available": 8,
      "utilized": -1
    },
    "memory":     {
      "configured": 1048576,
      "real": 1048576,
      "dedicated": 0,
      "available": 1048576,
      "utilized": 0
    },
    "disk":     {
      "configured": 1048576,
      "real": 1048576,
      "dedicated": 0,
      "available": 1048576,
      "utilized": 0
    },
    "swap":     {
      "configured": 4096,
      "real": 4096,
      "dedicated": 0,
      "available": 4096,
      "utilized": 0
    }
  },
  "resourceManagers": [  {
    "name": "msm",
    "isMaster": true,
    "stateReported": "Active"
  }],
  "jobs": [],
  "reservations":   [
        {
      "name": "system.5",
      "type": "user"
    },
        {
      "name": "system.17",
      "type": "user"
    }
  ],
  "virtualContainers": [],
  "virtualMachines":   [
    {"name": "vm3"},
    {"name": "vm4"}
  ],
  "triggers": []
}

4.12.2 Modifying Nodes

The HTTP PUT method is used to modify Nodes.

Quick Reference

PUT http://localhost/mws/rest/nodes/<name>?api-version=2[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.12.2.1 Modify Node

URLs and Parameters

PUT http://localhost/mws/rest/nodes/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Node, along with some sample values.

Sample JSON Request Body to Modify a Node

{
  "messages":   [
    {"message": "Message one"},
    {"message": "Message two"}
  ],
  "metrics": {"pwatts": 211},
  "operatingSystem": {"image": "esx4.1"},
  "partition": "part1",
  "states":   {
    "powerState": "On",
    "state": "Running"
  },
  "variables":   {
    "key": "value",
    "arbitrary text key": "more value"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":[
  "Successfully modified os to 'linux'",
  "Successfully powered node off"
]}

4.13 Pending Actions

This section describes behavior of the Pending Action object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Pending Action API contains the type and description of all fields in the Pending Action object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/pending-actions	Get all pending actions

4.13.1 Getting Pending Actions

The HTTP GET method is used to retrieve Pending Action information.

Quick Reference

GET http://localhost/mws/rest/pending-actions

4.13.1.1 Get All Pending Actions

URLs and Parameters

GET http://localhost/mws/rest/pending-actions

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/pending-actions

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "failureDetails": "",
    "hosts": ["hv3"],
    "id": "vmcreate-27",
    "maxDurationInSeconds": 3600,
    "migrationDestination": "",
    "migrationSource": "",
    "motivation": "requested by root",
    "pendingActionState": "RUNNING",
    "pendingActionType": "VMCREATE",
    "requester": "root",
    "serviceId": "Rhel55Vm.200",
    "startTime": "2011-11-15 21:57:55 UTC",
    "substate": "installing",
    "targetOS": "",
    "topLevelServiceId": "Lamp.132",
    "vmId": "vm8"
  }]
}

Generic vs Non-Generic Types

If generic job templates are used in Moab, MWS may be configured to translate pending actions with the generic type to the proper type such as VMCREATE. This is done in the configuration file. The Quickstart Guide provides the default mappings for this feature, as well as an example of adding a custom mapping from a custom template name to the correct type.

The default mappings are shown in the table below. The available pending action types may be seen on the PendingActionType API page.

Template Name	Mapped Type
genericVM-setup	VMCREATE
genericVM-migrate	VMMIGRATE
genericVM-destroy	VMDESTROY
OSStorage-setup	VMSTORAGE
OSStorage-destroy	VMSTORAGEDESTROY
extraStorage-setup	STORAGE
extraStorage-destroy	STORAGEDESTROY
genericPM-setup	OSPROVISION

When generic mappings are used, MWS will match the first template mapping that the pending action ID ends with. For example, an ID of Moab.1.genericVM-setup will map the type to VMCREATE.

To enable mapping for a custom template name such as myCustomVM-setup, simply add the following line to the MWS configuration file. The value of the pending action type is case insensitive.

mws.pendingActions.mappings["myCustomVM-setup"] = "vmcreate"

MWS also provides the ability to enable or disable the display of generic pending actions (or those pending actions that are not mapped). This behavior is controlled by the mws.pendingActions.displayGeneric setting as shown below. A false value will prevent generic pending actions from being displayed, while a true value will display all pending actions. By default this value is true.

mws.pendingActions.displayGeneric = false

4.14 Permissions

This section describes behavior of the Permissions object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Permission API contains the type and description of fields that all Permissions have in common.

Supported Methods

Resource	GET	POST	DELETE
/rest/permissions	Get all Permissions	Create Permission
/rest/permissions/id	Get specified Permissions		Delete Permission
/rest/permissions/users/id	Get users Permissions

4.14.1 Getting Permissions

The HTTP GET method is used to retrieve Permission information. You can query all objects or a single object.

Quick Reference

GET http://localhost/mws/rest/permissions
GET http://localhost/mws/rest/permissions/<id>

4.14.1.1 Get All Permissions

URLs and Parameters

GET http://localhost/mws/rest/permissions[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"CUSTOM"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/permissions?fields=resource,action,description

{
	"totalCount": 1,
	"resultCount": 1,
	"results": [{
		"resource" : "chart",
		"action" : "read",
		"description" : "The permission to view all charts."
		} ]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.14.1.2 Get a User's Permissions

URLs and Parameters

GET http://localhost/mws/rest/permissions/users/<name>

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the user

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/permissions/users/bob

[
	  {
	  "action": "read",
	  "description": "The permission to read all charts",
	  "id": "5033b842e4b09cc61bedb818",
	  "label": "",
	  "resource": "chart",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	},
	  {
	  "action": "read",
	  "description": "The permission to read all pages",
	  "id": "5033b8a5e4b09cc61bedb82d",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	},
	  {
	  "action": "update",
	  "description": "The permission to update all pages",
	  "id": "5033b8a5e4b09cc61bedb82f",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	}
]

4.14.1.3 Get Single Permission

URLs and Parameters

GET http://localhost/mws/rest/permissions/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Permission.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/permissions/

{
	"action" : "create",
	"description" : "The permission to create all charts.",
	"id" : "50296335e4b0011b0f8394ec",
	"label" : "Create Chart",
	"resource" : "chart",
	"resourceFilter" : null,
	"type" : "custom",
	"version" : 0
}

4.14.2 Creating Permissions

The HTTP POST method is used to create Permissions.

Quick Reference

POST http://localhost/mws/rest/permissions

4.14.2.1 Create Single Permission

URLs and Parameters

POST http://localhost/mws/rest/permissions

See Global URL Parameters for available URL parameters.

Request Body

The resource, action, and type are required on each Permission.

Api permissions are permissions with the type 'api' and are the only permissions enforced by MWS.

Api permissions must map to a valid resource. For example 'services' is valid because there is a resource /mws/rest/services.

Api permissions must have create, read, update, or delete as the action.

The following is an example request body to create a permission:

POST http://localhost/mws/rest/permissions

{
			"resource" : "Chart",
			"action" : "read",
			"type" : "custom",
			"label" : "Read all charts",
			"description" : "The permissions to view all charts."
}

Sample Response

If the request was successful, the response body is the new permission that was created exactly as shown in Get Single Permission. On failure, the response is an error message.

4.14.3 Deleting Permissions

The HTTP DELETE method is used to delete Permissions.

Quick Reference

DELETE http://localhost/mws/rest/permissions/<id>

4.14.3.1 Delete Single Permission

URLs and Parameters

DELETE http://localhost/mws/rest/permission/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Permission.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{}

4.15 Plugins

This section describes behavior of the Plugin object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The PluginInstance API page contains the type and description of all fields in the Plugin object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/plugins	Get all plugins		Create new plugin
/rest/plugins/id	Get specified plugin	Modify plugin		Delete plugin
/rest/plugins/id/poll			Trigger Plugin Poll
/rest/plugins/id/services/serviceName	Access Web Service	Access Web Service	Access Web Service	Access Web Service

4.15.1 Getting Plugins

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

Quick Reference

GET http://localhost/mws/rest/plugins
GET http://localhost/mws/rest/plugins/<id>

4.15.1.1 Get All Plugins

URLs and Parameters

GET http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/plugins?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "plugin1"},
    {"id": "plugin2"},
    {"id": "plugin3"}
  ]
}

4.15.1.2 Get Single Plugin

URLs and Parameters

GET http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED",
  "nextPollDate":"2011-12-02 17:28:52 UTC",
  "lastPollDate":"2011-12-02 17:28:22 UTC"
}

4.15.2 Creating Plugins

The HTTP POST method is used to create Plugins.

Quick Reference

POST http://localhost/mws/rest/plugins

4.15.2.1 Create Plugin

URLs and Parameters

POST http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Request Body

When creating a plugin, the id and pluginType fields are required. The request body below shows all fields that are available when creating a Plugin, along with some sample values.

JSON Request Body

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  }
}

Sample Response

JSON Response for successful POST

{"id": "plugin1"}

Restrictions

While it is possible to create a plugin with arbitrary nested configuration, such as:

…
"config":{
  "nestedObject":{
    "property1":"value1",
    "property2":"value2"
  },
  "nestedList:["listItem1", "listItem2"]
}

It is not recommended as the user interface does not support editing or viewing any configuration data values other than strings.

4.15.3 Modifying Plugins

The HTTP PUT method is used to modify Plugins. Additionally, the POST method may be used to trigger an immediate poll of a Plugin.

Quick Reference

PUT http://localhost/mws/rest/plugins/<id>
POST http://localhost/mws/rest/plugins/<id>/poll

4.15.3.1 Modify Plugin

URLs and Parameters

PUT http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Plugin, along with some sample values.

JSON Request Body for Plugin Modification

{
  "state":"STARTED",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED"
}

Sample Response

JSON Response

{"messages":["Plugin plugin1 updated", "Started Plugin 'plugin1'"]}

4.15.3.2 Trigger Plugin Poll

URLs and Parameters

POST http://localhost/mws/rest/plugins/<id>/poll

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Trigger Poll

This resource call will trigger an immediate poll of the specified plugin. It is equivalent to the same operation on the Monitoring and Lifecycle Controls page.

Request Body

No request body is required.

Sample Response

JSON Response

{"messages":["Polled Plugin with ID 'myPlugin'"]}

4.15.4 Deleting Plugins

The HTTP DELETE method is used to delete Plugins.

Quick Reference

DELETE http://localhost/mws/rest/plugins/<id>

4.15.4.1 Delete Plugin

URLs and Parameters

DELETE http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

Additional information about a successful DELETE can be found in the HTTP response header X-MWS-Message.

JSON Response for an unsuccessful DELETE

{"messages":["Plugin plugin1 could not be deleted", "Error message describing the problem"]}

4.15.5 Accessing Plugin Web Services

All HTTP methods can be used to access Plugin Web Services. However, some services only support specific methods. Check the specific plugin type documentation for more information.

Quick Reference

GET http://localhost/mws/rest/plugins/<id>/services/<serviceName>
POST http://localhost/mws/rest/plugins/<id>/services/<serviceName>
PUT http://localhost/mws/rest/plugins/<id>/services/<serviceName>
DELETE http://localhost/mws/rest/plugins/<id>/services/<serviceName>

4.15.5.1 Access a Plugin Web Service

URLs and Parameters

GET http://localhost/mws/rest/plugins/<id>/services/<serviceName>
POST http://localhost/mws/rest/plugins/<id>/services/<serviceName>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
serviceName	Yes	String	-	The name of the web service, either in CamelCase or hyphenated.

See Global URL Parameters for available URL parameters.

Web Service IDs

Translation is done to map CamelCase web service names to hyphenated names in the URL. For example, a web service method named notifyEvent on a plugin with a name of notifications may be called with the following URLs:

// CamelCase /rest/plugins/notifications/services/notifyEvent

// Hyphenated /rest/plugins/notifications/services/notify-event

HTTP Method and Request Body

Because plugin Custom Web Services do not need to distinguish which HTTP method is used, it is recommended to use GET and POST when making requests to access web services unless documented otherwise. The request body and output may vary for each web service called. See the plugin type documentation for the requested plugin for available web services, request parameters, and expected output.

4.16 Plugin Types

This section describes behavior of the Plugin Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The PluginType API page contains the type and description of all fields in the Plugin Type object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/plugin-types	Get all plugin types	Create or update plugin type
/rest/plugin-types/id	Get specified plugin type

4.16.1 Getting Plugin Types

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

Quick Reference

GET http://localhost/mws/rest/plugin-types/<id>

4.16.1.1 Get All Plugin Types

URLs and Parameters

GET http://localhost/mws/rest/plugin-types

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/plugin-types?fields=id

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
    {"id": "vCenter"},
    {"id": "Native"}
  ]
}

4.16.1.2 Get Single Plugin Type

URLs and Parameters

GET http://localhost/mws/rest/plugin-types/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "author": "Adaptive Computing Enterprises, Inc.",
  "commonsVersion": "0.9.3 > *",
  "description": "Polls a VMware® vCenter™ Server for information on the hypervisors and virtual machines it manages.",
  "documentationLink": "",
  "email": "",
  "id": "VCenter",
  "initialPlugins": { },
  "instances": [
    {"id":"vcenter"}
  ],
  "issueManagementLink": "",
  "license": "APACHE",
  "mwsVersion": "7.1.2 > *",
  "pollMethod": true,
  "scmLink": "",
  "title": "VCenter",
  "version": "1.0",
  "webServices": [ ],
  "website": "http://www.adaptivecomputing.com"
}

4.16.2 Creating or Updating Plugin Types

The HTTP PUT method is used to create or update Plugin Types. The Content-Type HTTP header is used to determine if the request contains a single class file as plaintext or the binary data of a JAR file. Each request is explained in the following sections.

Quick Reference

PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]

There is a known issue with dynamically updating plugin types with typed field injection. See the Add or Update Plugin Types section for more information.

4.16.2.1 Update Plugin Type (File)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]

Parameter	Required	Valid Values	Description
reload-plugins	No	true or false	Reloads all plugins of this type on successful update. Defaults to true.

See Global URL Parameters for available URL parameters.

Request Body

This function is idempotent, meaning it will create the Plugin Type if it does not exist or update it if it does. The request body is the actual contents of the class file to upload. This web service is an exception to most as it requires a content type of application/x-groovy or text/plain.

If the application/x-groovy or text/plain content types are not used in the request, it will be interpreted as JSON, resulting in a failure.

Plaintext upload

package testimport com.adaptc.mws.plugins.*
class UploadPlugin {
	static author = "Adaptive Computing"
	static description = "A sample plugin class"
	String id
	public void configure() throws InvalidPluginConfigurationException {
		def myConfig = config
		def errors = []
		if (!myConfig.arbitraryKey)
			errors << "Missing arbitraryKey!"
		if (errors)
			throw new InvalidPluginConfigurationException(errors)
	}
	public def customService(Map params) {
		return params
	}
}

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the Get All Plugin Types task. The reason that the return of this task is a list is to accommodate the possibility of uploading multiple plugin types in a single JAR file as explained in the next section.

4.16.2.2 Update Plugin Type (JAR)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types?jar-filename=<filename.jar>[&reload-plugins=false]

Parameter	Required	Valid Values	Description
jar-filename	Yes	String	The filename of the JAR file that is being uploaded.
reload-plugins	No	true or false	Reloads all plugins of this type on successful update. Defaults to true.

See Global URL Parameters for available URL parameters.

Request Body

This function is idempotent, meaning it will create the Plugin Types if they do not exist or update them if they do. The request body is the binary contents of the JAR file to upload. This web service is an exception to most as it requires a content type of application/x-jar.

If the application/x-jar content type is not used in the request, it will be interpreted as JSON, resulting in a failure.

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the Get All Plugin Types task. Note that when using a JAR file, multiple plugin types may be uploaded in the same request.

4.17 Policies

This section describes behavior of the Policies object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Policy API contains the type and description of fields that all Policies have in common.

Supported Policies

Name	Id
Auto VM Migration	auto-vm-migration
Hypervisor Allocation Overcommit	hv-allocation-overcommit
Node Allocation	node-allocation
Migration Exclusion List	migration-exclusion-list

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/policies	Get all policies
/rest/policies/id	Get specified policy	Modify specified policy

4.17.1 Getting Policies

The HTTP GET method is used to retrieve Policies information.

Quick Reference

GET http://localhost/mws/rest/policies

4.17.1.1 Get All Policies

URLs and Parameters

GET http://localhost/mws/rest/policies

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Query for specific results.	query={"state":"DISABLED","conflicted":"false"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"id":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/policies?fields=id,state,conflicted

{
  "totalCount": 2,
  "resultCount": 2,
  "results": [  {
    "conflicted": false,
    "state": "DISABLED",
    "id": "auto-vm-migration"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "hv-allocation-overcommit"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "node-allocation"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "migration-exclusion-list"
  }]
}

4.17.1.2 Get Single Policy

URLs and Parameters

GET http://localhost/mws/rest/policies/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Responses

Auto VM Migration

{
  "conflicted": false,
  "description": "Controls how virtual machines are automatically migrated.",
  "id": "auto-vm-migration",
  "name": "Auto VM Migration",
  "potentialConflicts": [],
  "priority": 1,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "genericMetricThresholds":{
  	"GMETRIC1":1.3
  },
  "processorUtilizationThreshold":0.5,
  "memoryUtilizationThreshold":0.4
}

Hypervisor Allocation Overcommit

{
  "conflicted": false,
  "description": "Controls how hypervisors are overallocated with regards to processors and memory.",
  "id": "hv-allocation-overcommit",
  "name": "Hypervisor Allocation Overcommit",
  "potentialConflicts": [],
  "priority": 2,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "processorAllocationLimit":29.5,
  "memoryAllocationLimit":1.2
}

Node Allocation

{
  "conflicted": false,
  "description": "Controls how nodes are selected for workload placement.",
  "id": "node-allocation",
  "name": "Node Allocation",
  "potentialConflicts": [],
  "priority": 3,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "nodeAllocationAlgorithm": "CustomPriority",
  "customPriorityFunction": "100*RSVAFFINITY - GMETRIC[numvms]"
}

Migration Exclusion List

{
    "conflicted": false,
    "description": "Controls which machines are excluded from automatic live migration operations.",
    "hvExclusionList": ["blade05", "blade02"],
    "name": "Migration Exclusion List",
    "potentialConflicts": [],
    "priority": 100,
    "state": "DISABLED",
    "tags": [],
    "types": [],
    "version": 1,
    "vmExclusionList": ["vm1", "vm5"],
    "id": "migration-exclusion-list"
}

4.17.2 Modifying Policies

The HTTP PUT method is used to modify Policies.

Quick Reference

PUT http://localhost/mws/rest/policies/<id>

4.17.2.1 Modify Policy

URLs and Parameters

PUT http://localhost/mws/rest/policies/<id>[?change-mode=set]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Additional URL parameters

URL parameters for modifying a Migration Exclusion Lists Policy.

Migration Exclusion Lists Parameter	Required	Valid Values	Description
change-mode	No	set(Default)	Replace the existing exclusion list(s) with the given one.
		add	Add the given VMs/HVs to the existing exclusion list(s).
		remove	Remove the given VMs/HVs from the existing exclusion list(s).

Request Body

In general, the fields shown in the Policy API are not available for modification. However, the state field may be modified to a valid Policy State. All other fields listed in the specific API pages may be modified unless documented otherwise.

The request body below shows all the fields that are available when modifying a Auto VM Migration Policy, along with some sample values.

JSON Request Body for Auto VM Migration Policy

{
    "genericMetricThresholds": {
        "GENERICTHRESHOLD": 5
    },
    "memoryUtilizationThreshold": 0.5,
    "processorUtilizationThreshold": 0.4
}

The request body below shows all the fields that are available when modifying a Node Allocation Policy, along with some sample values.

JSON Request Body for Auto VM Migration Policy

{
      "nodeAllocationAlgorithm" : "CustomPriority",
      "customPriorityFunction" : "100*RSVAFFINITY - GMETRIC[numvms]"
}

The request body below shows all the fields that are available when modifying a Migration Exclusion Lists Policy, along with some sample values.

JSON Request Body for Migration Exclusion Lists Policy

{
   "vmExclusionList" : ["vm1","vm3","vm5"], 
   "hvExclusionList" : ["hv2","hv3","hv6"]
}

Sample Response

JSON Response

{
    "messages": ["Policy auto-vm-migration updated"]
}

Samples

Enable the Auto VM Migration Policy and set values.

PUT http://localhost/mws/rest/policies/auto-vm-migration

{
  "state": "enabled",
  "migrationAlgorithmType": "overcommit",
  "processorUtilizationThreshold": 0.5,
  "memoryUtilizationThreshold": 0.4
}

As noted in the Auto VM Migration API documentation, if the state is set to ENABLED, then the migrationAlgorithmType must not be set to NONE.

Restrictions

All Policies

Fields cannot be modified while the policy is disabled. Enable the policy to modify the field.

Auto VM Migration

Arbitrary metrics can be added to genericMetricThresholds, but they cannot be removed once added.
The migrationAlgorithmType field cannot be modified while the policy is disabled. Enable the policy to modify the field.
Moab is configured with a default limit of 10 generic metrics. If this limit is reached, such as when arbitrary metrics are added to genericMetricThresholds, the metric will not be reported.

To increase this limit, set the MAXGMETRIC property in the Moab configuration file.

4.18 Principals

This section describes behavior of the Principal object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Principal API contains the type and description of all fields in the Principal object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/principals	Get All Principals		Create Principal
/rest/principals/id	Get Specified Principal	Modify Principal		Delete Principal
/rest/principals/name	Get Specified Principal	Modify Principal		Delete Principal

4.18.1 Getting Principals

The HTTP GET method is used to retrieve Principal information. You can query all objects or a single object.

Quick Reference

GET http://localhost/mws/rest/principals[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/principals/<id>
GET http://localhost/mws/rest/principals/<name>

4.18.1.1 Get All Principals

URLs and Parameters

GET http://localhost/mws/rest/principals[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"name":"Acme Principal"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/principals?fields=name,description

{
		"totalCount": 2,
		"resultCount": 2,
		"results":	 [
			{
				"groups": [	{
					"name": "CN=Engineering,CN=Users,DC=corp,DC=cloud,DC=dev",
					"type": "LDAPGROUP"
				}],
				"name": "Engineering-Principal"
			},
			{
				"groups": [	{
					"name": "CN=Marketing,CN=Users,DC=corp,DC=cloud,DC=dev",
					"type": "LDAPGROUP"
				}],
				"name": "Marketing-Principal"
			}
		]
	}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.18.1.2 Get Single Principal

URLs and Parameters

GET http://localhost/mws/rest/principals/<id>
GET http://localhost/mws/rest/principals/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Principal.
name	Yes	String	-	The name of the Principal.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

GET http://localhost/mws/rest/principals/principal8

{
	  "attachedRoles": [  {
		"description": "This is a role for normal users in the Acme BU Group.",
		"id": "5033b8eae4b09cc61bedb895",
		"name": "Acme-User-Role",
		"permissions":	 [
				{
			"action": "read",
			"description": "The permission to read all nodes",
			"id": "5033b842e4b09cc61bedb818",
			"label": "",
			"resource": "nodes",
			"resourceFilter": null,
			"type": "api",
			"version": 1
		  },
		],
		"version": 2
	  }],
	  "description": "Principal 8",
	  "groups": [  {
		"name": "CN=Engineering,CN=Users,DC=corp,DC=cloud,DC=dev",
		"type": "LDAPGROUP"
	  }],
	  "id": "5033d33fe4b018b28745fecd",
	  "name": "principal8",
	  "users":   [
		{
		  "name": "jhammon",
		  "type": "LDAP"
		},
		{
		  "name": "bjones",
		  "type": "LDAP"
		}
	  ],
	"version": 0
}

4.18.2 Creating Principals

The HTTP POST method is used to submit Principals.

Quick Reference

POST http://localhost/mws/rest/principals

4.18.2.1 Create Single Principal

URLs and Parameters

POST http://localhost/mws/rest/principals

See Global URL Parameters for available URL parameters.

Request Body

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

The attachedRoles field expects an array of Role IDs or names:

The following is an example request body to create a principal:

POST http://localhost/mws/rest/principals

{
	"name" : "Acme-Principal",
	"attachedRoles" : [{"name":"Acme-User-Role"}],
	"description" : "A cool principal",
	"groups" : [{"name": "CN=Engineering,CN=Users,DC=corp,DC=cloud,DC=dev", "type":"LDAPGROUP"}],
	"users" : [{
		"name" : "john",
		"type" : "LDAP"
	} ]
}

Sample Response

If the request was successful, the response body is the new principal that was created, exactly as shown in Get Single Principal. On failure, the response is an error message.

4.18.3 Modifying Principals

The HTTP PUT method is used to modify Principals.

Quick Reference

PUT http://localhost/mws/rest/principals/<id>
PUT http://localhost/mws/rest/principals/<name>

4.18.3.1 Modify Single Principal

URLs and Parameters

PUT http://localhost/mws/rest/principal/<id>
PUT http://localhost/mws/rest/principal/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Principal.
name	Yes	String	-	The name of the Principal.
change-mode	Yes	String	add	Add the given objects (ldapGroups, ldapOUs, etc) to the objects that already exist.
			remove	Delete the given objects from the objects that already exist.
			set	Add the given objects (ldapGroups, ldapOUs, etc) and remove the objects that already exist.

See Global URL Parameters for available URL parameters.

The change-mode set is the default if no change-mode parameter is given.

You must specify either id or name, but you do not have to specify both.

The name field must contain only letters, digits, periods, dashes, and underscores.

The attachedRoles field expects an array of Role IDs or names:

Example Request

PUT http://locahost/mws/rest/principals/Acme-Principal"

{
	"groups" : [ {
		"name" : "CN=Marketing,CN=Users,DC=mycompany,DC=com",
		"type" : "LDAPGROUP"
	},{
		"name" : "CN=Sales,CN=Users,DC=mycompany,DC=com",
		"type" : "LDAPGROUP"
	}],
	"users" : [ {
		"name" : "jhammon",
		"type" : "LDAP"
	}]
}

The version field contains the current version of the database entry. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object between the time that the data was retrieved and the modify request was delivered.

Sample Response

If the request was successful, the response body is the modified principal as shown in Get Single Principal. On failure, the response is an error message.

4.18.4 Deleting Principals

The HTTP DELETE method is used to delete Principals.

Quick Reference

DELETE http://localhost/mws/rest/principals/<id>
DELETE http://localhost/mws/rest/principals/<name>

4.18.4.1 Delete Single Principal

URLs and Parameters

DELETE http://localhost/mws/rest/principal/<id>
DELETE http://localhost/mws/rest/principal/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Principal.
name	Yes	String	-	The name of the Principal.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{}

4.19 Quotes

This section describes behavior of the Quotes object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Quote API contains the type and description of fields that all Quotes have in common.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/quotes/standard/quote			Quoting resources

4.19.1 Quoting Resources

Quick Reference

POST http://localhost/mws/rest/quotes/standard/quote?object-type=<OBJECTTYPE>&proxy-user=<USER>&charge-duration=<CHARGEDURATION>

4.19.1.1 Quote Single Job or Service

URLs and Parameters

POST http://localhost/mws/rest/quotes/standard/quote?object-type=<OBJECTTYPE>&proxy-user=<USER>&charge-duration=<CHARGEDURATION>

Parameter	Required	Type	Valid Values	Description
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
charge-duration	Yes	Integer	The charge duration of the job in seconds.	charge-duration=6400
object-type	Yes	String	The object to quote. It can be job or service.	object-type=job
itemize	No	Boolean	Returns the composite charge information in the response data.	itemize=true
rate	No	JSONArray	Uses the specified charge rates in the quote. The specified rates override the standard and quote rates. If the guarantee field is set to true, these charge rates will be saved and used when this quote is referenced in a charge action.	rate=[{"type":"VBR","name":"Memory","rate":1},{"type":"VBR","name":"Processors","rate":1}]
guarantee	No	Boolean	Guarantees the quote and returns a quote id to secure the current charge rates. This results in the creation of a quote record and a permanent usage record. This parameter is mutually exclusive with the cost-only parameter.	guarantee=true
grace-duration	No	Integer	The guaranteed quote grace period in seconds. If the quote duration is specified but not the quote end time, the quote endtime will be calculated as the quote start time plus the quote duration plus the grace duration.	grace-duration=6400
cost-only	No	Integer	Returns the cost, ignoring all balance and validity checks. This parameter is mutually exclusive with the guarantee parameter.	cost-only=true
description	No	String	The guaranteed quote description.	description="ABC Coupon Rate"
start-time	No	Date	The guaranteed quote start time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now.	start-time="2012-04-09 13:49:40 UTC"
end-time	No	Date	The guaranteed quote end time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now.	end-time="2012-04-09 14:49:40 UTC"

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all of the fields in a Job that could affect the quote.

POST http://localhost/mws/rest/quotes/standard/quote?object-type=job

{
  "id": "Moab.1",
  "user": "amy",
  "group": "group",
  "rmName": "machine1",
  "templateList": [
  "genericVm"
  ],
  "account": "biology",
  "qosRequested": "QOS1",
  "variables": {
    "imageName": "centos5.5-stateless",
    "topLevelServiceId": "myService.1",
    "serviceId": "vmService.1",
    "vmid": "VmService.1",
    "pmid": "VmService.1"
  },
  "requirements": [
  {
      "requiredProcessorsPerTask": 2,
      "genericResources": {
  	     "gold": 100,
  	     "os": 500
      },
      "requiredNodeCountMinimum": 1,
      "requiredMemoryPerTask": 1024,
      "requiredClass": "batch"
  }
  ]
}

The request body below shows all of the fields in a Service that affect the quote in a default MAM installation.

POST http://localhost/mws/rest/quotes/standard/quote?object-type=service

{
     "name":"service.1",
     "user": "amy",
     "account": "chemistry"
     "attributes":{
        "moab":{
           "job":{
              "resources":{
                 "procs":1,
                 "mem":2048,
                 "OS":500,
                 "gold":100
              },
              "variables":{
                 "Var1": 1524
              },
              "image":"centos5.5-stateless",
              "template":"genericVM",
           }
        }
     }
  }

Sample Responses

If the quote is not guaranteed

JSON Response

{
    "instance": "Moab.1",
    "amount": 600
}

If the quote is guaranteed

JSON Response

{
    "id": 1,
    "usageRecord": 2,
    "instance": "Moab.1",
    "amount": 600
}

If the quote is guaranteed and itemized

JSON Response

{
  "details":   [
        {
      "name": "Processors",
      "value": "2",
      "duration": 300,
      "rate": 1,
      "scalingFactor": 1,
      "amount": 600,
      "details": "2 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 300 [Duration]"
    },
        {
      "name": "Memory",
      "value": "1024",
      "duration": 300,
      "rate": 1,
      "scalingFactor": 1,
      "amount": 307200,
      "details": "1024 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 300 [Duration]"
    }
  ],
  "id": 20,
  "instance": "Moab.1",
  "usageRecord": 20,
  "amount": 307800
}

If the quote is on a service

JSON Response

{
  "services":   [
        {
      "details":       [
                {
          "name": "Processors",
          "value": "22",
          "duration": 30,
          "rate": 1,
          "scalingFactor": 1,
          "amount": 660,
          "details": "22 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 30 [Duration]"
        },
                {
          "name": "Memory",
          "value": "32343242",
          "duration": 30,
          "rate": 1,
          "scalingFactor": 1,
          "amount": 970297260,
          "details": "32343242 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 30 [Duration]"
        }
      ],
      "id": 120,
      "instance": "myVmWorkflow",
      "usageRecord": 157,
      "amount": 970297920
    },
        {
      "details": [      {
        "name": "Storage",
        "value": "2500",
        "duration": 30,
        "rate": 1.157E-7,
        "scalingFactor": 1,
        "amount": 0,
        "details": "2500 [Storage] * 1.157e-07 [ChargeRate{VBR}{Storage}] * 30 [Duration]"
      }],
      "id": 122,
      "instance": "myExtraStorageWorkflow",
      "usageRecord": 159,
      "amount": 0
    },
        {
      "details":       [
                {
          "name": "Processors",
          "value": "0",
          "duration": 30,
          "rate": 1,
          "scalingFactor": 1,
          "amount": 0,
          "details": "0 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 30 [Duration]"
        },
                {
          "name": "Memory",
          "value": "0",
          "duration": 30,
          "rate": 1,
          "scalingFactor": 1,
          "amount": 0,
          "details": "0 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 30 [Duration]"
        }
      ],
      "id": 123,
      "instance": "myPmWorkflow",
      "usageRecord": 160,
      "amount": 0
    }
  ],
  "amount": 970297920
}

Restrictions

The details field is only available with MAM version 7.1.0 or later.

4.20 Reports

This section describes behavior of the reporting framework in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Report, Sample, and Datapoint API contains the type and description of all fields in the Report, Sample, and Datapoint objects. They also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	POST	DELETE
/rest/reports	Get all reports	Create Reports	Deleting Reports
/rest/reports/name	Get single report with data
/rest/reports/id	Get single report with data
/rest/reports/name/datapoints	Get datapoints for report
/rest/reports/id/datapoints	Get datapoints for report
/rest/reports/name/samples	Get samples for report	Create sample(s) for report
/rest/reports/id/samples	Get samples for report	Create sample(s) for report

4.20.1 Getting Reports

The HTTP GET method is used to retrieve Report information. Queries for all reports with no attached data and a single report with associated data are available.

Quick Reference

GET http://localhost/mws/rest/reports[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/reports/<id>
GET http://localhost/mws/rest/reports/<name>

4.20.1.1 Get All Reports (No Data Included)

URLs and Parameters

GET http://localhost/mws/rest/reports[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"reportSize":4}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "3efe5c670be86ba8560397ff",
    "name": "cpu-util"
	…
  }]
}

No datapoints are returned when querying for all reports. To view the consolidated datapoints, the Get Single Report API call must be used.

Samples

GET http://localhost/mws/rest/reports?fields=id,name

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
        {
      "id": "3efe5c670be86ba8560397ff",
      "name": "cpu-util"
    },
        {
      "id": "3efe5c670be86ba856039800",
      "name": "cpu-temp"
    },
        {
      "id": "3efe5c670be86ba856039801",
      "name": "cpu-load"
    }
  ]
}

4.20.1.2 Get Single Report (Includes Data)

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>
GET http://localhost/mws/rest/reports/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

In the example below, the first datapoint has a null data element, which means that the minimumSampleSize configured for the report was not met when consolidating the datapoint. The second datapoint contains actual data.

JSON Response

{
  "consolidationFunction": "average",
  "datapointDuration": 15,
  "datapoints":   [
        {
      "endDate": "2011-12-02 17:28:22 UTC",
      "startDate": "2011-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:23 UTC",
      "startDate": "2011-12-02 17:28:37 UTC",
      "firstSampleDate": "2011-12-02 17:28:23 UTC",
      "lastSampleDate": "2011-12-02 17:28:30 UTC",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ],
  "description": "Example of CPU utilization reporting",
  "id": "3efe5c670be86ba8560397ff",
  "keepSamples": false,
  "minimumSampleSize": 1,
  "name": "cpu-util",
  "reportSize": 2
}

4.20.1.3 Get Datapoints For Single Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/datapoints[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/reports/<name>/datapoints[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.
query	No	JSON	Queries for specific results.	query={"data.test":true}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"startDate":-1}

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

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

This function is exactly the same as requesting a single report with only the datapoints returned. No report metadata (i.e. description, minimumSampleSize, etc.) is returned.

JSON Response

{
  "resultCount":1,
  "totalCount":1,
  "results":[
        {
      "endDate": "2011-12-02 17:28:22 UTC",
      "startDate": "2011-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:37 UTC",
      "startDate": "2011-12-02 17:28:37 UTC",
      "firstSampleDate": "2011-12-02 17:28:23 UTC",
      "lastSampleDate": "2011-12-02 17:28:23 UTC",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ]
}

4.20.2 Getting Samples For Reports

The HTTP GET method is used to retrieve Sample information.

Quick Reference

GET http://localhost/mws/rest/reports/<id>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/reports/<name>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]

4.20.2.1 Get Samples For Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/reports/<name>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.
query	No	JSON	Queries for specific results.	query={"agent":"cpu-monitor"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"agent":-1}

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

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
	"timestamp": "2011-12-02 17:28:37 UTC"
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	},
	…
  }]
}

4.20.3 Creating Reports

The HTTP POST method is used to create Reports. Operations are available to create reports with or without historical datapoints.

Quick Reference

POST http://localhost/mws/rest/reports

4.20.3.1 Create Report

URLs and Parameters

POST http://localhost/mws/rest/reports

See Global URL Parameters for available URL parameters.

Request Body

To create a report, several fields are required as documented in the Report API.

The request body below shows all the fields that are available during report creation.

JSON Request Body

{
	"name":"cpu-util",
	"description":"An example report on cpu utilization",
	"consolidationFunction":"average",
	"datapointDuration":15,
	"minimumSampleSize":1,
	"reportSize":2,
	"keepSamples":true,
	"datapoints":[
		{
			"startDate":"2011-12-01 19:16:57 UTC",
			"endDate":"2011-12-01 19:16:57 UTC",
			"data":{
				"time":30,
				"util":99.98
			}
		}
	]
}

Sample Response

{
	"messages":["Report cpu-util created"],
	"id":"3efe5c670be86ba8560397ff",
	"name":"cpu-util"
}

Samples

POST http://localhost/mws/rest/reports (Minimal report without datapoints)

{
	"name":"cpu-util",
	"datapointDuration":15,
	"reportSize":2
}

4.20.4 Creating Samples

The HTTP POST method is used to create Samples for Reports.

Quick Reference

POST http://localhost/mws/rest/reports

4.20.4.1 Create Samples For Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/samples
GET http://localhost/mws/rest/reports/<name>/samples

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Request Body

To create samples for a report, simply send data and an optional timestamp to the URL above.

The request body below shows all the fields that are available during sample creation. Note that the data field can contain arbitrary JSON.

JSON Request Body

{
	"timestamp":"2011-12-01 19:16:57 UTC",
	"agent":"my agent",
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	}
}

Sample Response

{"messages":["1 sample(s) created for report cpu-util"]}

4.20.5 Deleting Reports

The HTTP DELETE method is used to delete Reports.

Quick Reference

DELETE http://localhost/mws/rest/reports/<id>
DELETE http://localhost/mws/rest/reports/<name>

4.20.5.1 Delete Report

URLs and Parameters

DELETE http://localhost/mws/rest/reports/<id>
DELETE http://localhost/mws/rest/reports/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{"messages":["Report cpu-util deleted"]}

4.21 Reservations

This section describes behavior of the Reservation object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Reservation API contains the type and description of all fields in the Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/reservations	Get all reservations		Create reservation
/rest/reservations/id	Get specified reservation	Modify reservation		Release reservation

4.21.1 Getting Reservations

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

Quick Reference

GET http://localhost/mws/rest/reservations/<id>

Restrictions

Only admin or user reservations are returned with this call.

4.21.1.1 Get All Reservations

URLs and Parameters

GET http://localhost/mws/rest/reservations

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/reservations?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "system.1"},
    {"id": "system.2"},
    {"id": "system.3"}
  ]
}

4.21.1.2 Get Single Reservation

URLs and Parameters

GET http://localhost/mws/rest/reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "accountingAccount": "",
  "accountingGroup": "",
  "accountingQOS": "",
  "accountingUser": "root",
  "aclRules": [  {
    "affinity": "NEUTRAL",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "RESERVATION_ID",
    "value": "system.43"
  }],
  "allocatedNodeCount": 1,
  "allocatedProcessorCount": 8,
  "allocatedTaskCount": 1,
  "allocatedNodes": [
  	{"id":"node001"}
  ],
  "comments": "",
  "creationDate": null,
  "duration": 200000000,
  "endDate": "2018-03-17 16:49:10 UTC",
  "excludeJobs":   [
    "job1",
    "job2"
  ],
  "expireDate": null,
  "flags":   [
    "REQFULL",
    "ISACTIVE",
    "ISCLOSED"
  ],
  "globalId": "",
  "hostListExpression": "",
  "id": "system.43",
  "idPrefix": "",
  "isActive": true,
  "isTracked": false,
  "label": "",
  "maxTasks": 0,
  "messages": [],
  "owner":   {
    "name": "adaptive",
    "type": "USER"
  },
  "partitionId": "switchB",
  "profile": "",
  "requirements":   {
    "architecture": "",
    "featureList":     [
      "feature1",
      "feature2"
    ],
    "featureMode": "",
    "memory": 0,
    "nodeCount": 0,
    "nodeIds": ["node001:1"],
    "os": "",
    "taskCount": 1
  },
  "reservationGroup": "",
  "resources": {"PROCS": 0},
  "startDate": "2011-11-14 20:15:50 UTC",
  "statistics":   {
    "caps": 0,
    "cips": 2659.52,
    "taps": 0,
    "tips": 0
  },
  "subType": "Other",
  "taskCount": 0,
  "trigger": null,
  "triggerIds": [],
  "uniqueIndex": "",
  "variables": {}
}

4.21.2 Creating Reservations

The HTTP POST method is used to create Reservations.

Quick Reference

POST http://localhost/mws/rest/reservations

4.21.2.1 Create Reservation

URLs and Parameters

POST http://localhost/mws/rest/reservations

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when creating a Reservation, along with some sample values.

JSON Request Body

{
  "accountingAccount": "",
  "accountingGroup": "",
  "accountingQOS": "",
  "accountingUser": "root",
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "GROUP",
    "value": "staff"
  }],
  "comments": "",
  "duration": 200000000,
  "endDate": "2018-03-17 16:49:10 UTC",
  "excludeJobs":   [
    "job1",
    "job2"
  ],
  "flags":   [
    "SPACEFLEX",
    "ACLOVERLAP",
    "SINGLEUSE"
  ],
  "hostListExpression": "",
  "idPrefix": "",
  "label": "myreservation",
  "owner":   {
    "name": "adaptive",
    "type": "USER"
  },
  "partitionId": "",
  "profile": "",
  "requirements":   {
    "architecture": "",
    "featureList":     [
      "feature1",
      "feature2"
    ],
    "memory": 0,
    "os": "",
    "taskCount": 1
  },
  "reservationGroup": "",
  "resources":   {
    "PROCS": 2,
    "MEM": 1024,
    "DISK": 1024,
    "SWAP": 1024,
    "other1": 17,
    "other2": 42
  },
  "startDate": "2011-11-14 20:15:50 UTC",
  "subType": "Other",
  "trigger": {
    "eventType":"START",
    "actionType":"EXEC",
    "action":"date"
  },
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Create reservation if no conflicting reservations are found.

This is equivalent to mrsvctl -c -h node01 -E.

JSON Request Body

{
  "flags":   [
    "DEDICATEDRESOURCE"
  ],
  "hostListExpression": "node01"
}

Sample Response

JSON Response for successful POST

{"id": "system.44"}

4.21.3 Modifying Reservations

The HTTP PUT method is used to modify Reservations.

Quick Reference

PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>

4.21.3.1 Modify Reservation

URLs and Parameters

PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
change-mode	Yes	String	add	Add the given variables to the variables that already exist.
			remove	Delete the given variables from the variables that already exist.
			set	Replace all existing variables with the given variables.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Reservation, along with some sample values.

JSON Request Body for Reservation Modify

{
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["reservation 'system.43' attribute 'Variable' changed."]}

Restrictions

You can change the ACL Rules on a reservation, but not using this resource. See Create or Update ACLs.

4.21.4 Releasing Reservations

The HTTP DELETE method is used to release Reservations.

Quick Reference

DELETE http://localhost/mws/rest/reservations/<id>

4.21.4.1 Release Reservation

URLs and Parameters

DELETE http://localhost/mws/rest/reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

4.22 Resource Types

This section describes behavior of the Resource Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The ResourceType API contains the type and description of all fields in the Resource Type object.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/resource-types	Get all resource types

4.22.1 Getting Resource Types

The HTTP GET method is used to retrieve Resource Type information.

Quick Reference

GET http://localhost/mws/rest/resource-types

4.22.1.1 Get All Resource Types

URLs and Parameters

GET http://localhost/mws/rest/resource-types

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/resource-types?fields=id

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"id": "throttle_migrate"}
  ]
}

4.23 Roles

This section describes behavior of the Role resource in Moab Web Services. The role resource is used to control access to MWS resources based on the proxy-user. Each role is attached to a principal and contains a list of proxy-user permissions that the group can use in MWS. This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Role API contains the type and description of all fields in the Role object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/roles	Get All Roles		Create Role
/rest/roles/id	Get Specified Role	Modify Role		Delete Role
/rest/roles/name	Get Specified Role	Modify Role		Delete Role

4.23.1 Getting Roles

The HTTP GET method is used to retrieve Role information. You can query all objects or a single object.

Quick Reference

GET http://localhost/mws/rest/roles[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/roles/<id>
GET http://localhost/mws/rest/roles/<name>

4.23.1.1 Get All Roles

URLs and Parameters

GET http://localhost/mws/rest/roles[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"name":"Acme-User-Role"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/roles?fields=id,name

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "Acme-User-Role"
  }]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.23.1.2 Get Single Role

URLs and Parameters

GET http://localhost/mws/rest/roles/<id>
GET http://localhost/mws/rest/roles/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Role.
name	Yes	String	-	The name of the Role.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

GET http://localhost/mws/rest/roles/Acme-User-Role

{
	"description" : "This is a role for normal users in the Acme BU Group.",
	"id" : "5022e695e4b073f54e47c28d",
	"name" : "Acme-User-Role",
	"permissions" : [ {
		"action" : "create",
		"description" : "The permission to create all charts.",
		"id" : "5022e695e4b073f54e47c28e",
		"label" : "Create Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"version" : 0
	}, {
		"action" : "read",
		"description" : "The permission to view all charts.",
		"id" : "5022e695e4b073f54e47c28f",
		"label" : "View Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"version" : 0
	}, {
		"action" : "update",
		"description" : "The permission to modify the africa chart.",
		"id" : "5022e695e4b073f54e47c290",
		"label" : "Modify Africa Chart",
		"resource" : "chart",
		"resourceFilter" : {
			"name" : "africa"
		},
		"type" : "custom",
		"version" : 0
	}, {
		"action" : "read",
		"description" : "The permissions to view John's services.",
		"id" : "5022e695e4b073f54e47c291",
		"label" : "Read John's services",
		"resource" : "services",
		"resourceFilter" : {
			"user":"john"
		},
		"type" : "api",
		"version" : 0
	} ],
	"version" : 2
}

4.23.2 Creating Roles

The HTTP POST method is used to submit Roles.

Quick Reference

POST http://localhost/mws/rest/roles

4.23.2.1 Create Single Role

URLs and Parameters

POST http://localhost/mws/rest/roles

See Global URL Parameters for available URL parameters.

Request Body

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

The following is an example of a request body to create a role:

POST http://localhost/mws/rest/roles

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		},
		{
		"id" : "4fa197e68ca30fc605dd1df2"
		}
	]
}

Sample Response

If the request was successful, the response body is the new role that was created, exactly as shown in Get Single Role. On failure, the response is an error message.

Samples

The permissions field only expects an array of permission IDs, as shown in the following example:

Example payload of role with 2 permissions

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		}
	]
}

4.23.3 Modifying Roles

The HTTP PUT method is used to modify Roles.

Quick Reference

PUT http://localhost/mws/rest/roles/<id>
PUT http://localhost/mws/rest/roles/<name>

4.23.3.1 Modify Single Role

URLs and Parameters

PUT http://localhost/mws/rest/role/<id>
PUT http://localhost/mws/rest/role/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Role.
name	Yes	String	-	The name of the Role.
change-mode	No	String	add	Adds the given permissions to the permissions that already exist.
			remove	Deletes the given permissions from the permissions that already exist.
			set	Adds the given permissions and deletes the permissions that already exist.

If you do not specify a change-mode value, the system automatically assumes set as the default.

You must specify either id or name, but you do not have to specify both.

The name field must contain only letters, digits, periods, dashes, and underscores.

See Global URL Parameters for available URL parameters.

Example Request

PUT http://locahost/mws/rest/role/Acme-User-Role?change-mode=add

{
	"permissions":[{"id":"4fa197e68ca30fc605dd1cf0"} ]
}

Sample Response

If the request was successful, the response body is the modified role as shown in Get Single Role. On failure, the response is an error message.

4.23.4 Deleting Roles

The HTTP DELETE method is used to delete Roles.

Quick Reference

DELETE http://localhost/mws/rest/roles/<id>
DELETE http://localhost/mws/rest/roles/<name>

4.23.4.1 Delete Single Role

URLs and Parameters

DELETE http://localhost/mws/rest/role/<id>
DELETE http://localhost/mws/rest/role/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Role.
name	Yes	String	-	The name of the Role.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

JSON Response

{}

4.24 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 bodys, and responses delivered to and from Moab Web Services for each approach.

The Service API 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	Get all Services		Create Service
/rest/services/id	Get specified Service	Modify Service		Delete Service

4.24.1 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/mws/rest/services[?query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]
GET http://localhost/mws/rest/services/<id>[?[show-recursive-vc|show-vc]=true]
GET http://localhost/mws/rest/services/<name>[?[show-recursive-vc|show-vc]=true]

4.24.1.1 Get All Services

URLs and Parameters

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

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Query for specific results.	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	true	Show extended details about the service's virtual container including nested virtual containers and nested jobs.	show-recursive-vc=true
show-vc	No	true	Show details about the service's virtual container.	show-vc=true

Sample Response

GET http://localhost:8080/mws/rest/services?query={user:"bob"}

{ "totalCount": 9, "resultCount": 3, "results": [ { "dateCreated": "2011-12-07 16:03:40 UTC", "lastUpdated": "2011-12-07 16:03:40 UTC",

"name": "bobService.1", "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" ], "parent": null, "serviceTemplate": { "id": "4fbd42cfc4aa4c444cc54112", "name": "CentosVmPlusStorage" }, "attributes": {"moab": { "vc": {"id": "vc56"}, "dependencies": [ { "service": "machine0.1", "dependency": ["OSStoremachine0.1"] }] }}, "id": "4edff0cc6852f709fa777826" }, { "dateCreated": "2011-12-07 16:03:40 UTC", "lastUpdated": "2011-12-07 16:03:40 UTC", "name": "machine0.1", "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": [], "parent": "bobService.1", "serviceTemplate": { "id": "4fbd42cfc4aa4c444cc54113", "name": "CentosVm" }, "attributes": {"moab": { "vc": {"id": "vc57"}, "job": { "id": "Moab.24", "template": "genericVM", "image": "centos5.5-stateless", "features": ["vlan3"], "variables": {"QOS": "High"}, "resources": { "mem": 2, "procs": 2, "disk": 2 } } }}, "id": "4edff0cc6852f709fa777827" }, { "dateCreated": "2011-12-07 16:03:40 UTC", "lastUpdated": "2011-12-07 16:03:40 UTC", "name": "OSStoremachine0.1", "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": [], "parent": "bobService.1", "serviceTemplate": { "id": "4fbd42cfc4aa4c444cc54114", "name": "OpSysStorage" }, "attributes": {"moab": { "vc": {"id": "vc58"}, "job": { "id": "Moab.23", "template": "OSStorage", "resources": {"OS": 200} } }}, "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/mws/rest/services?query={"user":"bob"}

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

http://localhost/mws/rest/services?query={"type":"vm"}

To see only bob's vm services:

http://localhost/mws/rest/services?query={"user":"bob","type":"vm"}

To see only services that are NOT associated with bob:

http://localhost/mws/rest/services?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/mws/rest/services?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/mws/rest/services?query={"attributes.moab.job.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/mws/rest/services?query={"attributes.moab.job.resources.procs":{"$lt":2}}

To see services requesting >= 1024 memory:

http://localhost/mws/rest/services?query={"attributes.moab.job.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/mws/rest/services?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/mws/rest/services?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/mws/rest/services?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/mws/rest/services?query={"user":"bob","parent":{"$type":10}}

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

http://localhost/mws/rest/services?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/mws/rest/services?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/mws/rest/services?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/mws/rest/services?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/mws/rest/services?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"
    }
  ]
}

4.24.1.2 Get Single Service

URLs and Parameters

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

Parameter	Required	Valid Values	Description	Example
id	Yes	String	The unique identifier of the service.
name	Yes	String	The name of the service.
show-recursive-vc	No	true	Show extended details about the service's virtual container including nested virtual containers and nested jobs.	show-recursive-vc=true
show-vc	No	true	Show details about the service's virtual container.	show-vc=true

Parameter	Required	Type	Valid Values	Description

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Samples

GET http://localhost/mws/rest/services/bobService.1?

{
  "dateCreated": "2011-12-07 16:03:40 UTC",
  "lastUpdated": "2011-12-07 16:03:40 UTC",
  "name": "bobService.1",
  "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"
  ],
  "parent": null,
  "serviceTemplate":   {
    "id": "4fbd42cfc4aa4c444cc54112",
    "name": "CentosVmPlusStorage"
  },   
  "attributes": {"moab":   {
    "vc": {"id": "vc56"},
    "dependencies": [    {
      "service": "machine0.1",
      "dependency": ["OSStoremachine0.1"]
    }]
  }},
  "id": "4edff0cc6852f709fa777826"
}

4.24.2 Creating Services

The HTTP POST method is used to create a Service.

Quick Reference

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

4.24.2.1 Create Service From Service Template

URLs and Parameters

POST http://localhost/mws/rest/services[?proxy-user=bob]

Parameter	Required	Valid Values	Description	Example
proxy-user	No	String	The name of the user creating the service.	proxy-user=bob

Simple Case

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

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

{
  "user": "steve",
  "account": "cloud",
  "startDateRequested": "2011-11-08 13:18:47 MST",
  "durationRequested": 86400,
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": "Rhel54VmPlusStorage",
    }
  ]
}

Alternatively you can submit:

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

{
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": {
        "name":"Rhel54VmPlusStorage"
      } 
    }
  ]
}

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

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

{
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": {
        "id":"4fbd2d90c4aa4996400bsa5m"
      } 
    }
  ]
}

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.

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

{
  "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/mws/rest/services

{
   "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/mws/rest/services

{
   "user":"bob",
   "account":"cloud",
   "data":[
      {
         "name":"BobsCentosVmPlusStorage",
         "serviceTemplate":"CentosVmPlusStorage",
         "includedServices":[
            "NewStorageToAdd1",
            "NewStorageToAdd2"
         ],
         "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.requestedHosts	Hosts can be added but not removed.
attributes.moab.job.resources	Including procs, mem, disk, and any generic resource.
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"}

4.24.2.2 Create Custom Service

URLs and Parameters

POST http://localhost/mws/rest/services[?proxy-user=bob]

Parameter	Required	Valid Values	Description	Example
proxy-user	No	String	The name of the user creating the service.	proxy-user=bob

Request Body

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

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

{
   "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"
         ],
         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myNetworkStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ]
            },
            "sharedData":{
               "extraAttribute":"Some arbitrary value",
               "extraAttribute2":"Another arbitrary value"
            }
         }
      },
      {
         "name":"myVmContainer",
         "type":"container",
         "includedServices":[
            "myVmWorkflow",
            "myOsStorageWorkflow"
         ],
         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myOsStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ]
            }
         }
      },
      {
         "name":"myVmWorkflow",
         "type":"vm",
         "includedServices":[         ],
         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,
                     "mem":2048,
                     "disk":80
                  },                  
                  "variables":{
                       "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericVM",
                  "requestedHosts":["i16"],
                  "features":["vlan3"]
               }
            }
         }
      },
      {
         "name":"myOsStorageWorkflow",
         "type":"storage",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "template":"OSStorage",
                  "resources":{
                     "OS":2500
                  }
               }
            }
         }
      },
      {
         "name":"myNetworkStorageWorkflow",
         "type":"storage",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "template":"extraStorage",
                  "resources":{
                     "gold":500
                  },
                  "variables":{
                     "mount":"/path/to/mount"
                  }
               }
            }
         }
      },
      {
         "name":"myPmContainer",
         "type":"container",
         "includedServices":[
            "myPmWorkflow"
         ]
      },
      {
         "name":"myPmWorkflow",
         "type":"pm",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,           
                     "mem":2048,
                     "disk":100
                  },
                  "variables":{
                     "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericPM"
               }
            }
         }
      }
   ]
}

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

4.24.3 Modifying Services

The HTTP PUT method is used to modify Services.

Quick Reference

PUT http://localhost/mws/rest/services/<id>
PUT http://localhost/mws/rest/services/<name>

4.24.3.1 Modify Service

URLs and Parameters

PUT http://localhost/mws/rest/services/<id>
PUT http://localhost/mws/rest/services/<name>

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

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Example Request

Only the attributes, status, and statusCode fields may be modified in services. Note that the status field 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

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

{
    "name": "myStorageService",
    "dateCreated": "2012-02-01 14:54:52 UTC",
    "lastUpdated": "2012-02-01 14:54:52 UTC",
    "type": "storage",
    "label": null,
    "user": "john",
    "account": "corp",
    "status": "Done provisioning!",
    "statusCode": 200,
    "includedServices": [],
    "parent": "myVmWithStorage",
    "attributes": {
        "moab": {
            "vc    ": {
                "id": "vc3"
            },
            "job": {
                "id": "Moab.1",
                "template": "extraStorage",
                "resources": {
                    "gold": 2500
                }
            }
        },
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"        
        },
        "mount": "/mnt/myMount",
        "size": "2500"
    },
    "id": "4f29b4abe4b03c2f8e3a1a40"
}

4.24.4 Deleting Services

The HTTP DELETE method is used to delete Services.

Quick Reference

DELETE http://localhost/mws/rest/services/<id>
DELETE http://localhost/mws/rest/services/<name>

4.24.4.1 Delete Service

URLs and Parameters

DELETE http://localhost/mws/rest/services/<id>[?proxy-user=bob]
DELETE http://localhost/mws/rest/services/<name>[?proxy-user=bob]

Parameter	Required	Type	Valid Values	Description
force-delete	No	Boolean	-	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.
proxy-user	No	String	The name of the user deleting the service.	proxy-user=bob

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{}

4.25 Service Templates

This section describes the behavior of the Service Template object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Service Template API contains the type and description of all fields in the ServiceTemplate object. It also contains details regarding which fields are valid during PUT and POST actions.

See Create Service From Service Template to create Services from Service Templates.

The Service Template name has the following constraints:

It must contain only letters, digits, spaces, and these special characters: underscore, comma, hyphen, period, question mark, at sign, tilde, pound sign, square brackets, angle brackets, vertical bar, equals sign, ampersand, parentheses, asterisk, curly braces, grave accent, and dollar sign.

It cannot have the same form as a MongoDB ID (24 characters of 0-9 and a-f)

It must be unique in the database.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/service-templates	Get all Service Templates		Create ServiceTemplate
/rest/service-templates/id or name	Get specified Service Template	Modify ServiceTemplate		Cancel Service Template

4.25.1 Getting Service Templates

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

Quick Reference

GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/service-templates/<id>
GET http://localhost/mws/rest/service-templates/<name>

4.25.1.1 Get All Service Templates

URLs and Parameters

GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Query for specific results.	query={"type":"vm","createdBy":"name"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":1}

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "totalCount": 4,
  "resultCount": 4,
  "results":   [
        {
      "attributes":       {
        "moab": {"job":         {
          "resources": {"OS": 100},
          "template": "OSStorage",
          "variables": {"var1": "variable to be attached to tracking job"}
        }},
        "sharedData":         {
          "custom1": "Custom data to be attached to service",
          "custom2": "More custom data to be attached to service"
        }
      },
      "createdBy": "bob",
      "includedServices": [],
      "label": "Operating System Storage",
      "modified": null,
      "name": "OpSysStorage",
      "tags":       [
        "tag1",
        "tag2",
        "tag3"
      ],
      "type": "storage",
      "version": 0,
      "id": "50d4da1ac4aaceecaf386452"
    },
        {
      "attributes":       {
        "moab": {"job":         {
          "resources": {"gold": 100},
          "template": "extraStorage",
          "variables": {"var1": "variable to be attached to tracking job"}
        }},
        "sharedData":         {
          "custom1": "Custom data to be attached to service",
          "custom2": "More custom data to be attached to service"
        }
      },
      "createdBy": "bob",
      "includedServices": [],
      "label": "Network Storage",
      "modified": null,
      "name": "NetworkStorage",
      "tags":       [
        "tag1",
        "tag2",
        "tag3"
      ],
      "type": "storage",
      "version": 0,
      "id": "50d4da1ac4aaceecaf386453"
    },
        {
      "attributes":       {
        "moab": {"job":         {
          "image": "centos5.5-stateless",
          "resources":           {
            "procs": 1,
            "mem": 1024,
            "disk": 20480
          },
          "template": "genericVM",
          "variables": {"var1": "variable to be attached to tracking job"}
        }},
        "sharedData":         {
          "custom1": "Custom data to be attached to service",
          "custom2": "More custom data to be attached to service"
        }
      },
      "createdBy": "bob",
      "includedServices": [],
      "label": "Centos 5.5 VM",
      "modified": null,
      "name": "Centos55Vm",
      "tags":       [
        "tag1",
        "tag2",
        "tag3"
      ],
      "type": "vm",
      "version": 0,
      "id": "50d4da1ac4aaceecaf386454"
    },
        {
      "attributes":       {
        "moab": {"dependencies": [        {
          "dependency":           [
            "oss",
            "ns"
          ],
          "localName": "cvm"
        }]},
        "sharedData":         {
          "custom1": "Custom data to be attached to service",
          "custom2": "More custom data to be attached to service"
        }
      },
      "createdBy": "bob",
      "includedServices":       [
                {
          "localName": "cvm",
          "serviceTemplate": "Centos55Vm"
        },
                {
          "localName": "oss",
          "serviceTemplate": "OpSysStorage"
        },
                {
          "localName": "ns",
          "serviceTemplate": "NetworkStorage"
        }
      ],
      "label": "Centos 5.5 VM Plus OS and Network Storage",
      "modified": null,
      "name": "Centos55VmPlusStorage",
      "tags":       [
        "tag1",
        "tag2",
        "tag3"
      ],
      "type": "container",
      "version": 0,
      "id": "50d4da1ac4aaceecaf386455"
    }
  ]
}

Querying Service Templates

It is possible to query service templates by one or more fields based on the MongoDB query syntax.

Simple Queries

To see only service templates that are associated with the user "bob", use a query like the following:

http://localhost/mws/rest/service-templates?query={"user":"bob"}

To see only service templates that are of type "vm":

http://localhost/mws/rest/service-templates?query={"type":"vm"}

To see only bob's vm service templates:

http://localhost/mws/rest/service-templates?query={"user":"bob","type":"vm"}

To see only service templates that are NOT associated with bob:

http://localhost/mws/rest/service-templates?query={"user":{"$ne":"bob"}}

More Complex Queries

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

http://localhost/mws/rest/service-templates?query={"user":{"$in":["alice","bob","charlie"]}}

You can also query on embedded JSON objects within the service template JSON. For example, to see service templates requesting 3 processors, do the following:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":3}

Conditional Operators

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

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

To see service templates requesting < 2 processors:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":{"$lt":2}}

To see service templates requesting >= 1024 memory:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.mem":{"$gte":1024}}

Querying Service Templates by Date

To see all service templates modified after July 4, 2011 at 10:30:00 PM Mountain Standard Time (MST):

http://localhost/mws/rest/service-templates?query={"modified":{"$gt":"2011-07-04 22:30:00 MST"}}

To see service templates modified before July 6, 2011 at 12:00 AM Pacific Standard Time (PST):

http://localhost/mws/rest/service-templates?query={"modified":{"$lt":"2011-07-06 00:00:00 PST"}}

To see service templates modified between 12:00 AM and 11:59 PM (inclusive) Eastern Standard Time (EST) on July 5, 2011

http://localhost/mws/rest/service-templates?query={"modified":{"$gte":"2011-07-05 00:00:00 EST","$lte":"2011-07-05 23:59:00 EST"}}

Sorting

See the sorting section in Global URL Parameters.

Limiting the Number of Results

To limit the size of the result set, use the max parameter. For example, to see only 10 of bob's services:

http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10

To see bob's service templates 91-100 when sorted by name in ascending order, combine max with offset as follows:

http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10&offset=90

Retrieving a Subset of Fields

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

http://localhost/mws/rest/service-templates?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/mws/rest/service-templates?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"
    }
  ]
}

4.25.1.2 Get Single Service Template

URLs and Parameters

GET http://localhost/mws/rest/service-templates/<id>
GET http://localhost/mws/rest/service-templates/<name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Response

GET http://localhost/mws/rest/service-templates/Centos55Vm

{
  "attributes":   {
    "moab": {"job":     {
      "image": "centos5.5-stateless",
      "resources":       {
        "procs": 1,
        "mem": 1024,
        "disk": 20480
      },
      "template": "genericVM",
      "variables": {"var1": "variable to be attached to tracking job"}
    }},
    "sharedData":     {
      "custom1": "Custom data to be attached to service",
      "custom2": "More custom data to be attached to service"
    }
  },
  "createdBy": "bob",
  "id": "50d4da1ac4aaceecaf386454",
  "includedServices": [],
  "label": "Centos 5.5 VM",
  "modified": null,
  "name": "Centos55Vm",
  "tags":   [
    "tag1",
    "tag2",
    "tag3"
  ],
  "type": "vm",
  "version": 0
}

GET http://localhost/mws/rest/service-templates/OpSysStorage

{
  "attributes":   {
    "moab": {"job":     {
      "resources": {"OS": 100},
      "template": "OSStorage",
      "variables": {"var1": "variable to be attached to tracking job"}
    }},
    "sharedData":     {
      "custom1": "Custom data to be attached to service",
      "custom2": "More custom data to be attached to service"
    }
  },
  "createdBy": "bob",
  "id": "50d4da1ac4aaceecaf386452",
  "includedServices": [],
  "label": "Operating System Storage",
  "modified": null,
  "name": "OpSysStorage",
  "tags":   [
    "tag1",
    "tag2",
    "tag3"
  ],
  "type": "storage",
  "version": 0
}

GET http://localhost/mws/rest/service-templates/NetworkStorage

{
  "attributes":   {
    "moab": {"job":     {
      "resources": {"gold": 100},
      "template": "extraStorage",
      "variables": {"var1": "variable to be attached to tracking job"}
    }},
    "sharedData":     {
      "custom1": "Custom data to be attached to service",
      "custom2": "More custom data to be attached to service"
    }
  },
  "createdBy": "bob",
  "id": "50d4da1ac4aaceecaf386453",
  "includedServices": [],
  "label": "Network Storage",
  "modified": null,
  "name": "NetworkStorage",
  "tags":   [
    "tag1",
    "tag2",
    "tag3"
  ],
  "type": "storage",
  "version": 0
}

GET http://localhost/mws/rest/service-templates/Centos55VmPlusStorage

{
  "attributes":   {
    "moab": {"dependencies": [    {
      "dependency":       [
        "oss",
        "ns"
      ],
      "localName": "cvm"
    }]},
    "sharedData":     {
      "custom1": "Custom data to be attached to service",
      "custom2": "More custom data to be attached to service"
    }
  },
  "createdBy": "bob",
  "id": "50d4da1ac4aaceecaf386455",
  "includedServices":   [
        {
      "localName": "cvm",
      "serviceTemplate": "Centos55Vm"
    },
        {
      "localName": "oss",
      "serviceTemplate": "OpSysStorage"
    },
        {
      "localName": "ns",
      "serviceTemplate": "NetworkStorage"
    }
  ],
  "label": "Centos 5.5 VM Plus OS and Network Storage",
  "modified": null,
  "name": "Centos55VmPlusStorage",
  "tags":   [
    "tag1",
    "tag2",
    "tag3"
  ],
  "type": "container",
  "version": 0
}

4.25.2 Creating Service Templates

The HTTP POST method is used to create Service Templates.

Quick Reference

POST http://localhost/mws/rest/service-templates

4.25.2.1 Create Service Template

URLs and Parameters

POST http://localhost/mws/rest/service-templates

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows some of the fields that are available when creating a Service Template, along with some sample values.

JSON Request Body

{
   "name":"Centos55Vm",
   "label":"Centos 5.5 VM",
   "type":"vm",
   "createdBy":"bob",
   "tags":["tag1","tag2","tag3"],
   "attributes":{
      "moab":{
         "job":{
            "image":"centos5.5-stateless",
            "resources":{
               "procs":1,
               "mem":1024,
               "disk":20480
            },
            "template":"genericVM",
            "variables":{
               "var1":"variable to be attached to tracking job",
            }
         }
      },
      "sharedData":{
         "custom1":"Custom data to be attached to service",
         "custom2":"More custom data to be attached to service"
      }
   }
}

The following payload is an example of a Service Template that can be used to create an OS storage service.

OS Storage JSON Payload

{
   "name":"OpSysStorage",
   "label":"Operating System Storage",
   "type":"storage",
   "createdBy":"bob",
   "tags":["tag1","tag2","tag3"],
   "attributes":{
      "moab":{
         "job":{
            "resources":{
               "OS":100
            },
            "template":"OSStorage",
            "variables":{
               "var1":"variable to be attached to tracking job"
            }
         }
      },
      "sharedData":{
        "custom1":"Custom data to be attached to service",
        "custom2":"More custom data to be attached to service"
      }
   }
}

The following payload is an example of a Service Template that can be used to create an extra storage service.

Extra Storage JSON Payload

{
   "name":"NetworkStorage",
   "label":"Network Storage",
   "type":"storage",
   "createdBy":"bob",
   "tags":["tag1","tag2","tag3"],
   "attributes":{
      "moab":{
         "job":{
            "resources":{
               "gold":100
            },
            "template":"extraStorage",
            "variables":{
               "var1":"variable to be attached to tracking job"
            }
         }
      },
      "sharedData":{
        "custom1":"Custom data to be attached to service",
        "custom2":"More custom data to be attached to service"
      }
   }
}

The following payload is an example of a Service Template that can be used to create a container service that contains a vm service, an OS storage service, and an extra storage service.

Container JSON Payload

{
   "name":"Centos55VmPlusStorage",
   "label":"Centos 5.5 VM Plus OS and Network Storage",
   "type":"container",
   "createdBy":"bob",
   "tags":["tag1","tag2","tag3"],
   "includedServices":[
      {
         "localName":"cvm",
         "serviceTemplate":"Centos55Vm"
      },
      {
         "localName":"oss",
         "serviceTemplate":"OpSysStorage"
      },
      {
         "localName":"ns",
         "serviceTemplate":"NetworkStorage"
      },
   ],
   "attributes":{
      "moab":{
         "dependencies":[
            {
               "dependency":[
                  "oss","ns"
               ],
               "localName":"cvm"
            }
         ]
      },
      "sharedData":{
        "custom1":"Custom data to be attached to service",
        "custom2":"More custom data to be attached to service"
      }
   }
}

includedServices is a key-value pair of the internal service name and the serviceTemplate. The service name is unique for each service container.

Sample Response

JSON Response for successful POST

{"id":"4f06111184ae2bbfa31fa4c7"}

If the Service Template name is not unique:

JSON Response

{
    "messages": [
        "Service template Rhel54Vm could not be created", 
        "Request has a non-unique service template name 'Rhel54Vm'", 
        "Please correct the request and try again"
    ]
}

If the Service Template included service local name is not unique to this service template:

JSON Response

{
    "messages": [
        "Service template CentOS5 could not be created", 
        "Service template request has a non-unique included service template local name ([SQLServ05])", 
        "Please correct the request and try again"
    ]
}
}

If the Service Template depends on a non-existent included service:

JSON Response

{
    "messages": [
        "Service template NSStor34 could not be created", 
        "Service template requires service template(s) [NewRhel54Vm] which do not exist", 
        "Please correct the request and try again"
    ]
}

If the Service Template depends on more than one non-existent included service:

JSON Response

{
    "messages": [
        "Service template NSStor34 could not be created", 
        "Service template requires service template(s) [NewRhel54Vm, Storage003] which do not exist", 
        "Please correct the request and try again"
    ]
}

If the Service Template name contains a colon:

JSON Response

{
{
    "messages": [
        "Service template Rhel54Vm:C could not be created", 
        "Request contains a colon (:) in the service template name 'Rhel54Vm:C'", 
        "Please correct the request and try again"
    ]
}

If the Service Template name has the same format as a MongoDB ID (Service Template ID):

JSON Response

{
    "messages": [
        "Service template 4f2049a684ae6e1d4f09bd71 could not be created", 
        "Request has a MongoDB Object ID format for the service template name '4f2049a684ae6e1d4f09bd71'", 
        "Please correct the request and try again"
    ]
}

4.25.3 Modifying Service Templates

The HTTP PUT method is used to modify Service Templates.

The modified field is not automatically updated. It will need to be changed by the user.

Quick Reference

PUT http://localhost/mws/rest/service-templates/<id>
PUT http://localhost/mws/rest/service-templates/<name>

4.25.3.1 Modify Service Template

URLs and Parameters

PUT http://localhost/mws/rest/service-templates/<id>
PUT http://localhost/mws/rest/service-templates/<name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Request Body

This is similar to create, except you change the request body to what you need modified.

The request body below shows some of the fields that are available when modifying a Service Template, along with some sample values.

PUT http://localhost/mws/rest/service-templates/Centos55Vm

{
   "label":"Centos 5.5 VM (updated)",
   "createdBy":"newUser",
   "tags":["newTag","newTag2"],
   "attributes":{
      "moab":{
         "job":{
            "image":"centos5.5-stateful",
            "resources":{
               "procs":2,
               "mem":2048,
               "disk":22480
            },
            "template":"genericVM",
            "variables":{
               "newVar":"variable to be attached to tracking job",
            }
         }
      },
      "sharedData":{
         "custom3":"Custom data to be attached to service",
         "custom4":"More custom data to be attached to service"
      }
   }
}

Sample Response

JSON Response for successful PUT

{
   "attributes":{
      "moab":{
         "job":{
            "image":"centos5.5-stateful",
            "resources":{
               "procs":2,
               "mem":2048,
               "disk":22480
            },
            "template":"genericVM",
            "variables":{
               "newVar":"variable to be attached to tracking job"
            }
         }
      },
      "sharedData":{
         "custom3":"Custom data to be attached to service",
         "custom4":"More custom data to be attached to service"
      }
   },
   "createdBy":"newUser",
   "id":"50d4de6bc4aa6ca84bbe9be4",
   "includedServices":[
   ],
   "label":"Centos 5.5 VM (updated)",
   "modified":"2012-12-21 15:12:01 MST",
   "name":"Centos55Vm",
   "tags":[
      "newTag",
      "newTag2"
   ],
   "type":"vm",
   "version":0
}

If the Service Template depends on a non-existent included service:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Service template requires service template(s) [RhOs045] which do not exist",
        "Please correct the request and try again"
    ]
}

If the Service Template depends on more than one non-existent included service:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Service template requires service template(s) [Stor45, Stor12] which do not exist",
        "Please correct the request and try again"
    ]
}

An attempt to modify the Service Template name to an existing template name:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Request has a non-unique service template name 'Stor44'"
    ]
}

4.25.4 Deleting (Canceling) Service Templates

The HTTP DELETE method is used to delete Service Templates.

Quick Reference

DELETE http://localhost/mws/rest/service-templates/<id>
DELETE http://localhost/mws/rest/service-templates/<name>

4.25.4.1 Cancel Service Template

URLs and Parameters

DELETE http://localhost/mws/rest/service-templates/<id|name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Response

A successful deletion

JSON Response

{}

If the Service Template ID does not exist

JSON Response

{
    "messages": [
        "Service template not found with ID '4f2049a684ae6e1d4f09bd71'"
    ]
}

If the Service Template name does not exist

JSON Response

{
    "messages": [
        "Service template not found with ID 'Stor44'"
    ]
}

If other Service Templates depend on the one being deleted

JSON Response

{
    "messages": [
        "Service template Cent5 could not be deleted", 
        "Service template 'Cent5' cannot be deleted because Service template '[Cent5]' depends on it "
    ]
}

4.26 Standing Reservations

This section describes behavior of the Standing Reservation object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Standing Reservation API contains the type and description of all fields in the Standing Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/standing-reservations	Get all standing reservations
/rest/standing-reservations/id	Get specified standing reservation

4.26.1 Getting Standing Reservations

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

Quick Reference

GET http://localhost/mws/rest/standing-reservations/<id>

4.26.1.1 Get All Standing Reservations

URLs and Parameters

GET http://localhost/mws/rest/standing-reservations

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/standing-reservations?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "sr1"},
    {"id": "sr2"},
    {"id": "sr3"}
  ]
}

4.26.1.2 Get Single Standing Reservation

URLs and Parameters

GET http://localhost/mws/rest/standing-reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "access": "DEDICATED",
  "accounts": ["account1"],
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "EQUAL",
    "type": "USER",
    "value": "adaptive",
  }],
  "chargeAccount": "account2",
  "chargeUser": "user2",
  "classes": ["class1"],
  "clusters": ["cluster1"],
  "comment": "comment",
  "days": ["Monday"],
  "depth": 2,
  "disabled": false,
  "endOffset": 86415,
  "flags": ["ALLOWJOBOVERLAP"],
  "groups": ["group1"],
  "hosts": ["host1"],
  "id": "fast",
  "jobAttributes": ["TEMPLATESAPPLIED"],
  "maxJob": 2,
  "maxTime": 0,
  "messages": ["message1"],
  "nodeFeatures": ["feature1"],
  "os": "Ubuntu 10.04.3",
  "owner":   {
    "name": "root",
    "type": "USER"
  },
  "partition": "ALL",
  "period": "DAY",
  "procLimit":   {
    "qualifier": "<=",
    "value": 5
  },
  "psLimit":   {
    "qualifier": "<=",
    "value": 60
  },
  "qoses": ["qos1"],
  "reservationAccessList": [],
  "reservationGroup": "group2",
  "resources":   {
    "PROCS": -1,
    "tapes": 1
  },
  "rollbackOffset": 43200,
  "startOffset": 347040,
  "taskCount": 0,
  "tasksPerNode": 0,
  "timeLimit": -1,
  "triggers": [],
  "type": "type1",
  "users": ["user1"]
}

4.27 Usage Records

This section describes behavior of the Usage Record object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Usage Record API contains the type and description of all fields in the UsageRecord object.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/usage-records	Get all usage-records
/rest/usage-records/id	Get specified usage-record

4.27.1 Getting Usage Records

The HTTP GET method is used to retrieve Usage Record information.

Quick Reference

GET http://localhost/mws/rest/usage-records?proxy-user=<USER>[&custom-fields=QualityOfService][&query={"id":"2"}][&sort={"Stage":-1}]
GET http://localhost/mws/rest/usage-records/<id>?proxy-user=<USER>[&custom-fields=QualityOfService]

4.27.1.1 Get All Usage Records

URLs and Parameters

GET http://localhost/mws/rest/usage-records?proxy-user=<USER>[&custom-fields=QualityOfService][&query={"id":"2"}][&sort={"stage":-1}]

Parameter	Required	Valid Values	Description	Example
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
custom-fields	No	Comma-Separated String	Includes custom MAM usage-record attributes.	custom-fields=QualityOfService
query	No	JSON	Query for specific results.	query={"priority":"2","allocation.active":"false"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"stage":-1}

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/usage-records?proxy-user=amy&custom-fields=qualityOfService&fields=id,qualityOfService,type,instance

{
  "totalCount": 8,
  "resultCount": 2,
  "results":   [
        {
      "id": 1,
      "qualityOfService": "premium",
      "type": "Job",
      "instance": "job.123"
    },
        {
      "qualityOfService": "premium",
      "id": 2,
      "type": "Job",
      "instance": "job.1234"
    }
  ]
}

4.27.1.2 Get Single Usage Record

URLs and Parameters

GET http://localhost/mws/rest/usage-records/<id>?proxy-user=<USER>[&custom-fields=QualityOfService]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	Yes	String	Perform action as defined MAM user.	proxy-user=amy
custom-fields	No	Comma-Separated String	Includes custom MAM usage-record attributes.	custom-fields=QualityOfService

See Global URL Parameters for available URL parameters.

Sample Responses

GET http://localhost/mws/rest/usage-records/1?proxy-user=amy&custom-fields=qualityOfService

{
  "id": 1,
  "qualityOfService": "premium",
  "type": "Job",
  "instance": "job.123",
  "charge": 0,
  "stage": "Create",
  "quote": "",
  "user": "doug",
}

4.28 Virtual Containers

This section describes behavior of the Virtual Container object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Virtual Container API contains the type and description of all fields in the Virtual Container object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/vcs	Get all Virtual Containers		Create Virtual Container
/rest/vcs/id	Get specified Virtual Container	Modify Virtual Container		Destroy Virtual Container

4.28.1 Getting Virtual Containers

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

Quick Reference

GET http://localhost/mws/rest/vcs/<id>

4.28.1.1 Get All Virtual Containers

URLs and Parameters

GET http://localhost/mws/rest/vcs

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/vcs?fields=id

{
  "totalCount": 5,
  "resultCount": 5,
  "results":   [
    {"id": "vc3"},
    {"id": "vc1"},
    {"id": "vc4"},
    {"id": "vc5"},
    {"id": "vc2"}
  ]
}

4.28.1.2 Get Single Virtual Container

URLs and Parameters

GET http://localhost/mws/rest/vcs/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "root"
  }],
  "createDate": "2011-11-15 14:01:40 UTC",
  "creator": "root",
  "description": "vc2",
  "flags": ["DESTROYWHENEMPTY"],
  "id": "vc2",
  "jobs": [
    {"id":"Moab.1"}
  ],
  "nodes": [
    {"id":"node1"}
  ],
  "owner":   {
    "name": "root",
    "type": "USER"
  },
  "reservations": [
    {"id":"system.1"}
  ],
  "variables":   {
    "a": "b",
    "c": "d"
  },
  "virtualContainers": [
    {"id":"vc3"}
  ],
  "virtualMachines": [
    {"id":"vm1"}
  ]
}

4.28.2 Creating Virtual Containers

The HTTP POST method is used to create Virtual Containers.

Quick Reference

POST http://localhost/mws/rest/vcs[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.28.2.1 Create Virtual Container

URLs and Parameters

POST http://localhost/mws/rest/vcs[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when creating a Virtual Container, along with some sample values.

JSON Request Body

{
  "description": "ted's vc",
  "owner":   {
    "name": "ted",
    "type": "USER"
  },
  "requiredStartDate": "2012-11-08 13:18:47 MST",
  "flags": ["HOLDJOBS"],
  "virtualContainers":     [
    {"id": "vc93"},
    {"id": "vc94"}
  ],
}

Sample Response

JSON Response for successful POST

{"id": "vc8"}

Restrictions

When creating a Virtual Container, the creator field is set to the value of proxy-user (if set) or owner.name (if set), with proxy-user taking precedence. However, setting the creator field works only if you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

You can set the creator field as shown above, but you can never change it.

4.28.3 Modifying Virtual Containers

The HTTP PUT method is used to modify Virtual Containers.

Quick Reference

PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.28.3.1 Modify Virtual Container

URLs and Parameters

PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
change-mode	Yes	String	add	Add the given objects (jobs, VMs, etc) to the objects that already exist.
			remove	Delete the given objects from the objects that already exist.
			set	Modify the attributes of the virtual container itself and not the associated objects.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

Here are three examples of Virtual Container updates: add objects, remove objects, and update attributes. In each case, the examples below show all the fields that are available, along with some sample values.

Add objects with /rest/vcs/vc1?change-mode=add

{
  "jobs":     [
    {"id": "Moab.37"},
    {"id": "Moab.38"}
  ],
  "nodes":     [
    {"id": "node1"},
    {"id": "node2"}
  ],
  "reservations":     [
    {"id": "system.48"},
    {"id": "system.49"}
  ],
  "virtualContainers":     [
    {"id": "vc93"},
    {"id": "vc94"}
  ],
  "virtualMachines":     [
    {"id": "vm2"},
    {"id": "vm4"}
  ]
}

Remove objects with /rest/vcs/vc1?change-mode=remove

{
  "jobs":     [
    {"id": "Moab.37"},
    {"id": "Moab.38"}
  ],
  "nodes":     [
    {"id": "node1"},
    {"id": "node2"}
  ],
  "reservations":     [
    {"id": "system.48"},
    {"id": "system.49"}
  ],
  "virtualContainers":     [
    {"id": "vc93"},
    {"id": "vc94"}
  ],
  "virtualMachines":     [
    {"id": "vm2"},
    {"id": "vm4"}
  ]
}

Modify VC attributes with /rest/vcs/vc1?change-mode=set

{
  "description": "This is a new description.",
  "flags": ["HOLDJOBS"],
  "owner":     {
    "name": "ted",
    "type": "USER"
  },
  "variables":     {
    "a": "b",
    "c": "d"
  }
}

Sample Responses

These messages may not match the messages returned from Moab exactly, but they are given as examples of the structure of the responses.

JSON response for adding objects

{
  "messages":[
    "job '147' added to VC 'vc3'",
    "job 'Moab.1' added to VC 'vc3'"
  ]
}

JSON response for removing objects

{
  "messages":[
    "job '147' removed from VC 'vc3'",
    "job 'Moab.1' removed from VC 'vc3'"
  ]
}

JSON response for updating attributes

{"messages":["VC 'vc3' successfully modified"]}

Restrictions

You can change the ACL Rules on a Virtual Container, but not using this resource. See Create or Update ACLs.

4.28.4 Destroying Virtual Containers

The HTTP DELETE method is used to destroy Virtual Containers.

Quick Reference

DELETE http://localhost/mws/rest/vcs/<id>[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.28.4.1 Destroy Virtual Container

URLs and Parameters

DELETE http://localhost/mws/rest/vcs/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

4.29 Virtual Machines

This section describes behavior of the Virtual Machine object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.

The Virtual Machine API has changed with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2 in order to behave as documented.
In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Virtual Machine API contains the type and description of all fields in the Virtual Machine object. It also contains details regarding which fields are valid during PUT actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/vms	Get all VMs
/rest/vms/name	Get specified VM	Modify VM		Destroy VM

4.29.1 Getting Virtual Machines

The HTTP GET method is used to retrieve Virtual Machine information.

Quick Reference

GET http://localhost/mws/rest/vms/<name>?api-version=2

4.29.1.1 Get All Virtual Machines

URLs and Parameters

GET http://localhost/mws/rest/vms?api-version=2

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"migrationDisabled":true}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

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

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/vms?api-version=2&fields=name

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"name": "vm1"},
    {"name": "vm2"},
    {"name": "vm3"}
  ]
}

4.29.1.2 Get Single Virtual Machine

URLs and Parameters

GET http://localhost/mws/rest/vms/<name>?api-version=2

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "name": "vm3",
  "description": null,
  "host": {"name": "hv2"},
  "hostnames": [],
  "ipAddress": "10.0.0.5",
  "migrationDisabled": false,
  "lastUpdatedDate": "2012-10-11 17:46:32 UTC",
  "startDate": "2012-09-25 18:12:23 UTC",
  "trackingJob": null,
  "metrics": {"watts": 200},
  "variables": {},
  "resourceManagers": [  {
    "name": "msm",
    "isMaster": true,
    "stateReported": "Active"
  }],
  "operatingSystem":   {
    "image": "stateless1",
    "imageExpected": null,
    "imageLastUpdatedDate": null,
    "imagesAvailable": []
  },
  "states":   {
    "powerState": "On",
    "powerStateExpected": null,
    "powerStateLastUpdatedDate": null,
    "state": "Idle",
    "stateLastUpdatedDate": "2012-10-11 17:15:01 UTC",
    "subState": null,
    "subStateLast": null,
    "subStateLastUpdatedDate": null
  },
  "resources":   {
    "processors":     {
      "configured": 1,
      "dedicated": 0,
      "available": 1
    },
    "memory":     {
      "configured": 512,
      "dedicated": 0,
      "available": 512
    },
    "disk":     {
      "configured": 1024,
      "dedicated": 0,
      "available": 1024
    },
    "swap":     {
      "configured": 0,
      "dedicated": 0,
      "available": 0
    }
  },
  "triggers": [],
  "virtualContainers": []
}

4.29.2 Modifying Virtual Machines

The HTTP PUT method is used to modify Virtual Machines.

Quick Reference

PUT http://localhost/mws/rest/vms/<name>?api-version=2[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.29.2.1 Modify Virtual Machine

URLs and Parameters

PUT http://localhost/mws/rest/vms/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Virtual Machine, along with some sample values.

JSON Request Body for VM Modify

{
  "metrics": {"pwatts": 211},
  "migrationDisabled": true,
  "operatingSystem": {"image": "esx4.1"},
  "states":   {
    "powerState": "On",
    "state": "Running"
  },
  "triggers": [{"name": "trigger_id"}],
  "variables":   {
    "key": "value",
    "arbitrary text key": "more value"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["successfully updated VM variables"]}

4.29.2.2 Migrate Virtual Machine

URLs and Parameters

PUT http://localhost/mws/rest/vms/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows how to migrate a Virtual Machine to a host (hypervisor) with name "hv2".

JSON Request Body for VM Migrate to a specific host

{"host": {"name": "hv2"}}

The request body below shows how to migrate a Virtual Machine to any available host by using the destination name of ANY, which for this operation is a reserved word.

JSON Request Body for VM Migrate to any available host

{"host": {"name": "ANY"}}

Sample Response

The HTTP response code for this operation is 202 Accepted. See the responses section for more information.

JSON Response

{"jobId": "vm-migrate1"}

Restrictions

If a migration is requested by setting the host as shown in the above examples, any other properties in the same request body will be ignored.

4.29.3 Destroying Virtual Machines

The HTTP DELETE method is used to destroy Virtual Machines.

Quick Reference

DELETE http://localhost/mws/rest/vms/<name>?api-version=2[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.29.3.1 Destroy Virtual Machine

URLs and Parameters

DELETE http://localhost/mws/rest/vms/<name>?api-version=2[&proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
name	Yes	String	-	The name of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{"jobId": "vmdestroy-26"}

The jobId in the response identifies the job that will destroy the virtual machine.

<< 3API Documentation

5Reporting Framework >>

4 Resources

Table of Contents

4 Resources

4.1 Access Control Lists

Supported Methods

4.1.1 Getting ACLs

Supported Objects

4.1.2 Creating or Updating ACLs

Quick Reference

4.1.2.1 Create or Update ACL

URLs and Parameters

Request Body

Sample Response

Samples

Restrictions

4.1.3 Deleting ACLs

Quick Reference

4.1.3.1 Delete ACL

URLs and Parameters

Sample Response

Restrictions

4.2 Accounts

Supported Methods

4.2.1 Getting Accounts

Quick Reference

4.2.1.1 Get All Accounts

URLs and Parameters

Sample Response

4.2.1.2 Get Single Account

URLs and Parameters

Sample Responses

4.3 Credentials

Supported Methods

4.3.1 Getting Credentials

Quick Reference

4.3.1.1 Get All Account Credentials

URLs and Parameters

Sample Response

4.3.1.2 Get All Class Credentials

URLs and Parameters

Sample Response

4.3.1.3 Get All Group Credentials

URLs and Parameters

Sample Response

4.3.1.4 Get All QoS Credentials

URLs and Parameters

Sample Response

4.3.1.5 Get All User Credentials

URLs and Parameters

Sample Response

4.4 Diagnostics

Supported Methods

4.4.1 Version and Build Information

Quick Reference

URLs and Parameters

Sample Response

4.4.2 Diagnose Authentication

Quick Reference

URLs and Parameters

Sample Response

4.4.3 Connection Health Information

Quick Reference

4.4.3.1 Get Health Summary

URLs and Parameters

Sample Response

4.4.3.2 Get Health Detail

URLs and Parameters

Sample Response

4.4.4 LDAP Information

Quick Reference

URLs and Parameters

Sample Response

4.5 Events

Supported Methods

Configuration

Causing events.log to Roll Based on a Time Window

Configuring events.log to Roll Based on File Size Threshold

Additivity

Deleting Old Events

4.5.1 Getting Events