Articles in this section

See more

User Defined REST Pollers - RESTful API

Avatar
Stuart Hill
  • Updated
Follow

Summary:

List the current user defined REST pollers on the specified Entuity server, add new user defined REST pollers.

URL:

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

 

User defined REST polling

 

Methods summary

GET Method detail

POST Method detail

 

 

Methods summary

  • GET Method - lists the current user defined REST pollers on the Entuity server.
  • POST Method - create a new user defined REST poller.

 

 

GET Method detail

Lists the user defined REST pollers on the Entuity server.

Response:

Response includes a list of the user defined REST pollers on the Entuity server.

Example:

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

OUTPUT
{
  "items" : [ {
    "pollerId" : 1,
    "pollerType" : "API",
    "pollerName" : "AssocComp",
    "creationTime" : 1638371491,
    "createdBy" : "admin",
    "lastModified" : 1638371491,
    "modifiedBy" : "admin",
    "version" : 1.0,
    "revision" : 5,
    "priority" : 2002.0,
    "serverId" : null,
    "errorCount" : 0,
    "enabled" : false,
    "contextTypeName" : "PingOnlyDevice",
    "extendedTypeName" : null,
    "componentTypeName" : "udp_serviceInfo",
    "description" : "",
    "stepCount" : 1,
    "stepNames" : "AttrPolling",
    "serverIds" : null,
    "missingServerIds" : null
  }  ],
  "count" : 1
}

 

 

POST Method detail

Creates a new user defined poller.

Request:

User defined poller parameters:

Name Description

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.

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.

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.

priority

optional number determining collector priority. Can be omitted.

filterDefinition

determines which of the applicable objects the poller will actually be applied to. Can be omitted or left null to apply to all of them.

steps

list of the poller steps within this poller.

steps/authDetails

authentication method for this poller step.
steps/authDetails/authType authentication type. One of "AUTH_NONE", "AUTH_FIXED_CREDENTIALS" or "AUTH_DEVICE_CREDENTIALS"
steps/authDetails/credential only needed it authType is AUTH_FIXED_CREDENTIALS
steps/authDetails/credential/id ID of the credential set to be used
steps/authDetails/credential/name name of the credential set to be used

steps/stepName

name of the step. Must be unique within the poller and consists only of alphanumeric characters and underscores.

steps/endpointURLSample

example URL entered in the UI. Can be omitted or left blank for Rest API calls.

steps/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.

steps/apiPath

path part of the Rest API URL, including any query part and any interpolated values of the form ${placeholder}.

steps/methodType

HTTP request method, either "GET" or "POST".

steps/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

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/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/swAttrName

attribute name that will be used in the StormWorks data model. Must begin with udp_ and only contain alpha numeric characters and underscores.

steps/attributeMappings/nameToMapping/swAttrDisplayName

display name used for this attribute in the UI (dashboards, reports etc.)

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/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/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/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/range optional. Defines the minimum and maximum values this attribute can take.
steps/attributeMappings/nameToMapping/transform optional. Provides a mapping from raw value (as extracted from the data) to displayed value. Useful for e.g. numeric data representing a set of possible states (set enumerable to true in this case also)
steps/attributeMappings/nameToMapping/transform/name name of transform
steps/attributeMappings/nameToMapping/transform/displayName display name of transform, used in the UI.
steps/attributeMappings/nameToMapping/transform/inputType input data type, e.g. int32, string, etc.
steps/attributeMappings/nameToMapping/transform/outputType output data type, usually string
steps/attributeMappings/nameToMapping/transform/mapping map of input values to output values
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 severity
steps/attributeMappings/nameToMapping/eventThresholds optional. List of thresholds for events on this attribute.
steps/attributeMappings/nameToMapping/eventThresholds/name threshold name. Must be unique.
steps/attributeMappings/nameToMapping/eventThresholds/displayName threshold display name
steps/attributeMappings/nameToMapping/eventThresholds/description optional description of this threshold
steps/attributeMappings/nameToMapping/eventThresholds/groupName group this threshold belongs to
steps/attributeMappings/nameToMapping/eventThresholds/displayUnits units for the threshold value. Can be blank if no units apply.
steps/attributeMappings/nameToMapping/eventThresholds/minValue minimum value this threshold can have
steps/attributeMappings/nameToMapping/eventThresholds/maxValue Maximum value this threshold can have
steps/attributeMappings/nameToMapping/eventThresholds/defaultValue default value for this threshold
steps/attributeMappings/nameToMapping/eventThresholds/enabled flag for whether this threshold is enabled
steps/attributeMappings/nameToMapping/eventThresholds/userDefined flag for whether this threshold is user defined

Response:

The newly created user defined poller, as 'GET Method' above would return it.

Examples:

Example 1: Adding attributes to an existing device:

INPUT
curl -u -k admin:admin https://localhost/api/ud/pollers?pollerType=API -X POST -H "content-type:application/json" -d '
{
  "pollerType": "API",
  "pollerCollectorType": "ASSOCIATED_COMPONENT",
  "pollerName": "AssocComp",
  "contextTypeName": "PingOnlyDevice",
  "componentTypeDetails" : {
    "typeName" : "udp_AssocComp",
    "typeDisplayName" : "Service Info"
  },
  "priority": 2002,
  "filterDefinition": null,
  "steps": [
    {
      "authDetails": {
        "authType": "AUTH_DEVICE_CREDENTIALS"
      },
      "stepName": "AttrPolling",
      "endpointURLSample": "localhost/api/service/1004?media=json",
      "host": "${host}",
      "apiPath": "/api/service/1004?media=json",
      "methodType": "GET",
      "port": null,
      "useSSL": "false",
      "pathToData": "info",
      "attributeMappings": {
        "nameToMapping": {
          "udp_serviceName": {
            "sourcePath": "serviceName",
            "swAttrName": "udp_serviceName",
            "swAttrDisplayName": "Service Name",
            "dataType": "string"
           }
         }
      }
    }
  ]
}'  

OUTPUT
List will be empty if all went well, otherwise a list of error information.

 

Example 2: Adding attributes from a public API to a custom device:

INPUT
curl -u admin:admin -X POST -k "localhost/api/ud/pollers?pollerType=API&mode=BUILD_ALL_FORCE_OVERWRITE" -H "content-type: application/json" -d '
{
  "pollerType": "API",
  "pollerCollectorType": "ASSOCIATED_COMPONENT",
  "pollerName": "CovidGlobal",
  "contextTypeName": "UserCreatedNode",
  "componentTypeDetails": {
    "typeName": "udp_CovidGlobal",
    "typeDisplayName": "Covid Global Rates",
    "description": "",
    "visibility": "VISIBLE"
  },
  "filterDefinition": {
    "filterType": "FILTER_ATTRIBUTE_EQUALS_ANY",
    "attrDef": "name",
    "attrValue": {
      "array": [
        "CovidData"
      ]
    }
  },
  "obtainRate": 86400,
  "keepTime": 604800,
  "steps": [
    {
      "pollerStepType": "POLLING",
      "stepName": "Step 1",
      "authDetails": {
        "authType": "AUTH_NONE"
      },
      "endpointURLSample": "https://coronavirus.m.pipedream.net",
      "host": "coronavirus.m.pipedream.net",
      "apiPath": "/",
      "methodType": "GET",
      "port": "",
      "useSSL": true,
      "attributeMappings": {
        "nameToMapping": {
          "udp_CovidGlobal_confirmed": {
            "swAttrName": "udp_CovidGlobal_confirmed",
            "swAttrDisplayName": "Global Confirmed Cases",
            "dataType": "uint32",
            "displayType": "string",
            "visibility": "SHORTLISTED",
            "enumerable": false,
            "searchable": false,
            "statusMap": {},
            "eventInfo": {
              "eventMode": "NONE",
              "mapping": null
            },
            "sourcePath": "summaryStats.global.confirmed"
          },
          "udp_CovidGlobal_deaths": {
            "swAttrName": "udp_CovidGlobal_deaths",
            "swAttrDisplayName": "Global Covid Deaths",
            "dataType": "uint32",
            "displayType": "string",
            "visibility": "SHORTLISTED",
            "enumerable": false,
            "searchable": false,
            "statusMap": {},
            "eventInfo": {
              "eventMode": "NONE",
              "mapping": null
             },
           "sourcePath": "summaryStats.global.deaths"
          }
        }
      }
    }
  ]
}'

OUTPUT
List will be empty if all went well, otherwise a list of error information.

 

Example 3: Adding subcomponents to a custom device:

INPUT
curl -u admin:admin -X POST -k "localhost/api/ud/pollers?pollerType=API&mode=BUILD_ALL_FORCE_OVERWRITE" -H "content-type: application/json" -d '
{
  "pollerType": "API",
  "pollerCollectorType": "SUBCOMPONENTS",
  "pollerName": "CovidByCountry",
  "contextTypeName": "UserCreatedNode",
  "componentTypeDetails": {
    "typeName": "udp_CovidByCountry",
    "typeDisplayName": "Covid By Country",
    "description": "",
    "visibility": "VISIBLE"
  },
  "filterDefinition": {
    "filterType": "FILTER_ATTRIBUTE_EQUALS_ANY",
    "attrDef": "name",
    "attrValue": {
      "array": [
        "CovidData"
      ]
    }
  },
  "obtainRate": 86400,
  "keepTime": 604800,
  "steps": [
    {
      "pollerStepType": "DISCOVERY",
      "stepName": "Step 1",
      "authDetails": {
        "authType": "AUTH_NONE"
      },
      "endpointURLSample": "https://coronavirus.m.pipedream.net/",
      "host": "coronavirus.m.pipedream.net",
      "apiPath": "/",
      "methodType": "GET",
      "port": "",
      "useSSL": true,
      "pathToData": "rawData",
      "componentTypeDetails": {
        "typeName": "udp_CountryCovidStats",
        "typeDisplayName": "Country Covid Stats",
        "description": "",
        "visibility": "VISIBLE"
      },
      "attributeMappings": {
        "uniqueKeySourcePath": "Combined_Key",
        "componentNameSourcePath": "Country_Region"
      }
    },
    {
      "pollerStepType": "POLLING",
      "stepName": "Step 2",
      "authDetails": {
        "authType": "AUTH_NONE"
      },
      "endpointURLSample": "https://coronavirus.m.pipedream.net/",
      "host": coronavirus.m.pipedream.net",
      "apiPath": "/",
      "methodType": "GET",
      "port": "",
      "useSSL": true,
      "isDataForAllChildren": true,
      "pathToData": "rawData",
      "parentPath": "udp_CountryCovidStats",
      "componentTypeDetails": {
        "typeName": "udp_CountryCovidStats"
      },
      "attributeMappings": {
        "nameToMapping": {
          "udp_CovidByCountry_Confirmed": {
            "swAttrName": "udp_CovidByCountry_Confirmed",
            "swAttrDisplayName": "Confirmed Cases",
            "dataType": "uint32",
            "displayType": "string",
            "visibility": "SHORTLISTED",
            "enumerable": false,
            "searchable": false,
            "statusMap": {},
            "eventInfo": {
              "eventMode": "NONE",
              "mapping": null
            },            "sourcePath": "rawData[1].Confirmed"
          },
          "udp_CovidByCountry_Deaths": {
            "swAttrName": "udp_CovidByCountry_Deaths",
            "swAttrDisplayName": "Covid Deaths",
            "dataType": "uint32",
            "displayType": "string",
            "visibility": "SHORTLISTED",
            "enumerable": false,
            "searchable": false,
            "statusMap": {},
            "eventInfo": {
              "eventMode": "NONE",
              "mapping": null
            },
            "sourcePath": "rawData[5].Deaths"
          }
        },
        "uniqueKeySourcePath": "Combined_Key"
      }
    }
  ]
}'

OUTPUT
List will be empty if all went well, otherwise a list of error information.

 

Example 4: Adding basic support for vCenter VM monitoring

INPUT
curl -u admin:admin -X POST -k "localhost/api/ud/pollers?pollerType=API&mode=BUILD_ALL_FORCE_OVERWRITE" -H "content-type: application/json" -d '
{
  "pollerType" : "API",
  "pollerCollectorType" : "SUBCOMPONENTS",
  "pollerName" : "vCenterExtras",
  "contextTypeName" : "VirtualizationPlatformDevice",
  "componentTypeDetails" : {
    "typeName" : "udp_vCenterExtras",
    "typeDisplayName" : "vCenter Extras",
    "description" : "",
    "visibility" : "VISIBLE"
  },
  "filterDefinition" : {
    "filterType" : "FILTER_ATTRIBUTE_NOT_EQUALS",
    "attrDef" : "name",
    "attrValue" : "",
    "inverted" : false,
    "additionalORedFilters" : [ ]
  },
  "obtainRate" : 300,
  "keepTime" : 604800,
  "steps" : [ {
    "pollerStepType" : "SETUP",
    "stepName" : "Auth",
    "authDetails" : {
      "authType" : "AUTH_DEVICE_CREDENTIALS",
      "credential" : {
        "id" : 3,
        "deviceId" : 0,
        "kind" : "SHARED"
      }
    },
    "endpointURLSample" : "https://vcsa-lon-01.entuity.local/rest/com/vmware/cis/session",
    "host" : "",
    "apiPath" : "/rest/com/vmware/cis/session",
    "methodType" : "POST",
    "port" : "",
    "useSSL" : true,
    "mediaType" : "json",
    "attributeMappings" : { },
    "body" : "",
    "variables" : [ {
      "name" : "sessionApiKey",
      "sourcePath" : "value"
    } ]
  }, {
    "pollerStepType" : "DISCOVERY",
    "stepName" : "Discovery1",
    "authDetails" : {
      "authType" : "AUTH_NONE"
    },
    "endpointURLSample" : "https://vcsa-lon-01.entuity.local/rest/vcenter/vm",
    "host" : "",
    "apiPath" : "/rest/vcenter/vm",
    "methodType" : "GET",
    "port" : "",
    "useSSL" : true,
    "pathToData" : "value",
    "componentTypeDetails" : {
      "typeName" : "udp_vCenterVM",
      "typeDisplayName" : "vCenter VM",
      "description" : "",
      "visibility" : "VISIBLE"
    },
    "attributeMappings" : {
      "uniqueKeySourcePath" : "vm",
      "componentNameSourcePath" : "name"    },
    "headers": [ {
      "name" : "vmware-api-session-id",
      "value" : "${vars::sessionApiKey}"
    } ]
  }, {
    "pollerStepType" : "POLLING",
    "stepName" : "Polling1",
    "authDetails" : {
      "authType" : "AUTH_NONE"
    },
    "endpointURLSample" : "https://vcsa-lon-01.entuity.local/rest/vcenter/vm/vm-100",
    "host" : "",
    "apiPath" : "/rest/vcenter/vm/${ctx::id}",
    "methodType" : "GET",
    "port" : "",
    "useSSL" : true,
    "isDataForAllChildren" : false,
    "parentPath" : "udp_vCenterVM",
    "componentTypeDetails" : {
      "typeName" : "udp_vCenterVM"
    },
    "attributeMappings" : {
      "nameToMapping" : {
        "udp_vCenterExtras_guest_OS" : {
          "swAttrName" : "udp_vCenterExtras_guest_OS",
          "swAttrDisplayName" : "Guest Os",
          "dataType" : "string",
          "displayType" : "string",
          "visibility" : "SHORTLISTED",
          "enumerable" : false,
          "searchable" : false,
          "statusMap" : { },
          "eventInfo" : {
            "eventMode" : "NONE",
            "mapping" : null
          },
          "sourcePath" : "value.guest_OS"
        },
        "udp_vCenterExtras_power_state" : {
          "swAttrName" : "udp_vCenterExtras_power_state",
          "swAttrDisplayName" : "Power State",
          "dataType" : "string",
          "displayType" : "string",
          "visibility" : "SHORTLISTED",
          "enumerable" : false,
          "searchable" : false,
          "statusMap" : { },
          "eventInfo" : {
            "eventMode" : "NONE" ,
            "mapping" : null
        },
          "sourcePath" : "value.power_state"
        }
      },
      "uniqueKeySourcePath" : "vm"
    },
    "headers" : [ {
      "name" : "vmware-api-session-id",
      "value" : "${vars::sessionApiKey}"    } ]
  }, {
    "pollerStepType" : "DISCOVERY",
    "stepName" : "Discovery2",
    "authDetails" : {
      "authType" : "AUTH_NONE"
    },
    "endpointURLSample" : "https://vcsa-lon-01.entuity.local/rest/vcenter/vm/vm-100",
    "host" : "",
    "apiPath" : "/rest/vcenter/vm/${ctx::id}",
    "methodType" : "GET",
    "port" : "",
    "useSSL" : true,
    "pathToData" : "value.disks",
    "parentPath" : "udp_vCenterVM",
    "componentTypeDetails" : {
      "typeName" : "udp_vCenterDisk",
      "typeDisplayName": "vCenter Disk",
      "description" : "",
      "visibility" : "VISIBLE"
    },
    "attributeMappings" : {
      "uniqueKeySourcePath" : "key",
      "componentNameSourcePath" : "value.label"
    },
    "headers" : [ {
      "name" : "vmware-api-session-id",
      "value" : "${vars::sessionApiKey}"
    } ]
  }, {
    "pollerStepType" : "POLLING",
    "stepName" : "Polling2",
    "authDetails" : {
      "authType" : "AUTH_NONE"
    },
    "endpointURLSample" : "https://vcsa-lon-01.entuity.local/rest/vcenter/vm/vm-100",
    "host" : "",
    "apiPath" : "/rest/vcenter/vm/${ctx::id}",
    "methodType" : "GET",
    "port" : "",
    "useSSL" : true,
    "isDataForAllChildren" : true,
    "pathToData" : "value.disks",
    "parentPath" : "udp_vCenterVM/udp_vCenterDisk",
    "componentTypeDetails" : {
      "typeName" : "udp_vCenterDisk"
    },
    "attributeMappings" : {
      "nameToMapping" : {
        "udp_vCenterExtras_capacity" : {
          "swAttrName" : "udp_vCenterExtras_capacity",
          "swAttrDisplayName" : "Capacity",
          "dataType" : "int64",
          "displayType" : "string",
          "visibility" : "SHORTLISTED",
          "enumerable" : false,
          "searchable" : false,
          "statusMap" : { },
          "eventInfo" : {
            "eventMode" : "NONE",
            "mapping" : null
          },
         "sourcePath" : "value.capacity"
        },
        "udp_vCenterExtras_type" : {
          "swAttrName" : "udp_vCenterExtras_type",
          "swAttrDisplayName" : "Type",
          "dataType" : "string",
          "displayType" : "string",
          "visibility" : "SHORTLISTED",
          "enumerable" : false,
          "searchable" : false,
          "statusMap" : { },
          "eventInfo" : {
            "eventMode" : "NONE",
            "mapping" : null
          },
          "sourcePath" : "value.type"
        }
      },
      "uniqueKeySourcePath" : "key"
      },
      "headers" : [ {
        "name" : "vmware-api-session-id",
        "value" : "${vars::sessionApiKey}"
      } ]
    } ]
  }'

OUTPUT
List will be empty if all went well, otherwise a list of error information.

Related articles

Comments

0 comments

Please sign in to leave a comment.