Document Query Using Cypress.Web

This topic describes the DoQuery method for querying documents as well as ways to limit the query results and sort the retrieved documents.

DoQuery Method

The DoQuery method enables you to run Cypress expression queries from your Cypress.Web application. You can use prescripted expression queries or allow your end users to develop their own. Cypress returns results from the DoQuery method in the CypressQuery DocuSpace.

When you call the DoQuery method, Cypress displays this cancellation dialog after two seconds of processing:

This dialog allows the end user to stop queries that are processing too slowly.

The documents that the DoQuery method will display are based upon three key items: the expression query passed, the end user’s security, and the properties defined for the CypressQuery object being used.

To call the DoQuery method

Add this line to your Cypress.Web code:

where:

<expression criteria> is a valid Cypress expression query string.

You can call this method from JavaScript or VBScript code. Most Cypress.Web programmers use an HTML form to submit data to a function calling the DoQuery method.

All Cypress.Web expression queries are case-insensitive.

The web page code in this example shows one way you can implement the DoQuery method. You can also find this code in your Cypress\CypressWeb\SampleHTML\CreatorQuery directory.

<html>

<title>Cypress Document Creator Query</title>

<br>

<BR><BR><BR><BR>Search for documents created only by

</form>

</font>

</div>

function submit_query()

{

var query_crit;

query_crit = “[Document Creator] = “ + ”\”” +
document.queryform.creator_id.value = “\””;

parent.frames[1].CypressQuery.DoQuery(query_crit);

}

function queryform_onsubmit()

{

submit_query();

return (false);

}

</script>

</body>

</html>

DoQuery Method with Thin Client API

If you are using thin clients, you can call the DoQuery method with either of these methods:

•

You can put your JavaScript code directly in DocumentViewer/Query.html.

•

You can put code in a separate HTML file and use frames to call the DoQuery method.

To call the DoQuery method from the thin client API

Add this line to your web-page code:

<path to CypressQuery object>.DoQuery(<expression criteria>)

where:

<expression criteria> is a valid Cypress expression query string.

<path to CypressQuery object> is the path to a CypressQuery object; for example:

•

CypressQuery object is in different frame:

<window.frames[<frame number where CypressQuery object is situated>].CypressQuery.DoQuery(<expression criteria>)

•

CypressQuery object is in the same frame:

CypressQuery.DoQuery(<expression criteria>)

The web page code in these examples shows another way you can call the DoQuery method from a different frame:

MyWebPage.html:

<html>

<title>Cypress Document Creator Query</title>

<body>

<br>

<BR><BR><BR><BR>Search for documents with id greater than

</form>

</div>

{

var query_crit;

query_crit = "[Document Id] = " + "\"" +

document.queryform.document_id.value = "\""; parent.frames[0].CypressQuery.DoQuery(query_crit);

}

</script>

</body>

</html>

ApplicationWithFrames.html:

<html>

<head>

<title>Cypress Thin Client With Additional Form</title>

</head>

</frameset>

</html>

where:

/DocumentViewer/Query.html is the path to the thin client query control.

MyWebPage.html is the path to your Web page.

The range_incl Operator

Using Wildcard Query

Cypress is capable of doing a “begins with” wildcard search. An example of this type of search might be an end user who is looking for a specific serial number but knows only that it starts with XJ25 and could, therefore, search for XJ25*. Wildcard searches for information in the middle or end of a string are not allowed.

In order to perform a “begins with” wildcard search, you must use the range_incl operator. The range_incl operator includes the specified text in the query. For example, if you were searching for pages in a company name index that began with Bo, the code would need to search the range between Bo and BoZZZZZZZZZZZZZZZZZ including these two company names.

Wildcard searches of data indices use the available commands and syntax rules for expression queries; however, the wildcard portion of the search needs to be built by the submitting Web page. You must construct JavaScript or VBScript to perform these basic steps:

•

Strip out the wildcard character (usually an asterisk [*]).

•

Derive a low value string and a high value string.

•

Create a query that uses the range_incl operator.

For example, if a user wants to return all documents beginning with Bo, they will most likely enter Bo* in the search input field. Your code would take this string, remove the asterisk, derive the low end (Bo) and high end (BoZZZZZZZZZZZZZZZZZ) of the range, and insert these new values into a query using the range_incl operator.

This JavaScript code provides an abbreviated example of what your code will look like:

var low_value;
var high_value;
var query_string;
.
.
.
low_value=documentname.formname.fieldname.value.replace(“*”,””);
high_value=documentname.formname.fieldname.value.replace(“*”,”ZZZZZZZZZZZZ”);
.
.
.
query_string=”[CustomerName]=range_incl(“+”\””+low_value+”\””+”,”+”\””+high_value+”\””+”)”;
.
.

Wildcard Query Examples

Example 1

Business objective: You need to find information about a specific customer (Zellco Packing) but you are uncertain of the exact spelling of the customer’s name and know nothing else about the customer (e.g., document type, date range, or customer number).

You can submit this expression query:

[CustomerName] = range_incl("Z","Zzzzzzzzzzzzzzzzz")

This expression searches the data index CustomerName for names that begin with the letter z. This would commonly be designated as wildcard search criteria z*.

Example 2

Business objective: You need to find information about a specific company (Habanaroia Tusqe Inc.) but you are uncertain of the exact spelling of this company’s name and know nothing else about the customer (e.g., document type, date range, or customer number).

You can submit this expression query:

[CompanyName] = range_incl("hab","habzzzzzzzzzzzzzzzz")

This expression searches the data index CompanyName for names that begin with the string hab. This would commonly be designated as wildcard search criteria hab*.

Date Range-based Queries

You will often need to query documents based on date ranges. To construct date range queries, you will use the time specification object and the range_incl operator.

Searches on date ranges use the available commands and syntax rules for expression queries; however, the date range portion of the search needs to be built by the submitting Cypress.Web page. You will need to construct JavaScript or VBScript to perform these basic steps:

•

Convert the dates entered by the user into a valid Cypress time specification

•

Create a query that uses the range_incl operator.

For example, if a user wants to return all documents from January 1, 2005 to January 31, 2005, they will most likely enter 01-01-2005 and 01-31-2005 in the search input fields. Your code would take these strings, convert them to time specifications, and insert these new values into a query using the range_incl operator. The JavaScript code shown provides an abbreviated example of what your code will look like:

var low_value_year;
var low_value_month;
var low_value_date;
var high_value_year;
var high_value_month
var high_value_date;
var high_time_spec;
var low_time_spec;
var query_string;
.
.
.
low_value_month=documentname.formname.fromfieldname.value.substr(0, 2);
low_value_date=documentname.formname.fromfieldname.value.substr(3, 2);
low_value_year=documentname.formname.fromfieldname.value.substr(6, 4);
low_time_spec=”tstamp(“+low_value_year+“,”+low_value_month+“,”+low_value_date+“)”;

high_value_month=documentname.formname.tofieldname.value.substr(0, 2);
high_value_date=documentname.formname.tofieldname.value.substr(3, 2);
high_value_year=documentname.formname.tofieldname.value.substr(6, 4);
high_time_spec=”tstamp(“+high_value_year+“,”+high_value_month+“,”+high_value_date+“)”;
.
.
.

query_string=”[ClosingDate]=range_incl(“+low_time_spec+”,”+high_time_spec+”)”;
.
.

Limiting Document Retrieval

By default, when Cypress.Web performs a query, Cypress will retrieve all documents that match the search criteria and that match the end user security – regardless of duplicate titles, as shown:

However, it may be desirable to always have the most recent version of a document retrieved. You can use the TitleGen property to customize the number of documents of the same title displayed in the browser tree list of the Cypress.Web Query Viewer.

The sample code provided may be entered in the is_header.js file found within the Components directory.

This property may be used in only the CypressQuery control.

The property should be added in the form:

For example, if your is_header file currently reads

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" </object>";

and you want to return only one document with a particular title per query, you would modify the file so that it looks like this:

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"false@127.0.01\">" +

" <param name=\"TitleGen\" value=\"1\">" +

" </object>";

Customizing Sort Order

By default, Cypress sorts documents returned from a query by title and then by creation time. However, you can customize the order in which Cypress sorts retrieved documents using the DocSortingType property.

This table describes the document sorting type settings:

DocSortingType Setting	Effect
0 (default)	Primary sort by title ascending, secondary sort by creation time descending
1	Primary sort by title ascending, secondary sort by creation time ascending
2	Primary sort by title descending, secondary sort by creation time descending
3	Primary sort by title descending, secondary sort by creation time ascending
4	Sort by creation time descending
5	Sort by creation time ascending

This property may affect the TitleGen setting. If DocSortingType is set to 0 or 2, TitleGen works normally. However, if this property is set to 1 or 3, then the oldest generations of a document will be displayed instead of the most recent. If this property is set to 4 or 5, TitleGen will have no effect.

The sample code provided may be entered in the is_header.js file found within the Components directory.

This property may be used in only the CypressQuery control.

The property should be added in the form

For example, if your is_header file currently reads

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" </object>";

and you want to perform a descending sort by title and a descending sort by creation date, you would modify the file so that it looks like this:

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DV@127.0.01\">" +

" <param name=\"DocSortingType\" value=\"2\">" +

" </object>";

The sample code above would cause Cypress to sort the documents first by their titles in descending order, then by their creation dates in descending order, as shown:

Limiting Queried Documents

It is sometimes desirable to limit the number of documents that may be returned to a user by Cypress.Web queries. This might be done to improve overall performance of the Cypress environment, or to enforce more granular query parameters to improve the locating of specific documents in the DocuVault.

To limit the number of documents returned by any query initiated in Cypress.Web, set the QueryDocLimit property.

The sample code provided may be entered in the is_header.js file found within the Components directory.

This property may be used in only the CypressQuery control.

The property should be added in the form

For example, if your is_header file currently reads

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" </object>";

and you want to return no more than 100 documents per query, you would modify the file so that it looks like this:

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" <param name=\"QueryDocLimit\" value=\"100\">" +

" </object>";

The code listed above limits the number of returned documents to 100. Should the limit be exceeded, a message will be displayed to the user indicating that too many documents were found.

Setting the maximum number of returned documents to zero (0) causes Cypress to use the default value specified in the Maximum Document Hits field on the View tab of the Administration Tools module’s Parameter tab.

Querying Across Multiple DocuVaults

The QueryLevel property in the Cypress.Web Query Viewer can be used to override default behavior when errors are encountered during a query that searches multiple DocuVaults.

When searching across multiple DocuVaults using Cypress.Web, a DocuVault will not respond to a query if the server on which it is installed is turned off, if there is a communications problem and cannot be connected to, if an index being referenced no longer exists in a DocuVault, or other errors are encountered. Using the QueryLevel property, you can select the type of action and user notification when these circumstances are encountered when searching multiple DocuVaults.

This table lists and describes the supported QueryLevel settings:

QueryLevel Setting	Effect
0 (default)	The query will fail if the query for any index name failed, either because the index name did not exist or the index name was inaccessible. An error message will be displayed to the user and no results will be returned.
1	The query will ignore those DocuVaults on which access failed. A warning message will be displayed and any hits found in the accessible DocuVault(s) will be returned.
2	The query will ignore those DocuVaults on which access failed. No message will be displayed to the user and any hits found in the accessible DocuVault(s) will be returned. (Same as QueryLevel=1 except there is no notification that some DocuVaults were inaccessible.)

The sample code provided may be entered in the is_header.js file found within the Components directory.

This property can only be used in the CypressQuery control.

The property should be added in the form:

For example, if your is_header file currently reads

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" </object>";

and you want to ignore DocuVaults to which access fails, you would modify the file so that it looks like this:

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" <param name=\"QueryLevel\" value=\"1\">" +

" </object>";

Configuring Predefined Query

Sometimes you may wish to have a particular document (or set of documents) automatically display with a single click rather than leaving it to the user to formulate their own queries. For example, you might want to display frequently accessed documents such as policies and procedures or weekly company newsletters at the click of an icon or hyperlink. The InitQuery property allows you to programmatically invoke queries as a Cypress.Web page is being launched.

Pages using the CypressQuery control in conjunction with this property can automatically launch all query results displayed within a Cypress.Web viewer, eliminating the need for any user input related to the query. This property is designed for use with portal applications, corporate intranet logon pages, or any page where you wish to automatically display the results of a pre-defined query.

The sample code provided may be entered in the is_header.js file found within the Components directory.

This property may be used in only the CypressQuery control.

When using this property, be sure to escape quotation marks.

The property should be added in the form

For example, if your is_header file currently reads

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" </object>";

and you want to run a predefined query when the Query Viewer opens, you would modify the file so that it looks like this:

div.innerHTML =

"<object id=\"CypressQuery\" width=\"50\", height=\"50\" " +

" classid=\"clsid:9F73A958-3084-11D3-8C1B-006008B059FF\"> " +

" <param name=\"DocuVault\" value=\"ABC_DocuVault@127.0.01\">" +

" <param name=\"InitQuery\" value=\"[AccountNum] = 99888\">" +

" </object>";