Accepting HTTP Requests: Webdata API

 Top  Previous  Next

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, records management, monitoring or other types of systems, this provides a way for them to trigger messages in PageGate.

 

In other cases, you’ll need to host the API's executable on your outward facing web server to provide an internet accessible URL, then provide a UNC share path to the directory on the web server where webdata.exe is hosted for PageGate to access.

 

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 receive the WCTP protocol with this API 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 return URL for your API or WCTP host. 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 data sent to the receiver.

 

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:

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.

11) 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

 

12) 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.

13) 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.

 

For more information, please see the lookup table section of the documentation.