Data model integration of search results

Home Implementation Search Interface Integration

Managed by | Updated 5 years ago.

Funnelback provides native XML and JSON search responses (search.xml, search.json) that contains a complete question/response transaction data model. Changes to theses data models may occur between product versions, which may require updates to any integrations using these endpoints.

The default responses are exhaustive, verbose and natively supported. However, there may be occasions where an customised data model may be preferable to deliver a smaller, more focused XML/JSON search response that is consistent across Funnelback versions.

The table below presents the benefits and drawbacks of using Funnelback's native data model Vs using a customised data model:

	Native Data model (JSON/XML)	Custom Data model
Product Support	Natively supported. Managed by upgrades.	Freemarker templating for creating a custom Data model is supported as a template (i.e. Product issue with the templating engine is supported, but support is not offered for issues related to the custom data model.) Not managed by upgrades.
Response size	Full transaction for data model. ^{*NOTE: Hook scripts can be used to hide sections of the response to reduce the size.}	Tailored to the use case (integration requirements).
Backwards compatibility	May require changes in the consuming application if the data model changes. This can happen within product version updates and system patches.	Data model changes can be catered for in the custom template, mitigating the changes required in the consuming application. May require changes in the custom data model template if the data model changes. This can happen within product version updates and system patches.
Maintenance	All features are present in the data model out of the box. Making use of a new feature (e.g. Best Bet) only requires changing the consuming application.	May require updates to the custom data model template to add new data for the corresponding desired feature.
Flexibility	Inflexible to changes for the needs of the consuming application. Flexibility is limited to hiding parts of the response by utilising hook scripts.	Highly flexible to the needs of the consuming application. Can be configured fully to your requirements.

How to create a custom template for integration

This example shows how to create a JSON data model using a custom template, however any content type such as XML, CSV etc could be used.

Create a custom template via the Administration UI, e.g. custom-json.ftl
Configure the collection to specify the content-type to use for this template:
```
ui.modern.form.custom-json.content_type=application/json
```
Edit the template and implement the custom JSON format, for example:

custom-json.ftl

<#ftl encoding="utf-8" />                                                       
[                                                                               
    <#list response.resultPacket.results as result>                             
    {                                                                           
        "title": "${result.title?json_string}",                                 
        "author": "${result.metaData["a"]!"N/A"?json_string}",                  
        "url": "${result.indexUrl?json_string}"                                 
    }<#if result_has_next>,</#if>                                               
    </#list>                                                                    
]

Add the &form=custom-json parameter to the search URL: http://example.org/s/search.html?collection=example&form=custom-json

Other considerations

Escaping of strings

Strings in the template need to be escaped suitably for the JSON format. For example if a string contains a double quote, it needs to be escaped: key: "value with \"quotes\"" .

This can be achieved by using the ?json_string built-in as per the previous example. Alternatively the template output format can be set to JSON to automatically escape all strings (Available in Funnelback v15.8+): <#ftl output_format="JSON">

Cross-domain requests

If JSON requests are made client-side by a browser, cross domain requests may be an issue. Background about cross domain requests is outside of the scope of this article, however the two main techniques to mitigate the issues are:

Using JSONP and wrap the JSON response inside a Javascript callback,
Configuring CORS on the Modern UI. See ui.modern.cors.allow_origin . All cross domain requests are permitted by default (value = *).