How to Communicate with Web API Transcript for Video:
Welcome to the video tutorial on how to configure PageGate to pull information from a web API. In this tutorial, we’ll be going over how to use GET or POST methods to pull information from a web API, then pass it through a filter script for processing.
Before we begin, to have PageGate pull information from a web API, you will need the GetASCII interface and the Filter Script. Effectively, we’re going to have PageGate pass a GET or POST statement to a web API to retrieve information but once it has the data, it needs to be told how to format it and what to do with it. That’s where GetASCII and the Filter Script come in, they tell the program how to format and what to do with the data it retrieves.
With the HTTPGET and HTTPPOST protocols, you can poll information from any web API that supports the GET or POST methods.
For instance, if you have a web resource that provides XML content, you can configure PageGate to poll for that XML content and then feed it through a filter pack to turn it in to a readable text message. Alternatively, you could pull the XML content and then pass it completely intact to its destination.
In the example I’m going to take you through, we’re going to configure PageGate to automatically poll the National Weather service for weather information. When we’re finished, any time a any message is created for the check-weather recipient, the PageGate will request the current weather data from the National Weather service and send that information as a text message to the recipients and groups specified in the filter script’s configuration.
The first step is to open the PageGate Admin. I’ve configured this copy of PageGate to send SMS and, naturally, you would need to do the same if you want this information delivered as a text message. For more information on how to do that, have a look at the ‘How PageGate Sends SMS’ video tutorial.
Next, right click Carriers and select Add.
Give the carrier a name, something straightforward like weather or noaa
Set the protocol to: HTTPGET
Set the Host to the your web APIs URL. In this example, we’re going to be using the National Weather Service's web API: w1.weather.gov/xml/<your region>
For example, you would use this for the weather at Boston Logan International Airport: w1.weather.gov/xml/current_obs/KBOS.xml
For more information on the National Weather Service's web API/XML feeds, have a look at their website: http://w1.weather.gov/xml/current_obs/
Set the port to: 80
Click Apply to add the carrier to the list.
Now that we’ve created the basic carrier to poll the web API, we’ll need to tell PageGate what recipient should receive the information. To do so, go in to the ‘Template’ sub-section of your new carrier.
In the Settings section, specify the following: ResponseRecipient=weather-response
Click Apply.
Now we’ll need to create a File carrier to pass the web API information to PageGate's GetASCII interface and Filter Pack for processing
In Windows, create a new directory for PageGate's message processing to reference. This can be any folder accessible to PageGate, whether on the local hard drive or by UNC path to a network resource. However, if PageGate will need to reference a network resource, the services relevant to these processes will need permission to access it. For more information, see the services section of the documentation. We recommend creating a directory called ‘response’ as a sub-directory of PageGate's data directory (By default, c:\PageGateData\response\).
Next, go back in to the PageGate Admin, then right click Carriers and select click Add.
Give the carrier a name, something straightforward like weather-responses or NWSTranslation.
Set Protocol to: File
Set File Path to the directory you just created. By default, c:\PageGateData\response\
Set Extension to: .txt
Set Max Chars to: 2000
Click Apply.
Now we’ll need to create a recipient tied to the File carrier. To do so, right click Recipients and select Add.
Give the recipient a name, something straightforward like weather-response
Set Type to: Normal
Set Carrier to the carrier you just created. By default, weather-responses
Leave ID/PIN blank.
Set Max Chars to 2000
When finished, click Apply.
Now that we’ve told PageGate what web API to pull information from and configured the translation system, we’ll need to configure the GetASCII interface to look for this data.
In the PageGate Admin, go to Interfaces – GetASCII – Settings. If you already have a polling directory specified, you can skip this step. If you do not have a polling directory, we would recommend creating c:\PageGateData\ASCII\ and specifying that.
Next, go to Interfaces - GetASCII - Settings - Advanced Polling - Files.
Click Add.
Set recipient to: *
Leave From blank.
Set File(s) to: *.txt
In the Path, specify the folder the web API information will be written to. By default, C:\PageGateData\response\
Set File Type to: Standard
Click Apply, then click Apply again.
Now we’ll need to configure a filter script to remove the XML tags from the data before we send it as an SMS. To do so, you’ll first need to copy pgfilter.exe, pgfilter.xml and preproc.bat in to the directory you created for the weather-responses File carrier. By default, c:\PageGateData\response\
Next, we’ll need to edit the pgfilter.xml file to configure the script itself. In this specific example, we’ve configured the filter script to remove all content not related to the <weather> tag in the National Weather Service’s XML output, strip out the XML tags from the text to be sent and send all of the information to a specific group of recipients. However, it’s important to note that this is just an example of what can be done and that all of PageGate’s recipient types and communication methods, both input and output, can be called upon and used.
For the specific code referenced here, have a look at Example 4 in the ‘Complete Script Examples’ section of PageGate’s documentation:
https://www.notepage.net/manuals/pg/v8/server/html/example-4.htm
Once you’ve finished configuring your filter, save and close pgfilter.xml
The final step is to configure a recipient that will initiate the web API poll when prompted. To do so, right click Recipients and select Add.
Give the recipient a name, something straightforward like check-weather
Set Type to: Normal
Set Carrier to the web API polling carrier you created earlier. By default, noaa.
In ID/PIN, enter: 123
Set Max Chars to: 2000
When finished, click Apply.
Once you finish this configuration, any time any message is created for the check-weather recipient, the program will perform the necessary request to poll the current weather data from the National Weather service, then send that information as a text message to the recipients and groups specified in the filter pack's configuration.
As an added bonus, if you have the PageGate Client, you can configure a scheduled message to go to the weather-check recipient at a specified interval. So, you could configure the program to check and broadcast the weather every hour, day, week, month or at any other timescale you prefer.
It's also important to note that you can configure as many HTTPGET carriers to check as many web APIs as you need and have all output fed through the same filter script.
This concludes the video tutorial on how to configure PageGate to pull information from a web API.
|
