Business Interaction Server. Configuration Guide Rev A

(1)

Business

Interaction

Server

(2)

TOPCALL International GmbH.

Third-party software is copyrighted and licensed from Kofax’s suppliers. For information on third-party software included in this product, see

BISTHIRDPARTYLICENSEREADME.txt, which is in the Documentation folder where Kofax Business Interaction Server is installed (usually C:\Program Files\Kofax\Business Interaction Server).

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, Ascent, and Ascent Capture are trademarks or registered trademarks of Kofax Image Products, Inc. in the U.S. and other countries. TOPCALL is a trademark or a registered trademark of TOPCALL International GmbH. 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.

(3)

How to Use This Guide

Introduction

This guide contains essential information about configuring Business Interaction Server. It provides a description of configuration procedures for the Business Interaction Server features, which will be useful for system administrators and developers.

This guide assumes that you have a thorough understanding of Windows standards, applications, and interfaces. Additionally, it assumes that you have a thorough understanding of XML, your network configuration, and your SQL Servers and LDAP applications.

This guide also assumes that you have already installed Business Interaction Server and, in case you wish to send fax confirmations and notifications, the TOPCALL fax server or Captaris RightFax server before starting any of the configuration procedures described in this guide.

For further information about the installation and configuration prerequisites of Business Interaction Server, refer to the Kofax Business Interaction Server Component Installation Guide.

Training

Kofax offers both classroom and computer-based training that will help you make the most of your Kofax Business Interaction Server solution.Visit the Kofax Web site at www.kofax.com for complete details about the available training options and schedules in the Services menu.

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 provides 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 Business Interaction Server serial number Kofax Business Interaction Server software version Kofax Template Designer software version

Operating system and service pack version Network and client configuration

Copies of your log files

Special/custom configuration or integration information

(7)

Chapter 1 Overview

Introduction

This chapter provides an overview of the topics that are covered by this guide. In addition, it contains information on where Business Interaction Server modules can be configured. This information will help you configure your Business Interaction Server according to your needs.

Overview of Topics in this Guide

Business Interaction Server is a single server designed to handle real-time information exchange between business processes. In connection with the Ascent Capture Add-ins for Kofax Business Interaction Server, it enables you to handle business processes efficiently by automatically responding to both complete and incomplete customer documents.

The Kofax Business Interaction Server Configuration Guide includes the following information:

A description of the different modules of Business Interaction Server and their

configuration.

Data lookup: if you already use databases or LDAP for administering

customer data, you can connect Business Interaction Server to your data store and configure it to perform a data lookup whenever additional data is required to complete a business process.

Instructions to enable Business Interaction Server to send email and fax

messages.

Where to Configure Business Interaction Server

(8)

Kofax Administration Console

Kofax Administration Console enables administrators to manage Business Interaction Server and configure Business Interaction Server modules. Because Kofax

Administration Console is a browser-based application, it can be run from any workstation connected to Business Interaction Server.

X To configure Business Interaction Server in Kofax Administration Console 1 Do one of the following to open Kofax Administration Console:

From the Start menu, select All Programs | Kofax | Business Interaction

Server | Kofax Administration Console.

Enter http://<server>:<port>/adminconsole or

https://<server>:<port>/adminconsole into your internet browser, where <server> is the name of the computer your Business Interaction Server is running on, and <port> is the port used by Business Interaction Server.

Note For http, the default port is 8080. If you want to use a secure connection (https), use port 8443.

2 Log on with the username and password of a valid portal user. If you log on for the first time, use the username “admin” and the password “admin”. 3 Select the Business Interaction Server tab, where you can modify the

following Business Interaction Server modules:

Email

Conversion

Data Connector Fax Connector

Configuration Files

In default installations, the configuration files of Business Interaction Server are located in C:\Program Files\Kofax\Business Interaction

(9)

Overview

The following table lists the Business Interaction Server modules that are configured in configuration files:

Table 1-1. Modules Configured in Configuration Files

Module Configuration File

TemplateStore bis_config.xml

(10)

(11)

Chapter 2 Converting and Storing Templates

Introduction

This chapter describes the configuration procedures for the two Business Interaction Server modules Conversion and TemplateStore, which you need for converting and storing templates from Kofax Template Designer. It contains information about the functionalities of these two modules and explains their configuration parameters.

Conversion

This module controls the conversion from RTF or XML-RTF to FO, which in turn can be converted to TIFF or HTML. Thus, the published templates from Kofax Template Designer are converted into fax (TIFF) or email (HTML) format.

X To configure this module

1 In Kofax Administration Console, select the Business Interaction Server tab. 2 In the Navigator, select Configuration | Conversion. The Conversion page

appears.

Figure 2-1. Conversion Page

(12)

Tip If you want to know the location that is indicated by the variable %TEMP%, enter “set” into your Windows command line to display your system information.

4 Click Save to save your Conversion settings.

TemplateStore

This module determines the directory where all published templates are stored. You can configure this module in the configuration file bis_config.xml, usually located in C:\Program Files\Kofax\Business Interaction Server\Avalin\Jboss\server\ avalin\conf. The default configuration is:

<TemplatesDirectory>.\..\server\avalin\templates</ TemplatesDirectory>

</TemplateStore>

(13)

Chapter 3 Configuring Data Lookup

Introduction

This chapter describes the configuration steps that are necessary in order to make Business Interaction Server perform a data lookup. Business Interaction Server can be connected to the following databases:

Microsoft SQL Server 2000 and 2005 Microsoft Access 2003 and 2007

MySQL 5.0 and 5.1 Community Editions PostgreSQL 8.2

Note Your Business Interaction Server setup includes a Microsoft Access sample database and scripts to create sample data for Microsoft SQL, MySQL and PostgreSQL.

Additionally, data lookup is also possible in the following LDAP implementations:

OpenLDAP

Active Directory Service

Data lookup is necessary whenever a business process is disrupted due to missing data. If, for example, an incoming document contains only the customer number, Business Interaction Server will browse through the selected customer database and find other essential information like name, address, and fax number.

(14)

Using Microsoft Access, Microsoft SQL Server, MySQL, or

PostgreSQL

This section outlines the necessary steps to successfully perform a data lookup in Microsoft Access, Microsoft SQL Server, MySQL or PostgreSQL. The following lists a few things that you should consider before actually starting to configure the data connector.

Considerations for Microsoft Access

If you want Business Interaction Server to perform data lookup in your Microsoft Access database, the following prerequisites must be met:

For a successful data lookup, make sure your Microsoft Access database is

installed on the same computer as Business Interaction Server.

Do not use special characters in your databases. In the current JDK version,

JDBC-ODBC Bridge does not support Unicode UTF-16. Consequently, data lookup in Microsoft Access databases will fail if fields contain special characters. For more information about this bug see http://bugs.sun.com/ bugdatabase/view_bug.do?bug_id=6345277.

Considerations for MySQL

If you are using a MySQL database, follow these instructions to make your MySQL Server database ready for data lookup.

In order for Business Interaction Server to connect to your MySQL database,

install the appropriate JDBC driver.

a Download MySQL Connector/J, the official JDBC driver for MySQL, from http://dev.mysql.com/downloads/connector/j/5.1.html.

b Open the ZIP archive of MySQL Connector/J.

c Copy and paste mysql-connector-java-<current version>-bin.jar into the Avalin server library of Business Interaction Server, usually located in C:\Program Files\Kofax\Business Interaction

(15)

Configuring Data Lookup

Considerations for PostgreSQL

After the installation of Business Interaction Server, PostgreSQL includes a user with the name “postgres” and the password “postgres”. If you want to change the

password of this user, follow this procedure.

X To change the password of the user “postgres” 1 In the Windows Services panel, stop BISService.

2 In pgAdmin III, change the password of the user “postgres”.

Note For more information about user administration in PostgreSQL, refer to the PostgreSQL documentation.

3 In the configuration file postgresql-ds.xml, usually located in C:\Program Files\Kofax\Business Interaction Server\Avalin\Jboss\server\avalin \deploy, insert the new password in the <datasources> section. 4 In the configuration file liferay-ds.xml, usually located in C:\Program

Files\Kofax\Business Interaction Server\Avalin\Jboss\server\avalin \deploy, insert the new password in the <datasources> section. 5 Start BISService and verify that your changes are effective.

Configuring the Data Connector

After you have gone through the above-mentioned considerations, use the following procedure to configure the data connector.

X To configure data lookup in Microsoft Access, Microsoft SQL Server, MySQL, or PostgreSQL

1 In Kofax Administration Console, select the Business Interaction Server tab. 2 In the Navigator, select Configuration | Data Connector. The Data Connector

(16)

Figure 3-1. Data Connector Page with Data Source Type Other than None

Note The default source type is “None”.

3 Do one of the following to access the Data Connector Wizard:

If you want to configure the data connector for the first time or your

current data source type is None, click Configure data connector.

If you want to change your current data connector settings with a data

source type other than None, click Modify. Optionally, click Test Connection to verify that the connection to your data source can be established using the current settings.

4 Select the source type and click Next.

5 For Microsoft Access, complete the fields as follows:

ODBC data source name: Use the data source name that you have defined

(17)

For Microsoft SQL Server, complete the fields as follows:

Host name: The name of your Microsoft SQL Server. Default: localhost.

**Mandatory field.

Instance name: The name of the instance containing the database where

you want Business Interaction Server to browse for additional data.

Port: The port number used by Microsoft SQL Server. Default: 1433.

Note “Instance name” and “Port” are optional fields, but you need to specify at least one of them. If only the instance name is available, you need SQL Server Browser running as a Windows service on the computer where Microsoft SQL Server is installed. If both fields are filled, the port number will be used to connect to your database.

Database name: The name of the database where you want Business

Interaction Server to browse for additional data. **Mandatory field.

User name: Insert the user name of the user performing the data lookup. Password: Insert the password of the user performing the data lookup.

Important Business Interaction Server will not be able to connect to your Microsoft SQL database if you use the user name and password of a

Windows user. For a successful connection to your Microsoft SQL database, always use the credentials of a valid SQL user.

For MySQL and PostgreSQL complete the fields as follows:

Host name: The name of the computer where your MySQL or PostgreSQL

Server is running. Default: localhost. **Mandatory field.

Port: The port number used by the MySQL or PostgreSQL Server. Default:

3306 (MySQL) or 5432 (PostgreSQL). **Mandatory field.

Database name: The name of the database where you want Business

Interaction Server to browse for additional data. **Mandatory field.

User name: Insert the user name of the user performing the data lookup. Password: Insert the password of the user performing the data lookup.

6 Click Next.

(18)

Note In the list, tables are marked with an initial “T” and views are marked with an initial “V”. They are arranged alphabetically, with the tables listed first.

8 Optionally, click Test Connection to verify that the connection to your database can be established and that the selected table or view can be accessed using the current settings.

9 Click Finish. Your changes are saved, and you are returned to the Data Connector page.

Using LDAP (OpenLDAP, Active Directory Service)

This section outlines the necessary steps to successfully perform a data lookup in your OpenLDAP or Active Directory.

X To configure data lookup in OpenLDAP or Active Directory

1 In Kofax Administration Console, select the Business Interaction Server tab. 2 In the Navigator, select Configuration | Data Connector. The Data Connector

page appears.

Note The default source type is “None”.

3 Do one of the following to access the Data Connector Wizard:

If you want to configure the data connector for the first time or your

current data source type is None, click Configure data connector.

If you want to change your current data connector settings with a data

source type other than None, click Modify.

4 Select the source type “LDAP (OpenLDAP, Active Directory Service)” and click Next.

5 Complete the fields as follows:

Host name: The name of the computer where your OpenLDAP or Active

(19)

Port: The port number used by OpenLDAP or Active Directory. Default:

389.

**Mandatory field.

Administrator’s DN: The administrator's Distinguished Name (e.g.

cn=Manager,dc=domain,dc=com). **Mandatory field.

Password: The administrator's password.

Search root: The location within OpenLDAP or Active Directory where

you want Business Interaction Server to browse for additional data (e.g. ou=Users,dc=domain,dc=com).

**Mandatory field.

Note For more information about OpenLDAP and Active Directory configuration, refer to the documentation provided with each respective product.

6 Optionally, click Test Connection to check if the connection to your data source can be established.

(20)

(21)

Chapter 4 Mapping Request Fields to

Database or LDAP Fields

Introduction

This section outlines the necessary steps for mapping request fields to database or LDAP fields. Most probably, field names of existing databases or LDAP applications differ from the request field names defined in Ascent Capture or Ascent Xtrata Pro. Therefore, you can configure Business Interaction Server to map these different field names and thus enable it to process data from your existing data store.

Note The field names are case-sensitive.

Configuration

If you want to map request fields to database or LDAP fields, follow these steps. Make sure you are using all field names correctly.

X To map request fields to database fields, change the configuration file bis_dbfieldmapping.xml, usually located in C:\Program Files\Kofax\Business Interaction Server\Avalin\Jboss\server\avalin\conf.

X To map request fields to LDAP fields, change the configuration file

bis_ldapfieldmapping.xml, usually located in C:\Program Files\Kofax\Business Interaction Server\Avalin\Jboss\server\avalin\conf.

(22)

<?xml version="1.0" encoding="UTF-8"?>

<m:mapping xmlns:m="http://www.dicomgroup.com/avalin/bis/ fieldmapping"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <map>

<description>The first name</description> </map>

<map>

</map> <map>

<description>Email address</description> </map>

</m:mapping>

Tip For data lookup in your database, you can limit the number of fields where you want Business Interaction Server to browse for information. Change the SQL Select statement in the corresponding section of the configuration file bis_config.xml, usually located in C:\Program Files\Kofax\Business Interaction

Server\Avalin\Jboss\server\avalin\conf, to specify the fields for data lookup. For the example above, change the <SqlQuery> tag in the <DataLookup> section to <SqlQuery>SELECT ContactFirstName, ContactLastName, emailaddress FROM </SqlQuery>.

Supported Data Types

(23)

Mapping Request Fields to Database or LDAP Fields

Note The data types are case-sensitive.

Decimal Exact-number data type with fixed scale (12 bytes). Numbers are rounded off to two decimal places. Double Approximate-number data type representing a

double-precision floating-point number (8 bytes). Numbers are rounded off to two decimal places.

Float Approximate-number data type used for numeric data

with floating point (4 bytes). Numbers are rounded off to two decimal places.

Integer Exact-number data type used for integer data (4 bytes) Short Exact-number data type used for integer data but smaller

than the data type Integer (2 bytes)

String Represents a variable number of characters

Time Represents the time of the day

Timestamp Represents the date and the time of the day Table 4-1. Supported Data Types

(24)

(25)

Chapter 5 Sending Email Confirmations and

Notifications

Introduction

Business Interaction Server can be configured to send email confirmations and notifications indicating either that a complete customer document has been received or that some additional action on the customer’s part is required, for example

providing information that is missing in the original customer document. For security purposes, you can enable SMTP authentication so that Business Interaction Server has to authenticate at the email server. This chapter outlines the necessary steps to configure the send email functionality of Business Interaction Server and thus to easily respond to customer documents with email confirmations and notifications.

Configuration

Use the following procedure to configure the send email functionality of Business Interaction Server.

X To configure Business Interaction Server to send email confirmations and notifications

(26)

Figure 5-1. Email Page

SMTP server: The email server that is used for sending emails. Default:

localhost.

**Mandatory field.

SMTP port: The port number used by the server for sending emails.

Default: 25. **Mandatory field.

Originator address: The email address of the originator.

**Mandatory field.

Subject: The subject of the email sent by Business Interaction Server. You

can also specify the subject on a per-template basis in Kofax Template Designer, which will then overrule the subject defined in Kofax Administration Console.

User name: The name of the user that logs on to the SMTP server. Password: The password of the user that logs on to the SMTP server.

4 Optionally, click Test Connection to verify that the connection to your email server can be established.

(27)

Chapter 6 Sending Fax Confirmations and

Notifications

Introduction

This chapter describes the procedure to enable Business Interaction Server to send fax confirmations and notifications. It includes the necessary steps to connect Business Interaction Server to TOPCALL fax server or Captaris RightFax server.

Your Kofax Business Interaction Server installation includes the following fax connectors:

TOPCALL Web Services (TWS), which connects Business Interaction Server to

your TOPCALL server.

RightFax Web Services (RWS), which connects Business Interaction Server to

your Captaris RightFax server.

Business Interaction Server can be configured to use both TWS and RWS. You can only use one fax connector at a time, but Business Interaction Server stores the two configurations separately so you can switch between the two fax connectors without losing any configuration data.

For further information about TOPCALL or RightFax servers, see the documentation provided with each respective product.

Configuration

Make sure your fax server is running properly before you continue with the following procedure.

X To configure the fax connector

(28)

2 In the Navigator, select Configuration | Fax Connector. The Fax Connector page appears.

Figure 6-1. Fax Connector Page with Fax Connector Type Other than None

Note The default fax connector type is “None”.

3 Do one of the following to access the Fax Connector Wizard:

If you want to configure the fax connector for the first time or your current

fax connector type is None, click Configure fax connector.

If you want to change your current fax connector settings with a fax

connector type other than None, click Modify. Optionally, click Test Connection to verify that the connection to your fax server can be established using the current settings.

(29)

Sending Fax Confirmations and Notifications

Fax server name: The name of your TOPCALL or Captaris RightFax

server.

**Mandatory field.

User name: The name of the user that is used for accessing the fax server.

**Mandatory field.

Password: The password of the user that is used for accessing the fax

server. 6 Click Next.

7 Specify the advanced fax connector settings.

The advanced settings for TOPCALL Web Services are:

TWS server name: The name of the computer where TWS is running.

Default: localhost. **Mandatory field.

TWS port: The port number used by TWS. Default: 25082.

**Mandatory field.

Send service: must match the name of the fax send service you have

defined on your TOPCALL server, e.g. FAX (default), FXI, etc.

Originator fax number: if specified, the originator fax number will be

indicated in the fax header.

Originator name: if specified, the originator name will be indicated in the

fax header.

Codepage: Must match the codepage configured on your TOPCALL

server. Default: TCOSS code page 0.

The advanced settings for RightFax Web Services are:

RWS server name: The name of the computer where RWS is running.

Default: localhost. **Mandatory field.

RWS port: The port number used by RWS. Default: 25084.

**Mandatory field.

Important To change your TWS or RWS port, you must also modify the enhanced TWS or RWS configuration form. Follow the procedure described in the next section.

(30)

9 Click Finish. Your changes are saved, and you are returned to the Fax Connector page.

Changing TWS and RWS Ports

If the default ports of TWS and RWS are already used by other applications in your system, you can change the fax connector port.

X To change the TWS or RWS port

1 In Kofax Administration Console, go through the Fax Connector Wizard to change the TWS or RWS port as outlined in the previous procedure.

2 Run the configuration batch file Configure.bat, usually located in C:\Program Files\Kofax\Business Interaction Server\Fax Connector\TWS\00 or, for RightFax connector, in C:\Program Files\Kofax\Business Interaction Server\Fax Connector\RWS\00. The enhanced TWS or RWS configuration form appears.

3 Specify the port you want to use for TWS or RWS in the TcpPort field. 4 Click Save to save your changes and close the enhanced TWS or RWS

configuration form.

5 In the Windows Services panel, restart TOPCALL Web Services to make changes of the TWS port effective. For changes of the RWS port, restart Kofax RightFax Connector.

(31)

Appendix A

Ports Used by Business Interaction

Server

Introduction

This section lists the ports used by Business Interaction Server. This information might become useful especially when your Business Interaction Server does not start or work properly. In this case, make sure that the ports listed in this section are not used by any other applications before you take further troubleshooting actions.

Ports Used by Business Interaction Server

The list of used ports provided in this section applies to standard installations. You can reconfigure the ports with the caveat that this might cause your Business Interaction Server to stop working properly.

X To obtain a list of the local active addresses in numerical IP address form, enter “netstat -a -n” into your Windows command line.

The following ports are used by Business Interaction Server: Table A-1. Used Ports

Port Number Port Name

135 RightFax port

161 SNMP trap port

1098 RMI port

1099 RMI port

3528 OA port

(32)

Note RWS also uses RPC standard ports to connect to Captaris RightFax server. For more information on RPC port configuration, refer to

http://support.microsoft.com/kb/154596/EN-US/.

4445 Server bind port

8009 AJP port

8030 MBean server port

8080 HTTP port

8083 Web service port

8093 Server bind port

25082 TWS port

25084 RWS port

64508 TOPCALL port

(33)

Index

C

Configuration files, location, 2 Conversion configuration procedure, 5 description, 5

D

Data lookup description, 7 LDAP, 12 Microsoft Access, 8 Microsoft SQL Server, 8 MySQL, 8 PostgreSQL, 8

Data types, supported, 16

F

Fax connectors

RightFax Web Services, 21 TOPCALL Web Services, 21 Fax servers, supported, 21 Field mapping

configuration procedure, 15 description, 15

K

Kofax Administration Console description, 2 starting, 2 URL, 2

L

M

Modules

configured in configuration files, 3

configured in Kofax Administration Console, 2

P

Ports used by Business Interaction Server, 25

R

Related documentation, v Release Notes, vi

RightFax Web Services (RWS), 21 RPC standard ports, 26

S

Sending email confirmations and notifications, configuration procedure, 19

Sending fax confirmations and notifications, configuration procedure, 21 SQL servers, supported, 7

T

Technical support, vi TemplatesDirectory, 6 TemplateStore, 6

(34)

Business Interaction Server. Configuration Guide Rev A

Business

Interaction

Server

Contents

How to Use This Guide

Introduction

Related Documentation

Training

Kofax Technical Support

Chapter 1

Overview

Introduction

Overview of Topics in this Guide

Where to Configure Business Interaction Server

Kofax Administration Console

Configuration Files

Chapter 2

Converting and Storing Templates

Introduction

Conversion

TemplateStore

Chapter 3

Configuring Data Lookup

Introduction

Using Microsoft Access, Microsoft SQL Server, MySQL, or

PostgreSQL

Considerations for Microsoft Access

Considerations for MySQL

Considerations for PostgreSQL

Configuring the Data Connector

Using LDAP (OpenLDAP, Active Directory Service)

Chapter 4

Mapping Request Fields to

Database or LDAP Fields

Introduction

Configuration

Supported Data Types

Chapter 5

Sending Email Confirmations and

Notifications

Introduction

Configuration

Chapter 6

Sending Fax Confirmations and

Notifications

Introduction

Configuration

Changing TWS and RWS Ports

Appendix A

Ports Used by Business Interaction

Server

Introduction

Ports Used by Business Interaction Server

Index

C

D

F

K

L

M

P

R

S

T