Capture 8. Import Connector - Web Services SDK Developer s Guide Rev A

SDK Developer’s Guide

KOFAX

Capture

8

© 2008 Kofax Image Products, Inc., 16245 Laguna Canyon Road, Irvine, California 92618, U.S.A. All rights reserved. Use is subject to license terms.

Third-party software is copyrighted and licensed from Kofax’s suppliers. This product is protected by U.S. Patent No. 6,370,277.

THIS SOFTWARE CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF KOFAX IMAGE PRODUCTS, INC. USE, DISCLOSURE OR

REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF KOFAX IMAGE PRODUCTS, INC.

Kofax Image Products, Kofax, the Kofax logo, VirtualReScan, the “VRS

VirtualReScan” logo, and VRS are trademarks or registered trademarks of Kofax Image Products, Inc. in the U.S. and other countries. All other trademarks are the trademarks or registered trademarks of their respective owners.

U.S. Government Rights Commercial software. Government users are subject to the Kofax Image Products, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

You agree that you do not intend to and will not, directly or indirectly, export or transmit the Software or related documentation and technical data to any country to which such export or transmission is restricted by any applicable U.S. regulation or statute, without the prior written consent, if required, of the Bureau of Export Administration of the U.S. Department of Commerce, or such other governmental entity as may have jurisdiction over such export or transmission. You represent and warrant that you are not located in, under the control of, or a national or resident of any such country.

Contents

How to Use This Guide . . . v

Introduction . . . v

How This Guide is Organized . . . v

Related Documentation . . . .vi

Training . . . vii

Kofax Technical Support . . . vii

1 SDK Overview . . . 1

Introduction . . . 1

2 Application Considerations . . . 3

Introduction . . . 3

Batch Class Considerations . . . 3

Naming Conventions . . . 4

Field Display or Behavior . . . 5

Display Label or Name . . . 6

Fields Using Kofax Capture Values . . . 6

File Type Support . . . 6

Fixed Page Count . . . 6

Centralized User Management: Windows Authentication . . . 7

Secure Sockets Layer (SSL) . . . 7

3 System Requirements and Installation . . . 9

Introduction . . . 9

Contents

Installing the SDK . . . 10

Installed Components . . . 12

4 Using the API . . . 13

Introduction . . . 13

The Online API Documentation . . . 13

Accessing the API Documentation . . . 14

5 About the Sample Applications. . . 15

Introduction . . . 15

The C# Sample Application . . . 16

Using the C# Application . . . 16

The Java Sample Application . . . 18

Using the Java Application . . . 20

How to Use This Guide

Introduction

This guide contains an overview of and instructions for installing and using the Kofax Capture Import Connector - Web Services SDK, and instructions for using the API to create client applications that can submit batches into a Kofax Capture workflow.

Note Prior to version 8.0, this Kofax Capture Import Connector - Web Services

product was named Ascent Collection Server, and Kofax Capture was named Ascent Capture. Although the product names in most of the documentation has been changed, there remain instances of the old names or abbreviations in some code snippets, filenames, in the sample applications, and in the API reference.

How This Guide is Organized

This guide is divided into the following chapters:

Chapter 1 - Overview, offers an overview of the SDK components.

Chapter 2 - System Requirements and Installation, lists the software and other

requirements you need to compile the sample applications, and includes the SDK installation instructions.

Chapter 3 - Application Considerations, provides information on some security

and Kofax Capture batch class specifics that need to be addressed when creating your client application.

Chapter 4 - Using the API, provides information about the API documentation. Chapter 5 - About the Sample Applications, provides instructions for using the

How to Use This Guide

Related Documentation

In addition to this Kofax Capture Import Connector - Web Services SDK Developer’s Guide and the online API documentation, the following documentation may prove helpful to you.

„ The Kofax Capture Import Connector - Web Services Administrator’s Guide, which

provides instructions for installing, using, and maintaining the Kofax Capture Import Connector - Web Services components.

„ For more information about Kofax Capture, refer to the guides that are

provided and the online Help that is available from any Kofax Capture module and from your Kofax Capture program group.

„ Late-breaking product information is available from release notes. You should

read the release notes carefully, as they contain information not included in other documentation.

„ For more information about Microsoft products, including Microsoft Internet

How to Use This Guide

Training

Kofax offers both classroom and computer-based training that will help you make the most of your Kofax Capture distributed capture solution. Visit the Kofax Web site at www.kofax.com for complete details about the available training options and schedules.

Kofax Technical Support

For additional technical information about Kofax products, visit the Kofax Web site at www.kofax.com and select an appropriate option from the Support menu. The Kofax Support pages provide product-specific information, such as current revision levels, the latest drivers and software patches, online documentation and user manuals, updates to product release notes (if any), technical tips, and an extensive searchable knowledgebase.

The Kofax Web site also contains information that describes support options for Kofax products. Please review the site for details about the available support options. If you need to contact Kofax Technical Support, please have the following information available:

„ Kofax Capture Import Connector - Web Services version. „ Kofax Capture version.

„ Operating system and current service pack versions. „ Network configurations.

„ Copies of the Kofax Capture Import Connector - Web Services - Web Server

and Service log files, and the installation log files. Refer to the section

“Reviewing the Log Files” in the Kofax Capture Import Connector - Web Services

Administrator’s Guide for the names and locations of these files.

„ The Kofax Capture error log file (refer to the Kofax Capture documentation). „ Description of problem and error message.

„ Reproduction scenarios for problems or questions.

„ Background information about the requirements and/or function of the client

Chapter 1

SDK Overview

Introduction

The Kofax Capture Import Connector - Web Services SDK contains tools, sample applications, and the online API documentation that will enable you to create client applications that can submit batches for import into the Kofax Capture workflow. Figure 1-1 is a screen shot of the folder structure of the SDK on the Kofax Capture installation CD 2 (a subfolder located in \Import Connectors\Web Services\), and directly following it is a list of the contents of each of the folders.

Figure 1-1. Folder Structure

Folder name Contents

SDK Setup.exe, which starts the installation program, and the PDF file of this Kofax Capture Import Connector - Web Services SDK Developer’s Guide, which is copied to your hard drive during SDK installation SDK\Help The home page “Welcome_to ACS_SDK.htm” of the API

documentation and the Help subfolders, which are copied to your hard drive during SDK installation

SDK\SDK The SDK Setup.exe and installation files, which are called by SDK\Setup.exe

Chapter 2

Application Considerations

Introduction

Before creating a client application, decisions must be made about how to handle security, authentication, and some batch class considerations. If you, as the developer creating the client application, are certified on Kofax Capture and Web Server security, you might resolve these issues yourself and create the requirements specification for your client application. If not, you should consult with the Kofax Capture administrator or integrator to formulate the requirement specifications. In any case, your client application must handle each consideration in a manner that fulfills the requirements for the batch classes and authentication methods that will be available to the client users.

Batch Class Considerations

This section presents a sampling of batch class considerations: the administrator or integrator should be aware of these or similar settings, and should provide the specification requirements for implementation in your client application.

The specific elements and attributes in a batch class can be seen in its batch class XML file. The collapsed XML file in Figure 2-1 shows where you would look to find specific information about a batch class, such as field type and document class information. When the Kofax Capture Import Connector - Web Services - Service polls, the batch class XML files are updated in the \Kofax Capture Import Connector - Web

Chapter 2

Figure 2-1. Batch Class XML File (with elements collapsed)

Tip Documentation on the meaning of the attributes and elements of the published

batch class XML schema is found in the Kofax Capture ACAIDEF.dtd, which is located in the \ServLib\Bin folder where Kofax Capture server is installed.

Naming Conventions

The name of batch classes provided to the client application users can be formed by a combination of the batch class, document class, and form type names. If the batch class is to be visible in your application, the combination you code for the client application should be easily identifiable by client users, and documented for the Kofax Capture administrator to ensure that batch classes created in the future adhere to the appropriate naming conventions.

Example

If a batch class has several form types and you use the typical formula (batch class, document class, form type), your client users might see selections similar to the following:

Application Considerations

However, if the client application users submit batches based on regional orders, you could change the naming formula (to form type, document class, batch class) so that the selections would appear as:

Northwest Orders_Catalog Orders_Order Forms Southwest Orders_Catalog Orders_Order Forms

If the users of your client application will be submitting varied document and/or form types in submitted batches, you could choose to make the batch class elements (batch class, document class, and form type) display in separately selectable fields.

Field Display or Behavior

There may be some index fields in the batch classes that you decide shouldn’t be displayed in the client application, and some for which you need to decide whether to duplicate Kofax Capture field behavior. Below are just a few examples you might want to consider:

„ A field that has an Kofax Capture Value set as the default value: Because the

field is designed to receive the value during the Kofax Capture processing, you may want to hide it from the client user, whose entry would be used instead of the Kofax Capture value.

„ Fields where the Hidden value is set to True: If the design is to hide the field in

Kofax Capture, you may choose to hide it in the client applications as well.

„ Batch fields that are not required: If your application will be submitting

single-document batches and a field is designed as not required, you may want to hide it from the client user.

„ Fields with Force Match enabled: The value a client user might enter may not

match the list of values and would need to be corrected in the Validation module after the batch is imported into Kofax Capture. You may choose not to display such fields (which would then be set to the default value), or display a non-editable drop-down list from which the client user could select an appropriate value.

„ Default values: If there are multiple values for an index field that will be

displayed as a drop-down list in your client application, you may want to have the default value initially display. The default value will be listed in the IndexFieldDefinitions section of the published batch class XML file.

„ If the client application will be submitting batches containing index data that

Chapter 2

application. The values for such index fields will be populated by the Recognition Server module at your central site.

„ For fields that are defined as required, you may choose to enforce required

entry by the client user, and possibly differentiate required fields with underlining or another manner that can alert the user that the field requires an entry.

Display Label or Name

In Kofax Capture, if the field Display Label has content, that content will display instead of the field name. You need to decide whether your client application should behave the same.

Fields Using Kofax Capture Values

When data types such as DATE or TIME are assigned to an index field, Kofax Capture automatically assigns the Kofax Capture Value (such as {Current Date}) as the default value for the index field.

If fields that have a default value assigned to a Kofax Capture value display in your client application, any value entered by a client user will remain and not be

overwritten with a Kofax Capture Value, so you may want to hide these fields.

File Type Support

You can have your client application support submission of the various types of files (such as eDocuments, TIFF, or PDF files) or you can limit the selection in the client application to a subset.

Warning If submission of eDocuments or PDF files (PDF files can be imported as

either eDocuments or TIFF files) is a requirement, the Kofax Capture administrator must be aware of, and apply, the batch class settings and volume licenses that are required to support import of those file types.

Fixed Page Count

Application Considerations

warning message that will display if the client’s page count does not match the fixed page value, or prohibit the submission.

Centralized User Management: Windows Authentication

In Kofax Capture, user and group profiles can be managed locally (from within Kofax Capture), centrally (using operating system tools or utilities), or using a combination of both methods. Central management of users in Kofax Capture is also known as the feature Single Sign On. To enable Kofax Capture Import Connector - Web Services support for single sign on, you must enable your client application to use Windows authentication.

Note See the Kofax Capture Help topic About Centralized User Management for more

information on when and how to implement the Single Sign On feature.

The code required to use Windows authentication is shown in bold below (the code shown is from the Windows sample application included in the SDK).

/// <summary>

/// The main constructor /// </summary>

public MainController() {

// Create a proxy to the Kofax Capture Import Connector - Web Services - Web Server

// WebServiceAPIProxy was created as Web Reference m_oProxy = new WebServiceAPIProxy();

// Setup to pass Windows credentials in case single sign-on is enabled

m_oProxy.Credentials = CredentialCache.DefaultCredentials; m_oProxy.PreAuthenticate = true;

Secure Sockets Layer (SSL)

Chapter 3

System Requirements and

Installation

Introduction

This chapter lists some system requirements and provides the installation instructions and component specifics for the Kofax Capture Import Connector - Web Services SDK.

System Requirements

Along with the files that are installed with the SDK, you need the following items.

Tip All the items you need except a Web browser are provided in the Import

Connectors\Web Services\SDK\Tools folder on the Kofax Capture installation CD 2. To view the online PDF and the API HTML files:

„ Adobe Reader version 5 or higher.

„ Current version of Internet Explorer or Firefox.

To run the C# sample application:

„ Microsoft Web Services Enhancements (WSE) 1.0 Service Pack 1 (to implement

DIME) (see Installing Microsoft WSE 1.0 Service Pack 1 on page 10 for installation instructions)

To compile the Java sample application (for installation instructions, see To prepare the

Java application environment on page 19):

„ Java 2 Standard Edition (J2SE) SDK version 1.4.2

Chapter 3

Installing Microsoft WSE 1.0 Service Pack 1

If you need to install WSE, select the Complete setup type (see Figure 3-1), which will install documentation and samples that you can reference should you need WSE support.

Figure 3-1. WSE 1.0 Service Pack 1: Choosing Complete Setup Type

Installing the SDK

1 Log on to your computer as a member of the Administrators group, with full

administrative rights.

2 Make sure all applications are shut down (including the Control Panel, virus

detection software, and toolbars) that might be running.

3 Insert the Kofax Capture installation CD 2 into the CD drive. Browse to the

System Requirements and Installation

Figure 3-2. SDK Main Setup Screen

Chapter 3

Installed Components

Figure 3-4 is a screen shot of the local folder structure after SDK installation, and directly following it is a list of the contents of each of the folders. Note that the default location would put the structure in the C:\Program Files folder.

Figure 3-3.

Figure 3-4. SDK Samples Folder Contents

Folder name Contents

Code Subfolders for the C# and Java sample applications Code\CSharp The files for the C# sample application

Code\Java The files for the Java sample application

Docs The PDF file of this Kofax Capture Import Connector - Web Services SDK Developer’s Guide

Chapter 4

Using the API

Introduction

The Kofax Capture Import Connector - Web Services Application Programming Interface (API), is implemented as a Web service using ASP.NET 1.1 with the DIME binary extension. Although Kofax Capture Import Connector - Web Services is implemented using .NET, client applications may be implemented in either JAVA or .NET since they both support SOAP and DIME.

You can view the service description file at: http://<yourWebservername>/ AscentCollectionServer/api.asmx?WSDL.

In your application, you use SOAP request and response messages as the means to invoke the exposed methods by either:

„ Writing a client application that invokes the methods in the correct order „ Adding the invocations of the methods and any additional elements to an

existing application

The Online API Documentation

The API documentation is provided as a series of HTML pages that provide:

„ A description of the Web service methods and the order in which they are

called

„ A table of all the API exceptions

„ A link to view the Web Services Description Language (WSDL) file „ Detailed information about each method, where you will find:

„ Parameters and return values

Chapter 4

Accessing the API Documentation

From a supported browser (see To view the online PDF and the API HTML files: on page 9), you can access the API documentation by opening the welcome file Welcome_to_ACS_SDK.htm in any of the following ways.

„ Directly from the Kofax Capture installation CD 2 at \Import

Connectors\Web Services\SDK\Help\Welcome_to_ACS_SDK.htm

„ Installed as part of the SDK to the default location: Program Files\Kofax

Capture Import Connector - Web Services -

Chapter 5

About the Sample Applications

Introduction

During the SDK installation, the base code for two sample applications is also installed. You can compile and run them, and view the underlying code to understand how to use the API to create a client application.

The sample applications are:

„ A Windows sample application written in C# that provides a simple user

interface and uses all of the exposed API methods. Using the Windows application, you can submit batches into Kofax Capture and then check the batch status.

„ A console sample application written in Java that submits a hard coded

single-document batch.

All instructions in this chapter assume you have installed the SDK accepting the default installation path. If you installed to a different location, adjust the instructions accordingly.

Note The sample applications will not work with SSL or a Proxy server. Both

Chapter 5

The C# Sample Application

You must have the Kofax Capture Import Connector - Web Services SDK and

Microsoft WSE 1.0 Service Pack 1 (provided on the Kofax Capture installation CD 2 in Import Connectors\Web Services\SDK\Tools folder) installed.

X To prepare Kofax Capture

1 In the Kofax Capture Administration module, import the LESSON_1.cab file

located in the Tutorial folder where Kofax Capture is installed.

2 Publish the Order Forms batch class.

3 Assign the Order Forms batch class to a user that has the Scan module

assigned. Make note of the User ID and Password (if any): you will enter these as parameters in the sample application.

4 Restart the Kofax Capture Import Connector - Web Services - Service to

update the Web Server with the new batch class information.

The executable file is \Program Files\Kofax Capture Import Connector - Web Services - SDK\Samples\Code\CSharp\bin\Release\SampleApp.exe.

X To run the C# application, run the SampleApp.exe file to start the application and read the next section Using the C# Application for information on using it. To run the Windows sample application, the computer on which you run the executable must have WSE 1.0 installed.

Note You can copy the SampleApp.exe to the local drive of any computer with

Internet access and run it, but if you locate it on a network drive you must change settings to eliminate the default .NET security.

Using the C# Application

To use the sample application, a user would perform one of the the following steps after starting the application:

„ If you are not using Windows authentication and the sample application is

local, accept the default address (using localhost if you are running the application on the Web Server) or enter the Web Server URL followed by api.asmx (http://<webservername or IP adress>/AscentCollectionServer/ api.asmx) and the Kofax Capture user information.

„ If you are using Windows authentication and the sample application is local,

About the Sample Applications

on the Web Server) or enter the Web Server URL followed by api.asmx (http:/ /<webservername or IP adress>/AscentCollectionServer/api.asmx) and select Connect as Current User. This will make the user information fields

unavailable and pass the necessary blank user information so that the Kofax Capture Import Connector - Web Services - Web Server will connect as the Windows user. See Centralized User Management: Windows Authentication on page 7 for information on how to enable Windows authentication in your client application.

Figure 5-1. Sample Windows Application

1 Click Connect to contact the Web Server: user information is authenticated

and list of the batch classes assigned to the user is downloaded and displayed in the Document Type group for selection.

2 Select a Document Type. The sample application populates the drop-down

Chapter 5

3 Create the batch in two steps which can be performed in any order:

„ Enter index values (in the example in Figure 5-1, the only index field is

Customer Name).

„ Browse to select an image file to include in the batch.

4 Click Submit to upload the batch to the Web Server, where it will be imported

into the Kofax Capture workflow when the Kofax Capture Import Connector - Web Services - Service polls.

5 Select File | Batch Status to review the status of submitted batches. The status

information is related to the single instance of the sample application that is running, so once the application is closed, status history of previously submitted batches cannot be viewed again.

The Java Sample Application

When you install the SDK, the following files will be installed in the \Kofax Capture Import Connector - Web Services\ SDK\Samples\Code\Java folder of your specified installation path (by default, C:\Program Files):

„ build.bat is the batch file used on the command line to initiate the build. „ BuildFile.xml contains the build directions and paths to the component files

that are necessary to finalize the build. If you change the installation path, you will need to edit all paths in this file to match your installation and extraction paths.

„ JSample_ImportSession.xml contains the sample batch content and indexing

information. It is the file that will be submitted to the Kofax Capture Import Connector - Web Services when the Java application is run.

„ NWest_1.tif is the image selected for the sample batch.

„ JSample.cab is a cabinet file to import into Kofax Capture to be accessed by

the sample application.

„ \Class (created during build) and \src folder that contain supporting java and

other files.

Before you can use the Java application, you must prepare Kofax Capture, prepare the Java environment, and compile the application. Follow the steps below. Note that all paths used include the default installation location of C:\Program Files: if you installed to a different location, alter the paths accordingly.

X To prepare Kofax Capture

1 In the Kofax Capture Administration module, import the JSample.cab file

About the Sample Applications

2 Publish the JSampleOrder batch class.

3 Assign the JSampleOrder batch class to a user that has the Scan module

assigned. Make note of the User ID and Password (if any): you will enter these as parameters on the command line when you run the Java sample application.

4 Restart the Kofax Capture Import Connector - Web Services - Service to

update the Web Server with the new batch class information. X To prepare the Java application environment

1 Install the SDK.

2 If you don’t have the Java SDK installed, from the Kofax Capture installation

CD 2 \Import Connectors\Web Services\SDK\Tools folder run j2sdk-1_4_2_05-windows-i586-p.exe

3 Extract to your C:\ root folder the following files from the \Tools folder: Note If you extract to other than the C:\ root, you must edit the installation

path parameters in the BuildFile.xml file to match your extraction location.

„ apache-ant-1.6.2-bin.zip

This will create the folder C:\apache-ant-1.6.2.

„ axis-1_1.zip

This will create the folder C:\axis-1_1.

„ Xerces-J-bin.2.6.2.zip

This will create the folder C:\xerces-2.6.2.

4 Copy the following files to the \ext folder in the library folder where your

Java runtime is located (for example,

C:\Program Files\Java\j2re1.4.2_05\lib\ext):

„ The activation.jar and mail.jar from the \Tools folder „ The eight .jar files in the C:\axis-1_1\lib folder „ The five .jar files in the C:\xerces-2.6.2 folder

X To compile the Java application

1 Compile the application at the command line by running the build.bat batch

file located in the C:\Program Files\Kofax Capture Import Connector - Web Services - SDK\Samples\Code\Java folder.

Chapter 5

Using the Java Application

To use the Java sample application, do the following.

1 Run the JSample.jar sample application from the command line, adding the

Kofax Capture Import Connector - Web Services - Web Server URL and your Kofax Capture UserID and Password (or including a null quote set if there is no password) at the end, as in the following example where UserID is sblake and password is null:

java -jar JSample.jar http://<your Web server>/AscentCollectionServer/ API.asmx sblake ""

Note The Java sample application does not support Windows authentication. 2 The application will submit the batch from the JSample_ImportSession.xml

file with the attached image NWest_1.tif, as shown in Figure 5-2, and pause awaiting the return of a batch status.

If you want to see that batch status, just leave the sample application running until the Kofax Capture Import Connector - Web Services - Service completes its next scheduled polling interval (you can also restart the service to initiate an immediate poll).

Figure 5-2. Java Sample Application After Submitting the Sample Batch

Note The Java sample application is designed to limit the size of submitted image

Index

A

accessing the documentation, 14 how implemented, 13

list of online documentation, 13

B

Batch class considerations, 3

field display or behavior considerations, 5 naming conventions, 4

schema file documentation, 4 XML file, illustrated, 4

C

C# sample application

preparing Ascent Capture, 16 running, 16

using, 16

D

Development tools provided in the SDK, 9 Display label behavior considerations, 6 Displaying fields in your client application, 5

E

Example

of batch class naming conventions, 4

F

Fixed page count consideration, 6

I

J

Java sample application build files included, 18 compiling, 19

image size limit, 20

preparing Kofax Capture, 18 preparing the Java environment, 19 screen shot while running, 20 using, 20

K

technical support, vii training, vii

Web site, vii Kofax Capture

field display or behavior, 5

Index

hiding fields, 6

M

Microsoft Web Services Enhancements (WSE) required for DIME in C# sample application, 9

P

Planning

batch class considerations, 3

R

S

Secure Sockets Layer (SSL), 7 considerations, 7

will not work with sample applications, 15 System requirements

listed, 9

T