Help Center

Menu

Plugin: Map URL parameters

Purpose

Use this plugin if you need to support non-standard query parameters when calling the search.

This plugin enables you to translate or map custom or non-standard URL parameters provided when calling the search to the correct input parameters required by the search.

When to use this plugin

Use this plugin:

  • To map request parameters when setting up an extra search. e.g. map a field containing a code of a related item to the item’s code field in the extra search. e.g. map meta_relCode → meta_code

  • When migrating to the Squiz DXP search from another search product, and you cannot easily update the input parameters provided by your integration. For example if your query is supplied with a URL like https://example.com/search?q=example+search you could use this plugin to map the q parameter value to the query parameter that is required when using Funnelback.

  • To map HTTP request headers to input parameters of either the main or extra search.

Usage

Enable the plugin

  1. Select Plugins from the side navigation pane and click on the Map URL parameters 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.

Source URL parameter or request header

Configuration key

plugin.map-url-parameters.config.rewrite.*

Data type

string

Required

This setting is optional

Use this to set up parameter mappings for a regular search. 'Parameter 1' defines the source input parameter that will be extracted from the URL. The value defines the target input parameter that the 'Parameter 1' value will be mapped to. Supports URL parameters that are specified multiple times (such as what you might get from form checkboxes) and also HTTP request headers. Note: the 'collection' parameter cannot be modified.

The value of the input parameter defined by 'Parameter 1' will be appended to, or replace the inputParameters or additionalParameters fields in the data model.

Target parameter overwrite mode

Configuration key

plugin.map-url-parameters.config.overwrite.*

Data type

boolean

Default value

false

Required

This setting is optional

Use this to set up parameter mappings for a regular search. Sets the addition mode of the target input parameter. 'Parameter 1' should be set to the value of target input parameter. Acceptable values are no (false) - add the value to the target parameter, preserving any existing values (this is the default); yes (true) - remove any existing values for the target parameter and replace with the mapped value. Note: 'profile' and 'form' parameters are always overwritten.

Configuration key

plugin.map-url-parameters.config.extra_searches..rewrite.

Data type

string

Required

This setting is optional

Use this to set up parameter mappings for an extra search. 'Parameter 1' defines the ID of the extra search that you wish to modify. 'Parameter 2' defines the source input parameter that will be extracted from the URL. The value defines the target input parameter that the 'Parameter 1' value will be mapped to. Supports parameters that are specified multiple times (such as what you might get from form checkboxes). Note: the 'collection' parameter cannot be modified.

The value of the input parameter defined by 'Parameter 2' will be appended to, or replace the inputParameters or additionalParameters fields in the data model of the extra search specified in 'Parameter 1'. Note: the 'collection' parameter cannot be modified.

Configuration key

plugin.map-url-parameters.config.extra_searches..overwrite.

Data type

boolean

Default value

false

Required

This setting is optional

Use this to set up parameter mappings for an extra search. Sets the addition mode of the target input parameter. 'Parameter 1' should be set to the ID of the extra search that you wish to modify. Parameter 2 should be set to the value of target input parameter. Acceptable values are 'no' (false) - add the value to the target parameter, preserving any existing values (this is the default); 'yes' (true) - remove any existing values for the target parameter and replace with the mapped value. Note: 'profile' and 'form' parameters are always overwritten.

  • The collection input parameter is a protected parameter can and cannot be altered. e.g.

    Configuration key name Parameter 1 Value

    Source URL parameter

    collection

    exampleorg~sp-example

    is not allowed and will result in an error being written to the log files.

  • The query input parameter has no special processing to translate any supplied value and is interpreted as if you entered the value into a Funnelback search box.

  • The profile and form input parameters are handled specially. Anything mapped to these parameters will always overwrite the value, and you should ensure that the corresponding results page and template exists, or you may see unexpected behavior.

  • The source URL input parameter (value of the Parameter 1 field in a source URL parameter rule, or Parameter 2 in a source URL parameter - extra search rule) is removed from the data model when it is mapped using this plugin.

  • The source URL input parameter (value of the Parameter 1 field in your rule) can only be mapped to a single target parameter. If multiple Source URL parameter keys are set in the results page configuration with the same Parameter 1 value, only the first matching value will be used and the other mappings ignored. You can map multiple URL parameters, but each parameter can only be mapped to a single target input parameter.

  • Values will always map to question.inputParameters (and question.additionalParameters), regardless of the source being another input parameter or a HTTP request header.

  • If a source parameter appears both as a request header and a URL parameter, and overwrite mode is specified then the result will only contain the value from the URL parameter. However, if overwrite mode is not set then the result will contain both values.

Examples

Consider a scenario where you have a set of items indexed, each with a unique code, and the items also include a field where you can list the code of a related item.

In this example you wish to configure an extra search to bring back the related items, for use with your search.

Configuration key name

Parameter 1

Parameter 2

Value

Source URL parameter or request header - extra search

relitems

meta_code

meta_related

Target parameter overwrite mode - extra search

relitems

meta_related

true

If the URL called is something like http://search.example.com/search.html?collection=example~sp-example&meta_code=A123 this will result in the following being set in the search data model for the relitems extra search:

question.inputParameters["meta_related"]=["A123"]
question.additionalParameters["meta_related"]=["A123"]

The data model for the main search will not be modified.

  • The relitems extra search must be configured and enabled (see: Extra searches)

Example: Map a non-standard parameter containing the query terms to the Funnelback query parameter

Consider a scenario where you are migrating to a Funnelback search and would like to maintain existing URL parameters.

In this example your query terms are passed in the search via a parameter, q. Funnelback uses the query parameter for this purpose the plugin will be configured to map whatever is passed in as the q value and set this as the value for query:

Configuration key name Parameter 1 Value

Source URL parameter or request header

q

exampleorg~sp-example

Target parameter overwrite mode

query

true

If the URL called is something like http://search.example.com/search?q=dog this will result in the following being set in the search data model:

question.inputParameters["query"]=["dog"]
question.additionalParameters["query"]=["dog"]

  • The original q parameter will not be passed through to the search data model as it has been rewritten as query.

  • Any existing value for query will get overwritten, because overwrite mode has been configured for the query parameter.

Example: Map a set of 'filter' parameters as metadata query constraints

Consider a scenario where you have a search that passes in several filter values from checkboxes in a form that you wish to add as a metadata constraint to your search.

Configuration key name Parameter 1 Value

Source URL parameter or request header

filter

meta_searchFilters_orsand

If the URL called is something like http://search.example.com/search?q=dog&filter=small+size&filter=curly+hair this will result in the following being set in the Funnelback data model:

question.inputParameters["meta_searchFilters_orsand"]=["small size","curly hair"]

If your meta_searchFields_orsand parameter had any existing values (e.g. question.inputParameters["meta_searchFilters_orsand"] = ["pure bred"]) set then these will be preserved as the overwrite option is not set, and this would result in the following value in the data model: question.inputParameters["meta_searchFilters_orsand"] = ["pure bred","small size","curly hair"].

Example: Map the userkeys request header to an input parameter

Consider a scenario where you have a search that passes in a userkeys value for DLS using. You wish to map this to a meta_security parameter.

Configuration key name Parameter 1 Value

Source URL parameter or request header

userkeys

meta_security

If the request includes a header userkeys: jsmith then this will result in the following being set in the Funnelback data model:

question.inputParameters["meta_security"]=["jsmith"]

Change log

[2.1.0]

Added

  • Extended the plugin so that the request headers are also mapped to input parameters.

[2.0.0]

Added

  • Added configuration options to extend parameter mapping to extra searches.

Changed

  • Changed the default behavior for updating the query parameter to append. In previous versions query was always overwritten, regardless of any overwrite setting configured for the query parameter. To preserve existing behavior when upgrading to this version, add the following parameter to your configuration:

  • Modifications to the special profile and form parameters are now handled properly, ensuring that the dedicated data model items (question.profile and question.form) are set in addition to the inputParameters and additionalParameters.

Configuration key name Parameter 1 Value

Target parameter overwrite mode

query

true

[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