Integration: Third-Party Integration API v2

Overview

This page contains a discussion regarding various approaches to integrating the two products. The API itself has evolved from the needs of our third-party integrators over the years, and as such, if there is something that you feel is missing that would be beneficial, let CLS know and it is likely that it can be added for you. The following documentation indicates what CLS has chosen to do. This is not so much that you should follow these examples, but rather that you'll get an idea of how Image-Master is used at many existing law firms that also use Collection-Master.

Looking at scanning side first, you have three choices:

You can do nothing, and rely on Image-Master as a stand-alone scanning product to be completely responsible for the acquisition and filing of scanned documents.
You can establish a DDE conversation with the main imaging system (IMASTER.EXE) after the user has authenticated, selected a database, and invoked the Scanning Module. You can then programmatically request that a document be scanned and you can provide some or all of the filing criteria. Image-Master, upon receiving your request, will gain the window focus, raise the appropriate dialogs to initiate the scan, prompt the user for additional filing criteria, save and file the images, and return back to the idle mode.
You can establish a DDE conversation with the RAW image acquisition shim (FSCANTWN.EXE for TWAIN scanners or FSASF32.EXE for Kofax scanners) and control the scanning and image filing process directly. I am assuming that this option is not applicable to your project, but I mentioned it so you would have a complete picture of your options.

Looking at the viewing side, you have three choices:

You can do nothing, and rely on Image-Master as a stand-alone viewing product to be completely responsible for the search and retrieval of scanned documents.
You can establish a DDE conversation with the UI-less Image-Master control module (IMDDE.EXE) and request a search & view, a view only, or a print only operation be performed. Image-Master, upon receiving your request, will gain the window focus, raise the appropriate dialogs to prompt the user to select a document (or documents), retrieve and view the selected documents and return back to the idle mode.
You can create the viewing list file, establish a conversation with the Viewing Module directly (FVIEW32.EXE), and request retrieval and display (and/or print, email) directly from your application.

CLS chose option (1) for scanning and option (3) for viewing. This decision was partially arbitrary, partially to meet user requirements, and partially because they were and essentially still are a DOS application and are limited in their inter-process communications abilities. Most other third-party developers in our other markets have elected to go with option (2) for scanning and option (2) for viewing as well.

Deciding on a database structure for Image-Master:

Image-Master is a completely customizable and user-defined filing system. As such, you have complete control over the types of index fields, their lengths, data types, and rules. In addition to the user-defined fields, there are a number of mandatory internal control fields which may be of interest to you if you elect to parse the database directly. Since you might already possess a collection-attorney focused database for Image-Master (namely CLS000) this page describes how that is laid out. You can make changes to the database structure with the Image-Master configuration module yourself to suit your needs, and CLS can distribute an application-specific database (appropriately named, of course) for use with your software.

User Defined fields in CLS000:

Field Name Length          Data type       Description
fileno          8               Character       Collection-Master (attorney) file number
ddate           8               Date            Document Date
cmt             48              Character       Document Description
llcode          8               Character       Queue/Routing Person ID
docketno                15              Character       Docket Number
fwfileno                20              Character       Forwarder's File Number
client          40              Character       Client (Forwarder's) Name
debtor          30              Character       Debtor Name
creditor                25              Character       Creditor Name
lmdatec         6               Character       Computed Filing Folder ID**

**This field usually resolves to yyyymm or yyyyww where yyyy is the four-digit year, mm is the two-digit month, and ww is the two-digit week of the system date on the computer. The field is used to segregate documents into roughly equal periodic bundles on the hard drive to make backup and archiving administrative tasks easier to perform.

Internal Control Fields present in ALL Image-Master databases:

Field Name Length          Data type       Description
volume          8               Character       Volume ID if doc is on removable media
npath           60              Character       Path to Images in this document **

**This can be an absolute path (ie. C:\IMASTER\IMAGES\) [used with fixed media] or

**a relative path (ie. \DIR1\OCTOBER\IMAGES\) [used with removable media] or

**a UNC path (ie. \\SERVER\SHARE\FOLDER\) [doc on a NAS or similar] or

**a URL path (ie. Http://phillipsburg.idp.com/imaster/pump/mrr/)

(This assumes that all of JST customers will use absolute or UNC paths)

nfile 5 Character File Name Prefix *see naming of images below*
nfext 3 Character Image Name Extension (ie. TIF, JPG, PCX)
npages 3 Numeric Number of pages in the document (1-999)
status 1 Character Multiple Uses Flag.

(**In JST case, a "C" could mean exported to Collect-Max.)

status1             1 Character Document Creation Status N=New, C=Changed
status2             1 Character Special third-party use. (Undefined)
lmdate             8 Date Date of Scan (from workstation clock)
nfullname             8 Character Normalized multi-page filename. (Undefined)

Image Naming and Referencing with Image-Master:

An Image-Master generated image filename will always have the following attributes regardless of the raster format chosen for the file.

1. All images are single-frame (single page).

2. Filename is as follows: MJJJJnnn.EXT

M= Machine ID of workstation that image was scanned on

JJJJ= Base 26 sequentially assigned unique document ID "alpha-number"

nnn= Base 10 page number for the image (000 is the first page)

Ext= Image format extension (TIF,JPG,PCX,CAL,MIL etc...)

To find the first page of a document set, use npath+nfile+000.+nfext. Subsequent pages (up to npages) would be npath+nfile+(page-1).+nfext.

Scanning Under Your Control

Essentially, to scan under programmatic control the user performs the normal documented procedures for starting Image-Master at a scanning capable workstation. This will include starting the program, logging into Image-Master, selecting the desired database, and invoking the Scanning Module.

Once the Scanning Module loads, DDE server services are permitted and the following conversations will be honored from your application:

Service: IMASTER

Topic: SYSTEM

Executable: IMASTER.EXE (required to be running and in the Scanning Module by the user)

Request Type(s) Supported: EXECUTE

DDE Execute = SCAN (attended scanning) and SCANB (fully automated scanning) support the loading of index filing fields prior to the scan request being initiated.

The format is as follows:

SCAN=fieldname1=value1,fieldname2=value2, ...and so on.

Loading of field(s) during scanning is purely optional. The syntax also supports a DOS batch file compatible form that encloses the index fields in quotes as in: SCAN="fieldname1=value1..."

In all forms, the case of the commands and fieldnames are irrelevant, but the case of the values are preserved.

Note that fieldname123 is a literal which represents a valid, defined, index field from the currently selected database. If a third-party application tries to pass an undefined fieldname, the user will be advised and that field will be skipped. Any other valid fields will be loaded as expected.

Note that value123 is AN EXPRESSION! (One of FoxPro's greatest features). That means for simple literal assignments, the proper delimiters must be included around the value.

For example:

Storing a character literal: ADDRESS='123 Any Street' (note the SINGLE quotes around the value) Storing a date literal: TDATE={01/17/1996} (note the curly brackets around the value) and so on...

Note that since the value is an expression, more complex data can be exchanged.

For example:

Using an internal FoxPro function: TDATE=DATE() (this would store the current system date in the field) Using a third-party data source: DEALER=EXTNFN()+'extra literal value' quite simply, any expression that evaluates to the correct data type would work.

Another example:

SCAN="COMPANY='Able Fish Industries',TELEPH='(819) 555-1864'" (This uses the DOS compatible method. The corresponding batch command for a DOS app might be.. ...DISP32.EXE ...\IMASTER.EXE,SCAN=%1 and then the passed parameter would be "COMPANY='Able Fish Industries',TELEPH='(819) 555-1864'")

As mentioned earlier, the value(s) are loded into the appropriate fields prior to the start of scanning. Therefore, the typical workflow would be for the third-party application to send the request, the scanning operator loads the document set into the scanner as instructed, scans and QC's the document set, fills in any remaining index fields, and then chooses done.

Viewing Under Your Control

Using Option (2), invoking a specific or non-specific document search and retrieval:

Part I: Configure fixed API parameters in IMASTER.INI as follows:

Edit the IMASTER.INI file (Start, Programs, Image-Master, Image-Master Config File)

At the end, add the following text strings in order:

[Alpha4]

ViewServerID= {copy value from [StationA] or [StationS]}

ViewServerPath= {copy value from appropriate Station section for the WS}

SearchDBF= absolute path to the "SC" database to search

ExportPath=C:\

A typical Alpha4 section for Image-Master would be:

[Alpha4]

ViewServerID=FVIEW

ViewServerPath=C:\IMASTER\FVIEW32.EXE

SearchDBF=F:\IMASTER\CLS000SC.DBF

ExportPath=C:\

Save the file and exit the editor.

Part I only needs to be performed one time.

Part II: Establishing the DDE Conversation with the UI-less Module.

NOTE: When IMDDE.EXE is first invoked, either as part of a user logon script, shortcut icon, or ShellEx call from the application requesting service, the database specified in SearchDBF will be loaded in shared mode and the DDE server services will become available. It is important to leave IMDDE running to make queries operate as quickly as possible.

Service: IMDDE

Topic: SYSTEM

Executable: IMDDE.EXE

Request Type(s) Supported: EXECUTE

Function 1: Search the Image-Master Database and Display the resulting image(s):

SEARCH={expression to search on},{Custom Document Description/Annotation}

Ex: SEARCH=name="smith" .and. address="123 Any Street",UCC Filing

- If the SEARCH conditions result in exactly zero (0) matching documents, control returns to the caller and no document is displayed.

- If the SEARCH conditions result in exactly one (1) matching document, the Viewing window is invoked directly and the document is displayed.

- If the SEARCH conditions result in more than one (>1) matching document, the Search Results list dialog (grid control) displays the list of qualifying documents and the user is allowed to select (and/or multi-select) documents for viewing and printing purposes. The behavior and available controls are documented in the Viewing Module Search Results window topic.

Using Option (3), invoking the viewer directly with the list of pages to be viewed:

Step 1: Create the page list text file.

Create a text file on the workstation with a name of your choosing.

For each page to be viewed, populate a line in the text file in order as follows: Full Path and filename of the first Page {1 space} Description for the Title Bar/Printing/Emailing Full Path and filename of the 2nd Page {1 space} Description for the Title Bar/Printing/Emailing ...etc.

Close the file.

Step 2: Call the viewer passing the filename created in step 1.

Service: FVIEW

Topic: SYSTEM

Executable: FVIEW32.EXE

Request Type(s) Supported: EXECUTE

Function: listfile={full path and filespec to listfile created prior to call}, starting page # to view