Kofax�Reporting 1.0.
© 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.
Contents Legal Notice .......................................................................................................................................................................... 2 Preface .................................................................................................................................................................................... 5 Introduction .................................................................................................................
Contents Configuring WSA Remotely ...................................................................................................................................30 Configuring Advanced Settings of ETL Agent ................................................................................................... 30 Configuring Kofax Applications .................................................................................................................................
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.
Preface 6 Kofax Reporting Administrator's Guide
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.
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.
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.
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.
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.
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.
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.
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.
Chapter 3 Installation This chapter contains information and instructions for installing Kofax Reporting.
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.
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 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.
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).
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 8.0. 1 Start setup.exe from the Kofax Reporting installation ISO.
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.
Installation 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.
Chapter 4 Licensing A Kofax Reporting system license is required for operation. The license is checked in the ETL Agent.
Licensing 24 Kofax Reporting Administrator's Guide
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.
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).
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.
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.
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.
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.
Configuration 2 Restart the ETL Agent service to make the changes effective. Parameter Description PurgeFieldDataBatchSize 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.
Configuration Parameter Description DeleteStagingDataBatchSize 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.
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.
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.
Configuration d Create a remote queue definition, e.g. REPORTING.REMOTE.QUEUE using the SYSTEM.DEFAULT.REMOTE.QUEUE template. Set the Default persistence to Persistent. As remote queue, use the local queue of the central MQ Server. As queue manager, use the reporting queue manager of the central MQ Server. As transmission queue, use the previously created transmission queue. e Create a sender channel, e.g. SEND_REC_CHANNEL (same name as the receiver channel in the central site).
Configuration 2 On the second computer, create two queue managers, each with two local queues. 3 Optionally, for convenience, add all queue managers to a single MQ Explorer. 4 Create a queue manager cluster (named e.g. REPORTINGCLUSTER). Add all queue managers to the cluster. 5 On queue managers 2 and 3, create a cluster queue (named e.g. REPORTING.CLUSTER.QUEUE) and set it to be shared in cluster REPORTINGCLUSTER. It is recommended to set the default bind type to Not fixed.
Configuration On the central site, the following web services must be implemented: ▪ ReceiveMessages2 - ETL agent invokes this service to retrieve a number of messages which are written to the staging database ▪ ConfirmMessages2 - ETL agent invokes this service after processing the data retrieved via ReceiveMessages2 ▪ Ping - verifies connectivity 4 Configure the Kofax applications, e.g. Kofax Capture, to send their reporting data to the URL set in step 1.
Configuration 38 Kofax Reporting Administrator's Guide
Chapter 6 Operation and Maintenance This chapter provides information about daily operation of Kofax Reporting.
Operation and Maintenance On the WSA Receiver side: ▪ The Inbound Status | Active folder shows messages received from WSA Sender before ETL Agent attempts to retrieve them. Also, messages that the ETL Agent rejects and schedules for later retry land here. ▪ Messages are moved to the Outbound Status | Active folder when the ETL Agent attempts to retrieve them. Successfully confirmed messages land in the Outbound Status | Processed folder. Rejected messages return to Inbound Status | Active.
Operation and Maintenance Reactivating Messages Manual reactivating is usually not necessary. 1 Start WSA Receiver Monitor from the Kofax Reporting group in the Windows Start menu. 2 Click Outbound > Active to display a list of messages. 3 Optionally, select multiple messages. 4 Click Reactivate. Manual reactivating in WSA Sender is not practical, retries are performed very fast.
Operation and Maintenance Managing MS SQL Databases Microsoft SQL databases automatically create log files that contain historical changes in the database. Depending on your database configuration, these log files can potentially fill the hard drive. If you select "Simple" as the "Recovery model", make sure that you truncate the log files. E.g., you can use a similar SQL statement to perform this action manually: -- recovery model must be "simple" -- Shrink (truncate) the log file to 100 MB.
Operation and Maintenance The Windows user under which the ETL Agent service is running must have the "performance log user" right. If an ETL Agent running under admin or system user creates a log file and later the service is modified to run under a regular user, log files cannot be written. Non-admin/non-system user must be granted additional permissions for write access to the logs. Alternatively, delete the existing log files. The trace file is written using the Windows system locale setting.
Operation and Maintenance 44 Kofax Reporting Administrator's Guide
