DocSTAR Integration Toolkit Reference Guidesupport.docstar.com/portal/docstar/techdvd/docstar... · docSTAR Integration Agent Reference Guide Page 1 Introduction The docSTAR Integration

IInntteeggrraattiioonn AAggeenntt 22..00 RReeffeerreennccee GGuuiiddee

RReevviissiioonn 11:: 88//1155//22000066

docSTAR Integration Agent Reference Guide Contents

TTaabbllee ooff CCoonntteennttss

IInnttrroodduuccttiioonn .......................................................................................................................................................................................................................................... 11 Other Integration Products............................................................................................. 1 Integration Agent and WebView .................................................................................... 1

SSeeccttiioonn 11:: ddooccSSTTAARR IInntteeggrraattiioonn AAggeenntt RReeqquuiirreemmeennttss ................................................................................................ 33 The docSTAR WebView/Integration Agent/SmartLink Installation CD.......................... 3

SSeeccttiioonn 22:: ddooccSSTTAARR IInntteeggrraattiioonn AAggeenntt IInnssttaallllaattiioonn .......................................................................................................... 33 Installation Steps ........................................................................................................... 3 Step 1: Install docSTAR Integration License on docSTAR Host .................................. 4 Step 2: Install docSTAR WebView ............................................................................... 5 Step 3: Install Barcode Cover Sheets (Optional) .......................................................... 5 Step 4: Install Virtual Cover Sheets (Optional) ............................................................. 7 Step 5: Install docSTAR Integrator Software (Optional) ............................................... 9

SSeeccttiioonn 33:: HHoott KKeeyy IInntteeggrraattiioonn MMooddee ((IInntteeggrraattoorr)) ............................................................................................................ 1133 Steps ........................................................................................................................... 13 Step 1: Use docSTAR Integrator Setup to define hot keys......................................... 13 Step 2: Install Integrator and Hot Keys on Client Stations.......................................... 19 Integrator Setup Reference ......................................................................................... 20

SSeeccttiioonn 44:: PPrrooggrraammmmaattiicc IInntteeggrraattiioonn MMooddee................................................................................................................................ 2222 Thick or Thin Client...................................................................................................... 22 Quick Start ................................................................................................................... 23 Building the URL.......................................................................................................... 23 Sample VB Code ......................................................................................................... 27

SSeeccttiioonn 55:: CCoovveerr PPaaggeess ................................................................................................................................................................................................ 2277 Base URL .................................................................................................................... 27 Barcode Fonts ............................................................................................................. 28 Options ........................................................................................................................ 28

SSeeccttiioonn 66:: VViirrttuuaall CCoovveerr SShheeeettss...................................................................................................................................................................... 2288 How They Work ........................................................................................................... 28 Creating VCS............................................................................................................... 29 Using Virtual Cover Sheets.......................................................................................... 29 VCS Status .................................................................................................................. 33

docSTAR Integration Agent Reference Guide Page 1

Introduction

The docSTAR Integration Agent provides a simple application programming interface (API) to customers, value-added resellers, and developers of third party applications so that users of another application can retrieve and file docSTAR documents in an integrated manner. It also includes a “screen scraping” program, which can be used to trigger integrated retrieval without programming to the API.

Throughout this Guide, the third party application that is to be integrated with docSTAR will be referred to as the “target application”. Integration Agent is used primarily to “image enable” the target application. This includes two fundamental functions:

• Printing or generating virtual cover sheets from the target application to facilitate convenient filing of documents.

• Retrieving documents related to the current record (client, loan, policy, etc.) from within the target application.

Other Integration Products Note that the following other optional modules may also play a role in integration.

• Datalink connects to the target application database to help file documents.

• SmartLink captures data from the screen(s) of a target application to provide integrated filing and retrieval without programming. It is far more powerful that the screen scraping program included with Integration Agent.

• SmartClick is a “macro recorder”. It can be used to record keyboard presses and mouse operations and then reply them on demand, thereby automating a multi-click process in docSTAR and/or a target application.

• The Barcode module reads barcodes on documents. Integration Agent can generate barcodes that are readable by this module.

• The Dashboard and Reporting module includes a facility for generating custom reports, which can integrated data available from docSTAR and a target application.

Integration Agent and WebView The docSTAR Integration Agent uses the software framework of the docSTAR WebView product; therefore it requires that docSTAR WebView be installed. However, if does not require that WebView be purchase or licensed. If Integration Agent is purchased without WebView, then API features are available but the WebView “retrieve” page for non-integrated web-based retrieval is not available. If both products are licensed, then both API functions and non-integrated retrieval are available.

This manual will reference the docSTAR WebView Installation Guide, which is provided with each copy of Integration Agent.

The docSTAR Integration Agent consists of these components:

Notice: This document contains confidential company information and trade secrets of docSTAR. It is intended only for those customers, integration partners, or resellers who are using docSTAR Integration Agent and may not be distributed or reproduced without the permission of docSTAR

Page 2 docSTAR Integration Agent Reference Guide

• The docSTAR Retrieval API, which is used to retrieve and view documents programmatically. The docSTAR Windows (thick) client and WebView-like, browser-based (thin) client can be used in this manner.

• Cover Sheet API and Barcode Fonts, which are used to programmatically create barcoded cover pages from the target application for filing documents.

• Virtual Cover Sheet API, which is used to programmatically send filing information from the target application to docSTAR without a printed sheet.

• The docSTAR Integrator Setup utility, which allows a series of hot-key definitions to be set up to pull information off the screen of a target application. These hot keys will later be used to retrieve and view documents without programming.

• The docSTAR Integrator utility, which carries out the hot-key sequences created with the Integrator Setup utility.

As previously noted, the Integrator and Integrator Setup are superfluous when the more capable SmartLink module is used.

It is possible to use the docSTAR Integration Agent in any of these modes:

• Hot Key Integration Mode using SmartLink accommodates target applications for which custom programming is impossible or impractical. Almost any Windows application can be integrated in this manner. See the SmartLink documentation for more details.

• Hot Key Integration Mode using Integrator also can work with an application that cannot be easily modified. This process is described in detail in the hot key integration section of this guide. Note that thick client retrieval, cover sheet generation, and virtual cover sheet generation are not available in this mode.

• Programmatic Interface Mode allows fully custom or customizable applications to make calls directly to the docSTAR API to retrieve documents, create cover sheets, or virtual cover sheets. This process is described in detail in the programmatic interface section of this guide.

• Custom Integrations are really special cases of Programmatic Interface Mode. Cooperation between docSTAR and various third parties—including Applied Systems, Inc. and AMS Services, Inc.—has lead to custom integrations, which are now available as pre-programmed solutions.


SSeeccttiioonn 11:: ddooccSSTTAARR IInntteeggrraattiioonn AAggeenntt RReeqquuiirreemmeennttss The docSTAR Integration Agent has the same minimum requirements as the docSTAR WebView product. Please refer to the WebView Installation Guide for details.

The docSTAR Integration Agent also requires one of the following in order to work with a third party application:

• A target application that can be modified to make the necessary calls into docSTAR. This may require source code control of the target application, or it may be possible through a built-in “link” or “macro” feature provided therein. (This is programmatic integration.)

• A Windows-based or browser-based target application and SmartLink. SmartLink also requires that suitable indexing information is available from the target application.

• A Windows-based target application and SmartClick. Similar to SmartLink, SmartClick can be used in some instances to capture indexing information from the screen of a target application and provide it to Integration Agent.

• A pre-programmed custom integration, such as the TAM Integration Module, AfW Integration Module, or the docSTAR Module for Sagitta from AMS Services, Inc. Such integrations include supplemental, application-specific documentation.

• A Windows™-based target application that exposes a single, unique indexing key, such as a client ID or an invoice number, which can be captured using the docSTAR Integrator program (included with Integration Agent). It is not possible to definitively determine if an application exposes this information until the Integrator Setup Utility is run. Thus, this utility should be run to test compatibility with the target application before Integration Agent is purchased.

The docSTAR WebView/Integration Agent/SmartLink Installation CD The docSTAR WebView/Integration Agent/SmartLink Installation CD contains the following:

Folder Contents

\ (root) WebView and Integration Agent (IA) common SETUP and supporting files.

\Microsoft URL Scan 2.5 Security tool required and referenced by WebView/IA SETUP.

\SMARTLINK SETUP for SmartLink.

\VCS SETUP for Virtual Cover Sheets.

\BARCODE COVER PAGE SETUP for barcode cover sheets and fonts.

\INTEGRATOR SETUP for INTEGRATOR and INTEGRATOR SETUP programs.

SSeeccttiioonn 22:: ddooccSSTTAARR IInntteeggrraattiioonn AAggeenntt IInnssttaallllaattiioonn Installation Steps

1. Install docSTAR Integration Agent License (and any other licenses you are adding) on the docSTAR Host.

2. Install docSTAR WebView/Integration Agent common software.

If you are planning on using printed cover sheets:

3. Install Barcode Cover Sheets.


If you are planning on using virtual cover sheets:

4. Install Virtual Cover Sheets.

If you are planning on using the Integrator program for hot key integration mode:

5. Install docSTAR Integrator Setup Program on any PC, which is a networked client of docSTAR and runs the target application.

Step 1: Install docSTAR Integration License on docSTAR Host Purpose: This step enables the docSTAR Host to communicate with the Integration Agent, and the presence of the license also provides an indication to the DSHost Service/Desktop that virtual web shares must be established every time it starts, see docSTAR WebView Appendix A.

With the license certificate(s) in hand, call docSTAR Technical Support and add the docSTAR Integration License (as well as any additional licenses necessary) to the Hardware Key on the docSTAR Host System using the docSTAR Administration Program.


Step 2: Install docSTAR WebView Purpose: This step installs the necessary framework for the Integration Agent. Please follow the installation instructions for docSTAR WebView. See docSTAR WebView Installation Guide. You may notice that a license for docSTAR WebView is not included with the docSTAR Integration Agent, and it is not required. The Integration Agent only uses the framework of the docSTAR WebView software to perform searches and to view documents. The WebView license is only required if the full docSTAR WebView functionality, including home page, login page, and the search criteria page are required.

Step 3: Install Barcode Cover Sheets (Optional) Purpose: Barcode cover pages used to transmit filing information from the target application to docSTAR. They are printed from the target application and scanned along with a document.

Before you start: if you have previously modified coverpage.asp, you should make a backup copy of it now. This installation includes an option, which will overwrite that file.

From the Barcode Cover Pages folder on the WebView CD, run SETUP.EXE. Select Next to begin the installation process.

You will see the Choose Destination Location screen. Select Next to accept the default WebView directory.


You will see the Select Barcode Cover Page Type screen. Select the type of barcode cover page you would like to install and select Next. If an installation previously performed, the prior setting will be selected. If you have already created a custom cover page, select “Custom cover page”, so that your custom page will be retained and no new cover page will be installed.

.

However, if you want to convert your current page from Code 39 to Code 128, the best way to do so is to make a backup copy of your custom cover page first and then install the


standard Code 128 page. This will allow you to open and compare both files, and then apply your prior customizations to the new Code 128 page.

Next, you will see the Select Barcode Fonts screen. The correct font type will be selected based on the selection from the prior screen. You may install either Code 39 or Code 128 barcode fonts. Select Next to complete the installation process.

The barcode cover page installation will now complete and barcode cover pages are ready for use.

Note that the Barcode Cover Page setup can also be run on client stations. If the installation program detects that it is being installed on a system that is not the docSTAR host, only the true type font installation screen will be presented. This provides an easy way to install True Type fonts for client systems. Fonts can also be installed on client systems via their web browser, as described under Section 5.

Step 4: Install Virtual Cover Sheets (Optional) Purpose: Virtual Cover Sheets are used to transmit filing information from an integrated application to docSTAR. These steps install the files necessary for creating them.

Before you start: if you have previously modified MyVCS.ASP, you should make a backup copy of it now. This installation includes an option, which will overwrite that file.

From the Virtual Cover Sheet folder on the WebView CD, run SETUP.EXE. Select Next to begin the installation process.


You will see the Choose Destination Location screen. Select Next to accept the default WebView directory.

You will see the Select Virtual Cover Sheet Type screen. Select the type of virtual cover sheet you would like to install and select Next. If an installation was previously performed,


the prior setting will be selected. You should select Custom if you have previously installed and customized MyVCS.ASP. Otherwise, your custom VCS will be deleted and replaced with the default VCS file.

The Virtual Cover Sheet installation will now complete.

Step 5: Install docSTAR Integrator Software (Optional) This is required for hot-key integration mode without SmartLink only. Skip this step if using the SmartLink, programmatic integration mode, or a custom integration.

Purpose: This step installs the docSTAR Integrator Software. This can be installed on the docSTAR Host or on a client computer. It should be installed on one machine that is running the third party application you want to integrate with.

Find the Integrator director on the docSTAR WebView/Integration Agent CD and run SETUP.EXE. You will see the Choose Destination Location screen. Click Next.


You will see the Select Software Options screen. Notice that the docSTAR Integrator is checked and disabled. This means that this software is always installed. The docSTAR Integrator Setup program can be optionally installed.

You will see the Create Shortcuts screen. Select the options you desire for creation of program shortcuts and click Next.



You will see the Start Installation screen. Click Next.

You will see the Installation Complete screen. Click Finish.


SSeeccttiioonn 33:: HHoott KKeeyy IInntteeggrraattiioonn MMooddee ((IInntteeggrraattoorr)) The docSTAR Integrator Utility (DSIntegrator.exe) and Integrator Setup (DSFindProcess.exe) program provide a mechanism by which a user can retrieve documents related to the current context in a target application upon the press of a defined hot key.

Note: SmartLink is a newer and more capable option for hot key integration. Unlike Integrator, it supports capture of multiple fields at once, cover sheet generation, virtual cover sheet generation, and custom parameter manipulation.

There are two applications associated with the integrator process.

docSTAR Integrator Setup - This application is run first. It creates a DSIntegrator.xml file, which contains the information necessary to make the integration. This application displays all of the currently executing applications within the system. Once the appropriate application and window are found, and the retrieval criterion is defined, this information is saved to DSIntegrator.xml, and the docSTAR Integrator is automatically executed.

docSTAR Integrator– This application utilizes the DSIntegrator.xml file created by DSFindProcess. When the user presses the hot key that was defined by DSFindProcess, the integrator searches the currently running applications and attempts to locate the application and field that were defined for that particular hot key. If the field is found, the integrator extracts the value from the field and performs a docSTAR search based on the search criterion. If the application is not found, the hot key press is ignored by the Integrator and returned to the operating system.

Steps Below is a list of the steps to be performed to setup Hot Key Integration with the docSTAR Integration Agent:

1. Use docSTAR Integrator Setup to develop hot key definition(s)

2. Install Integrator Utility and hot key definition(s) on client stations

Step 1: Use docSTAR Integrator Setup to define hot keys Purpose: This uses the docSTAR Integrator Setup to locate the proper information on screen from a third party application so that the docSTAR Integrator can send the request to the docSTAR Integration Agent. In this example, integration will be set up with the Notepad accessory found in Windows.

Run the third party application that is to be integrated. In this example we will integrate with the Windows Notepad program. This is not something you really want to integrate with, but it serves as an example. From the Start menu, select Programs, Accessories, Notepad to run the Notepad program.


Enter a unique piece of information in the data entry field of the third party application so that we can use that information to locate the window containing the data. Enter 1234 into the Notepad window. Remember, this is an example; the value ‘1234’ sitting in Notepad could be a client code in customer relationship manager program or an order number in an accounting program.

Run the docSTAR Integrator Setup utility to perform the integration. From the Start menu, select Programs, docSTAR, docSTAR Integrator Setup to run the Integrator Setup program.


Click the New button to define a new Hot Key

Get the list of running processes and windows by clicking the Find Processes button.


We now want to locate the window that contains the unique information we entered into Notepad. Click Search and enter the unique piece of information. Enter 1234 into the Search window.


Click the Close on the search form. Select the hot key to be used at the top of the form by selecting the key to be pressed and checking any of the CTRL, SHIFT and ALT checkboxes to build a hot key. Click OK to save this new hot key.


Click Options to set the browser location, web address and docSTAR username and password. For this example, just enter the web address of your docSTAR Server. This was determined during the docSTAR WebView setup. Click OK to close the options window.

Click Save to save the Hot Key definition file. Click Close to exit the docSTAR Integrator Setup program.

From the Start menu, select Programs, docSTAR, docSTAR Integrator to run the Integrator program. The Agent Icon should appear in the System Tray.

Test the integration by pressing CTRL-A, or which ever hot key combination you set up. A search will be performed taking the number from the target application.


Step 2: Install Integrator and Hot Keys on Client Stations Purpose: This step installs the docSTAR Integrator on Client Stations so that they can use the integration set up under Step 1. The setup program is designed to look for a DSIntegrator.XML file in the same directory as the setup program, and if found, install it to a client station.

Copy the installation program (SETUP.EXE) to a directory or disk that can be read by the client computers.

Copy the DSIntegrator.XML from the C:\DOCSTAR directory to this same directory or disk.

On the client computer, run the installation program (SETUP.EXE). Notice that the option to install the docSTAR Integrator Setup is unchecked because it found the DSIntegrator.XML file in the setup directory and will install it on the client computer.

Click Exit on the docSTAR Integrator Setup and run the docSTAR Integrator from the docSTAR Menu. From the Start menu, select Programs, docSTAR, docSTAR Integrator to run the Integrator program. The Integration Agent icon should appear in the System Tray.

Test the integration as you had on the original station.


Integrator Setup Reference The preceding example just touched upon use of the Integrator Setup. Here is more complete information.

The initial Integrator Setup screen displays all hot keys that have been defined.

Commands The following commands are available.

Load

Loads (or reloads) the Integration Control File and displays any defined hot keys within it.

Save

Saves the Integration Control File.

Save As

Saves the Integration Control File to a new file. You may use any file name for temporary or backup copies of this file, but the Integrator Utility will ONLY use the file DSINTEGRATOR.XML in the docSTAR directory.

New

Creates a new hot key, as described in the example above.

Edit

Edits an existing hot key, which is similar to defining a new one.

Delete

Deletes an existing hot key definition.


Integrator Setup Options Browser

Enter the fully qualified path and browser executable name

(i.e. C:\Program Files\Internet Explorer\Iexplore.exe)

Internet Explorer version 5.0 or later must be used.

Web Address

Enter the full URL to your docSTAR IIS server. This can be a UNC path name on a LAN, such as //mydocstar, or it may be a registered domain name on the Internet, or it may be a valid IP address on either your LAN or the Internet.

User Name

Enter the docSTAR username that will be used to log onto docSTAR. If left blank, the user will be logged onto docSTAR as GUEST.

Password

Enter the docSTAR password associated with the username.

Seed Value

This numeric value must be between 0 and 64. This value will be used to obfuscate (encrypt) the Username and Password.

Defining Hot Keys Key

Choose a key combination that does not interfere with the target application or the operating system or anything else that might be running. Typically, a letter or a function key plus one or more of Ctrl, Shift, and Alt are selected.

Application

The application title (text) will be filled in automatically after you save the hot key definition, so you can generally ignore it. However, it is sometimes necessary to edit this field.

When an application changes its title bar to correspond to the current record (client, policy, invoice, whatever), it is necessary to remove the variable portion of the title from this field; otherwise, the hot key will only work for the one record that was active when it was defined. To edit the application title text, save the hot key. Then select the hot key in the list and choose Edit. Now remove the record-specific information from the Application Text. For instance, if the text reads “Customer: Smith”, remove “Smith” and leave “Customer:”. Then save the hot key definition. Now the hot key will operate on all customers, not just for Smith.

Check “Must be in the foreground” if the key combination may be used in other applications.

Process Identification As described in the example, click Find Processes to list all Windows processes currently running. Then press Search to find the specific field you want to capture in the process list. The value may appear in multiple fields so you may have a choice.

Sometimes, an application uses non-standard Windows controls and a desired value that you can clearly see on the screen cannot be found in the Processes list. Try looking for the same value elsewhere in the target application. It may be possible to find it elsewhere.


Note that, if you open or close any windows or alter the value in your target application, you must press Find Processes again to refresh the list.

Search Criteria

Enter the beginning of the search criterion into the “Search Text” field. The value found in the target application will be added to this. For instance, if you enter:

text =

in this field, and the target application contains the text “fred” in the field you’ve identified, this will perform a docSTAR search for the text “fred”. Besides, “text”, you may search for a value in any other docSTAR field, custom or built-in. Please see the table of valid field names and comparison operators under the Programmatic Interface Mode section, below.

Note that there must be a space before the operator.

It may be necessary to remove a prefix from the search value. For instance, let’s say the only place a client name appears is in a window title, but it appears in that title with a prefix as in “Customer: Smith”. If you search for “Customer: Smith” in docSTAR, you will not find a document filed under “Smith”. Therefore, you would type “Customer:” in the “Prefix to remove …” box. Thus, although the window you identify contains “Customer: Smith”, the docSTAR search will be for only “Smith”.

Yes, this is the same example for which it was necessary to alter the application text, as described above.

Finally, the remove punctuation option strips punctuation like periods, etc. from the value found in the target application. This should be turned on when you are performing text searches for names, such as “L. Peter Smith”, because the punctuation may not be found in docSTAR.

SSeeccttiioonn 44:: PPrrooggrraammmmaattiicc IInntteeggrraattiioonn MMooddee The docSTAR Integration Agent provides a mechanism to integrate customizable programs with the docSTAR retrieval and view mechanism. The following documentation is geared towards programmers and should provide all of the necessary to call docSTAR from their application by simply adding a button or menu item.

Thick or Thin Client With version 3.5.4 of docSTAR and later, integrated retrieval is available with either the docSTAR Windows client or browser client. The same mechanism is used to call either; each user chooses to use the thick vs. thin client through a configuration screen in the docSTAR client program. The screen is accessed from the Options->Setup menu on the docSTAR main window. It is found on the Integration Settings tab.


A properly formatted call to the program, GenericRetrieve.exe, will display selected documents in either the thick or thin client as specified on this screen.

Note: For convenience, GenericRetrieve.exe installs with docSTAR Version 3.5.4 or later, but it is licensed as Integration Agent.

Alternately, an application can choose to call only to the thin (browser) client. This is appropriate for integration with browser-based target applications or other situations in which the user may not have the full docSTAR client installed. In this case, the application launches Microsoft’s Internet Explorer program with a specifically formatted URL.

Note that a browser-based target application can easily integrate to docSTAR’s thin client just by providing a link with the properly coded URL.

Quick Start This simple example in Visual Basic shows how to perform thin client retrieval through Integration Agent. It references a server, www.docstar.net, which is available on the Internet to docSTAR Integration Agent users.

It searches for all documents whose title contains the word “service”. Private Sub Command1_Click()

Shell "c:\program files\internet explorer\iexplore.exe http://www.docstar.net/dswv/venom.asp?f=N&username=&password=&sv=0&docs=-1&folders=-1&q1=title contains service", vbMaximizedFocus

End Sub

Building the URL The mechanism for launching GenericRetrieve or Internet Explorer will depend upon your programming environment. This section will document how the URL is built. The same URL is used for either call.

The Base URL The beginning of the URL must be the proper web path to venom.asp on the docSTAR IIS Server. This may vary depending on your installations, but will typically be one of the following:

http://www.docstar.net/


http://machinename/dswv/venom.asp -- This is typical when docSTAR is accessed via a local area network.

http://domainname/dswv/venom.asp -- A complete domain name is used for integrated retrieval via the Internet.

http://ipaddress/dswv/venom.asp -- A static IP address (##.##.##.##) may be used to identify the docSTAR IIS server on a LAN or on the Internet.

The Base URL will always be followed by a query string consisting of a question mark and the following parameters. Note that all parameters—unless explicitly listed as “optional”—must be present even if they are unused.

Parameters The following parameters are passed via the query string to the IIS server, to the Venom.asp page. Each parameter must be separated with the ampersand (&) character. A sample URL request is shown below:

http://www.docstar.net/dswv/venom.asp?f=N&username=&password=&sv=0&docs=-1&folders=-1&q1=text%20=%20service

F

This Flag must be set to “n” or “N”. It identifies a docSTAR Integration request.

Username

This is the docSTAR Username. Passed as “username=” Note: The username and password can be obfuscated using the supplied obfuscated routine (described below). This will prevent viewers from seeing the username and password used for the integration request.

Password

This is the obfuscated Password as specified above. Passed as “password=”

Docs

This is a Boolean parameter that specifies that Documents should be either included in the search (True) or excluded from the search (False). Passed as “docs=”. A –1 (minus one) should be used for true and 0 (zero) used for false. For example: docs=-1

Folders

This is a Boolean parameter that specifies that Folders should be either included in the search (True) or excluded from the search (False). Passed as “folders=”. A –1 (minus one) should be used for true and 0 (zero) used for false. For example: folders=-1

SV

This is the Seed Value that was used in the Obfuscation routine. Passed as “sv=”.

E

This is an optional Boolean parameter that specifies whether or not the Username and Password were encrypted using the Obfuscation routine. If no UserName or Password is passed (Logging on as Guest), then this parameter should be false, other wise the parameter should be true. Passed as “e=”. A –1 (minus one) should be used for true and 0 (zero) used for false. For example: e=-1

http://machinename/dswv/venom.asp

http://domainname/dswv/venom.asp

http://ipaddress/dswv/venom.asp


Q1

This is the first of up to four query strings that will determine which documents and/or folders will be returned. If left blank, the result will be a search based on whether or not Docs or Folders is true or false. This parameter is case insensitive. Passed as “q1=”.

Each docSTAR field can be used in the search. Below is a table of search fields, valid operators and sample syntax.

Field Valid Operators Sample

TITLE =, <>, >, <, <=, >=, CONTAINS, DOES NOT CONTAIN, LIKE

Title contains service

PAGES =, <>, >, <, <=, >= Pages = 10

CREATED =, <>, >, <, <=, >= Created > 1/1/02

MODIFIED =, <>, >, <, <=, >= Modified = 1/1/02

ACCESSED =, <>, >, <, <=, >= Accessed = 1/1/02

VOLUME =, <>, >, <, <=, >=, CONTAINS, DOES NOT CONTAIN, LIKE

Volume = VOLUME_0001

CLASS =, <> Class = PUBLIC

Custom Field (Names defined within docSTAR)

=, <>, >, <, <=, >= InvoiceNumber = 12345

TEXT (Searches words and phrases)

= Text = service

Text = service AND export

Text = NOT service

Notes:

There must be one space before and after each operator. Because URL’s must be uuencoded, the spaces appear as ‘%20’.

Custom field names cannot contain spaces (existing custom field names with spaces can be changed in the docSTAR Administration screen)

Q2 – Q4

Same as Q1. Passed as “q2=”, “q3=” and “q4=” respectively.

newwin (optional) When this parameter is omitted or set to its default value, “newwin=0”, a selected document will be displayed in the same browser window as the search result list from which it was selected. Setting “newwin=-1” will cause any selected document to be displayed in a new window, so that the search result list will remain open in its own window. This parameter is available in build 15 of WebView/Integration Agent and later; the build number is displayed in the online help.

autodisp (optional) Setting “autodisp=-1” causes a document to be displayed immediately after any search which yields exactly one results, skipping the search result list with only one item in it. It has no effect if the search yields no documents or two or more documents. When this


parameter is omitted or set to zero, the search results list will always be displayed, even if there is only a single result. This parameter is available in build 16 of WebView/Integration Agent and later.

SO (optional)

Can be set to 0 or -1, this setting determines the sorting order, Ascending (-1) or Descending (0) of the Search Results. If left blank or omitted, the search results sorting order will default to the current docSTAR sort order. Setting “so=-1”

SK (optional)

This setting determines which field the Search Results will be sorted by, below is a list of the valid values and their meaning:

• -1 Default Sort

• 1 Title

• 3 Pages

• 4 Classification

• 5 Hits

• 8 Modified Date

• 9 Created Date

Setting “sk=1” will cause the search results to be sorted by Title. If left blank or omitted, the search results will be sorted by the current default docSTAR sort field.

Obfuscation Algorithm The toolkit utilizes a simple Obfuscation Algorithm to encrypt the Username and Password parameters so that this information is not visible during the request. Below is the encryption string used by this algorithm, this string must be used and must match exactly.

Const sMap = iGOnY8dRZ27CeVFg0IHBkuTxJ9EjlM3Sc4wmNqoP1pDyQA5rbLtU6vWXaf@h!zKs

Seed Value This value, which ranges from 0 to 64, is used to prefix the number of spaces specified to the front of the sMap constant above.

Once the spaces are pre-pended, each field is processed, 1 character at a time. The first Character in the UserName is located within the sMap constant and then, the location of the character is converted to its hexadecimal value. This process is continued throughout the Username and Password values.

The converted Username and Password values are stored, and will be transmitted to the toolkit interface via a Query String.

Example Toolkit Calls The following examples are given showing a Visual Basic Shell command interface to GenericRetrieve.exe. In each case, the network name of the docSTAR host is presumed to be “//docSTAR”. By substituting IEXPLORE.EXE (with a proper path) for GenericRetrieve.exe, thin client retrieval will occur.

Without Encrypted UserName and Password:


Shell “c:\docstar\genericretrieve.exe http://docstar/dswv/venom.asp?f=n&UserName=&Password=& Doc=-1&Folders=-1&SV=0&E=0& Q1=title%20contains%20service”,vbMaximizedFocus

With Encrypted UserName and Password: Shell “c:\docstar\genericretrieve.exe http://docstar/dswv/venom.asp?F=N&UserName= 5147501B381857&Password=5147501B381857&Doc=-1&Folders=-1&SV=23&E=-1&Q1=title%20contains%20service”

Sample VB Code Supplied on the CD are two Visual Basic Samples showing the use of the toolkit from a program.

Sample1 The first sample is a very simple example of how to use the Integration Agent from a program. The sample project, PrjSample1.vbp, contains one form, frmSample1.frm, which contains one text box and one button. When the button is clicked the data in the text box is read and integrated retrieval via thin client is performed. Note that you may need to change the web addresses used to match your own server, and that genericretrieve.exe should replace Iexplore.exe to allow the user’s choice of thin vs. thick client retrieval to take effect.

Sample2: Obfuscation The second sample can be used to experiment with the obfuscation routines that the Integration Agent recognizes to allow encoding of the username and password.

Section 5: Cover Pages Another feature of the Integration Agent is the ability to print a barcoded cover page. This is valuable when users perform data entry or other processing in the target application from paper documents before scanning them. (Back end scanning.) To facilitate easy and accurate filing, a cover page is printed after processing. This cover page is placed on top of the paper document. Later, all documents can be scanned together, and the cover pages serve as document separators and provide indexing (filing) info.

The cover page mechanism is installed from the WebView CD as described in section 2 of this guide.

Cover pages are available from several custom integrations including Sagitta™ and TAM™. Refer to the application-specific documentation provided.

Generating a cover page through Integration Agent programmatically is similar to retrieving documents, except that the base URL is slightly different and the parameters are much simpler, as follows:

Base URL The base URL to generate a cover page is http://machinename/dswv/coverpage.asp. “Machinename” can be the name of the docSTAR server on a LAN or a domain name or an IP address. Coverpage.asp accepts a query string consisting of a question mark (?) and one or more parameters in the form:

Key=Value

each separated by an ampersand (&).

http://machinename/dswv/coverpage.asp


For instance: http://www.docstar.net/dswv/coverpage.asp?client=smith&policy=1234 is a valid URL that will show two values, a client code (smith) and a policy number (1234).

The formatting of the cover page can be modified by editing coverpage.asp, which is an Active Service Page written with VBScript. By default, it shows all parameters, displaying the key in the default font and the value in both the default font and in a barcode font.

Barcode Fonts Two different barcode fonts are available: Code 39 (or “3 of 9”) and Code 128. The 3 of 9 font is free and it provides compact barcodes, but it has a very limited character set: the upper case alphabet, all digits, and a few punctuation marks (-, $, %, +, and /). The Code 128 barcode has been licensed for your use with docSTAR and contains almost all ASCII characters (upper and lower case letters, digits, spaces, and punctuation). However, its use is a little trickier. Note the include file and the barcode translation function contained in the Code 128 cover page. This include file and its translation function are essential to creating proper barcodes with this font. Both fonts can be installed from the WebView/IA CD. They can also be downloaded to each client station by browsing to http://machinename/dswv/fonts and following the instructions on that page, where “machinename” represents the Base URL of the WebView/Integration Agent server.

Note: Producing barcodes does not require a license for the docSTAR Barcode Module, but this license is required on each station which reads barcodes.

Options A number of options possible are possible by editing the HTML/ASP code within the cover page including:

• Identifying the user through his or her network authentication.

• Prompting the operator for additional info (via an HTML form) to be added to the cover page in barcode or in plain text.

• Displaying the current date.

Editing this page requires familiarity with HTML and VBScript. Assistance is available through your local partner and docSTAR’s Professional Services Department.

Section 6: Virtual Cover Sheets Yet another feature in Integration Agent is the Virtual Cover Sheet mechanism. This feature, supported in docSTAR version 3.4 or later, provides a way to transfer filing information from another application to docSTAR without printing a cover sheet.

How They Work Like printed cover sheets, Virtual Cover Sheets (VCS) are generated from an integrated application as a document is processed. They take fields passed from the application and store them in a special database record. A VCS ID number is displayed for the operator. Typically, this number is written unobtrusively in the top, right-hand corner of the first page of the document. That document is later scanned, and the filing clerk types in the VCS ID number to retrieve all of the fields stored in the VCS, filing the document accurately and automatically.

VCS may be preferable to printing cover sheets because of the potential confusion, which arises when users must retrieve their own cover sheets from a shared printer. Also, they are more environmentally friendly—you don’t have to print paper to eliminate paper.

http://www.docstar.net/dswv/coverpage.asp?client=smith&policy=1234

http://machinename/dswv/fonts


Users may still use a barcode separator, blank sheet separator, or scanner-specific separator with VCS to delimit each document in a stack. But these cover sheets are not document-specific and can be reused many times.

One more benefit of VCS is that docSTAR can report on any that have been created, for which no corresponding document has been filed. This can identify a document that was lost sometime between processing and scanning, or which has been improperly filed.

Creating VCS The VCS mechanism is installed from the WebView CD as described in section 2 of this guide.

An application creates the VCS in about the same way it creates a cover sheet: by opening a page in a web browser. However, due to the complexity of the ASP page that creates the virtual cover sheet, it is not customizable. Therefore, a second ASP page is provided to allow customizations. Thus, the integrated application opens the customizable page, and the customizable page opens the next page, which really creates the VCS.

Integrated ApplicationMyVCS.ASP

Customized virtualcover page form.

CreateVCS.ASP

By default, MyVCS.ASP simply takes all parameters it is passed and hands them off to CreateVCS.ASP. However, you may modify it to prompt for additional parameters via an HTML form. It can also add system or environment data (like the date or network user name) to the parameter list. A sample, customized ASP page is provided. The one thing that should not be changed is the call to CreateVCS.ASP.

The file CreateVCS.ASP should not be modified at all.

Converting Current Applications Any application now using printed cover sheets can readily be converted to virtual cover sheets. If you are the developer of the application or have the ability to modify source code, you can simply change “coverpage.asp” to “MyVCS.ASP” and adapt any customizations from the former file to the latter.

If source code modification is not possible, you can “fake out” the application by renaming MyVCS.ASP to coverpage.asp. The application will pass its parameters to what it “thinks” is its old cover page, but instead a virtual cover page will be created.

Of course, modifying any of these ASP scripts requires knowledge of HTML and ASP programming. Assistance is available from your reseller and docSTAR’s Professional Services Department.

Using Virtual Cover Sheets Virtual Cover Sheets (VCS) are available through programmatic integration as described above. They are also available through some of docSTAR’s custom integrations, including the TAM™ Integration Module. This section describes how they are used to file documents.

The key to using VCS in templates is the VCS Transform Type. But first, the VCS ID must be captured, generally through a user prompt action. Then subsequent actions transform into each of the data fields captured in the VCS.


Capturing the ID The first action of a VCS template will generally prompt the user for the VCS ID.

The data source may be OCR or Barcode recognition if the VCS ID is printed somehow, such as with a label printer. In any case, the destination should probably be “None” because the VCS ID itself is not meaningful to the document—it is just a way to get to the data stored in the VCS. This action will be used by subsequent actions to access these data.

The VCS Verification should be applied to this action.


On a user prompt, it will immediately alert the user if the VCS doesn’t exist, which might indicate a typo or that a document has been scanned and filed before. (Each VCS is automatically deleted when successfully used in a template.)

If a barcode or OCR zone is used to capture the VCS ID, and if this verification fails, this is regarding as an Action Failure and will probably send the document to the Review Box. (See Chapter 3 of the User’s Guide.)

Transforming Fields Additional actions are created, one for each field expected in the VCS.

Each additional action references the first action (the VCS ID) as its Data Source, and each uses the VCS Transformation to access a specific field and place in an appropriate destination: title, keywords, custom field, or a folder.

Setting up the VCS Transformation is easy, but you must create a sample VCS containing the correct fields first. (See Creating VCS, above.)


In order to specify the VCS Field, click on the little button (labeled “...”). You now must specify the VCS ID number of the sample VCS you’ve created. After entering the VCS ID number (“Cover Sheet ID”), click Get Fields to populate the list of available Fields.

All fields present in the sample VCS will be displayed; pick one. Now the VCS Transformation tab is complete.

When the template runs, the field you’ve specified will be placed in the destination designated on the General tab of the action. For instance, the Client_Code VCS field would be placed in the docSTAR custom field “ClientCode” as defined in the series of figures, above.

Additional actions employing VCS Transformations on the VCS ID can be created for each additional field. It is not necessary to use every field in the VCS.

On the other hand, it is necessary that the VCS selected when running a template contains every field specified in VCS Transformations. If a field is missing in the VCS, this represents an Action Failure, which may result in the document being sent to the Review Box per Chapter 3 of the Users Guide. A missing field may be due to an error in the integration programming, or a VCS created from one application or integration point being used by the wrong template. For instance, a VCS generated from a “Client Window” might lack a policy identifier, which would be expected if a template created for the “Policy Window”.

It is possible to employ a Datalink transformation on a VCS field. Simply create an additional action, which references the correct VCS field as its Data Source. Thus, one


action gets the VCS ID, another transforms it into one of the fields from the VCS, and a third transforms that field into one or more related fields.

Note that other actions may be employed along with a VCS, including additional user prompts, etc. However, VCS filing can generally be completed by someone with little training or business knowledge. Therefore, it is preferable to capture information using custom prompts (created within in MyVCS.ASP, described above) at the time a VCS is created.

VCS Status The VCS Status command from the docSTAR menu of docSTAR’s main screen is used to monitor and “clean up” unused VCS.

Ideally a VCS is created when a document is processed and then deleted when the document is filed. This command shows all VCS, each of which should represent a document that is either waiting to be scanned or waiting to be filed. If a document for which a VCS was created were to be lost prior to scanning or filing, its VCS would remain. Thus, the VCS Status display may help indicate a lost document. For your convenience, the list may be sorted by Created Date—ascending or descending—by clicking on the column heading.

The view command displays more detail (field names) about the selected VCS in a small window, as shown.

Any or all VCS records can be deleted from this window. A VCS record should be deleted if it was created for testing or training purposes, or if for some other reason there is no document waiting to be filed with it.