Help Center

Menu

Plugin: Modify the search result URL

Purpose

Use this plugin if you need to update the URL that is associated with a search result.

This plugin alters ths URL at the time the search results are returned. The URL is updated within the JSON response, ensuring that the change will work with both Freemarker templates and also any integrations with the JSON response.

The updated URL also works with click tracking (so clicks against the updated URL are correctly tracked against the indexed document).

An option is also provided which updates the displayUrl data model element in addition to the liveUrl.

Versions 3.0.0 and 2.0.0 of the Modify the search result URL plugin are NOT backwards compatible with previous versions. Please refer to the upgrade notes for the upgrade instructions.

Limitations

Because this plugin alters the URL at the time the search results are returned this means you will need to use the index URL when working with any functionality that operates on the search index. This includes:

  • sorting by URL

  • scoping at query time (e.g. using the scope parameter)

  • gscopes and faceted navigation based on URLs.

  • tuning training data

This plugin also does not work with the all-results endpoint.

Usage

Enable the plugin

  1. Select Plugins from the side navigation pane and click on the Modify the search result URL tile.

  2. From the Location section, select the results page to which you would like to enable this plugin from the Select a results page select list.

The plugin will take effect as soon as you finish running through the plugin setup steps.

Configuration settings

The configuration settings section is where you do most of the configuration for your plugin. The settings enable you to control how the plugin behaves.

The configuration key names below are only used if you are configuring this plugin manually. The configuration keys are set in the results page configuration to configure the plugin. When setting the keys manually you need to type in (or copy and paste) the key name and value.

URL match pattern

Configuration key

plugin.alter-live-url.config.*.regex-trigger

Data type

string

Required

This setting is optional

Regular expression used to match against the original live URL, to which the reformat will be applied. 'Parameter 1' is a unique identifier used to enable multiple URL match pattern to be defined.

If the original URL matches the Java regular expression then the URL will be replaced based on the Freemarker template defined in the URL reformatting template option.

URLs will not be modified by default.

URL reformatting template

Configuration key

plugin.alter-live-url.config.*.reformat-ftl

Data type

string

Required

This setting is optional

Freemarker template fragment that defines the new, modified live URL. 'Parameter 1' is a unique identifier which needs to match the corresponding URL match pattern option

The live URL will be replaced with the generated output of this Freemarker template.

Update display URL

Configuration key

plugin.alter-live-url.config.*.update-display-url

Data type

boolean

Default value

false

Required

This setting is optional

Should the display URL also be updated? 'Parameter 1' is a unique identifier which needs to match the corresponding URL match pattern option

Defining the Freemarker template

The URL reformatting template option uses a small Freemarker template fragment to define the transformed live URL.

The question, response and result objects from the standard data model are available for use in your template.

  • question: The SearchQuestion from the SearchTransaction. You can target sub-elements directly. e.g. question.query.

  • response: The SearchResponse from the SearchTransaction. You can target sub-elements directly. e.g. response.resultPacket.resultsSummary.fullyMatching.

  • result: The current result the template is being called on. You can target sub-elements directly. e.g. result.title, result.listMetadata["url"]?first.

In addition, a liveUrlParts element is provided which provides elements from the live URL that can be used when constructing the transformed URL:

  • liveUrlParts.fragment: The fragment of the live URL e.g. #foo.

  • liveUrlParts.path: The path of the live URL e.g. /path.

  • liveUrlParts.path_ends_with_slash: The path of the live URL ending in a slash e.g. /path/, /.

  • liveUrlParts.query: The URL query parameters of the live URL e.g. ?f=1.

  • liveUrlParts.query_ends_with_query_separator: The URL query parameters ending with a query separator so that you can append easily add parameters e.g. ?f=1&, ?.

  • liveUrlParts.scheme_host_port: The schema, host and port of the live URL e.g. +https://example.com+ , https://example.com:8443.

  • liveUrlParts.scheme_host_port_path_query_ends_with_query_separator: The schema, host, port, path and URL query parameters ending with a query separator so that you can append easily add parameters e.g. https://example.com/p?f=1&

The Freemarker template can also make use of Freemarker built-in functions and directives (e.g. you can use conditional directives such as <#if>, <#else>, or built-ins like ?url or ?lowercase).

Early versions of this plugin did not properly support the types used within the Funnelback data model and syntax such as ${result.listMetadata["url"]?first} did not work. This meant that earlier templates used function calls (e.g. getListMetadata()) to access these items. When upgrading to 3.x or higher existing templates must be reviewed and updated. See the upgrade notes below.

Error handling

When an error occurs the plugin will behave as follows:

  • If there is an error compiling the template then the plugin will abort. The template can be tested by running your search via the administration dashboard and viewing the errors output to the modernui.Admin.log. Note: this log will capture the majority of errors, however some fatal errors won’t be visible as these may be caught in system-level logs.

  • If the template compiles and returns data, but fails to produce a parseable URL - the result’s live URL will be updated but the click URL will remain unchanged.

  • If the template fails to produce a URL (e.g. the output is empty) then the result’s URLs will remain unchanged.

Upgrade notes

Upgrading from version [2.x.x] to version [3.x.x]

Version 3.0.0 of the Modify the search result URL plugin is NOT backwards compatible with version 2.x.

The methods for accessing the data model have been updated to be consistent with Freemarker templating used in other part of Funnelback. This means that the template no longer supports the use of .get() calls to retrieve data model values.

When upgrading to 3.x you will need to review your transformation templates and update any data model calls that call a get function.

e.g. replace:

  • result.getLiveUrl() with result.liveUrl

  • result.getListMetadata().get("fid")[0] with result.listMetadata["fid"]?first

Upgrading from version [1.x.x] to version [2.x.x]

Version 2.0.0 of the Modify the search result URL plugin is NOT backwards compatible with version 1.x.

Please follow the instructions below to upgrade from 1.x.x to version 2.x.x

Step 1: edit your results page configuration and unpublish the old plugin configuration keys:

  • plugin.alter-live-url.config.regex-trigger,

  • plugin.alter-live-url.config.reformat-ftl, and

  • plugin.alter-live-url.config.update-display-url

Step 2: Open the raw configuration key editor by selecting Tools  Edit raw data.

Edit the configuration keys to add an additional parameter 1 identifier into all the keys that you just unpublished. This updates the key format from plugin.alter-live-url.config.<config item> to plugin.alter-live-url.config.*.<config item>. Replace the * with an identifier.

For example, from

  • plugin.alter-live-url.config.regex-trigger,

  • plugin.alter-live-url.config.reformat-ftl, and

  • plugin.alter-live-url.config.update-display-url

to

  • plugin.alter-live-url.config.1.regex-trigger,

  • plugin.alter-live-url.config.1.reformat-ftl, and

  • plugin.alter-live-url.config.1.update-display-url.

Step 3: Update the plugin version to the current plugin version number.

e.g. update

  • plugin.alter-live-url.version=1.2.0

to

  • plugin.alter-live-url.version=2.0.0

Step 4: Press the save button, then publish the updated key values.

Examples

Update all http URLs to https

This example updates all http URLs to be accessed via https.

Configuration key name

Parameter 1

Value

Description

URL match pattern

http

http://.*

Apply this to all URLs that contain http:// followed by other characters.

URL reformatting template

http

${result.liveUrl!?replace("http://(.*)", "https://$1", "r")}

Updates the URL protocol to https.

The URL match pattern matches on any http schema URLs (.* will match anything that follows the http://).

Breaking down the URL reformatting template:

  • result.liveUrl(): Gets the live URL of the current result.

  • !: Prevents errors when getLiveUrl() returns null.

  • ?replace(: Calls the freemarker replace method.

  • http://(.*): Defines a regular expression which is matched against the document’s live URL. This example extracts everything after http:// as the first capture group.

    This regular expression doesn’t have to be the same as the one you defined for your URL match pattern. The URL match pattern determines if the transformation will run, the Freemarker regular expression extracts things from the live URL to build the transformed URL. https://$1: Defines the URL to generate - in this case, https:// followed by the first capture group ($1). "r": Tells Freemarker to use a regular expression when applying the Freemarker replacement. You can use the simpler replacement options within Freemarker when defining the template, if these serve your replacement needs.

Append a URL parameter from result metadata

This example appends the id parameter to the live URL with the value sourced from the fid metadata class of the result.

Configuration key name

Parameter 1

Value

Description

URL match pattern

all

.*

Apply this to all URLs

URL reformatting template

all

<#if result.listMetadata?keys?seq_contains("url")>${liveUrlParts.scheme_host_port_path_query_ends_with_query_separator}fid=${result.listMetadatae["id"]?first?url}${liveUrlParts.fragment}</#if>

Add the fid metadata to the id URL parameter.

The regex-trigger matches on any http schema URLs.

Breaking down the reformat-ftl: * <#if result.listMetadata?keys?seq_contains("url")>: Freemarker conditional check to ensure that the result.listMetadata element contains a url key, preventing the template from returning an error. * ${liveUrlParts.scheme_host_port_path_query_ends_with_query_separator}: Most of the URL ending with a query separator e.g. https://example.com/?a=b& * id=: adds an id parameter to the generated URL. * ${result.listMetadata["fid"]: Inserts the first value of fid metadata from the result.listMetadata["fid"] element of the data model. * ?url: Applies URL encoding to any special characters within the metadata field to ensure a valid URL is generated. * ${liveUrlParts.fragment}: Appends the url fragment, if there is one.

Change log

[3.0.0]

Fixed

  • Fixed a bug where the data model types were not fully compatible with Freemarker, meaning that many Freemarker built-in functions did not work in a way consistent with Funnelback search result templates. This means that it is now possible to use built-ins such as ?keys and ?seq_contains, and that you can access data model elements using the standard syntax (e.g. result.listMetadata["url"]?first).

Changed

  • Transformation template no longer supports using the get() methods to access the data model variables. When upgrading to 3.x or newer you will need to update your transformation templates. (see upgrade notes)

[2.2.0]

Fixed

  • Fixed a bug where click tracking url was not getting correct values if the LiveUrl was empty.

  • Added logic to exit the plugin when template fails to compile.

[2.1.0]

Fixed

  • Fixed a bug where the plugin fails to process URLs containing special characters such as "|".

[2.0.0]

Added

  • Multiple URL match patterns and reformatting templates can now be defined. This allows for more complex URL transformations to be defined.

Changed

[1.2.0]

Added

  • Added an option to also apply the updated URL to the displayUrl data model field. The default behavior does not update this field so upgrading to this version will not change existing behavior.

[1.1.0]

Changed

  • Updated to the latest version plugin framework (Funnelback shared v16.20) to enable integration with the new plugin management dashboard.

See also