Web Services Query template

 

Jump to:

Features
Template Notes
Video Walkthrough
Application Properties
Web Parameters

Template Features

The Web Services Query template is a very useful tool for developers to incorporate 3rd party web services into their m-Power applications. Designed like a Single Record Inquiry, these templates support consuming any outside web service that returns data in the standard JSON format. For more on the JSON format, see this link. At runtime, this template makes a request to your web service of choice and then displays the results within the m-Power environment.

All Templates Features:

Customize HTML with m-Painter:
m-Power ships with its own HTML editor. This tool, called m-Painter, allows you to modify the HTML code in a very easy way by using a WYSIWYG (What You See Is What You Get) editor, where all the graphical modifications are instantly visible. For the advance developers, there is a text editor mode too. You can access the HTML editor by clicking Presentation on the Application Menu. Learn more.

Tablet & Mobile Output:
m-Power allows developers to create applications specifically for PC browser, Tablet, and Smartphone devices. For the user, this means that they can access the same report on their PC, tablet, and smartphone and see a completely different output on each that has been tailor-made for their device. For the developer, it means that they can create and maintain one single application that will create the proper output formats automatically. Learn more.

Web Services Query Features:

Consumes Any Web Service:
Any web service that returns a JSON string can be called, opening the door to unrelated, interconnected applications.

Accepts All Needed Parameters:
Many web services require specific parameters in order to generate the desired response. Using this template allows you to easily pass these parameters to your web service at runtime, generating results on the fly.

Always Live Data:
Using this template to call a web service means you will always be displaying the latest results, not a cached version. As long as your web service accepts requests, this template will get and display the newest data.

Back To The Top

Template Notes

Application Settings

Description: Allow developers to give their application a description.

Program Name: This will be the application’s name, by default m-Power uses the letter I (Inquiry) followed by a five digits number. Also by default, for every new application m-Power will look at the largest number in use and increase it by 10, you can manually change this number.
Note: the number must be unique in the Data Dictionary.

Select Only Matching Records: N/A

Template: You can select a template by scrolling left or right through the available templates. The templates define the general layout and functionality of the resulting application. This section will list all the available retrieval templates; you will see a small screenshot of what that template looks like at runtime. Learn more about templates.

Data Selection

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for data. Instead, you must select one field from any table in your data dictionary in order to fulfill this required step.

Sequencing

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application. Instead, you must select one field as a sequence key in order to fulfill this required step.

Field Settings

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application, and can safely be ignored.

Record Selections

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application, and can safely be ignored.

Calculations

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application, and can safely be ignored.

External Objects

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application, and can safely be ignored.

SmartLinks

Since the Web Services Query template pulls all of its data through the web service API, this screen is not used for your application, and can safely be ignored.

Back To The Top

Video Walkthrough

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.

Back To The Top

Application Properties

When accessing the Application Properties, a window will slide open with several tabs; let’s go through each of the tabs:

Back to the Top

Web Parameters

Common Parameters — These parameters apply to every template:

Name Valid Values Example Value Default Value Description
basic
  • 0: Off
  • 1: On
1 0 This parameter allows the app to only display the main content area.
CALCULAXXX
  • Any URL-encoded value
5000 When a calculation is a parameter calc, you can pass its value across the URL to other mrc applications. Use CALCULA001 for your first calculation, CALCULA002 for your second calculation, and so on, for all your parameter calculations.
Custom Parameters
  • Any URL-encoded value
33 Freemarker custom parameters can be passed through the URL.
data
  • 0: Off
  • 1: On
1 0 This parameter allows the app to only display the main data table.
debug
  • 0: Off
  • 1: On
  • 2: On & Show Import URLs
1 0 Loads your application with SQL statement and application logic time listed. This is often useful in determining how your dataset was determined and deciding if indexes should be created for this query.
devicetype
  • pc: Computer
  • tab: Tablet
  • mob: Smartphone
tab pc This parameter sets the current device type mode for the entire session. While device is automatically seen and set, you can use this to manually change it to a different device type.
FIELD
  • Any URL-encoded value
23 Applications allow you to pass values directly to any field when it is specified as a sequence key.
help
  • 0: Off
  • 1: On
1 0 This parameter controls whether the parameter listing screen should be displayed for this application or not.
hide_header_footer
  • 0: Show header/footer
  • 1: Hide header/footer
1 0 This parameter controls whether the header and footer are hidden.
impTags
  • Any positive integer
1 0 This parameter allows the app to only display the HTML inside the associated custom import.
init
  • 0: Off
  • 1: On
1 0 Forces your application to refresh the page from the server. Useful if you are making changes in a development environment but are not seeing your changes.
locale
  • ar: Arabic
  • bg: Bulgarian
  • ca: Catalan
  • zh: Chinese
  • cs: Czech
  • da: Danish
  • nl: Dutch
  • en: English
  • et: Estonian
  • fi: Finnish
  • fr: French
  • de: German
  • el: Greek
  • he: Haitian Creole
  • hi: Hindi
  • ht: Hebrew
  • hu: Hungarian
  • id: Indonesian
  • it: Italian
  • ja: Japanese
  • ko: Korean
  • lv: Latvian
  • lt: Lithuanian
  • no: Norwegian
  • pl: Polish
  • pt: Portuguese
  • ro: Romanian
  • ru: Russian
  • sk: Slovak
  • sl: Slovene
  • es: Spanish
  • sv: Swedish
  • th: Thai
  • tr: Turkish
  • uk: Ukrainian
  • vi: Vietnamese
es en This lets you choose which language layer to view for the entire session. Only available when using the m-Power Translate feature.

Back To The Top

Created: August 12, 2015 | Modified: June 6, 2017