(Click to open topic with navigation)

Moab Web Services > Resources > Plugins

Plugins

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

The Fields: Plugins reference 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 Plugin --
/rest/plugins/reporting-jobs/<jobName>?api-version=3 Get All Plugins Reporting Object -- -- --
/rest/plugins/reporting-nodes/<nodeName>?api-version=3 Get All Plugins Reporting Object -- -- --
/rest/plugins/reporting-vms/<vmName>?api-version=3 Get All Plugins Reporting Object -- -- --
/rest/plugins/<id> Get Single Plugin Modify Plugin -- Delete Plugin
/rest/plugins/<id>/poll -- -- Trigger Plugin Poll --
/rest/plugins/<id>/services/<serviceName> Access a Plugin Web Service Access a Plugin Web Service Access a Plugin Web Service Access a Plugin Web Service

This topic contains these sections:

Getting Plugins

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

Quick reference

GET http://localhost:8080/mws/rest/plugins?api-version=3
GET http://localhost:8080/mws/rest/plugins/<id>?api-version=3
GET http://localhost:8080/mws/rest/plugins/reporting-jobs/<jobName>?api-version=3
GET http://localhost:8080/mws/rest/plugins/reporting-nodes/<nodeName>?api-version=3
GET http://localhost:8080/mws/rest/plugins/reporting-vms/<vmName>?api-version=3

Get All Plugins

URLs and parameters

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

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/plugins?api-version=3&fields=id
------------------------------------

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

Get All Plugins Reporting Object

URLs and parameters

GET http://localhost:8080/mws/rest/plugins/reporting-jobs/<jobName>?api-version=3
GET http://localhost:8080/mws/rest/plugins/reporting-nodes/<nodeName>?api-version=3
GET http://localhost:8080/mws/rest/plugins/reporting-vms/<vmName>?api-version=3
Parameter Required Type Valid values Description
jobName Yes String -- The name of the job to query by.
nodeName Yes String -- The name of the node to query by.
vmName Yes String -- The name of the VM to query by.

See Global URL Parameters for available URL parameters.

Sample response

This built-in query returns the same information as Get All Plugins, but filters the items to only plugins that are currently reporting the specified job, node, or VM (see Reporting State Data). The list is sorted ascending by the precedence field. In other words, the most authoritative plugin for the report is listed first. For more information, see Data Consolidation.

GET http://localhost:8080/mws/rest/plugins/reporting-nodes/node1?api-version=3&fields=id
------------------------------------

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

Get Single Plugin

URLs and parameters

GET http://localhost:8080/mws/rest/plugins/<id>?api-version=3
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"
}

Creating Plugins

The HTTP POST method is used to create Plugins.

Quick reference

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

Create Plugin

URLs and parameters

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

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, because the user interface (see Plugin Management) does not support editing or viewing any configuration data values other than strings.

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:8080/mws/rest/plugins/<id>?api-version=3
POST http://localhost:8080/mws/rest/plugins/<id>/poll?api-version=3

Modify Plugin

URLs and parameters

PUT http://localhost:8080/mws/rest/plugins/<id>?api-version=3
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'"]}

Trigger Plugin Poll

URLs and parameters

POST http://localhost:8080/mws/rest/plugins/<id>/poll?api-version=3
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 Monitoring and Lifecycle Controls.

Request body

No request body is required.

Sample response

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

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

Deleting Plugins

The HTTP DELETE method is used to delete Plugins.

Quick reference

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

Delete Plugin

URLs and parameters

DELETE http://localhost:8080/mws/rest/plugins/<id>?api-version=3
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"]}

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:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
POST http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
PUT http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
DELETE http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3

Access a Plugin Web Service

URLs and parameters

GET http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
POST http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
PUT http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
DELETE http://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the object.
objectId No String -- An arbitrary ID parameter that will be passed to the web service.
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 (see Custom Web Services), 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 Plugin Types for the requested plugin for available web services, request parameters, and expected output.

Related Topics 

© 2015 Adaptive Computing