Example workflows of creating user defined REST pollers

1. General tab:

1. Specify the Context Type as a Meraki Device (you will need to click 'Show More' or use the filter in the Explorer to find this type).
   
   
   
   
2. Specify the filter so that it will always apply to all Meraki device types:
   1. Under Show Advance Filter, click Add Filter.
   2. Change the Filter Attribute to 'StormWorks Type'
   3. Change the Filter Type to '!=', so that the filter will always pass.

2. Steps tab:

1. Specify the Credential Type as 'Device Credential'.
2. In the Credential field, select an existing credential that has a Meraki API key, or create a new one. This credential is only required for testing it.
3. In the Connection URL field, paste your URL. When adding attributes to a Meraki Device, this will contain some hardcoded references to the organization, network etc it is is on. An example connection URL would be: https://n399.meraki.com/api/v0/organizations/587343/networks/N_651896046061972475/devices/Q2RN-FWWU-JKXT.
4. In the Host field, replace the '${host}' default with the hostname used in the Connection URL field. In the above example, it is n399.meraki.com.
5. In the Headers field, add a header with the following parts:
   • Name: X-Cisco-Meraki-API-Key
   • Value: ${apikey} (you can paste the value of the key here instead, but this works better if you have different cloud controllers with different keys).
6. Use the Test button to check that you are getting data back.

3. Parameterize tab:

1. Under the Path Components table, you will need to replace all the hardcoded IDs in the URL:
   
   
   
   
   1. Select the device serial number part (Q2RN-FWWU-JKXT), click Edit Component, and enter the following in the Replacement field: ${sw::MerakiDeviceSerial}
   2. Select the network ID part (N_651896046061972475), click Edit Component, and enter the following in the Replacement field: ${sw::ref.merakiNetwork.MerakiNetworkID}
   3. Select the organization ID part (587343), click Edit Component, and enter the following in the Replacement field: ${sw::ref.MerakiNetwork.ref.MerakiOrganization.MerakiOrganizationID}
   4. These will extract the appropriate value from the Entuity StormWorks data model for each of theses values for every Meraki Device component against which the poller runs at runtime.

4. No Variables are needed in this case.

5. Attributes tab:

1. Add an attribute as appropriate from the Data Explorer and configure it as required.

6. Save your UD poller.

 

 

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

From Entuity v20.0 P03 upwards, you can add a user defined REST poller to a custom device.

1. General tab:

1. Give the poller a Poller Name and Display Name, and specify the Poller Type as Attributes.
2. Specify the Polling Period as 1 day.
3. In the Filter, select a custom device. You can add a custom device to management from the Asset Management page.  Please see this article for further help and information on how to add a custom device to Entuity. In this example, the custom device is called 'CovidData'.
   
   

2. Steps tab:

1. Add a New Polling Step, which is the only step needed for this poller.
2. We will be polling a public API with no authentication required, so the Credential Mode field can be specified as No Credential.
3. Specify the Connection URL field as https://coronavirus.m.pipedream.net/
4. Hardcode the Host as 'coronavirus.m.pipedream.net'.
   
   
5. Click Test to test the step, which will appear similar to the following:
   
   

3. No entries are required under the Parameterize or Variables tab.

4. Attributes tab:

1. Click Add, and then from the form, click Data Explorer to browse to the summary/global data section, and select 'confirmed' for the total global confirmed covid cases number, and then click Done.
   
   
   
   
2. Once this is added you will be returned to the Attributes tab. Create an attribute with the Display Name as 'Global Confirmed Cases' and the Data Type as 'Unsigned32'. The rest of the form can be left as is.
   
   
   
   
3. Add another attribute, and this time selcet global death count.
   
   

5. Summary tab:

1. Review and save your poller.

Then wait for a discovery to run (about 15 minutes), after which you can navigate to the Associations dashboard of the custom device in the Entuity UI, where will be listed an association called 'Covid Global Rates'. Because the polling frequency was set to daily, you will need to wait a day before it has any data, after which you will see similar to the following:

 

 

 

Example 3 - Adding sub components to a custom device:

The following is an example of adding sub components to a custom device. In this example, we will also use the public API as used in the above Example 2.

1. General tab:

1. Specify the Poller Name as 'CovidByCountry' and the Display Name as 'Covid By Country'.
2. Specify the Context Type as Custom Device.
3. Specify the Poller Type as Sub Components.
4. On the filter, select the same custom device as in the example above, 'CovidData'.
   
   

2. Steps tab:

1. Click New Discovery Step.
2. In the Step Details column, click the Component Type field. This will open the Discovery Component form wherein can be defined the type info for the sub components. Specify the Type Name as 'CountryCovidStats', and the Type Display Name as 'Country Covid Stats'.
   
   
   
   
3. Specify the Credential Mode as 'No Credential'.
4. Specify the Connection URL as https://coronavirus.m.pipedream.net.
5. Specify the Host as coronavirus.m.pipedream.net. It is important to make this change, because otherwise at run time the poller will attempt to take the host name rom the parent device.
   
   
6. Click Next three times to skip the Parameterize and Variables tabs and then reach the Attributes tab.

3. Attributes tab:

1. The Attributes tab for a Discovery step displays the Index attribute and the Name attribute. The Index attribute is mandatory and needs to supply a unique identifier for each sub component, and must always be specified. The Name attribute defaults to a value based on the value of the Index.
2. Select the Index and click Edit.
   
   
   
   For these predefined attributes, the only value that needs to be specified is where they get their data from. Because we are defining how to collect data for multiple child objects, we expect to find the data in an array. Click Explore Parent Path to select where in the source data this array is. In this example, we do not want the summary data, but instead want the data on a per-country basis, so select 'rawData'.
   
   
3. Click Explore Path to choose which field within each array will provide the most appropriate unique identifier for each sub component. In this example, we will select 'Combined_Key'.
   
   
4. Click Done to close this form, and then select the Name attribute and click Edit. It is not necessary to specify a value for the name but it is beneficial for UI purposes to do so. Click Explore Path to open the Data Explorer for this attribute, and in this example we will select 'Country_Region'.
   
   
5. Return to the Steps tab.

4. Steps tab:

1. Click New Polling Step.
2. Specify the Discovery Component Type field as 'CountryCovidStats'.
3. Specify the Data Scope field as 'Single Request'. This means that only a single call will be required to the API to return all the data for every sub component (rather than requiring a separate call to the API for each sub component).
4. Specify the Credential Mode field to 'No Credential'.
5. Specify the Connection URL field to 'https://coronavirus.m.pipedream.net'.
6. Specify the Host field as 'coronavirus.m.pipedream.net.
   
   
7. Click Next three times to skip the Parameterize and Variables tabs and then reach the Attributes tab.

5. Attributes tab:

1. Click Add and then Data Explorer, then browse to the 'rawData' entries and select the 'Confirmed' field.
   
   
   
   
2. Specify an appropriate Display Name and Data Type and click Done to save the attribute.
   
   
   
   
3. Repeat for covid deaths per country, and the two attributes are completed.
   
   

6. Summary tab:

1. Review the poller and then click Save.

Navigate to the Associations dashboard of the CovidData custom device, where can be seen (as associations) a number of Country Covid Stats objects, with relevant stats for confirmed cases and number of deaths per country:

 

 

 

Example 4 - Adding basic support for vCenter VM monitoring:

In this example, we will extend the support for an existing vCenter VM platform by adding sub components representing the VMs, and polling some metrics of interest on them.

You will need to access a vCenter device and the corresponding username/password credentials. The vCenter device in this example is called vcsa-lon-01.entuity.local, and for this poller to work, the following property in entuity/etc/CollectionEngine/cecfg.properties was amended as follows:

trustAllCertificates=true

When you add the vCenter in the Asset Management page, create a shared credential set for the username/password, and specify this as the User Defined Monitoring credentials to use when adding the device. Please see this article for further help and information on adding VM platforms to Entuity.

 1. General tab:

1. Specify a Poller name, which in this example is 'vCenterExtras'.
2. Specify the Context Type as VM Platform. 
3. Specify the Poller Type as Sub Components.
4. We will specify the Filter so that the poller will apply to all managed vCenters. This can be achieved by using the Advanced Filter to define a filter that will always pass - define a filter that passes if the name is not equal to the empty string.
   
   

2. Steps tab:

1. Add a New Setup Step.
2. Specify the Credentials Mode as Device Credential. This is because we intend to pick up whichever credentials are set on each vCenter VM platform device that the poller runs against. For the purpose of this example, we will also select the shared vCenter credential in the Credential field.
3. Specify the Connection Method as POST.
4. Specify the Connection URL in the format 'YOUR_VCENTER_HOSTNAME'.
5. The Host field is left blank. As a result, it will default to replacing the hostname part of the URL with the hostname from each device that it runs against. This means that polling will work for all managed vCenters if they have the correct credentials set.
6. Specify the Post Media Type as JSON, although in this example, no content is sent in the body.
   
   
   
   
   
   Click Test. The value returned will be the session ID.
   
   

3. No entries are required under the Parameterize tab.

4. Variables tab:

1. Click Add and then use the Data Explorer to select the value produced in the step above. In the variable Name, enter 'sessionApiKey' or similar. This stores the value of our session ID in a variable that can be accessed in all subsequent steps.
   
   

5. Return to the Steps tab:

1. Add a New Discovery Step.
2. Click the Component Type field to open the Discovery Component form. The components will represent VMs, so in Type Name we will enter 'vCenterVM' and in Type Display Name 'vCenter VM'.
3. Specify Credential Mode as No Credential, because the pre-stored session ID will be passed in a header field.
   
   
   
   
4. Specify the Connection URL in the format 'YOUR_VCENTER_HOSTNAME', which will provide a list of VMs.
5. Click the Headers field and then Add Header. Name the header 'vmware-api-session-id', and in the Value field enter '${vars::'. This will prompt a list of available variables (in this example just the one), which is the sessionApiKey, which we will select.
   
   
   
   
6. Click Test to test the step.

6. Attributes tab:

1. From the table, select the Index attribute and click Edit. From the Explore Parent Path button, select 'value' for the Parent Source Path, and drill down to select 'vm' for the Source Path.
   
   
   
   
   
   
2. From the table, select the Name attribute and click Edit. From the Data Explorer, select 'name'.
   
   

7. Return to the Steps tab:

1. Add a New Polling Step.
2. In the Discovery Component Type field, select the previously defined component type ('vCenterVM' defined above).
3. Specify Data Scope as Request Per Sub Component.
4. Specify Credential Mode as No Credential.
5. The Connection URL in this case needs an example VM appended to it, e.g. 'YOUR_VCENTER_HOSTNAME/vm-100'.
6. Click the Headers field and then Add Header. Name the header 'vmware-api-session-id', and in the Value field enter '${vars::'. This will prompt a list of available variables (in this example just the one), which is the sessionApiKey, which we will select.

8. Parameterize tab:

1. In the first column (Path Components), select the row that shows the hard-coded name of a VM (in this example, 'vm-100' and click Edit Component. This will need to be replaced with the identity of each VM that has been discovered. In the Replacement field, type '${', at which point a number of suggestions will be shown. Choose 'ctx::' and then choose Index. This will insert the unique Id (Index attribute at runtime for each of the discovered components.
   
   

9. Attributes tab:

1. Add the attributes you are interesting in using the Data Explorer. Ensure they have sensible display names and the correct data types, e.g. power state or guest OS fields.
   
   

10. Return to the Steps tab:

1. Now we will add components representing the disks under each VM component. This requires adding another New Discovery Step.
2. Specify the Component Type Name as 'vCenter Disk'.
3. Specify Credential Mode as No Credential.
4. These new components will be children of the VM components that we have already defined, and so specify the Parent Discovery Step as 'vCenterVM (Step: Discovey 1)' in the dropdown menu.
5. Specify the Connection URL as ''YOUR_VCENTER_HOSTNAME/vm-100' as with the previous step.
6. Click the Headers field and then Add Header. Again name the header 'vmware-api-session-id', and in the Value field enter '${vars::'. This will prompt a list of available variables (in this example just the one), which is the sessionApiKey, which we will select.
   
   

11. Parameterize Step:

1. As previously, in the first column (Path Components), select the row that shows the hard-coded name of a VM (in this example, 'vm-100') and click Edit Component. This will need to be replaced with the identity of each VM that has been discovered. In the Replacement field, type '${', at which point a number of suggestions will be shown. Choose 'ctx::' and then choose Index. This will insert the unique Id (Index attribute at runtime for each of the discovered components.
   
   

12. Attributes tab:

1. Select the Index attribute and, from the Data Explorer, specify the 'disks' list as the Parent Source Path and 'key' for the Source Path'.
   
   
   
   
2. Select the Name attribute and, from the Data Explorer, select 'label'.
   
   

13. Return to the Steps tab:

1. Add a New Polling Step. For this step, we will specify the Discovery Component Type as 'vCenterDisk (Step: Discovery2)'. This will indicate that we are adding attributes on our latest set of sub components.
2. Specify the Data Scope as 'Single Request'. This means that a single request will get all the necessary data, rather than having to make a request for each of the disk sub components.
   
   

14. Parameterize tab:

1. As previously, in the first column (Path Components), select the row that shows the hard-coded name of a VM (in this example, 'vm-100') and click Edit Component. This will need to be replaced with the identity of each VM that has been discovered. In the Replacement field, type '${', at which point a number of suggestions will be shown. Choose 'ctx::' and then choose Index. This will insert the unique Id (Index attribute at runtime for each of the discovered components.

15. Attributes tab:

1. Drill down into the disk's data and select the desired metrics. In this example, we have selected 'capacity' and 'type'.
   
   

16. Summary tab:

1. Review your poller and click Save.

 

 

 

Example 5 - Adding basic support for monitoring Edges on a VMware VeloCloud:

1. Add a custom device that represents your VeloCloud controller:

1. Add a new custom device that represents your VMware VeloCloud via Asset Management. It is recommended to use the hostname of the VeloCloud controller for the custom device's display name (otherwise you will later need to hardcode the host name in the Host field on the Steps tab, rather than leaving it as '${host}').
2. Specify User Defined Monitoring credentials on the device. Use a shared credential set which has the token stored in an API Key credential. You can obtain the token from the VeloCloud dashboard by clicking on your account name in the top right of the screen > API Tokens > Actions > New API Token. It is important to add credentials to the custom device at this point rather than later specifying credentials to the device on from the Credential field under the Steps tab.
   
   

 

2. Navigate to the User Defined REST Polling page, and create a new User Defined REST Poller.

3. General tab:

1. Give the poller an appropriate name, and specify the Poller Type as 'Sub Components'.
2. Specify the Context Type as 'Custom Device'.
3. In the Filter, select the newly-added custom device that represents your VeloCloud.
   
   

4. Steps tab:

1. Add a New Discovery Step.
2. In the Component Type field, specify an appropriate type name for the Edge objects you will monitor.
   
   
   
   
3. From the Credential field, select the shared credential that was specified when first adding the custom device. Note, it is important to ensure that a credential set is already added to the custom device rather than specifying device credentials at this point.
4. Specify the Connection Method as POST, and in the Connection URL field, paste in the REST URL for getting the list of Edges. This will look similar to the following: https://vco211-fra1.velocloud.net/portal/rest/enterprise/getEnterpriseEdges
5. A small JSON entry is required in the Body field to instruct as to the enterprise ID. This will look similar to the following: {"enterpriseId":112}
   
   
   
   
6. Add a new header to the Headers field, which will contain the authentication token. For the Name enter 'Authorization' and for Value enter 'Token' followed by a space and then your authorization token. Note, because this value has already been entered into the User Defined Monitoring credentials, you can use the ${apikey} extrapolation rather than hardcoding the authorization token. This makes it easier to change if required, and means that the UD REST poller can work with more than one VeloCloud if necessary (Token ${apikey})
   
   
   
   
7. Click Test to ensure the Step is working, and then click Next until you reach the Attributes tab.

5. Attributes tab:

1. From the table, select the index attribute and click Edit. In this case, you can leave the Parent Source Path field empty. For the Source Path field, click Explore Source Path to drill down into the Data Explorer and select one of the properties named 'id'. Note, whilst it is possible to make a manual entry into the Source Path, Entuity recommends that you use the Explore button to prevent the possibility of typographical or transcriptive error. This will present the available data and automatically populate the correct expression. In rare cases when either the JSON/XML data is not available during testing, or a specially-crafted expression is required, is it preferable to manually type an entry.
   
   
   
   
2. Select the name attribute and click Edit. Click Explore Path and from the Data Explorer, select the 'name' property.
   
   

6. Steps tab:

1. Return to the Steps tab and add a New Polling Step.
2. In the Discovery Component Type field, select the component type that was specified in the Discovery Step above (which should be the only choice available).
3. In the Data Scope field, specify 'Single Request'. Since the data request made in discovery returns a lot of useful information for each Edge, this single call can be used to populate data for each sub component. This prevents needing to make unnecessary requests for each Edge to get exactly the same data.
4. Use the same Connection Method, Connection URL, Body and Headers as in the Discovery Step above.
   
   
5. Click Test to ensure there are no errors in this step, and then click Next until you reach the Attributes tab.

7. Attributes tab:

1. Click Add and then Data Explorer to search for the data you are interested in.
   
   
   
   
2. As an example, we will use the value of the property 'edgeState' to drive the status icon of each Edge sub component. After selecting it from the Data Explorer, select it in the table of attributes and click Edit. In the Edit Attribute form, specify Use this attribute for object status to 'true'.
   
   
   
   
3. In the Status Mapping field, click +Add Status Mapping to provide mapping from the values of 'edgeState' to the status values used by Entuity. The two values available in this example are OFFLINE and CONNECTED.
   
   

8. Summary tab:

1. Save your poller.

Wait a few minutes for the polling to begin, and then navigate to the Associations dashboard of the custom device. The Associations dashboard will be populated in a similar manner to the following:

 

 

 

Creating example user defined REST pollers through RESTful API calls:

Please refer to the Entuity RESTful API documentation for the commands required to create the above examples.