Creating a URL to a custom search form or search results

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.

To create a URL for a custom search definition:

1. Obtain the URL to a search definition that you want to use for this customization:
   1. 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.
   2. Right-click the saved search and click Link > View Link.
   3. Copy the URL to a text editor. You will use this URL later.
2. 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.
3. 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.
4. 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}]

5. 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.

6. 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.
7. 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.