Implementation: Filters - Creating Pre-sets for Discovery Searches
The URL parameters setting on the Discovery Configuration page allows Administrators to construct URLs for the Discovery Module Search Results page so that the page can be loaded into a pre-filtered state based on a range of URL query parameters.
This functionality allows organisations to link to the Discovery Module from other sites, using the pre-set filters to direct users to a specific subset of the available profiles, groups or equipment. Using this functionality, organisations can link directly to a list of all of the experts associated with a specific group, theme, or other category represented in your filters.
This feature allows organisations to build URLs which pre-filter the search results page using one of the configured filters. When a visitor clicks on a one of these constructed URLs, the search results page will load showing just the subset of data with the relevant filter values. The user can then go on to adjust the filters more if desired.
Using the URL parameters feature
To use the URL parameter feature, it must be first enabled in the Discovery Configuration settings:
For clients running Elements v6.7 to v6.19: This can be done within the Discovery Configuration file (please submit a support ticket to request this change).
For clients running Elements v6.20 onwards: System Administrators can enable this setting on the ‘Core Settings’ tab on the Discovery Configurations page.
Once the feature is enabled, you can construct URLs to create the pre-filtered state you desire. Each URL you construct can include more than one filter, however, you will only be able to apply one value from each filter at the same time. For example, your URL could contain one value from the Department filter and one value from Custom Filter 1; but it cannot contain two values from the Department filter.
Selecting parameter codes
Each of the filters is represented as a part of the URL structure via the following parameter codes:
Filter Name | Parameter code |
Custom filter 1 | c1 |
Custom filter 2 | c2 |
Custom filter 3 | c3 |
Custom filter 4 | c4 |
Custom filter 5 | c5 |
Department filter (Users only) | d |
Object types (Equipment only) | ot |
You can check the underlying filter name on the Filters tab of the Manage Discovery Configurations page, in this section:
Image: The underlying filter name is available in the filter column.
Building URLs
To use this feature, you need to build URLs in a specific structure that includes the relevant filter parameter codes and associated values such as: https://demo.discovery.symplectic.org/search?by=text&type=user&v=&d=Symplectic&c1=Media%20enquiries
In this example, the part in bold represents the part of the URL that you will construct to add the URL parameters and filter values you want. The following instructions will guide you through the process of building a URL.
To build a URL:
Start with the base URL for your search results page with no search or filter parameters included. You can get this by going to your Discovery site and running a search in the desired search mode (users, groups or equipment) with no search terms. For example for users, it should look like this: https://demo.discovery.symplectic.org/search?by=text&type=user&v=
Add the desired URL parameters in the following format: an ‘&’ sign followed by the parameter code of the desired filter (eg. ‘d’) followed by an ‘=” sign, followed by the exact filter value. For example, to filter by the department filter to the department ‘Symplectic’, it should look like this: https://demo.discovery.symplectic.org/search?by=text&type=user&v=&d=Symplectic
To pre-set more filters, simply add more URL parameters using the same format, i.e. &filterCode=value. For example, to filter by the Department to "Symplectic" and by Custom filter 1 to "Media enquiries", use the URL: https://demo.discovery.symplectic.org/search?by=text&type=user&v=&d=Symplectic&c1=Media%20enquiries
Preparing filter values to add to URLs
When preparing the filter values you want to include in the URL, there are a number important steps to follow:
The filter values must match exactly, including case sensitivity (ie. any capitalisation must be the same).
Some characters have special meanings in URLs; If your filter value contains any of these, they must be "percent encoded". For example:
a space ( ) must be replaced with %20
an ampersand (&) must be replaced with %26
a comma (,) must be replaced with %2C
For example to pre-set the Department filter to "Physics, Chemistry & Mathematics" you would use the URL: https://demo.discovery.symplectic.org/search?by=text&type=user&v=&d=Physics%2C%20Chemistry%20%26%20Mathematics
For a full list of characters that require percent encoding, see https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding.
Important notes
Expected user experience: When a visitor to Discovery clicks on a URL containing URL parameters, the search results page that loads will function in the same way as if a user had manually applied those filters, and they can go on to further interact with the results and filters as desired. If the user then chooses to run a new search, the pre-applied filters will be removed.
Impact of changes to filter values: If the values in your filters change (eg. you change the spelling, capitalisation or remove certain values), any URLs based on those values will no longer work.
Impact of changes to Discovery URL structure: It is possible that Discovery URL structures could change in the future. Whilst we don’t anticipate needing to change the URL structure often, there is a chance it may be necessary that the URL structure is changed at some point to support the future development of Discovery. If so, this could break any URLs already in use and you will be responsible for recreating any URLs in use following a revised pre-defined structure. Should this need to occur, it will be announced in our release and upgrade notes to allow you to plan for the change.