SmmaarrttLLiinnkk™™ nIInntteeggrraattiioon Guuiiddeesupport.docstar.com/portal/docstar/techdvd/manuals/... · 2006-08-08 · Note: this distinguishes Sm artLink from Datalink,

SSmmaarrttLLiinnkk™™ IInntteeggrraattiioonn GGuuiiddee

((vv11..00..44)) RReevviissiioonn 11 88//0022//22000066

Contents Introduction ................................................................................................ 3

S m artLink™ ................................................................................................ 3 System Requirements .................................................................................. 3 This and Other Documentation ...................................................................... 3 Installation ................................................................................................. 4

Configuration .............................................................................................. 5 Font Database ............................................................................................ 6 Creating Applications ................................................................................... 7 Creating Fields ............................................................................................ 8 Defining the Command Line ........................................................................ 16 Setting the Hot Key ................................................................................... 17 Repeat ..................................................................................................... 18 Test ......................................................................................................... 18

Rollout ...................................................................................................... 19 Installation ............................................................................................... 19 Locking the Configuration ........................................................................... 19

Advanced Configuration ............................................................................ 20 Custom Cover Pages .................................................................................. 20 Custom Retrieval ....................................................................................... 20

docS TA R C P O w ner’s M anual Page 3

Introduction docSTAR offers a suite of integration products designed to add integrated retrieval and integrated filing functions to your primary line of business application, which herein will be referred to as the target application.

The central product in this suite is the Integration Agent, which provides a simple application programming interface (API) for retrieving documents or generating a cover sheet or virtual cover sheet for filing. (See the Integration Agent Reference Guide for more information.) The API can be used in situations where the custom software code can be added to the target application.

When custom code cannot be added to the target application, SmartLink may be the bridge between the target application and Integration Agent.

N ote: Integration A gent includes a utility called “Integrator”, w hich can perform integration w ithout custom code. However, its capabilities are quite limited. SmartLink is recommended, going forward, for all such integration requirements.

Sm artLink™ SmartLink captures on-screen data from a target application and passes it to Integration Agent to retrieve or file documents. Note the significance of capturing on-screen data; this allows SmartLink and Integration Agent to retrieve or file documents based on the current item a user is working on. For instance, if a loan officer is working on Loan Number 1034, he or she can retrieve the documents related to this loan or generate a (virtual) cover sheet with the data of this loan with a single keystroke.

N ote: this distinguishes S m artLink from D atalink, w hich connects to the target application’s database and is therefore not sensitive to the current item (context) a user is working on.

SmartLink runs in two distinct modes: a configuration mode and a runtime mode. The configuration mode lets a technician or administrator define how the integration will operate. In runtime mode, SmartLink sits unobtrusively in the systray. A user presses a pre-defined “hot key” to trigger the integrated retrieval or filing operation that had previously been defined.

System Requirements SmartLink can be installed and used on any PC that supports the docSTAR client program (version 3.5.4 or later) and the target application. Integration Agent must be installed on the docSTAR host.

This and Other Documentation This Guide is written for the technician, administrator, or another individual with information technology experience. It covers installation, configuration, and deployment of SmartLink. Some advanced configurations may require custom software coding or scripting, which is beyond the scope of this Guide.

The docS TA R U ser’s R eference M anual describes normal scanning and filing operations, as well as building filing templates. Generally, special filing templates

Page 4 docSTAR CP Owners Manual

must be built to take advantage of cover sheets or virtual cover sheets generated through SmartLink. This manual also describes the Integration Settings preference, which determines whether the (thick) Windows client or the (thin) browser client is used for integrated retrieval by each user.

The docS TA R A dm inistrator’s G uide covers the licensing mechanism, which is needed to activate SmartLink.

The Integration Agent Reference Manual covers installation of Integration Agent and defines the syntax of the API. When defining integrations in SmartLink, the proper syntax must be used for every API operation.

Installation Initially, SmartLink should be installed a networked PC which is both a docSTAR client and a target application client. This will be the station on which the integration is defined. Later, SmartLink and the final configuration will be installed on other PCs; this is described in the Rollout section of this Guide.

For the initial installation, run the SETUP program found on the SmartLink CD. (It may also be found in the SmartLink folder of the WebView/Integration Agent CD.)

Generally, you should accept the default installation location:

C:\DOCSTAR\SMARTLINK

And, generally, you should run SmartLink on Startup for all users as shown.

The license for SmartLink must be added through the Licensing feature in the A dm inistrator’s program , as described in the A dm inistrator’s G uide.


Configuration Launch SmartLink from the docSTAR group in the Start menu. Its icon (a chain link) will appear in the Systray.

Right-click on the icon to open the menu and choose Configure. That opens the SmartLink configuration window. (The other menu choice, Exit, closes the application.)

The following terms are used to describe integrations developed with SmartLink.

Application Each integrated function, either retrieving documents based on a certain criterion or generating a cover sheet containing certain data, is called an application. You can define up to ten different applications, but often only two are needed: one for retrieval and one for filing, as in the example above. Note that there are command buttons for Adding, Deleting, Modifying, and Duplicating Applications located below the application list.

Field Each application may have one to ten fields. Each field is a value on the screen, like a claim number or client name, which you would use to retrieve or file documents. In the example above, the AfWVCS application is selected and its list of fields is shown. The field list always displays the fields defined for the selected application. The command buttons for Adding, Deleting, and Modifying a field, located below the field list, apply to the selected application only.

Command Line S m artL ink’s job is to capture data from fields and pass them to another program or to a w eb page, usually docS T A R ’s retrieval or cover sheet A P I. T he command line defined for each application specifies exactly what program or web page will be launched and how the fields will be passed formatted. Every application has only one command line.

Hot Key The term hot key is used to refer to a key or key combination, like F12 or Ctrl+Shift+R, used to “fire” an application defined in S m artL ink. W hen the hot key is pressed, the fields are read and the command line is run. Each application has only one “hot key”, and a distinct hot key is required for each.


The Application tab of the S m artLink configuration w indow let’s you define applications and their fields. The Command Line and Hot Key tabs define these respective properties for each application. (The C om m and Line tab also let’s you test the application’s fields.) Finally, the Fonts tab is used for a special function described below.

Font Database Later in this Guide, different types of fields will be described. One type of field relies on software that identifies text on the screen based on the arrangement of pixels. This software is called optical character recognition, or OCR.

Note: docSTAR users may be familiar with OCR, and may know that it is not a perfect technology. This is true, but it should be noted that the OCR system in SmartLink is far more accurate, because it operates on a perfect image, with no skew, speckles, or other imperfections that make OCR on a scanned image more difficult.

O C R Fields (they’re actua lly referred to as Location fields in SmartLink) use font data. So, the first time SmartLink is run, it automatically examines all fonts on the PC and builds a “font database”. This can take a m inute or tw o; please be patient.

Generally, you will only have to do this the first time SmartLink is run on each PC. However, if fonts or resolution are changed, OCR fields may fail to provide accurate data. This can be cured clicking the button on the Fonts tab to rebuild the font database.


Creating Applications To create a new application, click the Add New button and give the application a descriptive nam e, such as “V endor-R etrieve” or “C lient-V C S ”.

Other Application Commands The name can be changed with the Modify command.

The Delete command deletes the entire application, including all of its fields, its command line, and its hot key assignment.


The Duplicate command asks you for a new name, and then makes a copy of the application with that new name. Why duplicate an application? It is common to have two applications with similar or identical fields, but different command lines and hot-keys. Typically, one application is for retrieval and another is for filing (cover sheet generation). Creating one application, duplicating it, and then adjusting the command line (and fields, if needed) saves time over recreating the fields from scratch.

Note: the duplicate application is created with no hot key, because it cannot share a hot key with the original.

Creating Fields First, select the application for which you wish to add (or modify or delete) fields.

Then, to create a field, click Add New.

Types of Fields

Choose a type of field. The process of creating a field varies for each type, as described below.

Automatic Fields Most applications are built entirely of automatic fields. Automatic fields capture data from the screen without relying on the clipboard, mouse position, or text highlight. This is the only type of field that can be used multiple times within one application.


Start defining an automatic field by giving it a name. Then click Next.

Note: The name is arbitrary. It should be logical to you, but it doesn ’t need to m atch the label used within the target application, a custom field name used within docSTAR, or anything else.

Before continuing, make sure that the target application is running, and that the text you wish to capture is visible on screen. Then click Set Source.


Step 1: Following the on-screen prompt, position the mouse over the source text. Hold the mouse still, and within a second or so, step 2 will turn green.

Note: Timing is important. If it takes too long to move the mouse into position, or if the mouse moves at the wrong time, the process will fail and an appropriate error description will be displayed. For best results, m ove at a steady pace but don’t rush. If you encounter an error, just click S et S ource and try again.

Step 2: Click on the source text. Within a second, you should see the following screen.


And now click Next to see the result.

If the text result displayed is correct, then the field is properly defined. Click Done.

If the wrong text was picked up, the mouse may have been positioned wrong. You can try again by clicking on “Prev” and repeating the process.

However, some fields cannot be retrieved with this method. If this is the case, click “Proceed to location setup” to define this field using O C R .

Location Setup (OCR) The mouse pointer will become a crosshair during location setup.


Drag the mouse to define a box around the desired text. Draw the box large enough to fully contain the text, but avoid nearby text or graphic elements.

For instance, if creating a field to capture the full name (Ira Whitman) displayed in the Contact form, above, start the box just inside the top right corner of the text box and extend it down to the bottom of the box way out to the right, as shown.

Note: Remember to extend the box far enough to accommodate the longest name or largest value that can appear in the field.


After you draw the box, SmartLink will show you the graphic image it captured as well as the text result it generated.

If the text is correct, there is one more choice to make: anchor point. Generally, when a window is resized, all or most fields maintain a consistent position relative to the top left corner of the window. However, some fields on some windows move w ith the right edge of the w indow w hen it is resized. If the text field you’re capturing is one of these, choose “top right” as your anchor point. Then click D one.

If the image isn’t quite right (egs. desired text is cut off or extraneous graphics are included), you can click “Proceed to location setup” to try again.

If the image is right, but the text is wrong, try rebuilding the font database, as described above. Then do the location setup again. If it still fails, this particular text may not be readable by the OCR technology. Look for another place on the screen, or a different screen, that contains the desired text.

Also, you can try the other field types.

Clipboard Field The clipboard field captures data from the Windows clipboard rather than the screen. It works with any application in which data can be copied to the clipboard. However, like all of the remaining field types, only one can be defined per application.

Like all fields, a clipboard field requires a name.


It also contains an option to send “C trl+ C ” to the target application. C trl+ C is the standard keyboard shortcut to copy selected text to the clipboard, so sending it can save a step.

If an integration is defined with this field type, the user must highlight the desired text (if Ctrl+C is sent) or copy it to the clipboard before hitting the hot key.

Mouse Position Field Similar to the clipboard field, only one mouse position field can be defined per application. It attempts to capture any text under the mouse position.

Choose a name, and decide whether or not to send a mouse click to the target application.

The m ouse click isn’t im portant for capturing the field, but will save a click if the normal workflow process requires selecting that field when the integration is triggered.


Highlighted Text Field Finally, there is one m ore “one per application” field. It captures any highlighted text without using the clipboard.

It only requires a name.

With this field type, the user need only highlight the desired text and hit the hot key.

Field Options There are two field options (check boxes) that can be critical for proper operation of the application. These are set independently for each field of each application.

Find by Class only Usually, SmartLink uses the Window Title and the Window Class to identify the target application. However, some applications vary their title bar depending upon the record or document open. For instance, the title bar of the Outlook Contacts form show s the contact nam e. If this is the case, enable “Find by C lass only”. Otherwise, the application will only work on the specific record for which it was defined.

Must be selected to read This option was originally developed for MS-Access, but it may apply to other target applications. It was found that MS-Access fields were only readable when they had the “focus”, m eaning that they w ere selected. W hen m ultiple M S -Access fields were defined in an application, they would all produce the same text— whatever text was found in the selected field.


Turning this option on causes S m artLink to “fake out” the target application by selecting each field before reading it. Use this option only if you find a problem reading text without it.

Defining the Command Line After defining all fields for the application, move on to the Command Line tab.

SmartLink supports two types of command lines:

If the C om m and Line begins w ith “http:” or “https:”, it is interpreted as a U R L (universal resource locator, or “w eb address”). Internet Explorer is launched to open the specified URL. An example URL-type command line is:

http://mydocstar/dswv/coverpage.asp?firstparam={firstparam}&secondparam={secondparam}

Note: The fields are automatically uuencoded so that special characters like slashes and ampersands can be passed effectively. Web servers like Microsoft Internet Information Server automatically uudecode the parameters.

Otherwise, the command line is passed to Windows. This means that the line is presumed to start with a path and file name of a program, followed by one or more command line parameters separated by spaces. Here is an example Windows-type command line:

C:\DOCSTAR\GENERICRETRIEVE.EXE //mydocstar/dswv/venom.asp?f=N&e=0&sv=0&docs=-1&folders=0&q1=Text%20=%20{ClientName}

The Test Shell Generally, you should test the fields for the application before defining the actual command line. S tart by clicking “A dd test shell”. This w ill place the path to “C om m andLine.exe” in the com m and line text box. This program is installed with


SmartLink. All it does is display the parameter(s) it has been passed in a message box. Therefore, this is a great utility for confirming that the fields and other text you add to the command line are working properly.

Add Fields A dd a field to the com m and line by selecting the field and pressing “A dd Field to C om m and Line”. Field nam es in the com m and line are show n in curly braces. You could also type the field nam e in braces m anually, but clicking the “A dd Field… ” button avoids typos. Continue adding fields, until all the fields you need are added.

For testing purposes, you may start out by just separating the fields with spaces to confirm that they are each working properly. Ultimately, the formatting of the command line must match the requirements for the cover page, retrieve program, or other application you are launching. (Refer to the Integration Agent Reference Guide for syntax for each API call.) Add any necessary prefixes, suffixes, punctuation, or delimiters to the command line by typing directly into the Command Line text box.

Testing The “Test fields” button fires the application, reading the specified fields from the target application and running the com m and line you’ve specified. First, confirm that the target application is running and the necessary window(s) are open. Also, make sure you click Apply to save your edits. Then click Test Fields. If you’re using CommandLine.exe, you should see a message box pop up with the proper field values.

Specify the Actual Path or URL After confirming that all fields are properly formatted in the command line, you should substitute your actual path/filename or URL address for CommandLine.exe. Now, when you test the application again, the actual integrated retrieval or filing function should run.

Note: It is recommended that you start by building the integrated filing function using a cover sheet or virtual cover sheet. This will run more quickly, which is important while honing the syntax of the command line. When the cover sheet or VCS command line is complete, you can use the Duplicate Application function as the starting point for creating the retrieval application.

Setting the Hot Key The last step is quite easy.


Choose a key or key combination for the hot key, which will not interfere with any other W indow s operations. Then click “A pply new H ot K ey”.

N ote: S m artLink recognizes the hot key pressed, but it does not “trap” it; it passes it on to whichever application is active. Therefore, if you choose a hot key of Ctrl+F4, for instance, pressing Ctrl+F4 will trigger your SmartLink application, but it will also be send to the active windows progam. Most Windows programs close when this key combination is pressed.

Repeat The process should be repeated for each “application” you are defining for SmartLink. As previously stated, the Duplicate command should be used to create applications that are based on existing ones. Often, common fields will be used among several applications.

Test Test each application carefully using different records within the target application. That m eans, for instance, if you built your fields using the client, “B . S m ith”, m ake sure you test on another client. Catching and correcting any errors now will save you the trouble of repeating the rollout process.


Rollout Once configured, SmartLink must be rolled out to each client station at which it will be used. A special mechanism is included to facilitate copying the configuration developed on the first station to all other stations as SmartLink is installed.

Installation C opy the S m artLink S ETU P program to a shared netw ork folder available to all PC ’s to which you will roll out SmartLink. You can create a SMARTLINK subfolder under C:\DOCSTAR\DATABASE\SETUP on the docSTAR Host for this purpose. You can also use any convenient shared folder.

Next, exit SmartLink; right-click on the icon in the systray and choose Exit. Copy the tw o configuration files you’ve just created to this shared folder. The files are called Command.ini and Config.dat. They are found in the sam e folder you’ve installed SmartLink in, which is C:\DOCSTAR\SMARTLINK by default.

N ote: Y ou’ve exited S m artLink before copying the files to m ake sure that they are closed.

Now, go to each PC on the network. Open the shared network folder containing S m artLink’s SETUP.EXE, Command.ini and Config.dat. Run SETUP.

The setup program detects the presence of the two configuration files and automatically copies them to the specified destination directory. (If you are reinstalling on a station that has had SmartLink before, and the configuration files are already present, you will be asked if the prior configuration files should be overwritten.)

When deployed in this manner, SmartLink also automatically locks the configuration, as described below.

Launch SmartLink and test the applications on each PC. Note that the font database must be built the first time SmartLink launches on each PC.

Locking the Configuration The file, SmartLink.ini, is automatically created in the SmartLink installation directory if it doesn’t already exist. A m ong its settings are:

[CONFIG_SETTINGS] config={on | hkey | off}

When config=on, full configuration is enabled. This is true for a normal CD-based install.

When rolled out through a network with configuration files, as described above, config=off is set. This disables all configuration controls, although the font database can still be rebuilt if necessary.

The option, config=hkey, allows the hot key(s) to be reassigned, but prevents edits to the applications, fields, or command lines. This option can only be set by manually editing this INI file.


Advanced Configuration Smooth and effective integrations can be built using SmartLink with the command line for each application directly calling the retrieval or cover page A PI’s specified in the Integration Agent Reference Guide. However, there are times when something else is needed.

For example, consider an application where a critical field appears in a text box or Windows title along with a prefix, like “C ustom er: S m ith, John J.” You don’t w ant to file the docum ent w ith the prefix, “C ustom er:”. Instead, you w ant to rem ove this prefix for both filing and retrieval.

Another example is the docSTAR AfW Integration, whose two SmartLink applications have been pictured in this Guide. This integration can retrieve from any of three screens in this target application, and it can file documents from any of these same screens. Yet, only one application/hot key is used for each: filing and retrieval. A little Visual Basic code is used to determine which screen is active based on the parameters present, and this determines how the docSTAR API is called. The resulting application is much simpler for the users then providing different hot keys for each different screen.

The section of the Guide describes briefly how advanced configurations may be created. Solid understanding of a programming or scripting language is necessary to implement such configurations.

Custom Cover Pages If the fields captured from the target application must be modified before being passed to docS TA R ’s cover page or virtual cover page A PI, they can be m odified through a custom web page.

In this exam ple, the param eters are passed to the custom w eb page “afw vcs.asp”, which is written using VB Script. (Other scripting languages can be used.) This page determines the current screen based on which parameters are present and not present. Depending on this determination, a web form may or may not be used to collect additional filing parameters from the user. Zero values are generated for missing parameters, because the template which processes the VCS will be looking for every parameter. Also, a prefix is removed from the CustomerName field. The final collection of parameters is sent to CreateVCS.ASP, which is the API provided by Integration Agent.

This is just one example. Highly sophisticated customizations are possible.

Custom Retrieval The Integration Agent API provides the program GenericRetrieve.Exe for integrated retrieval. If the fields captured from the target application are not quite suitable to send to GenericRetrieve, they can be modified through a custom retrieval program.


This example uses a custom retrieval program, afwretrieve.vbs, written in VB Script. The standard Windows utility, Wscript, is used to run afwretrieve.vbs. The parameters are passed in a format that afwretrieve.vbs can easily parse. Afwretrieve performs processing similar to afwvcs.asp. Then it launches genericretrieve.exe with the properly-formatted final parameters.

This, too, is just an example. VBS or ASP files placed between SmartLink and the docSTAR Integration Agent can do just about anything.

Documents

SmmaarrttLLiinnkk™™ nIInntteeggrraattiioon Guuiiddeesupport.docstar.com/portal/docstar/techdvd/manuals/... · 2006-08-08 · Note: this distinguishes Sm artLink from Datalink,