Creating a Custom Web Lookup Component

Overview

A Custom Web Lookup component may be created and used in place of the standard QWebLookup component to provide extended functionality to the CAPSYS CAPTURE Web Client through the Lookup/Validation behavior of an index field. Lookup/Validation components must be designed and implemented as a SOAP-based Web Service.

Module Input

Custom modules must include the following public (VB) function:

Public Function ProcessXML(ByVal DocTypeName As String, ByVal FieldName As String, ByRef PromptFlag As Boolean, ByRef Prompt As String, ByRef ShowMultMatches As Boolean, ByRef IndexXML As String) As String

This function will be called at run-time and will be given values for the DocTypeName and the IndexXML. DocTypeName represents the name of the document type being used to index the current page. FieldName represents the specific Index Field that triggered the call of the Web Service. IndexXML is an XML string that represents the indexes (names and current values) of the index fields on the page. The module may take the index values and manipulate them as necessary, then return the values in the return parameter as an XML string.

The PromptFlag, Prompt and ShowMultMatches parameters are intended to be populated by the module and returned for use in the web client. Descriptions for these parameters are provided below.

Module Output

The module is responsible for returning values for PromptFlag, Prompt and ShowMultMatches. As well, an XML string should be sent as the return parameter that represents the information found.

PromptFlag: Boolean value that indicates whether or not a message box should be displayed to the user.

Prompt: String value representing the message to be displayed in the message box presented to the user.

ShowMultMatches: Boolean value that indicates whether or not to show a selection dialog with all of the matches found and returned in the xml string return parameter. Upon receiving the information back from the module, the web client will follow these processing rules for populating the index fields with the data returned:

If ShowMultMatches is true, then a selection dialog will be displayed allowing the user to select which set of data (as represented by the record nodes in the XML) to use.
If ShowMultMatches is false, then the PromptFlag is checked:
If PromptFlag is true, a Yes/No message box will be displayed with the text message from the Prompt parameter. If the user selects ‘No’, then the data represented by the first record node in the XML will be used. If the user selects ‘Yes’, then the data represented by the second record node in the XML will be used.
If ShowMultMatches and PromptFlag are false, then the data represented by the first record node in the XML will be automatically populated into the index fields for the user without any dialog or message box.

XML String Parameter

The IndexXML parameter and the function’s return parameter are both XML strings that represent a recordset which follows the XML form of:

The “IndexList” tag represents a set of indexes for the current document. Each “IndexList” may contain one or more “Index” tags that present individual index fields. Each Index Field will be represented by the Name and Value tag pairs. If the Index Field is a picklist, then the values from the picklist will be represented as shown above.

The incoming IndexXML parameter will include one “IndexList” node that represents the indexing structure on the current indexing page.

Following is a description of what is expected in the return string:

The Return Parameter:
This XML string will be similar to the IndexXML parameter described above. Any modifications to values and picklist values will be reflected on the indexing page. Additional sets of “IndexList” tags may be included as alternative sets of information to be used by the indexing page.

Multiple Matches:
If multiple matches are found and returned, there should be one record node for each individual set of index values. The first record node in the XML will be considered the default data value.

Single or No Match With No Prompt:
If a single match is found and no message prompt is desired, one record node should be provided with the data that should be used to populate the index fields.

Single or No Match With Prompt:
If a single match is found a message prompt is desired, the xml string should include two record nodes. The first record node will be treated as the default data and will be used if the user selects ‘No’ from the message prompt. The second record node will be treated as the altered data and will be used if the user selects ‘Yes’ from the message prompt.

Index Fields used in connection with the Lookup/Validation behavior should NOT contain spaces in the field name.