You can provide users with a bookmark URL that opens a search form that contains a
set of predefined search criteria. You create the set of search criteria by passing a list
of property name-value pairs in JSON format, which is applied to the bookmark URL at run
time when the user invokes the URL. The search form is displayed with your search definition
in a simplified view of IBM® Content
Navigator where users can modify
the values for the custom search criteria.
About this task
You define a custom search by applying custom search criteria, which you provide as
a list of property name-value pairs in a JSON array, to the search bookmark URL. To
change the search definition, you pass the JSON array to the
searchCriteria URL parameter. When a user invokes this URL,
IBM Content
Navigator retrieves the search, applies the
custom search criteria, and displays the search form in a simplified search view window.
Alternatively, you can retrieve the results list directly by appending the
autoRunSearch URL parameter.
You must provide your own error
handling and test your search to ensure that it runs and behaves as you
expect.
Procedure
To create a URL for a custom search definition:
- Obtain the URL to a search definition that you want to use for this
customization:
- In the Search view, create a search that you
want to use as the basis for your custom criteria and save the
search. If you already have a saved search in Search or Teamspaces that you
want to use, you can go to that saved search instead.
- Right-click the saved search and click .
- Copy the URL to a text editor. You will use this URL later.
- Create a JSON array of property name-value pairs to override the values in the
search:
- Use the following format to specify properties and values in the JSON
array: [{"property":"id-1","value": "value-1"}, ... , {"property":
"id-n","value"="value-n"}]
- Use the following format to specify properties and values for child
components:
{"property":"childComponentName","searchCriteria":[{property:"id-1",value:"value-1"},
... , {"property": "id-n","value"="value-n"}]}
For example, the following JSON array contains three property name-value
pairs and one child component:
[{"property":"State","value":"Florida"},{"property":"City","searchCriteria":
[{property:"Orlando",value:"Tampa"}]},{"property":"semanticType",
"value":["1","10"]},{"property":"createdTimestamp",
"value":"2014-01-24T00:00:0-08:00"}]
Tip: You do not need to override the values for all the properties
in your search definition. For example, if you use a search definition that
contains three property pairs, you can override one of the values in the
JSON array. When the search form is rendered, the search form displays the
property with the overriding value and the two properties that you did not
choose to override. Use the following guidelines when you create your JSON
array:
- Dates must be in ISO format, for example,
2014-01-24T00:00:00:00-08:00.
- If you add a choice list to your custom criteria, you must use
symbolic names and actual values only. Do not use display
names.
- For security reasons, ensure that you do not add HTML code or
scripts to the URL.
- Encode the search criteria in the JSON array, for example:
- Before encoding
-
searchCriteria=[{"property":"City","value":"Orlando"},
{"property":"semanticType","value":["1","10"]},
{"property":"createdTimestamp","value":"2014-01-24T00:00:0-08:00"}]
- After encoding
-
searchCriteria=[{%22property%22%3A%22City%22%2C%22value%
22%3A%22Orlando%22},{%22property%22%3A%22semanticType%22%2C%22
value%22%3A%5B%221%22%2C%2210%22%5D},{%22property%22%3A%22
createdTimestamp%22%2C%22value%22%3A%222014-01-24T00%3A00%3A0
-08%3A00%22}]
Important: You must encode the search criteria and set up the
appropriate encoding on the page that invokes the bookmark URL. For example,
use UTF-8 encoding to support extended character sets.
- Pass the searchCriteria parameter with the encoded JSON
array as its value to the URL. For example, add the following parameter to your URL:
searchCriteria=[{%22property%22%3A%22City%22%2C%22value%22%3A%22Orlando%22},
{%22property%22%3A%22semanticType%22%2C%22value%22%3A%5B%221%22%2C%2210%22%5D},
{%22property%22%3A%22createdTimestamp%22%2C%22value%22%3A%222014-01-24T00%
3A00%3A0-08%3A00%22}]
- If you do not want to display the form and instead access the results list
directly when the user invokes the URL, add the parameter
autoRunSearch=true to the URL, for
example:
http://host:port/navigator/bookmark.jsp?desktop=default&repositoryId
=P8_or_CM_System&docid=document_ID&template_name=search_name
&version=version_number&searchCriteria=[{"property":"City","value":"Orlando"},
{"property":"semanticType","value":["1","10"]},{"property":"createdTimestamp",
"value":"2014-01-24T00:00:0-08:00"}]&autoRunSearch=true
When the user invokes the URL, the search results are returned if the search
criteria are valid, values meet the minimum criteria requirements, and
required criteria have default values.
- Implement basic error handling for your custom criteria. For example, follow these error handling suggestions to reduce potential
errors:
- When you use the between operator in your search criteria, ensure that
you display an error if only one value is provided.
- Implement validation for hidden or read-only properties.
- Searches that are set to auto-run must not be run if the data contains
errors. For example, if incompatible data types exist, or if any
required fields are empty.
Because the IBM Content
Navigator web client cannot
predict what custom criteria you might add, the web client does not provide any
error handling for custom criteria. For example, IBM Content
Navigator will not pass an exception if the
custom data is malformed JSON.Important: Do not provide an opening
for cross-site scripting vulnerability in your URL. For example, do not add
JavaScript to your URL. Prevent third parties from executing embedded
scripts through your custom URL, for example, by including a layer of
security such as a redirection alert.
- Test the search. Confirm whether your custom criteria and values are set and
that the search runs. If the search does not return any results or the search
produces an error, check the SystemOut.log server log
file.
What to do next
Distribute the URL to users so that they can add their custom values to the search
definition as needed. You can also use the
autoRunSearch=true
parameter and value and implement the URL in an application to invoke the search results
directly.