KofaxReporting. Administrator's Guide

Transcription

1 KofaxReporting Administrator's Guide

2 2012 Kofax, Inc. All rights reserved. Use is subject to license terms. Third-party software is copyrighted and licensed from Kofax s suppliers. THIS SOFTWARE CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF KOFAX, INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF KOFAX, INC. Kofax, the Kofax logo, and the Kofax product names stated herein are trademarks or registered trademarks of Kofax, 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, 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. DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

3 Contents Legal Notice... 2 Preface... 5 Introduction...5 Related Documentation... 5 Help...5 Release Notes... 5 Overview... 7 Architecture... 7 HTTP Transport...7 Message Queue Transport... 8 Transport via Third-Party ESB...9 Central Site Components...11 System Requirements Hardware Requirements Supported Operating Systems Supported Software Supported Database Management Systems...14 Installation Installing Configuration Tool...15 Installing WSA...15 Command Line Installation Installing ETL Agent Installing Kofax License Utility Installing Database Scripts...18 Running MS SQL Database Installation Scripts...19 Running Oracle Database Installation Scripts Installing Integration SDK Network Load Balancing Installing Windows NLB...21 Restrictions...22 Licensing...23 Configuration...25 Configuring WSA...25 Configuring WSA Advanced Settings Configuring Central Site Kofax Reporting Administrator's Guide 3

4 Contents Configuring WSA Remotely...30 Configuring Advanced Settings of ETL Agent Configuring Kofax Applications...32 Configuring Microsoft Message Queuing...33 Configuring IBM WebSphere MQ...34 Configuring Central Site Configuring Application Site (with MQ Server)...34 Configuring Application Site (with MQ Client)...35 Configuring MQ Cluster Configuring ESB Operation and Maintenance...39 Monitoring WSA Managing Failed Messages Manually Deleting Messages...40 Reactivating Messages Deleting Old Data from Warehouse Database...41 Deleting Old Data from Staging Database Managing MS SQL Databases...42 Log Files...42 Managing Logs in WSA...42 Managing Logs in ETL Agent Kofax Reporting Administrator's Guide

5 Preface Introduction This guide contains essential information about installing and configuring Kofax Reporting. This guide assumes that you have a thorough understanding of Windows standards, applications, and interfaces. It also assumes that you have a thorough understanding of the Internet and your network configuration. This guide is for system administrators who are installing and configuring Kofax Reporting, or who need a description of the installation procedures, requirements, and configuration. Related Documentation In addition to this Kofax Reporting Administrator's Guide, the following documentation is available: Help Release notes Additional documentation is available as a part of the SDK. Refer to Installing Integration SDK. Help The online Help systems included in Kofax Reporting provide online assistance for system administrators and operators alike. You can access online Help from Kofax Reporting Configuration tool by clicking Help. Release Notes Late-breaking product information is available from release notes. You should read the release notes carefully, as they contain information that may not be included in other Kofax Reporting documentation. Kofax Reporting Administrator's Guide 5

6 Preface 6 Kofax Reporting Administrator's Guide

7 Chapter 1 Overview Kofax Reporting helps system administrators, business process managers, and other stakeholders gain visibility into and take control of Kofax-managed business processes. This product serves as the single conduit across many Kofax products, providing a centralized storage of historical operational metrics and audit data. In this release, the following Kofax products are supported: Kofax Capture Kofax Transformation Modules Kofax Front Office Server Architecture Kofax Reporting has a distributed architecture where one or more Kofax application sites deliver information to a central reporting site. Between sites, the information is transported in a message-based store and forward mode. Three possible transport mechanisms are supported. In all three scenarios, Kofax applications provide reporting data via API calls to the reporting integration API. This API uses web service calls to feed the data into a local transport entry point. In the central site, the ETL agent uses web service calls to read data from the central transport entry point. The data is then transformed and finally stored in the database. HTTP Transport The Kofax Reporting API (integrated in Kofax applications, such as Kofax Capture) communicates with the central site via a message based protocol implemented over web services. This diagram shows a distributed deployment, where two WSA (web service access) components are inserted between reporting data producers (Kofax applications on site A) and the data consumer (central reporting site). This scenario does not require any external transport mechanisms. Kofax Reporting Administrator's Guide 7

8 Overview Message Queue Transport In this scenario, the customer wants all messaging to go via IBM WebSphere MQ or MSMQ. WSA runs as a service on each computer with Kofax application. It could also run on a standalone server. The Kofax Reporting API sends the reporting data to WSA using the same web service interface as in the HTTP transport scenario; WSA handles the translation to IBM WebSphere MQ or MSMQ. The WSA server at the central reporting site receives information from the message queue and stores it locally. The ETL agent then pulls data from the WSA storage. 8 Kofax Reporting Administrator's Guide

9 Overview Transport via Third-Party ESB In this scenario, the customer already has an enterprise service bus (ESB), such as Sonic. They implement the Kofax Reporting web service interface on their ESB by simply importing the Reporting WSDL into the ESB integration tool. The ESB will take care of the communication. The client DLL talks directly to the local ESB server on the Kofax applications site. At the central site, the ETL agent pulls information from the central ESB server. Kofax Reporting Administrator's Guide 9

10 Overview Central Site This diagram details the Kofax Reporting core components in the central site. The ETL agent continuously pulls information from the central transport entry point and stores it into the staging database. At configurable intervals, the agent takes all available information from the staging tables and populates the data warehouse. Data consumers like BI applications or third party reporting tools access only the data warehouse tables. 10 Kofax Reporting Administrator's Guide

11 Overview Components This section describes various parts of Kofax Reporting environment. Kofax Reporting API Kofax application like Kofax Capture use the API to forward information about batch processing events and administrator actions to the reporting platform. WSA Sender (application site) This component runs either on the same computer as the Kofax application or on another computer in the same site. It acts as a web server and receives web service calls from the API, containing data from the Kofax applications. The received data is stored in local temporary storage and later delivered to central site via a configured transport. ESB (application site) As an alternative to WSA, customers can use third-party ESB. Local ESB receives information from the API and delivers it to central site. Kofax Reporting Administrator's Guide 11

12 Overview IBM WebSphere MQ or MSMQ Customers can use message queues as the transport mechanism between sites. Alternatively, they can rely on HTTP transport, or ESB transport. WSA Receiver (central site) This component runs in the central site as a Windows service, on one or more computers. WSA receiver takes data from local WSA and stores it, until ETL agent picks it up. ESB (central site) This component receives data from remote ESB and makes it available for the ETL agent. ETL Agent The ETL agent (extract/transform/load) runs in the central site. It retrieves Kofax application data from the central WSA or central ESB and stores it in the staging database. In off-peak times, ETL agent transforms the data from the staging database and stores it into data warehouse. Staging Database This central database (SQL Server or Oracle) temporarily stores the reporting data from Kofax applications. Data Warehouse Reporting data are permanently stored in the data warehouse. 12 Kofax Reporting Administrator's Guide

13 Chapter 2 System Requirements Before installing and operating Kofax Reporting, please carefully read the following requirements. Hardware Requirements Kofax Reporting ETL Agent requires at least 1 GB of free RAM. Supported Operating Systems Kofax Reporting client software is supported on the following operating systems (both 32 and 64 bit): Windows XP (32-bit only) Windows Vista Windows 7 Windows Server 2003 Windows Server 2008 Windows Server 2008 R2 Kofax Reporting server software is supported on the following operating systems (both 32 and 64 bit): Windows Server 2003 (32-bit only) Windows Server 2008 Windows Server 2008 R2 Supported Software Kofax Reporting is compatible with the following Kofax products: Kofax Capture Kofax Transformation Modules Kofax Front Office Server Kofax Reporting can be used with Microsoft Message Queuing (MSMQ) or IBM WebSphere MQ. Microsoft.NET Framework 3.5 Service Pack 1 is required for Kofax Reporting Configuration Tool, ETL Agent, and Kofax License Utility. Kofax Reporting Administrator's Guide 13

14 System Requirements Note Third-party software requires appropriate license. Customers must provide their own licenses, as these are not included in the Kofax Reporting license. Supported Database Management Systems Kofax Reporting supports the following database systems: Oracle 11 RDBMS on Windows, Linux, Unix (with real application clusters) Microsoft SQL Server 2008 R2 or 2012 (with failover clustering) Express editions of the databases can be used for testing. 14 Kofax Reporting Administrator's Guide

15 Chapter 3 Installation This chapter contains information and instructions for installing Kofax Reporting. The following components belong to the central site: Kofax Reporting - Configuration ETL Agent Kofax License Utility Databases WSA Receiver (when using IBM MQ/MSMQ/HTTP transport) ESB (when using ESB transport) The following components belong to the application site: WSA Sender (when using MQ/MSMQ/HTTP transport) ESB (when using ESB transport) The setup also includes the integration SDK. This component provides sample code and documentation how to integrate Kofax Reporting with ESB transport, and information about Kofax Reporting views and tables. Installing Configuration Tool Kofax Reporting - Configuration tool must be installed in the central site. 1 Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. 2 Click Install Configuration tool. The setup wizard is displayed. 3 Follow the setup wizard, using default options. Click Install. 4 Wait until the configuration tool is installed. Click Finish. Installing WSA WSA stands for web service architecture and it is one of options for communication between application sites and the central reporting site. The other option is ESB. This component must be installed both in the central site (WSA receiver) and the application site (WSA sender). In the application site, WSA can be either a dedicated computer or directly Kofax Reporting Administrator's Guide 15

16 Installation on the computer with Kofax applications. In the central site, WSA can be installed either on a dedicated computer or on the same computer as the ETL agent. 1 Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. 2 WSA must be installed in both the central (server) site and the application (client) site. Do one of the following: If you are installing WSA in the central site, click Install WSA Receiver. Multiple instances of WSA receiver are supported on one computer. Click one of the instances to start the setup wizard. If you are installing WSA in the application site, click Install WSA Sender. Multiple instances of WSA sender are supported on one computer. Click one of the instances to start the setup wizard. For tests and demonstrations, it is possible to install both sender and receiver WSA on the same computer. 3 Specify the destination folder. Click Next. 4 If you selected to install WSA Receiver, you have the option to configure it: Tip You can keep the default values while installing and configure WSA later. Refer to Configuring WSA. Specify the Service name. Usually there is little reason to modify the default. Select the Transport mode: HTTP, MSMQ, IBM WebSphere MQ. Use the default value for Local server name. Specify the Local port. 5 If you selected to install WSA Sender, you have the option to configure it: Tip You can keep the default values while installing and configure WSA later. Refer to Configuring WSA. Specify the Service name. Usually there is little reason to modify the default. Select the Transport mode: HTTP, MSMQ, IBM WebSphere MQ. Specify the Local server name, i.e. name of the local server, as it is known to the client applications. Specify the Local port. Specify the Central URL (URL of the WSA Receiver in the central site). Specify the "Client config. file" (path and file name). WSA Sender saves the URL of its web service interface to this configuration file. Kofax applications read this file and use it for connecting to the web service interface. E.g., Kofax Capture expects this configuration file in one of these folders: C:\ProgramData\Kofax\Capture\Config\Reporting.Client.Configuration.xml (Windows Vista, 7, Windows Server 2008) C:\Documents and Settings\All Users\Application Data\Kofax\Capture\Config \Reporting.Client.Configuration.xml (Windows XP, Windows Server 2003) 16 Kofax Reporting Administrator's Guide

17 Installation 6 Click Next, then click Install. 7 Click Unblock if a firewall warning appears. 8 Wait until Kofax Reporting - WSA is installed. Click Finish. Note If you install WSA on a Windows Vista or Windows 7 computer, make sure that the computer does not enter sleep mode (on these operating systems, it is enabled by default). Change it via Power Options. Command Line Installation Alternatively, you can install WSA via command line, e.g.: Installation without showing user interface with default values msiexec.exe /i D:\WSASender\Kofax.Reporting.WSA.Sender.msi /quiet Installation without user interface modifying some values: msiexec.exe /i D:\WSASender\Kofax.Reporting.WSA.Sender.msi INSTALLDIR= C: \WSA\WSA-Sender TRANSPORT_MODE=3 SERVICE_NAME= Kofax WSA Sender /quiet Use the following switches and parameters to control the installation: To modify the installation directory, use the parameter INSTALLDIR, e.g.: INSTALLDIR= %ProgramFiles%/Kofax/Reporting/WSA-Sender To modify the name of the Windows service used by WSA, use the parameter SERVICE_NAME, e.g. SERVICE_NAME="Kofax Reporting WSA Sender" To modify the transport mode, use TRANSPORT_MODE, e.g.: TRANSPORT_MODE=1. Supported values are: 1: HTTP 2: MSMQ 3: IBM MQ To modify the name of the local server, use e.g. LOCAL_SERVER_NAME="localhost" To modify local port of the web service interface, use e.g. LOCAL_PORT="25480" To specify the central queue for MSMQ, use e.g. CENTRAL_QUEUE_MSMQ="DIRECT=OS:.\private$\reporting" To specify the central queue for IBM MQ, use e.g. CENTRAL_QUEUE_IBMMQ="REPORTING.QUEUE.MANAGER:2REPORTING.QUEUE" To specify the URL of the receiver WSA in the central site, use e.g. CENTRAL_URL=" Use the "/quiet" switch to suppress installer user interface. Installing ETL Agent Kofax Reporting ETL agent must be installed in the central site. 1 Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. Kofax Reporting Administrator's Guide 17

18 Installation 2 Click Install ETL Agent. 3 Multiple instances of ETL agent can be installed on a single computer. Click the instance you want to install to start the setup wizard. 4 Optionally, modify the service name and the destination folder. Click Next, then click Install. 5 Wait until ETL Agent is installed. Click Finish. If you want to run ETL Agent under a different Windows user, the following user rights are required: "Log on as a service" Member of "performance log user" (needed if debugging is enabled in ETL agent trace configuration) Installing the ETL Agent as a Windows cluster resource is not supported. Installing Kofax License Utility Kofax License Utility must be installed in the central site along with the ETL Agent. 1 Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. 2 Click Install ETL Agent. 3 Click Install License Utility. 4 Optionally, modify the destination folder. Click Next, then click Install. 5 Wait until Kofax License Utility is installed. Click Finish. Installing Database Scripts Kofax Reporting database scripts can be installed on any computer. They are required for installing databases in the central site. 1 Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. 2 Click Install Scripts for manual database installation. The setup wizard is displayed. 3 Follow the setup wizard, using default options. Click Install. 4 Wait until the database scripts are installed. Click Finish. The scripts for manual database installation are now available in the <programs>\kofax \Reporting\Database Scripts folder: kofax_analytics.sql - MS SQL script for data warehouse kofax_analytics_staging.sql - MS SQL script for staging database kofax_analytics_oracle.sql - Oracle script for data warehouse kofax_analytics_staging_oracle.sql - Oracle script for staging database. A brief description of how to use this scripts is available in the beginning of each file. 18 Kofax Reporting Administrator's Guide

19 Installation Running MS SQL Database Installation Scripts This section assumes that a compatible database server has been already installed. You need to perform these steps twice: once for the staging database, once for the data warehouse. 1 Stop ETL agent. 2 Log on to the Microsoft SQL Server Management Studio as the database administrator. 3 Create the database. 4 Run the script to create database objects: kofax_analytics_staging.sql (staging database) kofax_analytics.sql (data warehouse). 5 Create an SQL Server user for the ETL agent. Alternatively, use two users, one for each database. Assign the following role(s) to the user(s): kfx_staging (for staging database) kfx_etl, kfx_reader, kfx_advanced_reader (for data warehouse). 6 Start ETL agent. Running Oracle Database Installation Scripts This section assumes that a compatible database server has been already installed. You need to perform these steps twice: once for the staging database, once for the data warehouse. 1 Stop ETL agent. 2 Log on to a database management tool, such as Oracle SQL Developer, as the sys user (role SYSDBA). 3 Create a user, e.g. StagingUser or DwhUser. 4 Assign tablespace quota to this user, or grant it unlimited tablespace privilege. 5 Grant required privileges user created in step 2: GRANT CREATE TYPE, CREATE ANY INDEX, DROP ANY INDEX, CREATE SESSION, CREATE PROCEDURE, CREATE VIEW, ALTER SESSION, CREATE SEQUENCE, CREATE TABLE, CREATE TRIGGER, CREATE ROLE, GRANT ANY OBJECT PRIVILEGE, GRANT ANY PRIVILEGE TO <user_name>; 6 Optionally, edit the script and uncomment the first paragraph to be prompted for username and password. kofax_analytics_oracle_staging.sql (staging database) kofax_analytics_oracle.sql (data warehouse). 7 Run the script to create database objects. Sample sqlplus command: sqlplus 8 Revoke the system privileges granted in step 4: REVOKE CREATE TYPE, CREATE ANY INDEX, DROP ANY INDEX, CREATE SESSION, CREATE PROCEDURE, CREATE VIEW, ALTER SESSION, CREATE SEQUENCE, CREATE TABLE, CREATE TRIGGER, CREATE ROLE, GRANT ANY OBJECT PRIVILEGE, GRANT ANY PRIVILEGE FROM <user_name>; Kofax Reporting Administrator's Guide 19

20 Installation 9 Assign the following database role(s) to the user: kfx_staging (for staging database) kfx_etl, kfx_reader, kfx_advanced_reader (for data warehouse). 10 Start ETL agent. Installing Integration SDK The Kofax Reporting integration software development kit includes the following: Documentation for Kofax Reporting views and tables. Documentation and sample code for integration with Sonic ESB Start setup.exe from the Kofax Reporting installation ISO. Setup splash screen is displayed. 2 Click Install SDK. The setup wizard is displayed. 3 Follow the setup wizard, using default options. Click Install. 4 Wait until the integration SDK is installed. Click Finish. The SDK includes: KofaxReportingTables.docx - database table description KofaxReportingViews.docx - database view description IntegrationWithSonicESB_8.docx - describes sample integration with Sonic ESB 8 ESB8_Scripts.zip - sample code for ESB integration Network Load Balancing Network load balancing is the ability to distribute load to multiple computers. In Kofax Reporting, WSA Receivers can run in a load balancing scenario. The NLB concept by itself provides failover only for the case when an NLB node in the cluster is completely shut down: NLB directs all TCP-based traffic automatically only to the working NLB nodes. However, NLB does not provide a failover solution for the case when a node is running but the TCP-based services on the node (in our case web service listeners) have problems, or if the service is stopped. Therefore, WSA includes a feature called NLB Port Control that monitors the health of its processes. In case of problems, the port control makes the node unavailable. NLB is used to divide load to two or more computers. All computers run in parallel. 20 Kofax Reporting Administrator's Guide

21 Installation Configuration hints: In the WSA Sender, configure the NLB IP address and port in the Central URL field. Refer to Configuring WSA. If you are using remote configuration of WSA Receiver from the Kofax Reporting Configuration tool, do not use the NLB port! You must configure each WSA Receiver node individually. Refer to Configuring WSA Remotely. Installing Windows NLB 1 Install Windows NLB on each WSA Receiver node. On Windows Server 2008, NLB has to be installed as an additional feature of the operating system. a Start Server Manager. b Select Features. c Click Add Features d Select Network Load Balancing. e Click Next, then click Install. On Windows Server 2003, NLB has to be installed as an additional service in the Local Area Network Properties. a Start Windows Control Panel. b Go to Network Connections. c Right-click Local Area Network and select Properties. d Click Install. e Select Service and click Add. f Select Network Load Balancing and click OK. g Activate Network Load Balancing and click Close. 2 Configure a fixed IP address on each node. 3 The recommended method to create an NLB cluster is using the Windows Network Load Balancing Manager. Run "nlbmgr". 4 Create a new cluster: a Right-click Network Load Balancing Cluster and select New Cluster. Kofax Reporting Administrator's Guide 21

22 Installation Restrictions b Specify an IP address of one of the cluster hosts and click Connect. Select an interface and click Next. c It is recommended to change the Default state to Suspended and to select "Retain suspended state after computer restarts". Message Connector updates the state after startup. Click Next. d Click Add and specify the cluster IP address. Click OK, then click Next. e In the Full Internet name field, enter the name of the cluster computer. f Select Multicast (unless you have at least 2 network adapters on each node). Click Next. g Click Add to add port rules for web service input (default for receiver instance 1). Select Multiple host as a Filtering mode and set Affinity to None. h Click Finish. 5 Add additional cluster nodes: a Right-click the cluster and select Add Host. b Specify an IP address of the node and click Connect. Select an interface and click Next. c Click Next and Finish. The NLB port control still leaves some short unavailability time window (usually 1 to 8 seconds) when the failover is not provided and a web service connection to the common NLB IP address fails. This occurs (always) in the following situations: Unavailability time window when WSA node stops abruptly: In this case it is the NLB (and not the port control) that handles this situation. NLB requires ~5 seconds to detect a failed node. NLB requires 2 to 3 seconds to remove the failed node and redistribute its load to the live nodes. Unavailability time window when a node starts. Some seconds elapse between when the NLB service starts (with enabled ports - depends on cluster host configuration) and when the WSA with port control starts. You can eliminate most of this delay by properly configuring the cluster: refer to Installing Windows NLB, step 4c. Unavailability time window at WSA process crash. Some (1 3) seconds elapse until the WSA port control detects the crash and the disables the ports for NLB. Nevertheless, if the web service client supports retries, the second attempt will presumably be outside of this time window and the connection request will be directed to a working node. 22 Kofax Reporting Administrator's Guide

23 Chapter 4 Licensing A Kofax Reporting system license is required for operation. The license is checked in the ETL Agent. Kofax Reporting Administrator's Guide 23

24 Licensing 24 Kofax Reporting Administrator's Guide

25 Chapter 5 Configuration This chapter lists the most common tasks necessary to configure Kofax Reporting. A general overall procedure for deploying the product is shown below. This procedure assumes that all components are installed (refer to Installation) and licensed. 1 In the central site, create a new configuration and save it to the default location. Connect ETL Agent with databases and transport end point (WSA Receiver/ESB). Configure ETL Agent operation. Refer to Configuring Central Site. 2 In the application site, enable reporting within the application (if needed) and configure the path to the transport entry point (WSA Sender/ESB). Refer to Configuring Kofax Applications. 3 Configure the transport mechanism. Do one of the following: If you are using HTTP transport (default option), edit WSA Sender configuration and in the Central URL field (General tab) specify the URL of the WSA Receiver. Refer to Configuring WSA. If you are using ESB, refer to Configuring ESB. If you are using IBM MQ or MS MQ: Edit WSA Sender configuration. Click Advanced. In the General Settings tab, configure the fields Transport, Central Queue, MQ User, and MQ Password. In the MQ tab, configure dead letter queue options. For more information about advanced WSA settings related to MQ, refer to Configuring WSA Advanced Settings. For tips about configuring the MQ part, refer to Configuring IBM WebSphere MQ and Configuring Microsoft Message Queuing. Configuring WSA 1 Start WSA Receiver Configuration or WSA Sender Configuration from the Kofax Reporting group in the Windows Start menu. 2 Go to the General Settings tab. a In the Position field, you can modify the role of this WSA instance: Use Receiver role in the central site or Sender in the application site. Generally, modifying this field is not recommended - install proper WSA instead. Kofax Reporting Administrator's Guide 25

26 Configuration b In the Transport field, select how sender and receiver WSA instances should communicate. The available options are HTTP, MSMQ, and IBM WebSphere MQ. The setting on the sender and receiver must match. c In the Central URL field, specify the URL of the receiver WSA in the central site. If WSA receiver is installed in a network load balancing mode, specify the NLB port. This field is only available for sender WSA (application site). When you are using WSA Receivers running in a network load balancing configuration, use the NLB IP address and port. Note Do not enter the URL of the sender WSA into this field. Messages will be sent in a loop. d In the Central Queue field, specify the queue to use. This field is only available if you did not use HTTP as the transport option. E.g.: IBM MQSeries: "REPORTING.CLIENT.QUEUE.MANAGER:REPORTING.REMOTE.QUEUE" MSMQ: "DIRECT=TCP: \MyQueue" 3 Go to the HTTP Settings tab. a In the Local Port field, specify the port of the local web server. The default is for application sites and for central site. You might need to modify this value in case of port conflicts. b In the Local IP Address field, optionally specify the IP address of the local interface used for web portal. The web portal offers monitoring functions, mostly for troubleshooting. c In the Local server name field: For WSA Receiver, this parameter is not used. For WSA Sender, specify the name of the local server, as it is known to the client applications. E.g., if client computers know the server under a different name, specify that name here. d Select the SSL Active field to enable secure communication. 4 If you enabled SSL, fill in the configuration fields in the SSL Certificate tab. 5 Click Advanced to display advanced parameters. Configuring advanced parameters is necessary e.g. in these cases: Message queue transport Troubleshooting, configuring traces Password protection of WSA Load balancing configuration of WSA Receiver WSA storage management Performance tuning Refer to Configuring WSA Advanced Settings. 6 Click Save. Click Exit and restart service. 26 Kofax Reporting Administrator's Guide

27 Configuration Configuring WSA Advanced Settings The advanced settings of WSA are not needed for many Kofax Reporting installations. You must use them to configure message queue transport and for troubleshooting (traces). 1 Start WSA Receiver Configuration or WSA Sender Configuration from the Kofax Reporting group in the Windows Start menu. 2 Click Advanced. 3 Go to the General Settings tab. a In the MQ User field, type Domain\UserId or SID for queue access. This Windows user must have the user right "logon as service". b In the MQ Password field, type the password of the user set above. c In the Storage Size field, type how much disk space should WSA reserve for storing messages. d In the Storage File field, type the name and location of the storage file. e The Instance Name field displays name of the WSA instance. f In the Senders (up to 10) field, type the number of parallel processes responsible for sending data to WSA receiver (only applies to WSA Sender). Using a higher value increases performance, but it requires more system resources. 4 Go to the HTTP Settings tab. a In the Listener Threads field, specify the maximum number of concurrent web service/http connections to this WSA instance. b In the Proxy server field, specify the name or IP address of the central proxy server. Configuring a proxy server is only available for WSA Sender instances. c In the Proxy port field, specify the port of the proxy server. 5 Go to the Trace tab. For more information, refer to Managing Logs in WSA. a In the Trace Level field, specify the trace level (0..100). Higher value provides more detailed traces but might affect performance. b In the Message Trace Size field, specify the message size limit to trace traffic between components: 0 = off 1 = single line per message More than 1 = size limit in bytes c In the Size of Trace File field, specify the maximum size of trace files in KB d In the Number of Trace Files field, specify the maximum number of generated trace files. When all files are full, the oldest is overwritten. e Select Append Trace if you want to append trace to existing trace file after restarting the application. 6 Go to the MQ tab. The parameters are only available for message queue transport. a Select Check Dead Letter Queue if you want monitor messages that could not be delivered. b In the Dead Letter Queue Check Interval field, specify in seconds how often should the dead letter queue be examined. c In the Dead Letter Queue Retries field, specify how many retries should be made for messages in the dead letter queue. Kofax Reporting Administrator's Guide 27

28 Configuration d Select RejectMsgOnMqError if you want to reject message when the message queue cannot be written. 7 Go to the Store tab. a In the Object Fill Target field, specify a value in percent of object fill target for storage cleanup. b In the Disk Fill Target field, specify a value in percent of disk fill target for storage cleanup. c In the OutboxReactivate field, specify the number of minutes to wait until unsuccessfully retrieved messages from the outbound folder of WSA Receiver storage are reactivated so that the ETL agent can reattempt to retrieve them. This parameter is only available for WSA Receiver. Setting this parameter to zero means that failed messages are never reactivated. They can still be activated by an operator; refer to Managing Failed Messages Manually. 8 Go to the Security options tab. a In the Users field, select "admin" if you want to restrict access to WSA monitor and remote configuration. Select "no password protection" if you don't want to restrict access. b In the Admin password field, type the password for the admin user. c Select DisableRemoteConfig if you want to disable remote configuration of a particular WSA completely. 9 Go to the Load Balancing Settings tab. a In the Load Balancer Support field, select what type of load balancer are you using. Network load balancing is only available for WSA receiver. Select None to disable NLB Port Control feature of Kofax Reporting. This does not disable network load balancing if you have configured it. Select Win-NLB and Ext-LB to enable port control. Select Windows NLB if you are using Windows NLB solution. Select External LB if you are using an external load balancer. b In the Load Balancer Port field, type the port that web service clients can use to access load-balanced WSA receivers. c In the Load Balancing IP Address field, type the IP address of the local interface used for web service access (if you have multiple network cards on your computer, you can dedicate one for this purpose). 10 Go to the Advanced tab. a In the Client Config File field, specify the path and file name where WSA Sender should save its connection information. This file is used by Kofax applications for connecting to Kofax Reporting. Only available for WSA Sender. E.g., Kofax Capture might use the following path and name: C:\ProgramData\Kofax\Capture\Config\Reporting.Client.Configuration.xml (Windows Vista, 7, Windows Server 2008) C:\Documents and Settings\All Users\Application Data\Kofax\Capture\Config \Reporting.Client.Configuration.xml (Windows XP, Windows Server 2003) 11 Click Save. Click Exit and restart service. 28 Kofax Reporting Administrator's Guide

29 Configuration Configuring Central Site The Kofax Reporting Configuration tool can be used to configure the ETL agent and connect to the databases. It is recommended that the databases are properly set up in advance; refer to Installing Database Scripts. You can also use it for remote configuration of any WSA instances. 1 Start Configuration from the Kofax Reporting group in the Windows Start menu. 2 Do one of the following: Open an existing configuration or create a new one. To create a new configuration: a Click New on the Home tab. b Type a descriptive name of the new configuration. c If the ETL Agent is installed on the same computer, the Location field is automatically populated. By default, this is C:\Documents and Settings\All Users\Application Data\Kofax\Reporting \KofaxReportingETLAgent\Config (Windows Server 2003) C:\ProgramData\Kofax\Reporting\KofaxReportingETLAgent\Config (Windows Server 2008) Alternatively, you can type the path where the configuration should be stored, or click the... button and navigate to the any folder. However, to make a configuration active, it must be in the designated folder. To open an existing configuration: a Click Open on the Home tab. b Navigate to the folder where configuration is stored, select it, and click OK. 3 Click Staging database in the Kofax Reporting pane to display its settings. 4 In the Server Type field, select either Oracle or MS SQL Server. If you selected MS SQL Server: a Click Load SQL Servers on the Database tab to search for all Microsoft SQL Server instances on the network. You may skip this step if you want to type the connection information manually. b In the Server field, select one of the instances or type its name (servername \instancename). c In the Port field, type the port for connecting to the database. d Select Use SQL Server User if you want to access the database with a specific account. If you don't specify an account, the user under which the ETL Agent service is running is used for connecting to the database. e Click Get List of Databases and select one of them in the Database Name field. Alternatively, type the database name directly. f Click Test Connection to verify that ETL Agent can connect to the database. If you selected Oracle: a In the Server field, type the name of the server where the database is running. b In the Port field, type the port for connecting to the database. c In the Connection Type field, select if you want to use Basic connection (through the Oracle Call Interface) or TNS (using an alias entry from a tnsnames.ora file). d In the User Name and Password, specify the credentials for connecting to the database. Kofax Reporting Administrator's Guide 29

30 Configuration e In the Service Name field, type the global database name in the format database_name.database_domain. f In the Target Schema field, type the schema to use. g Click Test Connection to verify that ETL Agent can connect to the database 5 Click Warehouse database in the Kofax Reporting pane and configure its settings (similar to step 4). Optionally, click Copy Configuration to copy the settings from the Staging database pane. 6 Click ETL Settings in the Kofax Reporting pane to display configuration of the ETL agent. a In the "Run daily from" and "To" fields, you can restrict the time when ETL agent analyzes data from the staging database, transforms it, and stores it to the data warehouse. b in the "Wait time between jobs (minutes)" field, specify how long should ETL agent wait before starting another round of data transfer from staging to warehouse database. The default value is 60 minutes. c in the "Purge interval for field detail data (days)" field, specify how many days should ETL agent wait before deleting field detail data (table field_accum_fact) from the data warehouse. The default is 5 days. d In the URL field, type the URL for WSA Receiver or ESB in the central site. The ETL Agent polls them for reporting data. You can add multiple entries. 7 Click Workstations in the Kofax Reporting pane to display the list of client computer that have sent information to this ETL agent. 8 Click Save on the Home tab to save the configuration. Configuring WSA Remotely The Kofax Reporting - Configuration tool can be used for remote configuration of WSA. Only a subset of parameters can be configured remotely. To access all parameters, refer to Configuring WSA. 1 Start Configuration from the Kofax Reporting group in the Windows Start menu. 2 Click Configure WSA Server in the Kofax Reporting pane. 3 In the URL field, type the URL to a WSA instance, e.g. Click Connect. If you are using NLB, specify the port of an instance, not the NLB port. 4 If WSA password protection is enabled, log on using the user name "admin" and a password. 5 Edit the settings as necessary. Click Advanced to display additional parameters. Refer to the online help for more information about the parameters. 6 Click Save on the WSA Server tab to confirm the changes and restart the WSA instance. Configuring Advanced Settings of ETL Agent The ETL Agent has an internal configuration file that generally does not need modification. These advanced parameters can be used to finetune performance and for troubleshooting. The configuration is located in the ETL Agent program files directory, by default: %Program Files%\Kofax\Reporting\ETLAgent\Kofax.Reporting.ETLAgent.exe.config 1 Edit the file with a text editor. 30 Kofax Reporting Administrator's Guide

31 Configuration 2 Restart the ETL Agent service to make the changes effective. Parameter PurgeFieldDataBatchSize DatabaseCmdTimeoutSec MQ2StagingServiceEnabled ETLServiceEnabled ETLBatchSize WSABatchSize Description Deleting large data from indexed tables can be expensive, therefore the ETL Agent deletes data in batches of a given size. The parameter determines how many rows are deleted in a single transaction when purging old field data. The ETL Agent will continue to run transactions that delete the given number of records until all data has been deleted. The default value should fit most of the databases. Default = The timeout controls how many seconds is a SQL command allowed to take. The default value should fit most of the databases. Default = 600 Setting this to False disables pulling of data from WSA and saving into the staging database. It might be used for debugging and tracking down issues. Default = True Setting this to False disables processing data from the staging database into the warehouse. It might be used for debugging and tracking down issues. Default = True The number of messages that are processed at a time when processing data from staging database to the warehouse. The default value should fit most of the cases. However, if batches contain a very large average number of pages (e.g. a batch in average contains 100 documents and each document 100 pages), then it might be appropriate to decrease this value. Default = The number of messages that are processed at a time when processing data from WSA database to the staging database. The default value should fit most of the cases. However, if batches contain a very large average number of pages (e.g. a batch in average contains 100 documents and each document 100 pages), then it might be appropriate to decrease this value. Default = Kofax Reporting Administrator's Guide 31

32 Configuration Parameter DeleteStagingDataBatchSize MaxMQ2StagingIterationsNum DeleteStagingDataOlderThanDays DropIndexesOnMq2Staging Description Deleting large data from indexed tables can be expensive, therefore the ETL Agent deletes data in batches of a given size. The parameter determines how many rows will be deleted in a single transaction when deleting processed staging data. The ETL Agent will continue to run transactions that delete the given number of records until all data has been deleted. The default value should fit most of the databases. Default = Determines how many times will the WSA to staging database process run, until it is checked if it is time to run an ETL job. Default = 10 Determines how many days is the staging data allowed to stay in the database before it is deleted. By default the data is deleted immediately after it's been processed. Changing the value might help in some debugging cases to trace down eventual problems. Default = -1 If this is set to True, the ETL Agent will drop the indexes in the staging database when loading data into it and then recreate them for extracting data before an ETL job. True is the default option that will typically give better performance and should not be changed. Default = True Configuring Kofax Applications The support for Kofax Reporting must be enabled in Kofax applications (e.g. Kofax Capture). 1 Install a compatible version of Kofax application. Refer to Kofax Reporting Release Notes for latest information about supported versions. 2 Enable reporting in the Kofax application if necessary. Refer to the documentation of the specific product for instructions. 3 Kofax applications must know the URL to transport entry point (WSA Sender or ESB) in order to start sending reporting data. Kofax applications read the URL from a special configuration file, Reporting.Client.Configuration.xml. WSA Sender can write its URL to the file during installation (refer to Installing WSA) or during configuration (refer to Configuring WSA Advanced Settings, Advanced tab). Alternatively, you can manually edit the file with a text editor and type the URL. 32 Kofax Reporting Administrator's Guide

33 Configuration Configuring Microsoft Message Queuing Microsoft Message Queuing (MSMQ) is one of the possible transport options between application and central site. 1 On the central site, create a new queue. You must use transactional queues for Kofax Reporting. Authentication and privacy level are not supported. 2 On the central site, install the Message Queuing Server and WSA Receiver. WSA Receiver on the central site reads always and only from a local transactional MSMQ queue. 3 On the application site, install the Message Queuing Server and WSA Sender. WSA Sender on the application site sends messages to a remote transactional queue that is located on the central site. 4 Configure WSA, both Sender and Receiver. a In the General Settings tab, set Transport to MSMQ, configure MQ User/Password, and set Central Queue to the queue created in step 1. E.g.: DIRECT=OS:.\private$\PrivateQueueName DIRECT=OS:Computer_Name\PublicQueueName DIRECT=OS:Computer_Name\private$\PrivateQueueName DIRECT=TCP:IP_Address\PublicQueueName DIRECT=TCP:IP_Address\private$\PrivateQueueName DIRECT= DIRECT= DIRECT= DIRECT= b In the MQ tab of WSA Sender, you can enable support for dead letter queue. If you want to use HTTP/HTTPS, Internet Information Services (IIS) has to be installed and configured on the WSA Receiver computer. Refer to MSMQ documentation. The HTTP/ HTTPS protocol is only supported for sending messages to MSMQ, i.e. on the application site. It is not supported for receiving messages from MSMQ on the central site. Messages sent from WSA Sender to a remote transactional queue are first stored in a local outgoing queue (created automatically). MSMQ automatically transfers the messages to the destination remote queue. Messages that cannot be delivered to the destination queue are automatically moved by MSMQ to the local MSMQ system transactional dead letter queue (DEADXACT) on the WSA Sender computer and a property CLASS is set which contains the reason of failure (e.g. remote queue does not exist, remote server not reachable...). The WSA Sender service has a built-in mechanism that checks periodically in background the DEADXACT queue at the sending side and a retry mechanism that takes the messages from the DEADXACT queue and requeues them into the outgoing queue again. Kofax Reporting Administrator's Guide 33

34 Configuration Configuring IBM WebSphere MQ It is recommended to use a dedicated Queue Manager for Kofax Reporting. It is possible reuse an existing Queue Manager, however, if the WSA is configured for "Check Dead Letter Queue", it will take all messages from the dead letter queue (including possibly messages that do not belong to Kofax Reporting). 1 Configure the central site. Refer to Configuring Central Site. 2 Do one of the following: If you install MQ Server on the application site, proceed with Configuring Application Site (with MQ Server). If you install MQ Client on the application site, proceed with Configuring Application Site (with MQ Client). Configuring Central Site 1 On the central site, install MQ Server and WSA Receiver. 2 In the MQ Server: a Create a queue manager, e.g. REPORTING.QUEUE.MANAGER. Enable Create server-connection channel. Create a listener configured for TCP/IP. Specify the names of the local queue and local dead letter queue (you create these queues in steps b and c). b Create a local queue, e.g. 2REPORTING.QUEUE. Set the "Default persistence" to "Persistent". c Create a local dead letter queue, e.g. REPORTINGDEADLETTER.QUEUE using the SYSTEM.DEAD.LETTER.QUEUE template. Set the "Default persistence" to "Persistent". If you don't want WSA to check dead letter queue, you can keep queue manager's dead letter queue configuration as it is. d Create a receiver channel, e.g. SEND_REC_CHANNEL. 3 In the WSA Receiver: a In the General Settings tab, set Transport to IBM WebSphere MQ, configure MQ User/Password and set Central Queue to REPORTING.QUEUE.MANAGER:2REPORTING.QUEUE. b In the MQ tab, you can enable checking of dead letter queue and decide how often the queue should be checked. Configuring Application Site (with MQ Server) 1 On the application site, install MQ Server and WSA Sender. 2 In the MQ Server: a Create a queue manager, e.g. "REPORTING.CLIENT.QUEUE.MANAGER" with its local and dead letter queue. b Optionally, for convenience, you can add a remote queue manager, e.g. REPORTING.CLIENT.QUEUE.MANAGER and connect to MQ Server in the central site. You can now manage the server on the application site from the central site. c Create a local transmission queue, e.g. REPORTING.TRANSMISSION.QUEUE. Set the Default persistence to Persistent and Usage to Transmission. 34 Kofax Reporting Administrator's Guide