|
How to Set Up PageGate's WebData API Video:
Welcome to the video tutorial on how to use PageGate’s Webdata API.
PageGate has an HTTP data receiver (webdata.exe) that can receive input from nearly any API or protocol that offers an HTTP/S request like HTTP GET, HTTP POST and WCTP.
This allows you to receive JSON, XML, HTML, WCTP and similar data submissions via HTTP/S request. Received data doesn't need to conform to a single standard as it is fully processed with the GetASCII interface and, optionally depending on what you want to do with the received data, Filter Pack.
If you want to receive multiple data formats, the Filter Pack isn't optional and you will need to implement a filtering system to tell PageGate what to do with each format received.
The API itself is a CGI executable named ‘webdata.exe’ that must be hosted on a web server your sending systems can access.
In some cases, this lets you run IIS on the PageGate server for an intranet accessible API.
If you have something that can submit webforms or post information via HTTP/S, like ticket tracking system, records management system, monitoring system, this provides a way for them to trigger messages in PageGate.
In other cases, you’ll need to host the executable on your outward facing web server to provide an internet accessible URL, then provide UNC access to the directory on the web server where webdata.exe is hosted.
If you’re dealing with an internet or cloud based system, this provides a way for that system to provide information to your PageGate server.
In more practical terms, the file webdata.exe is located in the PageGate program directory and MUST be copied to the webserver hosting the API.
If PageGate is not running on the web server hosting webdata.exe, you'll also need to share the directory where webdata.exe is hosted on the web server and provide the UNC filepath to PageGate’s GetASCII interface.
The Webdata API is only a receiver. All data received is ultimately processed by GetAscii and potentially with assistance from the filter pack.
PageGate's Filter Pack opens up quite a few possibilities by allowing you to receive multiple data types from a single or multiple sources but it also allows you to create conditional logic for message processing.
As an example, you could configure a filter that changes who should receive an alert or message based on keywords or keyphrases in the received data. For instance, you could scan for the word lunch in the body of the message and direct it to the cafeteria group instead of a general distribution group.
As another example, it is possible to receive replies from WCTP gateways and you could configure a filter that directs all replies from specific senders to a specified destination, like an email distribution list, an SMS to administrators or any number of things.
You could configure a system where messages from a certain phone number or sender ID will always be copied to certain recipients or groups.
One of the other benefits of the filter is that it can do everything described at the same time. You aren’t limited in the type, style or number of filters you can apply to your server.
Step 1: Host webdata.exe on your web server
The first thing you'll need to do is host webdata.exe on your web server to provide the URL for the API. In the example I’m going to show you, we’re walking through configuring a local instance of IIS on the PageGate server to provide an intranet API.
To note it, the following steps are for IIS but this can be done with any web server suite.
1) Copy webdata.exe from the PageGate program directory to your server's scripting directory.
2) Open the IIS Admin and select the server object.
3) Open Handler Mappings.
4) Right click CGI-exe, left click Edit Feature Permissions
5) Check Execute.
6) Click OK.
7) Select the Server object again.
8) Open ISAPI and CGI Restrictions.
9) Right click in the box and select Add.
10) Specify the following and click OK:
ISAPI or CGI path: Specify the location of webdata.exe
Description: PageGate API Handler
Check 'Allow extension path to execute'
Step 1a: Share the folder webdata.exe is hosted in
If PageGate is not running on the server hosting webdata.exe, you will need to share the directory where webdata.exe is hosted to allow the GetASCII interface to parse the received data.
Step 2: Configure GetASCII to process the received data
Each API and protocol will have a unique structure to the data returned to your server and you'll need to tell PageGate how to interpret the data and what to do with it in general.
To do that, you'll want to configure an 'Advanced Polling' rule for the GetAscii interface:
1) Open PG Admin.
2) Expand Interfaces - GetAscii - Settings - Advanced Polling
3) Click Files.
4) Click Add.
5) Specify the following and click Apply:
Recipient: *
From: Leave Blank
File(s): *.asc
Path: The path to the folder webdata.exe is stored in on the web server.
Example: \\WebServer01\pgscripts\
File Type: Custom
NOTE: If you will be implementing a filtering system, you will do so at this point. For more information, please see PageGate's Filter Script documentation.
6) Go to Interfaces - GetAscii - Settings - Advanced Polling - Record
7) Specify the following and click Apply:
Start Pattern: *
Start Offset: 0
End Pattern: ~
End Offset: 0
8) Go to Interfaces - GetAscii - Settings - Advanced Polling - Recipient.
This section tells PageGate where in the data to look for the recipient or group this reply should go to.
9) Select 'Dynamic Recipient' and configure the parameters.
For example, let's say you're working with the WCTP protocol and want to auto-respond to the person who sent the message. In WCTP, you can key off of senderID="Value".
As another example, let's say you're receiving an XML form and one of the tags will determine who needs to receive the reply. You would key off of <XML Tag>Value</XML Tag>.
Start Pattern: This value determines the first character in the recipient block.
For example, if you're working with WCTP and want to key off of senderID="Value". You would use senderID=" as the Start Pattern.
As another example, if you're working with XML and want to key off of
<XML Tag>Value</XML Tag>. You would use <XML Tag> as the Start Pattern.
Start Offset: The number of characters in the start pattern.
End Pattern: This value determines the last character in the recipient block.
For example, if you're working with WCTP and are using senderID=" as the Start Pattern, you would use " as the End Pattern.
As another example, if you're working with XML are using <XML Tag> as the Start Pattern, you would use </XML Tag> as the End Pattern.
End Offset: The negative value of the number of characters in the End Pattern.
Examples: -1, -10, etc
10) Go to Interfaces - GetAscii - Settings - Advanced Polling - Sender. This section tells PageGate where in the data to look for the sender value.
For most implementations, you can select 'Static Sender' and specify a sender value.
However, if the sender's name will be contained in the data read, you can select 'Dynamic Sender' and parameters are configured similarly to the recipient section.
Start Pattern: This value determines the first character in the sender block.
For example, if you're working with WCTP and want to use the value in senderID="Value". You would use senderID=" as the Start Pattern.
As another example, if you're working with XML and want to key off of
<XML Tag>Value</XML Tag>. You would use <XML Tag> as the Start Pattern.
Start Offset: The number of characters in the start pattern.
End Pattern: This value determines the last character in the sender block.
For example, if you're working with WCTP and are using senderID=" as the Start Pattern, you would use " as the End Pattern.
As another example, if you're working with XML are using <XML Tag> as the Start Pattern, you would use </XML Tag> as the End Pattern.
End Offset: The negative value of the number of characters in the End Pattern.
Examples: -1, -10, etc
11) Go to Interfaces - GetAscii - Settings - Advanced Polling - Message.
This section tells PageGate what in the data should be considered the message and also allows for basic reformatting of messages.
12) Select 'Dynamic Message' and configure the parameters. If you want everything in the received data to be considered the message, you would use a Start Pattern of * and an End Pattern of ~.
Start Pattern: This value determines the first character in the message block.
For example, if you're working with WCTP and want to use the value in the
<wctp-Alphanumeric> tag, you would use <wctp-Alphanumeric> as the Start Pattern.
As another example, if you're working with XML and want to key off of
<XML Tag>Value</XML Tag>. You would use <XML Tag> as the Start Pattern.
Start Offset: The number of characters in the start pattern.
End Pattern: This value determines the last character in the sender block.
For example, if you're working with WCTP and are using <wctp-Alphanumeric> as the Start Pattern, you would use </wctp-Alphanumeric> as the End Pattern.
As another example, if you're working with XML are using <XML Tag> as the Start Pattern, you would use </XML Tag> as the End Pattern.
End Offset: The negative value of the number of characters in the End Pattern.
Examples: -1, -10, etc
The lookup table enables PageGate to perform basic search and replace commands. This allows you to interchange or translate values as needed.
To enable this feature, check Use Lookup Table and click Edit Table.
Here, we can add and remove search and replace routines.
This concludes the video tutorial on how to configure PageGate’s Webdata API. For more information, including how to use the filter pack, have a look at our website, www.notepage.net
|
