Creating Your Own Look-up Service

A data source query look-up service is a web service that responds to requests by returning JSON data in a specified format. There are two types of service:

A list service that has a single end point and returns a list of values. The Widget Framework then carries out the actual look-up operation using the returned list.
An active service that does the look-up itself and returns a list that matches the characters entered (so far) by the user. An active service has two end points, for performing different types of look-up.

A list service is simpler to implement and is fine if the collection of objects to look up is relatively small. For look-ups involving very large object collections, it is probably better to create an active service that does most of the work on the server.

Defining a list service

A list service has a single endpoint (for example: https://mycompany.com/webservice/recipes/search), and responds by returning a JSON file of the following form:

{"lookUpInfo":[
    {
      "value":"apple-pie-1",
      "label":"Apple Pie",
      "summary": "Just like Mom used to make it"
    },
    {
      "value":"apple-pie-2",
      "label":"Apple Pie with chili",
      "summary": "For the jaded palate"
    },
    ...
  ]}

The Widget Framework retrieves this list from the web service the first time it is needed in a Content Studio session, and caches it. It then uses the cached copy to perform the necessary look-ups when the Content Studio user starts typing in the query form look-up field. The values in the JSON file are used as follows:

value: is the value that will actually be stored in the field
label: is matched against the characters entered by the user and displayed in the field when the user finally makes a selection
summary: is optional. If present, summaries are displayed below the labels in the list of options shown while the user is typing in the field

If the user opens a query form in which a look-up field already contains a value, then the Widget Framework uses the same list to look up the label it needs to display in the field.

Defining an active service

An active service has two endpoints, and the last part of each endpoint URL is used as a look-up string. For example:

https://mycompany.com/webservice/recipes/search/{term}, and
https://mycompany.com/webservice/recipes/name/{value}

Each time the user types a character in the look-up field, the contents of the field are used to replace {term}, and the Widget Framework sends a GET request to the resulting URL. Every time the service receives such a request it is expected to use submitted term as a look-up string and return a JSON file. This file has the same structure as the JSON file returned by a list service, but instead of containing containing only entries where label matches the supplied characters. As the user types more characters, the JSON structure returned will therefore get shorter. The returned structure is used to display a list of options from which the user can pick the required value.

The second {value} endpoint is used when the user opens a query form in which a look-up field already contains a value. The Widget Framework then replaces {value} with the field value and sends a GET request to the resulting URL. The service is expected to respond by returning a JSON structure containing a single record, thereby providing the correct label to display in the field.

If, for example, the Widget Framework sent a request to https://mycompany.com/webservice/recipes/name/apple-pie-2, then the response might be:

{
  "value":"apple-pie-2",
  "label":"Apple Pie with chili",
  "summary": "For the jaded palate"
}

The Widget Framework API includes a LookUpInfoclass that you may find helpful in implementing an active lookup service in Java: it provides various useful methods for manipulating and comparing look-up service JSON structures. If you want to use this class then you should add the following dependency to your service's POM file:

<dependency>
  <groupId>com.escenic.widget-framework</groupId>
  <artifactId>wf-webservice</artifactId>
  <version>3.8.0.183277</version>
  <classifier>lib</classifier>
</dependency>