Overview of Command Line/ASCII Interface Transcript for Video:
Welcome to the video tutorial overview of PageGate’s GetASCII module. In this tutorial, we’ll be going over the ASCII parsing and command line capabilities of the GetASCII API.
GetASCII, also known as the Command Line/ASCII interface, is capable of monitoring a directory or series of directories on a local hard drive or network share for ASCII file output and also provides a command line interface for other applications to use. This module allows many 'off the shelf' and custom applications, such as SolarWinds' Orion platform and Paessler's PRTG and CAD systems, like those made by Superion, Tritech, Southern Software and many others, to easily integrate with PageGate.
GetAscii can accept messages from other applications in the following ways:
GetASCII provides a 16-bit and 32-bit command line executable for other applications to use. This is typically how network monitoring programs integrate with PageGate.
- ASCII Text/XML/HTML/JSON File
GetASCII can monitor a directory or series of directories on the local hard drive(s) or by UNC path for ASCII file output. The contents of the file just need to be in ASCII, so you could have the program read in XML, HTML or JSON formatted content as easily as you could have it read the custom text files output by a CAD, security or card access monitoring system.
GetASCII has the ability to monitor a very specific location in the registry for specific keys. If those keys appear, they trigger the module to deliver the message specified to the recipient or groups specified. For the location and specification information for the keys, please see the Registry Polling section of GetASCII’s documentation in our manual.
Let’s go over the command line first. To provide the command line, you’ll first need to create a basic data processing folder to work within. To make things easy, we generally recommend creating a folder named ‘ASCII’ under your PageGateData folder. So, by default, the path would be c:\PageGateData\ASCII\
Once we have the folder created, open the PageGate Admin.
Here in the Admin, go to Interfaces – GetAscii – Settings.
Set the ‘Polling Directory’ the folder you just created. By default, c:\PageGateData\Ascii\
Check Enabled, then click Apply and tell it yes, you do want this to be enabled.
You’ll notice that as soon as we do, PageGate creates a few data processing folders and populates the base folder with two files: sendpage.exe and sendpage32.exe
These two executables are PageGate’s command line executables. Sendpage.exe is a 16-bit application and sendpage32.exe is a 32-bit application that can be called in 64-bit environments.
When calling on PageGate’s command line executable, you’ll need to use the following command structure:
<path to executable>\<executable> <recipient or group> <sender> <message>
For example, let’s say that we have GetAscii pointed at c:\PageGateData\ASCII\ and that we want to call on sendpage32.exe. Let’s also say that we want to send a message to the group it_alerts from the sender ‘ALARM’ and that the message should say, “This is an example”. You would use this command:
C:\PageGateData\ASCII\sendpage32.exe it_alerts ALARM This is an example
Using the command line interface makes it incredibly easy to integrate applications capable of executing an executable or batch file when an alert or message needs to be sent.
Above and beyond the command line interface, the GetASCII module has the ability to monitor a directory or series of directories for ASCII files and it does so in two ways.
First, we have a basic file format that the basic polling is configured to recognize. The basic polling function of GetAscii scans the specified polling directory for any files that have an extension of .asc; which means you can name the file whatever you like, just make sure to use .asc as the file’s extension – not .txt or .rtf or anything else.
The format of the files written should be as follows:
<Recipient or Group>
<Sender>
<Message>
Since they’re non-visible characters, it’s important to note that each variable needs a carriage return, line feed after it as GetASCII looks for CRLF as the terminating character in each variable statement. For example, if you wanted to send a message to the group it_alerts from the sender ALARM and the message should say “This is an example”, you would need the following in the file:
It_alerts
ALARM
This is an example
In addition to the basic processing and basic file format, PageGate’s GetASCII module can handle completely custom formats as well by using the Advanced Polling function. The Advanced Polling allows you to do many, many different things, so let’s go through how advanced ASCII processing works.
To start, you’ll have to tell PageGate what file names to look for and where to find them. To do that, go to Interfaces – GetAscii – Settings – Advanced Polling – Files.
Here in the Files table, click Add.
If all files of a certain name or type should always go to the same recipient or group, you can tie this file processing rule to them. Otherwise, leave the Recipient value set to * to indicate that this polling rule is valid for all recipients and groups.
If you want to specify a static From value, enter it here. If the output system will write a sender’s name in the text processed, leave From blank.
In the File(s) section, you can specify the files GetAscii should look for. This can be a specific file name or any portion of a file name. For example, you could use *.txt to have the program process all text files but you could also use warn*.xml to tell the module only to process those text files whose names begin with warn and end with .xml. For example, it would process warn123.xml and warning.xml but would not process warden.xml or warren.xml or any file that didn’t have the .xml extension.
The Path should be set to the folder the data will be written to. This can be any local or network share/UNC path. Also, just to note it, if you have GetAscii reference cross-network data, you will need to specify a service account for the GetAscii Windows Service. Typically speaking, the “System Account” most services use by default does not read/write/modify network privileges. If the GetAscii module is pointed at a network location but its service is configured to use the “System Account”, the module will be able to see the data but it won’t be able to process it appropriately as its service doesn’t have permission to read/write/modify/delete the data.
And last we have the File Type. The Standard file type will use the basic polling as described earlier.
The Custom file type allows you to tell PageGate how to pattern-match the data contained in the processed files. This is the file type you should use for XML, JSON and HTML data processing as well as the file type you should use for any ASCII file that doesn’t follow PageGate’s basic processing format.
The Adding file type tells PageGate that all data processed will be contained in a single file that has information appended to the end of it. So, you could have a single file called “alerts.txt” that PageGate monitors and any time new information is appended to the end of the file, the program will process it as a new message to be delivered.
The Changing file type is a bit like the Adding file type, where you tell PageGate to monitor a single file. However, the Changing file type scans to see if any of the existing document has been modified. If it has, PageGate re-reads the file as a new message to be delivered.
We’ll go over the specifics of how to configure advanced data processing in another video but I do want to give you a general overview of how it works. Once you establish a new advanced polling rule in the Files section, you’ll need to tell PageGate how to understand the data to be processed. GetAscii functions off of basic pattern matching to determine what constitutes a record and what within the record constitutes the recipient, sender and message to be processed.
For example, let’s say you’re reading XML formatted data that looks something like this:
<Data>
<Unit>
FD12
</Unit>
<Body>
This is an example message
</Body>
</Data>
You would use <Data> as the Record start pattern and </Data> as the record stop pattern to tell PageGate that everything between the Data tags should be treated as a record to be scanned for recipient, sender and messaging information.
As another example, let’s say you’re reading a raw text file that looks something like this:
SubscriberName=FD12
[Message]
Line1=The first line of the message
Line2=The second line of the message
You would use * for the start pattern and ~ as the end pattern to tell PageGate that the entire contents of the file constitute a record that should be scanned for recipient, sender and messaging data.
So, it really is just a matter of looking at the data you need processed and determining the most efficient method of breaking that down into its constituent components (record, recipient, sender and message).
This concludes the overview of the GetASCII module.
|
