User Defined REST Poller Details - RESTful API – Entuity

Summary:

List details of, modify or delete a specified user defined REST poller.

URL:

http(s)://{server hostname}/api/ud/pollers/[id]

User defined REST polling

Methods summary

GET Method - list details of a specified user defined REST poller
PUT Method - modify an existing user defined REST poller
DELETE Method - delete a user defined REST poller

GET Method detail

Lists details about the specified user defined REST poller.

Response:

Name	Description
pollerId	unique ID of this poller on this specific Entuity server.
pollerType	type of poller. Currently only "API" is supported, but "SNMP" may be supported in future versions.
pollerName	unique poller name, without spaces. Alpha numeric characters and underscores are allowed but other characters are invalid. Should start with udp_ and this will be added if missing.
creationTime	unix timestamp for when this poller was first created.
createdBy	name of Entuity user that created this poller.
lastModified	unix timestamp for when this poller was last modified.
version	version number.
revision	revision number. This is incremented each time the user edits this poller.
priority	number determining collector priority.
serverId	this field is currently redundant and will always be null.
errorCount	number of errors while creating this poller. Should be zero or null for a successful poller.
pollerDef	details of this poller's definition.
pollerType	type of poller. Currently only "API" is supported, but "SNMP" may be supported in future versions.
pollerCollectorType	sub-type of poller. Currently only "ASSOCIATED_COMPONENT" is supported.
pollerId	ID of the poller.
version	version number.
revision	revision number. This is incremented each time the user edits this poller.
priority	optional number determining collector priority. Can be omitted.
contextTypeName	StormWorks type name of the type of object this poller will connect to. This will be a device or associated device type such as "DeviceEx", "PingOnlyDevice" or "MerakiDevice".
componentTypeDetails	specifies details of the component type of object(s) that will be created by the poller. For ASSOCIATED_COMPONENT pollers (the only ones currently supported) the typeName field should be the same as the pollerName, and a typeDisplayName field should also be supplied to specify the display name for the single associated object.
componentTypeDetails/typeName	unique StormWorks type name for the component type.
componentTypeDetails/typeDisplayName	display name that will be given to the associated object of the device. It can have spaces in the name. It does not need to be unique but it is best if it is.
description	description of the association.
visibility	optional. Visibility level for this attribute. Can be one of "SHORTLISTED", "VISIBLE", "ADVANCED" or "HIDDEN".
displayNameAttr	display name used for this attribute in the UI (dashboards, reports etc).
setAsParentsChildren	flag to indicate that the objects created by this poller should count as the children of the context object in e.g. the Explorer tree. It is only available if the context type is a user defined one, so is currently redundant.
obtainRate	frequency (in seconds) that the data will be polled at. Usually restricted to the following values: 60, 300, 600, 900, 1200, 1800, 3600, 21600, 43200, 86400
keepTime	length of time (in seconds) which polled data will be retained. Usually restricted to the following values: 3600, 86400, 604800, 1209600, 3024000, 16934400
steps	list of the poller steps within this poller.
stepName	name of the step. Must be unique within the poller and consists only of alphanumeric characters and underscores.
authDetails	authentication method for this poller step.
authType	authentication type. One of "AUTH_NONE", "AUTH_FIXED_CREDENTIALS" or "AUTH_DEVICE_CREDENTIALS"
endpointURL	example URL entered in the UI. Can be omitted or left blank for REST API calls.
host	host to connect to. Use "${host}" to automatically use the host of the device the poller is running under, or a fixed string to always connect to the same host.
apiPath	path part of the Rest API URL, including any query part and any interpolated values of the form ${ placeholder }.
methodType	HTTP request method, either "GET" or "POST".
port	port number to connect to. Can be omitted for the default HTTP or HTTPS ports 80 / 443 based on the useSSL value.
steps/useSSL	either "true" or "false" depending on whether the request should be made using HTTPS or HTTP.
steps/pathToData	optional starting point for all attribute source paths in this step. Can be omitted or left blank if the full path is specified in each attribute's sourcePath.
steps/attributeMappings	information on the attributes added by this step.
steps/attributeMappings/nameToMapping	a map from attribute name to attribute definition. The key for each entry should be unique and match the value of the swAttrName in the value part. Attribute names must start with udp_ and this will be added automatically if omitted.
steps/attributeMappings/nameToMapping/swAttrName	unique StormWorks attribute name for this attribute. Should be prepended with udp_ and the poller name so that it only needs to be unique within this poller
steps/attributeMappings/nameToMapping/swAttrDisplayName	display name for this attribute. Does not need to be unique but usually best if it is.
steps/attributeMappings/nameToMapping/dataType	data type to store the attribute value as. Valid values include "string", "float", "integer". If omitted will default to "string".
steps/attributeMappings/nameToMapping/displayType	optional. How the value will be displayed in the UI. A displayType can allow the data to be shown including e.g. appropriate units and formatting.
steps/attributeMappings/nameToMapping/visibility	optional. Visibility level for this attribute. Can be one of "SHORTLISTED", "VISIBLE", "ADVANCED" or "HIDDEN".
steps/attributeMappings/nameToMapping/graphable	optional. If true this attribute will be considered a valid choice for display on a chart, if false it will not. If omitted then a default will be determined based upon the data type (numeric values are graphable, strings are not).
steps/attributeMappings/nameToMapping/enumerable	optional. If true this attribute will be considered to have a limited enumeration of values. This makes it eligible for example for being used as the data to drive the groupings of a generic pie chart.
steps/attributeMappings/nameToMapping/searchable	optional. If true this attribute will be searchable using the search tool.
steps/attributeMappings/nameToMapping/statusMap	optional. A mapping of value on to status category which is only relevant for attributes that are used as the status of the object they are on.
steps/attributeMappings/nameToMapping/sourcePath	path to the data for this attribute within the JSON or XML returned by the API request. This can be simply the name of a property in the JSON or a more complex expression.
steps/attributeMappings/nameToMapping/eventInfo	optional. Information on what if any events to raise when this attribute's value changes.
steps/attributeMappings/nameToMapping/eventInfo/eventMode	either "NONE", "THRESHOLD" or "STATUS"
steps/attributeMappings/nameToMapping/eventInfo/mapping	map of values to event sever

Example:

INPUT
curl -u admin:admin https://localhost/api/ud/pollers/1

OUTPUT
{
  "pollerId" : 1,
  "pollerType" : "API",
  "pollerName" : "AssocComp",
  "creationTime" : 1638371491,
  "createdBy" : "admin",
  "lastModified" : 1638371491
  "modifiedBy" : "admin",
  "version" : 1.0,
  "revision" : 1,
  "priority" : 2002.0,
  "serverId" : "400e61cf-873d-4504-8784-f9075a9a5150",
  "errorCount" : 0,
  "pollerDef" : {
    "pollerType" : "API"
    "pollerCollectorType" : "ASSOCIATED_COMPONENT",
    "pollerId" : 1,
    "pollerName" : "AssocComp",
    "version" : 1.0,
    "revision" : 1,
    "priority" : 2002.0,
    "contextTypeName" : "PingOnlyDevice",
    "componentTypeDetails" : {
      "typeName" : "udp_serviceInfo",
      "typeDisplayName" : "Service Info",
      "keyAttribute" : "uDCIndexUserDefined",
      "setAsParentsChildren" : false
    },
    "steps" : [ {
      "stepName" : "AttrPolling",
      "authDetails" : {
        "authType" : "AUTH_DEVICE_CREDENTIALS"
      },
      "endpointURLSample" : "localhost/api/service/1004?media=json",
      "host" : "${host}",
      "apiPath" : "/api/service/1004?media=json",
      "methodType" : "GET",
      "useSSL" : false,
      "pathToData" : "info",
      "attributeMappings" : {
        "nameToMapping" : {
          "udp_serviceName" : {
            "swAttrName" : "udp_serviceName",
            "swAttrDisplayName" : "Service Name",
            "dataType" : "string",
            "sourcePath" : "serviceName"
          }
        }
      }
    } ]
  }
}

PUT Method detail

Modifies the parameters of the specified user defined REST poller.

Request:

Request has the same structure as the 'POST Method' request for adding a new user defined REST poller. You need to specify only properties you want to be changed.

Response:

On success returns the poller definition for the newly updated poller.

Example:

INPUT
curl -u -k admin:admin https://localhost/api/ud/pollers/1 -X PUT -H "content-type:application/json" -d '
{
  "pollerName": "ServiceInfoOnPingDevice"
}'

OUTPUT
{
  "pollerId" : 1,
  "pollerType" : "API",
  "pollerName" : "ServiceInfoOnPingDevice",
  "creationTime" : 1638461440,
  "createdBy" : "admin",
  "lastModified" : 1638461705,
  "modifiedBy" : "admin",
  "version" : 1.0,
  "revision" : 2,
  "priority" : 2000.0,
  "serverId" : "400e61cf-873d-4504-8784-f9075a9a5150",
  "errorCount" : 0,
  "pollerDef" : {
  "pollerType" : "API",
  "pollerCollectorType" : "ASSOCIATED_COMPONENT",
  "pollerId" : 1,
  "pollerName" : "ServiceInfoOnPingDevice",
  "version" : 1.0,
  "revision" : 2,
  "priority" : 2000.0,
  "contextTypeName" : "PingOnlyDevice",
  "componentTypeDetails" : {
  "typeName" : "udp_serviceInfo",
  "typeDisplayName" : "Service Info",
  "keyAttribute" : "uDCIndexUserDefined",
  "setAsParentsChildren" : false
},
  "steps" : [ {
    "stepName" : "AttrPolling",
    "authDetails" : {
    "authType" : "AUTH_DEVICE_CREDENTIALS"
    },
  "endpointURLSample" : "localhost/api/service/1004?media=json",
  "host" : "${host}",
  "apiPath" : "/api/service/1004?media=json",
  "methodType" : "GET",
  "useSSL" : false,
  "pathToData" : "info",
  "attributeMappings" : {
    "nameToMapping" : {
      "udp_serviceName" : {
        "swAttrName" : "udp_serviceName",
        "swAttrDisplayName" : "Service Name",
        "dataType" : "string",
        "sourcePath" : "serviceName"
        }
      }
    }
  } ]
}
}

DELETE Method detail

Deletes the selected user defined poller.

Request:

No additional parameters needed.

Response:

Returns a list of error information. This will be empty, i.e. just [] in the case of success.

Example:

INPUT
curl -u admin:admin https://localhost/api/ud/pollers/1 -X DELETE

OUTPUT
[ ]

Articles in this section

User Defined REST Poller Details - RESTful API

Summary:

URL:

Methods summary

GET Method detail

PUT Method detail

DELETE Method detail

Comments

Articles in this section

Summary:

URL:

Methods summary

GET Method detail

PUT Method detail

DELETE Method detail

Related articles