Telemetry & Webhook

The article below contains examples on how to setup the telemetry and webbook on our box.


WTI Continuous Streaming Telemetry Service 


(Splunk EndPoint)


WTI devices are capable of streaming continuous JSON power, current or temperature data to a collection point in your organization. When data on the WTI device is ready to be sent, the data can be sent to common collection end point and examined at a later time.


To do this we need to get into the WTI telemetry command and for this example we will use Splunk as the collection end point.


On the Splunk program you need to make an HTTP Event Collector (HEC), when you make this collector it will create a Token Value. You will need to copy this value to be used for WTI device.


Information on how to create and manage a Splunk HEC can be found here:


https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector


When the Splunk HEC has been created and the Token Value has been copied, you can now login to the WTI device, issue the following command


/tel


choose:


1. Continuous (Streaming Data)


Choose the slot in which you want to make the service.


Below is a sample screen for a Telemetry service that is already complete.


CONTINUOUS TELEMETRY DETAILS: [splunkstreampower] IPv4/IPv6

1. Enable: On

2. Name: splunkstreampower

3. User Name: Splunk

4. Password: XXXXXXXXXXXXXXXXXXXXXX

5. Shared Secret: (undefined)

6. Dataset: Power

7. Frequency: 600

8. Timeout: 10

9. Retries: 2

10. Command: https://splunk.yourcompany.com:8088/services/collector

11. Display Status

12. Display Debug Info


These fields should be filled out to match your setup


      1. Enable – Starts the WTI service sending telemetry data.
      2. Name – Any arbitrary name you want to name this service.
      3. User Name – Name on the Splunk account utilizing the HTTP Collector from the Splunk Program
      4. Password – The HTTP Collector Token Value from the Splunk program
      5. Shared Secret – not used for this particular type of end point
      6. Dataset – We choose Power, but other streaming datasets are Current and Temperature
      7. Frequency – In seconds, how often to send the Dataset
      8. Timeout when to give up on sending the command before retying again
      9. Retries – How many times to try a command before it has signaled a failure
      10. Command – Where your collector is located.
      11. Display Status – Dynamically changes after a command is send to tell you their response.
      12. Display Debug Info – If the debug for the system is on, will contained debug information after a command is sent.

After all the parameters are entered, you can back out to the main menu, you should start seeing the Power data filling into your Splunk host. The same procedure can be used for Current and Temperature Datasets.


NOTE 1:


Raw Power Data JSON output that is sent to the collection end point

      { “sourcetype”: “powerdata”, “event”: { “timestamp”: “2020-06-18T17:40:08+00:00”, “siteid”: “CPM-1600-1-ECAM-LAB”, “location”: “LABRACK1”, “powerunit”: “1”, “outletmetering”: “1”, “ats”: “1”, “branchcount”: “2”, “plugcount”: “4”, “powerfactor”: “100”, “powereff”: “100”, “powerdatacount”: “1”, “powerdata”: [{ “timestamp”: “2020-06-18T17:40:08+00:00”, “plug1”: [{ “plugname”: “HP1”, “voltage”: “113.00”, “current”: “0.50”, “branch”: “1” }], “plug2”: [{ “plugname”: “HP_2100”, “voltage”: “113.00”, “current”: “0.20”, “branch”: “1” }], “plug3”: [{ “plugname”: “Meraki”, “voltage”: “113.00”, “current”: “0.00”, “branch”: “1” }], “plug4”: [{ “plugname”: “CiscoNXOS1”, “voltage”: “113.00”, “current”: “1.20”, “branch”: “1” }], “plug5”: [{ “plugname”: “CiscoNXOS2”, “voltage”: “114.00”, “current”: “0.00”, “branch”: “2” }], “plug6”: [{ “plugname”: “Juniper3000”, “voltage”: “114.00”, “current”: “0.00”, “branch”: “2” }], “plug7”: [{ “plugname”: “”, “voltage”: “114.00”, “current”: “0.00”, “branch”: “2” }], “plug8”: [{ “plugname”: “”, “voltage”: “114.00”, “current”: “0.00”, “branch”: “2” }] }] } }

WTI Event based Streaming Telemetry Service


(Custom EndPoint)


First of all, what is a WebHook ?


A WebHook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A WebHook delivers data to other applications as it happens, meaning you get data immediately. They’re incredibly useful and a resource-light way to implement event reactions.


WebHooks is a free form type of interaction with WTI devices. It allows the WTI device to send information (usually JSON formatted) to an endpoint of your choosing.


This end point can be Splunk, Elasticsearch, a Syslog server, WebEx, Slack or a custom endpoint that is customized to your needs.


Below we will show you how you can send Alert data to a custom endpoint.


/** To send data to another endpoint such as Splunk or Syslog you can search here. **/


The first thing to setup is your custom endpoint, such as my.wti.com


      1. Login to my.wti.com,
      2. Click on the “Download” button.
      3. “API Key” click on “Make APIkey”

Now at this location is your API key for later use.

      1. Login to the WTI device
      2. /tel
      3. Choose 2. Event Based (One Shot Data)
      4. Choose an empty slot.
      5. Fill in the data as follows:

EVENT BASED TELEMETRY DETAILS: [my.wti.com] IPv4/IPv6

      1. Enable: On
      2. Name: my.wti.com
      3. User Name: (undefined)
      4. Password: (undefined)
      5. Shared Secret: (undefined)
      6. Dataset: Alert Data
      7. Timeout: 10
      8. Retries: 2
      9. Command: https://my.wti.com/testing/webhook.aspx?apikey=7d5SplMJghewggTSVpgFbAjEJFvrgh3E
      10. Display Status
      11. Display Debug Info

This will send a predefined block of JSON data, when an alert occurs to the my.wti.com endpoint as shown in the sample below:


{ “sourcetype”: “wtiaudit”, “event”: { “timestamp”: “2020-07-28T16:47:30+00:00”, “location”: “LABRACK1”, “siteid”: “CPM-1600-1-ECAM-LAB”, “assettag”: “1234567890”, “package”: [{ “timestamp”: “2020-07-28T16:47:30+00:00”, “type”: “audit”, “trigger”: “LOGIN Network”, “additional”: ” SSH Port 22″, “message”: “LOGIN Network SSH Port 22 super1” }] } }


If you need to customize the format of your data output to match the requirements of your endpoint that can be accomplished by choosing:


6. Dataset: Custom


Then enter a “Custom Post String” in the menu option, as shown below


EVENT BASED TELEMETRY DETAILS: [my.wti.com] IPv4/IPv6


      1. Enable: On
      2. Name: my.wti.com
      3. User Name: (undefined)
      4. Password: (undefined)
      5. Shared Secret: (undefined)
      6. Dataset: Custom
      7. Timeout: 10
      8. Retries: 2
      9. Command: https://my.wti.com/testing/webhook.aspx?apikey=7d5SplMJghewggTSVpgFbAjEJFvrgh3E
      10. Custom Post String: {‘text’:’HelloWorld %date%, lo=%location% si=%siteid%, at=%assettag%, t=%type%, l=%level%, t=%trigger%, u=%user% m=%message% a=%additional% office’}
      11. Display Status
      12. Display Debug Info

This sample will appear on the end point as below:


{‘text’:’HelloWorld 2020-07-28T16:37:06+00:00, lo=LABRACK1 si=VMR-8HS20-2, at=AssetTagVMRLabEng123, t=audit, l=-1, t=LOGIN Network, u=super1 m=LOGIN Network SSH Port 22 super1 a= SSH Port 22 office’}


Notice the variables between the % marks are replaced with active data by the WTI device when the data gets posted to the endpoint.


%date% – GMT time/date of the WTI device


%location% – Contents of the Location Field


%siteid% – Contents of the Site ID


%assettag% – Contents of the Asset Tag


%type% – Type of alert, either “audit” or “alarm”


%level% – if level is defined for this message


%trigger% – What trigger this data being sent


%user% – Username (if applicable) that caused the trigger


%message% – Message of the triggered alert


%additional% – Any miscellaneous information with the alert


WTI Event based Streaming Telemetry Service


(WebEx EndPoint)


WTI devices are capable of sending event based JSON data to a program of your choosing utilizing WebHook technology. When an event is triggered on a WTI device the data from the event can be sent to common collection end point and examined at a later time.


To do this we need to get into the WTI telemetry command and for this example we will use a WebEx bot as a collection end point.


On the WebEx end you need to make an WebEx bot, when you make this bot it will create a Access Token. You will need to copy this value to be used for WTI device.


Information on how to create and manage a WebEx bot can be found here:


https://developer.webex.com/docs/bots

After you sign into your developer.cisco.com account:


      1. Click on the button “Start Building Apps”
      2. Click on the Button “Create a New App”
      3. Click on the button “Create a Bot”

You are now at the “New Bot” screen, fill in the “Bot Name”, “Bot Username”, select an icon and enter a Description. The important field here is the ”Bot Username”, this is how you are going to see the information in your WebEx client. When you are done entering your bot’s information, click on “Add Bot”


At this point you have created your bot. You need to copy the “Bot’s Access Token” and the “Bot Username”, you are now done on the WebEx developer website.


When the WebEx bot has been created and the Access Token has been copied, you can now login to the WTI device, issue the command


/tel


Choose:


2. Event Based (One Shot Data)


Choose the slot in which you want to make the service.


Below is a sample screen for a Telemetry service that is already complete.


EVENT BASED TELEMETRY DETAILS: [testwebex] IPv4/IPv6


      1. Enable: On
      2. Name: testwebex
      3. User Name: (undefined)
      4. Password: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      5. Shared Secret: (undefined)
      6. Dataset: Custom
      7. Timeout: 10
      8. Retries: 2
      9. Command: https://api.ciscospark.com/v1/messages
      10. Custom Post String: { “text”: “WTI event %date%, loc=%location% site=%siteid%, at=%assettag%, t=%type%, l=%level%, t=%trigger%, u=%user% m=%message% a=%additional%”, “toPersonEmail”: “mytest@wti.com”}
      11. Display Status
      12. Display Debug Info

These fields should be filled out to match your setup


      1. Enable – Starts the WTI service sending telemetry data.
      2. Name – Any arbitrary name you want to name this service.
      3. User Name – not used for this particular type of end point
      4. Password – The WebEx Access Token created by WebEx for your bot
      5. Shared Secret – not used for this particular type of end point
      6. Dataset – We choose Custom, but there is also Alert Data
      7. Timeout when to give up on sending the command before retying again
      8. Retries – How many times to try a command before its signaled a failure
      9. Command – Where your collector is located.
      10. Custom Post String – This is the string that gets sent to your bot, since not all collectors are the same this string is customizable with variable that can be used to fit you exact needs. Please see below for a more detailed explanation.
      11. Display Status – Dynamically changes after a command is send to tell you the response.
      12. Display Debug Info – If the debug for the system is on, will contained debug information after a command is sent.

After all the parameters are entered, you can back out to the main menu, you should start seeing the event data appearing into your WebEx client when the next event occurs (i.e. a login/logout for example).


Custom Post String


Depending on if you are using WebEx, Slack, or your custom WebHook client, the JSON data format required for that client may vary and be rigid to its requirements. To accommodate a varied number of clients, WTI has allowed total customization of the JSON block along with replaceable variables. Below is the sample of JSON that could be sent for a WebEx bot


{ “text”: “WTI event %date%, loc=%location% site=%siteid%, at=%assettag%, t=%type%, l=%level%, t=%trigger%, u=%user% m=%message% a=%additional%”, “toPersonEmail”: “mytest@wti.com”}


The text tag is required by the WebEx API, it is a string with text that will appear in your WebEx client.


Anything that is enclosed with quotes will be replaced by the corresponding text before it is sent to the WebEx client.


%date% – UTC unit based date and time


%location% – The location field of the WTI device


%siteid% – The Site ID field of the WTI device


%assettag% – The Asset Tag field of the WTI device


%type% – the type of alert that the WTI device is generating


%level% – The level (if there is one defined) for this alert


%trigger% – What triggered this alert


%user% – The user (if applicable) that triggered the alert


%message% – The message that goes along with the alert


%additional% – Any additional information that was generated by the alert.


This is the text that should appear in your WebEx client when an alert is sent in the example above.


WTI event 2020-06-08T22:46:02+00:00, loc=LABRACK1 site=CPM-1600-2-EC-158, at=156009, t=audit, l=-1, t=LOGIN Network, u=super m=LOGIN Network SSH Port 22 super a= SSH Port 22 office