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.
Note: This step does not apply for
IBM Content Manager OnDemand searches. For more
information about valid parameters and values for viewing
IBM Content Manager OnDemand
searches, see
Constructing a URL for IBM Content Navigator.
-
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}]
-
You can optionally specify the following parameters in your URL:
Parameter |
Description |
autoRunSearch |
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.
|
autoOpenItem |
If the search returns
a single item, you can automatically open that item by specifying
autoOpenItem=true in the search 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&
autoOpenItem=true
Important: This parameter is valid only if the search is configured to run
automatically, for example:
- The search that you specify in the template_name parameter is configured to
run automatically.
- You specify
autoRunSearch=true in the URL
This setting is ignored if the search returns more than one result.
|
hideSearchCriteria |
If you do not want to display the search criteria when the user invokes the URL, add the
parameter hideSearchCriteria=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&
hideSearchCriteria=true
Important: This parameter is valid only if the search is configured to run
automatically, for example:
- The search that you specify in the template_name parameter is configured to
run automatically.
- You specify
autoRunSearch=true in the URL
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.