HTTP Request

Using HTTP Query Databoxes in your scripts

Introduction

HTTP Query Databoxes can be used to retrieve information from any web API. They are also capable of updating data in certain environments that supply a web API to do so.

To demonstrate the functionality this page will show how to produce this message based upon the HTTP APIs offered by Geoapify (a paid for service that provides local area information around the globe - see here: https://www.geoapify.com/):

Creating the HTTP Databoxes

Two HTTP databoxes are required to get the data for the above message box. This is due to the design of the Geoapify API. The hospital search API requires a 'Place_id' which is defined within Geoapfify; this place_id can only be accessed by providing the tenant's postcode to the Geoapify API. So:

• The first HTTP databox gets the place_id by passing Geoapify the tenant's postcode.

• The second HTTP databox passes the place_id to Geoapify and gets back the list of hospitals in the local area (equally this could be dental surgeries or supermarkets)

The first databox looks as follows (with the apiKey blanked here - the Geoapify website will provide you with an API key when an account is created).

The second databox references the first, utilising the returned place_id in it's HTTP URL:

In previous versions of Keyfax it was not possible to 'chain' calls to SQL databoxes by nesting references to other bookmarks within the SQL - but in 4.4.8 these rules have been relaxed to make multi-call SQL or HTTP databoxes a possibility.

Creating the Message

The message is a normal message - but as we are creating HTML elements from the output of a databox (in this case a list using 'ul' and 'li' HTML elements) there's a little bit of scripting trickery to take care of.

The 'HTML Source' view of the message should be set to the following:

<p>Local services:</p>

<div id="hospitals">{HTTP.NearestHospitals.Hospital}</div>
<script>
    // Hospital injection!
    var data = document.getElementById('hospitals').innerHTML;
    var items = data.split('&lt;br/&gt;');

    var html = items
        .filter(x => x.trim().length > 0)
        .map(x => x.trim())
        .join('</li><li>');
    html = '<ul><li>' + html + '</li></ul>';
    document.getElementById("hospitals").innerHTML = html;
</script>

Overview

Properties

Group - when displayed in the Selection List, Databoxes are arranged into groups. Select a group from the drop down list to add the Databox to an existing group or type in a new group name to create a new group.

HTTP Verb - a the 'verb' is part of the HTTP protocol specification. Common verbs to use are: GET, POST, PUT, UPDATE, OPTIONS - see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods for the full list

Name – a descriptive name for the Databox. If you can, make this a meaningful description to enable easy identification in your scripts..

Xpath Record Identifier – all data retrieved from an HTTP databox is converted to XML (even JSON responses), this setting allows Xpath to be used to identify the root element of each record of data in a multi-record response.

Description - a short description of the Databox. This is displayed in the Databox Selection list in and is searchable using the filter.

URL – The URL to call when this databox is executed - this field can incorporate references to other databox expressions to pass URL parameters taken from, for example, the startup XML.

Headers - some HTTP web api servers require authorisation headers to be callable, those authorisation and authentication headers can be placed here. In some cases and initial HTTP call to retrieve a token (via one databox) is required before that token is used in a second HTTP databox to full authenticate against the service. Headers are also used to specify the format of the incoming Body of the HTTP request - please see an HTTP tutorial for full details.

Body - the HTTP body is usually only passed in a POST or PUT (HTTP Verb) request but can be present for any call. If the aim of the request is to update a server with information, that information is almost always POST'ed in the body section of the request in either JSON or 'Forms Encoded' format. Once again, please see an HTTP tutorial for full details.

Test – test the HTTP request and Expressions setup against the databox.

Expressions – these are covered in-depth in the Databox Expressions section. Typically, the Expression Item will be used to access individual 'columns' of data returned by the query. In the example above you'll see a rowmerge Expression which merges the 'formatted' field returned from the HTTP request into a single string which is then displayed by the message definition in script.

All Databoxes are re-evaluated every time they are referenced either directly or through an Expression; for HTTP Databoxes this will re-run the HTTP query and could be inefficient. If it is known the request will always return the same result and the request returns multiple values or is referenced several times in the script then it is better to use a Databox-Write to store the original result into a separate Script Databox and use the latter for all subsequent references.

Handling multiple rows of data

Since 4.4.8 of Keyfax it is now possible to handle multiple rows of data with both SQL and HTTP databoxes. For HTTP databoxes this is built in by default. For SQL databoxes - so as not to change the operation of existing scripts - the multi-row support requires an opt-in on the SQL databox definition page by selecting 'Multiple records in result allowed'.

For 4.4.7 and earlier:

If an SQL Query returns more than a single row, this is considered an error and the SQL query should be amended to ensure this cannot happen. It is good practice to always test for this eventuality in which case you will see this message: 'Unable to process multiple rows returned'.

Depending on the context, there may be various techniques to restrict results to a single row; typically this may use the 'TOP n' clause. For example, to return a single row containing the current balance for the most recent tenancy record: SELECT TOP 1 CurrentBalance FROM Tenants WHERE TenantID = {Import.CallerId} ORDER BY TenancyStartDate DESC Having said that, there are exceptions where multiple rows can be returned but the results must be coerced into an XML packet; this will require more specialist knowledge - see the section Handling multiple rows from SQL.

It should also be taken into consideration that if an SQL Query doesn't return anything then any Expressions against it will not run.