Skip to main content
CCH Software User Documentation

KPI Monitoring: Visual Basic (VB) Scripting

Product Help Banner.png


Visual Basic (VB) scripts can be used in two ways: As a trigger to an event or as a Deliverable to an event

Visual Basic (VB) Scripting

Among KPI Monitoring’s capabilities is its ability to use Visual Basic (VB) scripts in two ways:

  • As a trigger to an event (i.e., to determine if certain conditions exist). For example, to see if a specific file exists in a folder
  • As a deliverable to an event (typically used to add or update information within application databases). For example, to change an overdue customer’s credit status from ‘Good’ to ‘On Hold’

This component should be used only by those individuals who are familiar with VB syntax and have expertise in writing VB scripts.

KPI Monitoring Support will answer questions about how the VB Scripting works and will also provide VB script samples. However, KPI Monitoring Support does not provide custom script design support or debugging services. Please contact your Business Partner for details on these services.

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 ( 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!/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.

Trigger Script Part 1: Name and Purpose

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

' Script Name                  : vs_sample_diskspace.bas
' Script Author                : Development
' Script Purpose             : Check available diskspace and trigger event
' Script Creation Date    : 2/20/2001
' Script Modified by       :
' Script Modified Date    :
' Script Modifications    :

Trigger Script Part 2: Trigger Function

The second part of a “trigger” script enables you to call the event for which the script is acting as a trigger:

Declare Function KSTrigger( ByVal ukey As String) As Boolean

' This function triggers the event in the Application Server. This function
' can be called when the script is being used instead of a query
' and you want to trigger an event.
' The parameters are as follows:
' ukey  The data that uniquely identifies this triggered item.
'       Passed as a string. You may pass an empty string if
'       you do not want KnowedgeSync to keep track of triggered items.

Trigger Script Part 3: The Trigger Script

The third part of a “trigger” script is the script itself; in the following example, a script is used to retrieve the amount of free space on a disk.

Declare Function GetDiskFreeSpace Lib "kernel32" Alias "GetDiskFreeSpaceA" _
(ByVal lpRootPathName As String, lpSectorsPerCluster As Long, lpBytesPerSector As Long, lpNumberOfFreeClusters As Long, lpTtoalNumberOfClusters As Long) As Long

Dim strDrive As String
Dim lngSectorsPerCluster As Long
Dim lngBytesPerSector As Long
Dim lngNumberOfFreeClusters As Long
Dim lngTotalClusters As Long
Dim lngSts As Long
Dim DS
Dim IntLoop As Integer
Dim dblSpace As Double

'These variables can be seen from the event email message screen because they are global
'By declaring these, they can be used as content when we send email, faxes or pages...

Global DiskDrive As String
Global FreeSpaceBytes As Double
Global FreeSpaceMegs As Double
Global FreeSpaceFormatted As String
Global FreeSpaceMessage As String
Global MinMegs As long

MinMegs=50000       'This is our threshold. Less than 500 MB is a problem for us.

For IntLoop = 67 To 90

       strDrive = Chr$(IntLoop) & ":\"     ' Ensure path is at the root.
       lngSts = GetDiskFreeSpace(strDrive, lngSectorsPerCluster, lngBytesPerSector, lngNumberOfFreeClusters, lngTotalClusters)

       If lngSts <> 0 Then

      FreeSpaceBytes = CDbl(lngSectorsPerCluster) * CDbl(lngBytesPerSector) * CDbl(lngNumberOfFreeClusters)

      FreeSpaceFormatted = Format$(FreeSpaceBytes, "###,###0")

             FreeSpaceFormatted = FreeSpaceFormatted & " bytes are free."
             FreeSpaceMegs = FreeSpaceBytes / 1000000
             If FreeSpaceMegs < MinMegs Then  'Less than MinMegs megs is BAD.

                     DiskDrive=chr$(intloop) & ":"

                     If DiskDrive <> "D:" Then  'Don't check the cdrom drive. * change this to your CDROM drive.

                           FreeSpaceMessage = "Disk " & DiskDrive & " has less than " & MinMegs & "mb free."

                           x= KSTrigger(DiskDrive)    'We have low space on this drive

                     End If

              End If

       End If

Next IntLoop

KSReturnMessage=0          'Clean as a whistle.

End    'End of Script’


  • Was this article helpful?