KPI Monitoring: Visual Basic (VB) Scripting

Sample Scripts

KPI Monitoring has sample scripts for your review and use; please contact KPI Monitoring’s Technical Support department for assistance.

Scripting Tools: Version 9 (& Prior); Version 10

In version 9 (and previous versions of KPI Monitoring), the embedded VB Scripting Tool was published by Cypress Enable. As of version 10, the VB scripting tool is the WinWrap VB Scripting engine (http://winwrap.com/web2/). Cypress Enable scripts were designed and debugged within KPI Monitoring; WinWrap scripts are designed and debugged outside of KPI Monitoring, and only the name and location of the script file is stored in KPI Monitoring.

All version 9 KPI Monitoring sites that are using Cypress Enable scripts and choose to upgrade to version 10 code will have their existing scripts auto-converted to the new syntax required by WinWrap Basic. If you have issues running any Cypress Enable scripts under v10, please contact the KPI Monitoring Support department.

With KPI Monitoring version 10.02 and newer, we suport VB.NET scripts in additional to VB. The WWB.NET Scripting language enables WinWrap script writers to use VB.NET style syntax in their scripts. WWB.NET Scripting Language scripts can access and utilize Microsoft .NET Framework’s vast array of public classes and interfaces.

COM and .NET

WinWrap allows two styles of scripting – COM and .NET. The difference is indicated in code files by the header and style of scripting specified.

• '#Language "WWB.COM" compatible with VB6, VB scripting style syntax (this is the current implementation to support scripts from KPI Monitoring V9)
• '#Language "WWB.NET" compatible with VB.NET style syntax.

KPI Monitoring V10 identifies the script type by the file extension: .vb indicates that the file uses '#Language "WWB.NET" and .bas or .bat indicates '#Language "WWB.COM".

WinWrap Basic documentation can be found at http://www.winwrap.com/web2/basic/#!/ref/doc-references.

Create a Script

Before you create a script, determine whether the script will be used as a trigger or as a deliverable.

If to be used as a trigger, be sure the script retrieves all the data fields your event requires. Only fields that are retrieved by the script trigger will be able to be used in an event’s alert messages, passed into the event’s reports, and used in any of the event’s “Actions” deliverables.

If the script is to be used as an event’s “Action” deliverable, be sure that the event’s trigger(s), retrieve all the data that is needed by the script deliverable.

To define a script within KPI Monitoring, expand the “All Events” branch, expand the application you’re working with, click on the “Basic Scripts” sub-branch and click on the “New Script” button.

WinWrap VB Script Definition

Name.  Specify a brief descriptive name for the script. It is suggested that you also include in this name whether the script is to be used as a “trigger” or as a “deliverable”.
Description.  The name you specify is auto-copied into the script description field, in which you may enter a more detailed purpose of the script.
File Specification.  Specify the name and location of your script; you may wish to store them in the KPI Monitoring “Scripts” folder. Be sure not to reference mapped drives in this field.

Save and close the script definition window.

Sample Script as a Deliverable

A script selected as an event’s deliverables will look like the following:

Linking a deliverable Script to an Event

Deliverable Script Part I:  Name & Purpose

A “deliverable” script should begin with the identification of the script’s name, purpose, and author:

' Script Name          : vs_sample_action.bas
' Script Author        : Development
' Script Purpose       : sample showing script used as action
' Script Creation Date : 9/14/2019
' Script Modified by   :
' Script Modified Date :
' Script Modifications :

Deliverable Script Part II:  Retrieve 'Connection' Data

The second part of a “deliverable” script retrieves information about the KPI Monitoring application the event belongs to and its (database) connection:

Declare Function KSGetEvent App ( ByVal s As String ) As String

‘
‘ This function retrieves specific data about the event that
' has triggered.
'
' The available values that can be passed to KSGetEvent in order
' to retrieve data are as follows:
'
' lookup            Returns the Lookup key as defined in
'                   the Event Manager
' application The application that the event belongs to
' description The description of the event
' id                The id of the event
' dns               The ODBC datasource name of the application
' username          The username for the connection of the application
' password          The password used for the connection

Deliverable Script Part III:  Retrieve 'Connection' & Alert Message Data

The third part of a “deliverable” script retrieves information about the triggered event’s alert message:

Declare Function KSGetPackage App ( ByVal s As String ) As String

'

' This function retrieves specific data about the package that was

' created for delivery. The available values that
' can be passed to KSGetEvent in order to
' retrieve data are as follows:
'
' email subject       The subject of the email created for delivery
' email message       The email message text created for delivery
' text message        The text message text created for delivery
' webcast subject   The webcast subject text created for delivery
' webcast message   The webcast message text created for delivery

Deliverable Script Part IV:  Retrieve SQL Syntax

The fourth part of a “deliverable” script retrieves the triggered event’s SQL syntax:

Declare Function KSGetSQL App ( ByVal l As Long ) As String

'
' This function retrieves the SQL from the query that was used to
' trigger the event.
' You pass a number of the query used.
' For example if the event has only one (1)
' query, then you would pass the number 1
' Example: mysql=ksgetsql(1)
' retrieves the sql from the first query

Deliverable Script Part V:  Retrieve Query (Trigger) Columns

The fifth part of a “deliverable” script retrieves data from the event’s queries/triggers:

Declare Function KSGetData App ( ByVal s As String ) As String

'
' This function retrieves columns of data from the queries that
' were used to trigger the event.
' You pass the customized column name as defined in the query builder to
' retrieve that information.
' Example: print ksgetdata("companyname") ' prints
' company name from the query data

Deliverable Script Part VI:  Retrieve Script completion Status

The sixth part of a “deliverable” script retrieves the completion status code and status description of the executed script:

Global KSReturnStatus As Long

'
' Set this value if your script if you want to return an error status number.
' If you don't set this value, then the script is assumed to have
' worked successfully and is stamped completed by the system.
'
Global KSReturnMessage As String
'
' Set this value in your script of you want to return an error message

Deliverable Script: Sample Output

You can use syntax such as the following to show the results of the executed script:

Open "c:\vs_sample_action.txt" For Append As #1

' Print out some event specific information

Print #1, "ID:" & ksgetevent("id")
Print #1, "Desc:" & ksgetevent("description")
Print #1, "App:" & ksgetevent("application")
Print #1, "Look:" & ksgetevent("lookup")
Print #1, "DNS:" & ksgetevent("dns")
Print #1, "username:" & ksgetevent("username")
Print #1, "password:" & ksgetevent("password")
Print #1, "Notes:" & ksgetevent("notes")

' Now print out some content delivery package info

Print #1, "Here is some the package info:"
Print #1, "Subject:" & ksgetpackage("email subject")
Print #1, "Message:" & ksgetpackage("email message")
Print #1, "Some other info:"

' Here is the SQL that was used to generate the event

Print #1, "SQL:" & ksgetsql(1)

' Now print out some of the query info

Print #1, "Company:" & ksgetdata("companyname")
Print #1, "Contact:" & ksgetdata("contactname")
Print #1, "Ordered:" & ksgetdata("orderdate")
Print #1, "Orderid:" & ksgetdata("orderid")
Print #1, "Total$:" & ksgetdata("total")
Close #1

Sample Script as Trigger

A “trigger” script contains instructions to check for a specific condition of data and then identify those elements of data that need to be passed into an event. (A single script cannot be used as both a trigger and a deliverable.)

Linking a Trigger Script to an event

A trigger script can perform whatever sort of checking you need it to – monitoring the status of hardware devices, checking the revision dates of files, scanning for critical processes that must be running, or retrieving data from a database.