Webservice Lookups

A Webservice Lookup performs a GET to a REST service and returns one value from the response. The WebserviceLookup function runs it. The Webservices Cookbook works through one against a live service.

Open the screen from Setup > Webservices > Webservice Lookups. It shows a grid of the existing lookups with Add, Edit and Delete. A lookup opens as a dialog: the settings on the left and, on the right, the request, the value it returns and a trace of the exchange.

Id

The id of the lookup, up to 12 characters. It is the first argument of the WebserviceLookup function. You cannot change it after you save the lookup.

Description

A description, up to 60 characters.

Webservice Behaviour

The behaviour that supplies the authentication, base URL, request headers, throttling and paging. It is optional. Without a behaviour, the Query Url must be a full URL and the request is unauthenticated.

Paging

If the behaviour pages, a lookup fetches every page before it looks for the value, then searches the pages in order and returns the first match. A lookup whose query returns many pages is slow and heavy. Refine the query so that it returns the record you want, or cache the result so that IMan fetches the pages once.

Request Headers

Http Headers sent with each lookup request, in addition to the behaviour's. A header value can carry the same %[1], %[2] placeholders as the Query Url.

IMan masks the value of a secret header in the list. Secret values explains which headers count as secret. The list shows ********, followed by the last three characters when the value is eight or more characters long. Press Reveal above the list to show the stored values, and press Hide to mask them again. Revealing needs the Can reveal a stored secret in full permission.

Query Url

The URL sent to the service. With a behaviour, IMan joins it to the behaviour's Base Url. Without one, it must be the full URL. IMan applies the URL checks to it, so a placeholder can appear in the path or query but not in the host.

You parameterise the URL with %[1], %[2], %[3] and so on. IMan replaces each with the matching value passed in the wherevalues argument of the WebserviceLookup function. It URL-encodes the value as it inserts it, so spaces and reserved characters are safe. Unlike other lookups, the number must be in square brackets.

Parameter values

As you type, a box appears beneath the Query Url for each placeholder it contains. Only TEST uses the values you enter there. They let you try a parameterised lookup without an integration, and IMan does not save them with the lookup.

Return Path

The path to the value the lookup returns. IMan reads the response as JSON, so the path is a JPath, absolute from the root of the response. In the example above, /order/name returns the name property of the order object.

The return path is optional here. The returnpath argument of the WebserviceLookup function overrides it.

Parameterised return path

You can parameterise the return path with the same syntax as the Query Url, so that IMan substitutes part of the path at run time. This is useful when the service returns a collection instead of the single record you want. A query in the path picks the matching element.

The placeholder numbers continue from the Query Url. If the URL uses %[1] and %[2], the first placeholder in the return path is %[3]. In the lookup below the URL has no placeholder, so the return path uses %[1]. The path returns the id of the list whose name matches the value passed.

You cannot test a parameterised return path from this screen.

Cache Lookup

When ticked, IMan keeps the result of each request for the rest of the run, keyed on the behaviour and the resolved URL. It answers a later call with the same URL from the cache without making a request. For a lookup called once per record against a small set of keys, this removes most of the requests.

TEST and the results pane

TEST makes the request with the parameter values you entered above. The right-hand pane shows:

• Http Request Materialisation: the GET as IMan will send it, with the placeholders resolved.
• Return Value: the value the Return Path produced from the response.
• Request Trace: the request and response in full, headers and body. Use it to diagnose a lookup that returns nothing.