The Web Services Query template is a template designed to allow m-Power developers to consume third party web services. This differs from other m-Power templates in that this template is used to access data that might live outside of your database. While the possible applications for this template are limitless, let's look at one simple example for a demonstration of how to use this template.

There are a plethora of web services available, many of which are free. All that m-Power requires to use an existing web service is that it accepts a URL request with or without some parameters, and returns a response in the form of a JSON string. This site, json.org, has some examples of sample JSON objects.

For our example, we have a table where we have logged end user requests of developed m-Power applications. One column in particular holds something called a user agent string, which is really just a browser identifier. In this painted report, we are displaying them along with a pie chart. As can be seen, they are not readily apparent what browser each one represents. So, we will want to "decode" them somehow into data that we can use.

Fortunately, there is a free service available to do exactly this. UserAgentString.com is a simple website where you can copy and paste a user agent string, which then decodes it and tells you what that particular string means, as seen with this example here. In this case, the browser is Internet Explorer 8, and the full details are printed in the table below.

Since we do not want to have to copy and paste every single value we have, we can choose to use this website's API, which stands for application programming interface. Every service has its own API, and the instructions for this one can be seen here on the screen. In particular, for our example, we can see that we can pass the user agent string to the uas parameter, and that in order to get the results back in JSON format, we also need to pass the getJSON parameter with a value of all.

You can see that by clicking on the example link on this page, I get a JSON response back in my browser. We will need this sample data for our next step, so I will go ahead and copy it to my clipboard. Now that we have a web service, the API for the web service, and a sample of the JSON response, its time to build our application. To do so, I will go to the m-Power interface, and create a new retrieval. For our example, I will give it a name of User Agent Decoder, and pick the Web Services Query template. Then I can select any table, one field from this table, and a sequence key, in order to build this application. Note that although all other m-Power specs such as calculations and record selections are available, they are not supported in this template.

Moving on to the build screen, m-Power now asks for a sample of the data in order to know how to create this application. Fortunately, we already copied the data earlier, so we can paste the contents of our clipboard onto the textbox and then press Confirm and Build Application. Once completed, we can open m-Painter to view the generated HTML, as well as paint it as desired. For now, we will leave this alone as painting in this template does not differ from other templates you may be familiar with.

Finally, notice how running this template now causes a 500 error. This is because we have not told the application where to actually access the API we have chosen. To do this, open the app properties and use the web service URL property. For our example, we want to use the previously discussed API, so let's copy and paste that sample URL. Now, when we run it, it runs and returns data. However, what we need is to load in different user agent values at runtime. To do this, we can utilize URL parameters.

To do so, let's open the application properties and delete the current user agent string. Then, we'll replace this value with a custom parameter by typing in the parameter name we want to use, userAgent, surrounded by a dollar sign and curly brackets. You might recognize this syntax from our maintenance redirect feature, however this differs as the parameter won't be a field name from the current application, but rather a parameter of your choosing. Then, we can call the application by passing in this value at runtime, like so.

Now that we have a working example of this template, let's finish our example by linking to this application in our original list of user agents. Back to our initial report, let's open m-Painter, and then put a hover link on each user agent string back to our application. This is not different than other applications, however in this case we will need to ensure we pass the user agent string to our userAgent parameter we defined earlier. Additionally, let's set this link to be a hover link. If we now save and run this report, we can see the same report as before, however now I can easily see what browser each value really represents simply by hovering over them.