4.16 Plugins

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

The 8.4.12 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/<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

In this section:

Getting Plugins
Creating Plugins
- Create Plugin
Modifying Plugins
- Modify Plugin
- Trigger Plugin Poll
Deleting Plugins
- Delete Plugin
Accessing Plugin Web Services
- Access a Plugin Web Service

4.16.1 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 https://localhost:8080/mws/rest/plugins?api-version=3
GET https://localhost:8080/mws/rest/plugins/<id>?api-version=3
GET https://localhost:8080/mws/rest/plugins/reporting-jobs/<jobName>?api-version=3
GET https://localhost:8080/mws/rest/plugins/reporting-nodes/<nodeName>?api-version=3

4.16.1.A Get All Plugins

URLs and Parameters

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

See 3.3 Global URL Parameters for available URL parameters.

Sample Response

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

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

4.16.1.B Get All Plugins Reporting Object

URLs and Parameters

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

Parameter	Required	Type	Value	Description
jobName	Yes	String	--	The name of the job to query by.
nodeName	Yes	String	--	The name of the node to query by.

See 3.3 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 or node (see 6.2.9 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 6.1.6 Data Consolidation.

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

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

4.16.1.C Get Single Plugin

URLs and Parameters

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

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

See 3.3 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":"2024-12-02 17:28:52 UTC",
  "lastPollDate":"2024-12-02 17:28:22 UTC"
}

4.16.2 Creating Plugins

The HTTP POST method is used to create Plugins.

Quick Reference

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

4.16.2.A Create Plugin

URLs and Parameters

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

See 3.3 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 6.5 Plugin Management) does not support editing or viewing any configuration data values other than strings.

4.16.3 Modifying Plugins

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

Quick Reference

PUT https://localhost:8080/mws/rest/plugins/<id>?api-version=3
POST https://localhost:8080/mws/rest/plugins/<id>/poll?api-version=3

4.16.3.A Modify Plugin

URLs and Parameters

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

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

See 3.3 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.16.3.B Trigger Plugin Poll

URLs and Parameters

POST https://localhost:8080/mws/rest/plugins/<id>/poll?api-version=3

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

See 3.3 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 6.5.6 Monitoring and Lifecycle Controls.

Request Body

No request body is required.

Sample Response

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

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

4.16.4 Deleting Plugins

The HTTP DELETE method is used to delete Plugins.

Quick Reference

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

4.16.4.A Delete Plugin

URLs and Parameters

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

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

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

4.16.5.A Access a Plugin Web Service

URLs and Parameters

GET https://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
POST https://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
PUT https://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3
DELETE https://localhost:8080/mws/rest/plugins/<id>/services/<serviceName>[/<objectId>]?api-version=3

Parameter	Required	Type	Value	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 3.3 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 can 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 6.1.4 Custom Web Services), we recommend using 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 4.17 Plugin Types for the requested plugin for available web services, request parameters, and expected output.