Kofx Reporting 2.0.0 Administrtor's Guide 2013-09-19
2013 Kofx, Inc. All rights reserved. Use is subject to license terms. Third-prty softwre is copyrighted nd licensed from Kofx 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. Kofx, the Kofx logo, nd the Kofx product nmes stted herein re trdemrks or registered trdemrks of Kofx, Inc. in the U.S. nd other countries. All other trdemrks re the trdemrks or registered trdemrks of their respective owners. U.S. Government Rights Commercil softwre. Government users re subject to the Kofx, Inc. stndrd license greement nd pplicble provisions of the FAR nd its supplements. You gree tht you do not intend to nd will not, directly or indirectly, export or trnsmit the Softwre or relted documenttion nd technicl dt to ny country to which such export or trnsmission is restricted by ny pplicble U.S. regultion or sttute, without the prior written consent, if required, of the Bureu of Export Administrtion of the U.S. Deprtment of Commerce, or such other governmentl entity s my hve jurisdiction over such export or trnsmission. You represent nd wrrnt tht you re not locted in, under the control of, or ntionl or resident of ny 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.
Contents Prefce... 5 Introduction...5 Relted Documenttion... 5 Overview... 7 Architecture... 7 HTTP Trnsport...7 Messge Queue Trnsport... 8 Trnsport Through Third-Prty ESB... 9 Centrl Site... 10 Components...11 System Requirements... 13 Hrdwre Requirements... 13 Supported Operting Systems... 13 Supported Virtuliztion Servers... 13 Supported Softwre... 14 Supported Dtbse Mngement Systems...14 Instlltion... 15 Performnce Considertions...15 Instlling the Configurtion Tool...16 Instlling WSA...16 Commnd Line Instlltion... 17 Instlling the ETL Agent...18 Instlling the Kofx License Utility...19 Instlling Dtbse Scripts...19 Running MS SQL Dtbse Instlltion Scripts...20 Running Orcle Dtbse Instlltion Scripts... 20 Instlling the Integrtion SDK... 21 Network Lod Blncing... 21 Instlling Windows NLB on Windows Server 2008/2012...22 Instlling Windows NLB on Windows Server 2003... 22 Creting New Cluster... 23 Adding Cluster Nodes... 23 About NLB Unvilbility... 23 Upgrding from Kofx Reporting 1.0.0...24 Configurtion...25 Configuring the Centrl Site... 25 Kofx Reporting Administrtor's Guide 3
Contents Configuring Advnced Settings of ETL Agent... 27 Configuring Kofx Applictions...29 Configuring Microsoft Messge Queuing...30 Configuring IBM WebSphere Messge Queuing...30 Configuring the Centrl Site for IBM WebSphere Messge Queuing...31 Configuring the Appliction Site (with MQ Server)... 31 Configuring the Appliction Site (with MQ Client)...32 Configuring the MQ Cluster... 32 Configuring WSA...33 Configuring WSA for HTTP Trnsport... 33 Configuring WSA for Messge Queue Trnsport...34 Configuring WSA Advnced Settings... 34 Configuring Enterprise Service Bus...36 Configuring WSA Remotely...37 Opertion nd Mintennce...39 Monitoring WSA Sttus... 39 WSA Storge... 39 Mnging Filed Messges Mnully... 40 Deleting Messges...40 Rectivting Messges... 41 Deleting Dt from the Wrehouse Dtbse...41 Deleting Old Dt from Stging Dtbse... 41 Mnging MS SQL Dtbses...42 Mnging Orcle Dtbses...42 Log Files...42 Mnging Logs in WSA...42 Mnging Logs in ETL Agent...43 4 Kofx Reporting Administrtor's Guide
Prefce Introduction This guide contins informtion bout instlling nd configuring Kofx Reporting. To use this guide, you should hve thorough understnding of Windows stndrds, pplictions, nd interfces, nd thorough understnding of the Internet nd your network configurtion. This guide is intended for system dministrtors who re instlling nd configuring Kofx Reporting, or who need description of the instlltion procedures, requirements, nd configurtion. Relted Documenttion In ddition to this Kofx Reporting Administrtor's Guide, the following documenttion is vilble: Help The online Help system included in Kofx Reporting provides online ssistnce for system dministrtors nd opertors. Access online Help from the Kofx Reporting Configurtion tool by clicking Help. Kofx Product Support for Kofx Reporting The support document contins product-specific informtion bout the wys in which vrious Kofx products support Kofx Reporting. Kofx will updte this guide s dditionl products include support for Kofx Reporting. This document is vilble on the Kofx Support website. Relese Notes The relese notes provide lte-breking product informtion. Red the relese notes crefully; they contin informtion tht my not be included in other Kofx Reporting documenttion. SDK Additionl documenttion is vilble s prt of the SDK. See Instlling the Integrtion SDK. Kofx Reporting Administrtor's Guide 5
Prefce 6 Kofx Reporting Administrtor's Guide
Chpter 1 Overview Kofx Reporting gives system dministrtors, business process mngers, nd other stkeholders importnt informtion bout Kofx-mnged business processes. This product serves s the single conduit cross mny Kofx products, providing centrlized storge of historicl opertionl metrics nd udit dt. For list of Kofx products supported with this relese of Kofx Reporting, see Supported Softwre. Architecture Kofx Reporting uses distributed rchitecture for delivering informtion from one or more Kofx ppliction sites to centrl reporting site. Between sites, the informtion is trnsported in messge-bsed store nd forwrd mode. Kofx Reporting supports three trnsport mechnisms: HTTP Messge queues Third-prty enterprise service bus (ESB) With ll three mechnisms, Kofx pplictions provide reporting dt through API clls to the reporting integrtion API. The API uses web service clls to feed the dt into locl trnsport entry point. At the centrl site, n extrct/trnsform/lod (ETL) gent uses web service clls to red dt from the centrl trnsport entry point. The dt is then trnsformed nd stored in the dtbse. HTTP Trnsport The Kofx Reporting API, which is integrted in Kofx pplictions such s Kofx Cpture, communictes with the centrl site through messge-bsed protocol implemented over web services. The following digrm shows distributed deployment, in which two web service rchitecture (WSA) components re inserted between reporting dt producers (Kofx pplictions on site A) nd the dt consumer (centrl reporting site). This scenrio does not require ny externl trnsport mechnisms. Kofx Reporting Administrtor's Guide 7
Overview Messge Queue Trnsport In this scenrio, ll messging between sites is trnsmitted through IBM WebSphere MQ or MSMQ. WSA usully runs s service on ech computer with Kofx ppliction; or it cn lso run on stndlone server. The Kofx Reporting API sends the reporting dt to WSA using the sme web service interfce s in the HTTP trnsport scenrio; WSA hndles the trnsltion to IBM WebSphere MQ or MSMQ. The WSA server t the centrl reporting site receives informtion from the messge queue nd stores the informtion loclly. The ETL Agent then pulls dt from the WSA storge. 8 Kofx Reporting Administrtor's Guide
Overview Trnsport Through Third-Prty ESB This scenrio leverges n existing enterprise service bus (ESB), such s Sonic. Implement the Kofx Reporting web service interfce on n ESB by importing the Reporting WSDL into the ESB integrtion tool. The ESB tkes cre of the communiction. The client DLL communictes directly to the locl ESB server on the Kofx pplictions site. At the centrl site, the ETL Agent pulls informtion from the centrl ESB server. Kofx Reporting Administrtor's Guide 9
Overview Centrl Site The following digrm shows detils bout Kofx Reporting core components t the centrl site. The ETL Agent continuously pulls informtion from the centrl trnsport entry point nd stores the informtion in the stging dtbse. At configurble intervls, the gent tkes ll vilble informtion from the stging tbles nd popultes the dt wrehouse. Dt consumers such s business intelligence pplictions (Kofx Altosoft) or third-prty reporting tools ccess only the dt wrehouse tbles nd views. 10 Kofx Reporting Administrtor's Guide
Overview Components This section describes the Kofx Reporting environment. Kofx Reporting API Kofx pplictions such s Kofx Cpture use the API to forwrd informtion bout btch processing events nd dministrtor ctions to the reporting pltform. WSA Sender (ppliction site) This component runs on the sme computer s the Kofx ppliction or on nother computer t the sme site. The WSA Sender cts s web server nd receives web service clls from the API. The web service clls contin dt from the Kofx pplictions. The received dt is stored in locl temporry storge nd lter delivered to the centrl site through configured trnsport. ESB (ppliction site) As n lterntive to WSA, customers cn use third-prty ESB. A locl ESB receives informtion from the API nd delivers the informtion to the centrl site. Kofx Reporting Administrtor's Guide 11
Overview IBM WebSphere MQ or MSMQ You cn use messge queues s the trnsport mechnism between sites. Alterntively, you cn rely on HTTP trnsport or ESB trnsport. WSA Receiver (centrl site) This component runs t the centrl site s Windows service, on one or more computers. The WSA Receiver tkes dt from the locl WSA nd stores the dt until the extrct/ trnsform/lod (ETL) gent picks up the dt. ESB (centrl site) This component receives dt from remote ESB nd mkes the dt vilble to the ETL Agent. ETL Agent The extrct/trnsform/lod (ETL) gent runs t the centrl site. The gent retrieves Kofx ppliction dt from the centrl WSA or centrl ESB nd stores the dt in the stging dtbse. In configurble intervls (usully in off-pek times), the ETL Agent trnsforms the dt from the stging dtbse nd stores the dt in dt wrehouse. Stging Dtbse This centrl dtbse (SQL Server or Orcle) temporrily stores the reporting dt from Kofx pplictions. Dt Wrehouse Reporting dt is permnently stored in the dt wrehouse. 12 Kofx Reporting Administrtor's Guide
Chpter 2 System Requirements Before instlling nd operting Kofx Reporting, crefully red the following requirements. For the most recent informtion bout system requirements, see the Cross-Pltform Comptibility Mtrix (CPCM). Hrdwre Requirements The Kofx Reporting ETL Agent requires t lest 1 GB of free RAM. Supported Operting Systems Kofx Reporting client softwre is supported on the following operting systems (both 32 nd 64 bit unless noted otherwise): Windows 8 Windows 7 Windows Vist Windows XP (32-bit only) Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 (32-bit only) Kofx Reporting server softwre is supported on the following operting systems (both 32 nd 64 bit unless noted otherwise): Windows Server 2012 Windows Server 2008 R2 Windows Server 2008 Windows Server 2003 (32-bit only) Supported Virtuliztion Servers The following virtul server environments re supported with Kofx Reporting: Microsoft Hyper-V role on Windows Server 2008 R2 Hyper-V Server 2008 R2 (stndlone) VMwre VMwre vsphere 4.1 (ESX nd ESXi hypervisor rchitectures) VMwre vsphere 4.0 (ESX nd ESXi hypervisor rchitectures) Kofx Reporting Administrtor's Guide 13
System Requirements VMwre ESX Server 3.5 Citrix Citrix XenServer 5.6 Citrix XenServer 5.5 Citrix XenServer 5.0 Supported Softwre The following minimum versions of Kofx products support Kofx Reporting: Kofx Cpture 10.0.1 Kofx Trnsformtion Modules 6.0.0 Kofx Front Office Server 4.0.0 Kofx TotlAgility 7.0.0 Kofx Altosoft Insight 4.3.0 Vrious tools nd pplictions cn ccess the dt collected by Kofx Reporting. We recommend Kofx Altosoft business intelligence solutions. Kofx Reporting cn be used with Microsoft Messge Queuing (MSMQ) or IBM WebSphere MQ. Microsoft.NET Frmework 4 is required for Kofx Reporting Configurtion Tool, ETL Agent, nd Kofx License Utility. The setup process ttempts to downlod nd instll the frmework if it is not instlled on the trget computer. Note Third-prty softwre requires pproprite license. Customers must provide their own licenses; third-prty licenses re not included in the Kofx Reporting license. Supported Dtbse Mngement Systems Kofx Reporting supports the following dtbse systems: Microsoft SQL Server 2008 R2 (with filover clustering) Microsoft SQL Server 2012 (with filover clustering nd lwys-on filover clustering) Orcle 11 RDBMS on Windows, Linux, UNIX (with rel ppliction clusters) Note Kofx TotlAgility does not support the Orcle operting system. Express editions of the dtbses cn be used for testing. 14 Kofx Reporting Administrtor's Guide
Chpter 3 Instlltion Use the informtion in this chpter to instll Kofx Reporting. Instll the following components t the centrl site: Kofx Reporting Configurtion tool ETL Agent Kofx License Utility Dtbses WSA Receiver (when using IBM MQ/MSMQ/HTTP trnsport) ESB (when using ESB trnsport) Instll the following components t the ppliction site: WSA Sender (when using MQ/MSMQ/HTTP trnsport) ESB (when using ESB trnsport) The setup includes the integrtion SDK. The SDK provides smple code, describes how to integrte Kofx Reporting with n ESB trnsport, nd includes informtion bout Kofx Reporting views nd tbles. Performnce Considertions To correctly scle your instlled solution, consider the following: WSA Sender instnces WSA components re complicted pplictions with multiple processes. They require significnt CPU processing power nd ctively use input/output opertions on the hrd disk. These opertions decrese computer performnce nd cn degrde the performnce of other Kofx pplictions. Instll WSA on dedicted computer if your Kofx ppliction genertes significnt mount of reporting dt. You cn lso hve multiple computers with Kofx pplictions on the sme site send reporting dt through single dedicted WSA Sender. Or, instll the WSA Sender directly on computer with the Kofx ppliction to increse the relibility nd speed of delivery for reporting dt to WSA Sender. This configurtion lso works well for smller instlltions. Multiple instnces of WSA Sender on single computer cn be useful, for exmple, when you hve multiple Kofx pplictions sending reporting dt in prllel, ech using dedicted sender instnce. If one Kofx ppliction floods the sender with reporting dt tht tkes while to process, nother sender cn trnsfer reporting dt from other pplictions without dely. WSA Receiver instnces Multiple WSA Receiver instnces cn increse the mount of reporting dt to be processed in prllel. Often, single sender is linked with single receiver. If certin sender-receiver pir is overwhelmed, other WSA pirs cn process dt without dely. Kofx Reporting Administrtor's Guide 15
Instlltion Alterntively, WSA Senders cn send reporting dt to multiple WSA Receivers grouped in network lod blncing cluster. Refer to Network Lod Blncing. ETL Agent instnces You cn instll multiple instnces of n ETL Agent on single computer. One instnce is considered primry, nd the others re secondry. If the primry instnce fils, secondry instnce becomes the primry. Instlling the Configurtion Tool Instll the Kofx Reporting Configurtion tool in the centrl site. 1 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 2 Click Instll Configurtion tool. The setup wizrd ppers. 3 Accept the defult settings in the setup wizrd 4 On the instlltion window, click Instll. 5 When the configurtion tool is instlled, click Finish. If you use n Orcle dtbse, instll Orcle Dt Access Components (ODAC) on the sme computer s the configurtion tool. ODAC is vilble from Orcle website. Instlling WSA The web service rchitecture (WSA) is n option for communicting between ppliction sites nd the centrl reporting site. The other option is n Enterprise Service Bus (ESB.) Instll the WSA Receiver t the centrl site nd the WSA Sender t the ppliction site. At the ppliction site, instll WSA on dedicted computer or on the computer with Kofx pplictions. At the centrl site, instll WSA on dedicted computer or on the sme computer s the ETL Agent. 1 Disble Sophos nd ny other nti-virus or firewll pplictions on the system. Sophos Endpoint Security, Control 10.0, nd other nti-virus nd firewll pplictions re known to cuse instlltion problems. To temporrily disble Sophos: Nvigte to <Sophos>\Sophos Anti-Virus\Web Intelligence\ where <Sophos> is the directory where the Sophos nti-virus softwre is instlled. b Run the following commnd: swi_lsp32_util.exe -u -d swi_ifslsp.dll 2 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 3 Instll WSA on both the centrl (server) site nd the ppliction (client) site: To instll WSA on the centrl site, click Instll WSA Receiver. Multiple instnces of WSA Receiver re supported on one computer. Click n instnce to strt the setup wizrd. 16 Kofx Reporting Administrtor's Guide
Instlltion To instll WSA t the ppliction site, click Instll WSA Sender. Multiple instnces of WSA Sender re supported on one computer. Click n instnce to strt the setup wizrd. For tests nd demonstrtions, you cn instll both the sender nd receiver WSA on the sme computer. 4 Specify the destintion folder nd click Next. 5 To configure the WSA Receiver: Tip You cn keep the defult vlues during instlltion nd configure WSA lter. See Configuring WSA. Select the Trnsport mode: HTTP, MSMQ, IBM WebSphere MQ. b Use the defult vlue for the Locl server nme. c Specify the Locl port. 6 To configure the WSA Sender: Tip You cn keep the defult vlues during instlltion nd configure WSA lter. See Configuring WSA. Select the Trnsport mode: HTTP, MSMQ, IBM WebSphere MQ. b Specify the Locl server nme s it is known to the client pplictions. c Specify the Locl port. d Specify the Centrl URL (the URL of the WSA Receiver on the centrl site). e Specify the Client config. file (pth nd file nme). The WSA Sender sves the URL of the web service interfce to this configurtion file. Kofx pplictions red the file nd use it for connecting to the web service interfce. For exmple, Kofx Cpture looks for this configurtion file in one of the following folders: C:\ProgrmDt\Kofx\Cpture\Config\Reporting.Client.Configurtion.xml (Windows Vist, 7, 8, Windows Server 2008, 2012) C:\Documents nd Settings\All Users\Appliction Dt\Kofx\Cpture\Config \Reporting.Client.Configurtion.xml (Windows XP, Windows Server 2003) 7 Click Next nd click Instll. 8 If firewll wrning ppers, click Unblock. 9 Once the Kofx Reporting - WSA instlltion is finished, click Finish. 10 Restrt Sophos or nti-virus pplictions tht you stopped before instlling WSA. Note If you instll WSA on computer with desktop version of the Windows operting system (for exmple, Windows 7), use the Windows Power Options to keep the computer from going into sleep mode. Commnd Line Instlltion You cn instll WSA using commnd line insted of the user interfce. Enter the following commnd to instll WSA with the defult vlues: msiexec.exe /i D:\WSASender\Kofx.Reporting.WSA.Sender.msi /quiet Kofx Reporting Administrtor's Guide 17
Instlltion Enter the following commnd to instll WSA nd modify some vlues: msiexec.exe /i D:\WSASender\Kofx.Reporting.WSA.Sender.msi INSTALLDIR= C: \WSA\WSA-Sender TRANSPORT_MODE=3 /quiet The following switches nd prmeters control the instlltion: To modify the instlltion directory, use the prmeter INSTALLDIR, such s, INSTALLDIR=%ProgrmFiles%/Kofx/Reporting/WSA-Sender To modify the trnsport mode, use TRANSPORT_MODE with one of the following vlues: 1: HTTP 2: MSMQ 3: IBM MQ To modify the nme of the locl server, use LOCAL_SERVER_NAME="myserver" To modify locl port of the web service interfce, use LOCAL_PORT="25480" To specify the centrl queue for MSMQ, use CENTRAL_QUEUE_MSMQ="DIRECT=OS:. \privte$\reporting" To specify the centrl queue for IBM MQ, use CENTRAL_QUEUE_IBMMQ="REPORTING.QUEUE.MANAGER:2REPORTING.QUEUE" To specify the URL of the receiver WSA in the centrl site, use CENTRAL_URL="http:// loclhost:25481" To suppress the instller user interfce, use the "/quiet" switch. Instlling the ETL Agent Instll the Kofx Reporting ETL Agent t the centrl site. 1 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 2 Click Instll ETL Agent. Multiple instnces of the ETL Agent cn be instlled on single computer. 3 Click the instnce to instll. The setup wizrd ppers. 4 Optionlly, modify the service nme nd the destintion folder. 5 Click Next nd click Instll. 6 Once the ETL Agent instlltion is finished, click Finish. Running the ETL Agent under different Windows user requires the following: The right to Log on s service. Membership in the performnce log user group. (This membership is needed if the ETL Agent trce configurtion hs debugging enbled.) Instlling the ETL Agent s Windows cluster resource is not supported. If you use n Orcle dtbse, instll Orcle Dt Access Components (ODAC) on the sme computer s the ETL Agent. ODAC is vilble from Orcle website. 18 Kofx Reporting Administrtor's Guide
Instlltion Instlling the Kofx License Utility Instll the Kofx License Utility t the centrl site long with the ETL Agent. 1 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 2 Click Instll ETL Agent. 3 Click Instll License Utility. 4 Optionlly, modify the destintion folder. 5 Click Next nd click Instll. 6 Once the Kofx License Utility instlltion is finished, click Finish. Kofx Reporting requires system license. The ETL Agent checks the license. Instlling Dtbse Scripts Instll Kofx Reporting dtbse scripts on ny computer. You need the scripts for instlling dtbses in the centrl site. Cution If you re upgrding Kofx Reporting, bck up your dtbse instlltion scripts. The upgrde process overwrites the current scripts nd ny customiztions tht the scripts contin. By defult, the instlltion process sves the scripts in the progrm files folder, \Kofx\Reporting\Dtbse Scripts. 1 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 2 Click Instll Scripts for mnul dtbse instlltion. The setup wizrd ppers. 3 Accept the defult settings in the setup wizrd. 4 On the instlltion window, click Instll. 5 After the dtbse scripts re instlled, click Finish. This procedure mkes the scripts for mnul dtbse instlltion vilble in the following folder: <progrms>\kofx\reporting\dtbse Scripts lter_kofx_nlytics.sql MS SQL script for dt wrehouse; for upgrdes lter_kofx_nlytics_stging.sql MS SQL script for stging dtbse; for upgrdes lter_kofx_nlytics_orcle.sql Orcle script for dt wrehouse; for upgrdes lter_kofx_nlytics_stging_orcle.sql Orcle script for stging dtbse; for upgrdes kofx_nlytics.sql MS SQL script for dt wrehouse; for new instlltions kofx_nlytics_stging.sql MS SQL script for stging dtbse; for new instlltions kofx_nlytics_orcle.sq Orcle script for dt wrehouse; for new instlltions kofx_nlytics_stging_orcle.sql Orcle script for stging dtbse; for new instlltions The beginning of ech file gives brief description bout how to use these scripts. Kofx Reporting Administrtor's Guide 19
Instlltion Running MS SQL Dtbse Instlltion Scripts Before running these scripts, verify tht comptible dtbse server is lredy instlled. 1 Stop the ETL Agent. 2 Log on to the Microsoft SQL Server Mngement Studio s the dtbse dministrtor. 3 Crete the stging dtbse nd dt wrehouse. 4 Run the following scripts to crete dtbse objects: For the stging dtbse kofx_nlytics_stging.sql For the dt wrehouse kofx_nlytics.sql 5 Crete SQL Server user for the ETL Agent. Alterntively, crete two users, one for ech dtbse. 6 Assign the following role to the user: For the stging dtbse kfx_stging For the dt wrehouse kfx_etl, kfx_reder, kfx_dvnced_reder 7 Strt the ETL Agent. Running Orcle Dtbse Instlltion Scripts Before running these scripts, verify tht comptible dtbse server is lredy instlled. 1 Stop the ETL Agent. 2 Log on to dtbse mngement tool, such s Orcle SQL Developer, s the sys user (role SYSDBA). 3 Crete two users, one for the stging dtbse nd one for the dt wrehouse, such s StgingUser or DwhUser. 4 Assign tblespce quot to ech user, or grnt ech user unlimited tblespce privilege. 5 Grnt the following privileges to the creted users: 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_nme>; 6 To prompt for usernme nd pssword, edit the scripts nd uncomment the first prgrph. For the stging dtbse kofx_nlytics_orcle_stging.sql For the dt wrehouse kofx_nlytics_orcle.sql 7 Run the scripts to crete dtbse objects. For exmple, the following is smple sqlplus commnd: sqlplus DwhUser/pwd@loclhost @kofx_nlytics_orcle.sql 8 Revoke the system privileges grnted in step 4 for both users: 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_nme>; 20 Kofx Reporting Administrtor's Guide
Instlltion 9 Assign the following dtbse roles to the user: For the stging dtbse kfx_stging For the dt wrehouse kfx_etl, kfx_reder, kfx_dvnced_reder 10 Strt the ETL Agent. Instlling the Integrtion SDK The Kofx Reporting integrtion softwre development kit includes the following: Documenttion for Kofx Reporting views nd tbles. Documenttion nd smple code for integrtion with Sonic ESB 8.0. 1 From the Kofx Reporting instlltion ISO, strt setup.exe. A setup splsh screen is displyed. 2 Click Instll SDK. The setup wizrd ppers. 3 Accept the defults in the setup wizrd. 4 On the instlltion window, click Instll. 5 After the integrtion SDK instlltion is finished, click Finish. The SDK includes: KofxReportingTbles.docx dtbse tble description KofxReportingViews.docx dtbse view description IntegrtionWithSonicESB_8.docx description of smple integrtion with Sonic ESB 8 ESB8_Scripts.zip smple code for ESB integrtion Network Lod Blncing Network lod blncing (NLB) is the bility to distribute the worklod to multiple computers. In Kofx Reporting, WSA Receivers cn run in lod-blncing scenrio. NLB by itself only provides filover when n NLB node in the cluster is completely shut down; NLB directs ll TCP-bsed trffic to the remining working NLB nodes. NLB does not provide filover solution when node is running but the TCP-bsed services on the node (such s, web service listeners) hve problems, or if the service is stopped. Therefore, WSA includes feture clled NLB Port Control tht monitors the helth of the processes. If problem occurs, the port control mkes the node unvilble. NLB divides the worklod between two or more computers, which run in prllel. Kofx Reporting Administrtor's Guide 21
Instlltion Configurtion hints: In the WSA Sender, configure the NLB IP ddress nd port in the Centrl URL field. See Configuring WSA. If you re using remote configurtion of WSA Receiver from the Kofx Reporting Configurtion tool, do not use the NLB port. Configure ech WSA Receiver node individully. See Configuring WSA Remotely. Instlling Windows NLB on Windows Server 2008/2012 Instll Windows NLB on ech WSA Receiver node s n operting system feture. 1 Strt the Server Mnger. 2 Select Fetures. 3 Click Add Fetures. 4 Select Network Lod Blncing. 5 Click Next nd click Instll. 6 Configure fixed IP ddress on the node. Instlling Windows NLB on Windows Server 2003 Instll Windows NLB on ech WSA Receiver node s n dditionl service in the Locl Are Network Properties. 1 Open the Windows Control Pnel nd nvigte to Network Connections. 2 Right-click Locl Are Network nd select Properties. 3 Click Instll. 4 Select Service nd click Add. 5 Select Network Lod Blncing nd click OK. 6 Activte Network Lod Blncing nd click Close. 7 Configure fixed IP ddress on the node. 22 Kofx Reporting Administrtor's Guide
Instlltion Creting New Cluster 1 Run nlbmgr (Windows Network Lod Blncing Mnger.) 2 Right-click Network Lod Blncing Cluster nd select New Cluster. 3 Enter the IP ddress of cluster host nd click Connect. 4 Select n interfce nd click Next. 5 We recommend tht you chnge the Defult stte to Suspended, select Retin suspended stte fter computer restrts. The Messge Connector updtes the stte fter strtup. 6 Click Next. 7 Click Add, enter the cluster IP ddress, click OK, nd click Next. 8 In the Full Internet nme field, enter the nme of the cluster computer. 9 Unless you hve 2 or more network dpters on ech node, select Multicst. 10 Click Next. 11 To dd port rules for web service input (defult 25500 for receiver instnce 1), click Add. 12 Select Multiple host s Filtering mode nd set Affinity to None. 13 Click Finish. Adding Cluster Nodes 1 To mnge n NLB cluster, run nlbmgr (Windows Network Lod Blncing Mnger.) 2 Right-click the cluster nd select Add Host. 3 Specify the IP ddress of the node nd click Connect. 4 Select n interfce nd click Next. 5 Click Next gin, then click Finish. About NLB Unvilbility The NLB port control is not vilble for short time (usully 1 to 8 seconds) during which filover is not provided nd the web service connection to the common NLB IP ddress fils. The following situtions cuse this to occur: The WSA node stops bruptly. In this cse, the NLB, not the port control, hndles the sitution. The NLB requires bout 5 seconds to detect filed node nd from 2 to 3 seconds to remove the filed node nd redistribute the lod to live nodes. A node strts. Some seconds elpse between when the NLB service strts (with enbled ports - depends on cluster host configurtion) nd when the WSA with port control strts. Eliminte most of this dely by properly configuring the cluster. See Creting New Cluster, step 5. A WSA process filure occurs. Up to 3 seconds elpse before the WSA port control detects the filure nd disbles the ports for NLB. If the web service client supports retries, the second ttempt is usully outside of the time window nd the connection request is directed to working node. Kofx Reporting Administrtor's Guide 23
Instlltion Upgrding from Kofx Reporting 1.0.0 Cution Before upgrding your version of Kofx Reporting, bck up your dtbse instlltion scripts. The upgrde process overwrites the current scripts nd ny customiztions tht the scripts contin. By defult, the instlltion process sves the scripts in the progrm files folder, \Kofx\Reporting\Dtbse Scripts. 1 Instll the new dtbse scripts (see Instlling Dtbse Scripts). 2 Stop ll reporting services on the server site (ETL Agent, WSA Receiver). 3 Updte the stging dtbse: Use stndrd dtbse mngement tool to log on to the stging dtbse s user with full ccess. b Run the script for your site, such s lter_kofx_nlytics_stging.sql (MS SQL) or lter_kofx_nlytics_stging_orcle.sql (Orcle). When the script finishes without error, the stging dtbse contins the new structure. 4 Updte the dt wrehouse: Use stndrd dtbse mngement tool to log on to the dt wrehouse s user with full ccess. b Run the script for your site, such s lter_kofx_nlytics.sql (MS SQL) or lter_kofx_nlytics_orcle.sql (Orcle). When the script finishes without error, the dt wrehouse contins the new structure. 5 Instll the updted server components. Note The first version of Kofx Reporting let you specify custom Windows service nme from some Kofx Reporting components (WSA Sender, WSA Receiver, ETL Agent). Upgrding resets the service nme to the defult vlue. Configurtion tool: see Instlling the Configurtion Tool. b ETL Agent: see Instlling the ETL Agent. c License utility: see Instlling the Kofx License Utility. d WSA Receiver: see Instlling WSA. Instlling the components strts the services. 6 Optionlly, updte WSA Sender instnces on Kofx ppliction sites. Stop the WSA Sender service. b Updte Kofx pplictions, if necessry. c Updte the WSA Sender (refer to Instlling WSA). Instlling WSA strts the service. 24 Kofx Reporting Administrtor's Guide
Chpter 4 Configurtion This section describes how to configure Kofx Reporting. The subsequent sections describe this process in more detil. 1 In the centrl site, configure the ETL Agent nd connect to the dtbses. See Configuring the Centrl Site. 2 On the ppliction site, enble reporting within the ppliction (if necessry) nd configure the pth to the trnsport entry point (WSA Sender/ESB). See Configuring Kofx Applictions. 3 Configure the trnsport mechnism: Messge Queuing (MQ): Microsoft Messge Queuing (MSMQ) see Configuring Microsoft Messge Queuing IBM Messge Queuing see Configuring IBM WebSphere Messge Queuing HTTP trnsport see Configuring WSA. Enterprise service bus (ESB) see Configuring Enterprise Service Bus Configuring the Centrl Site Use the Kofx Reporting Configurtion tool to configure the ETL Agent nd connect to the dtbses. Set up the dtbses before you configure the centrl site; see Instlling Dtbse Scripts. 1 Strt Configurtion from the Kofx Reporting group in the Windows Strt menu. 2 Either open n existing configurtion, or crete new one. To crete new configurtion: Click New on the Home tb. b Type descriptive nme for the new configurtion. c Enter the Loction. If the ETL Agent is lredy instlled on the sme computer, the Loction field is utomticlly populted. By defult, this is: C:\Documents nd Settings\All Users\Appliction Dt\Kofx\Reporting \KofxReportingETLAgent\Config (Windows Server 2003) C:\ProgrmDt\Kofx\Reporting\KofxReportingETLAgent\Config (Windows Server 2008/2012) If the ETL Agent is not lredy instlled on the centrl site, enter the pth where the configurtion should be stored, or browse to the loction. Note To mke configurtion ctive, it must be in the designted folder. To open n existing configurtion: Click Open on the Home tb. b Nvigte to the folder where configurtion is stored, select the folder nd click OK. Kofx Reporting Administrtor's Guide 25
Configurtion 3 Click Stging dtbse in the Kofx Reporting pne to disply the dtbse settings. 4 In the Server Type field, select either Orcle or MS SQL Server. For MS SQL Server: Click Lod SQL Servers on the Dtbse tb to serch for ll Microsoft SQL Server instnces on the network. Skip this step to type the connection informtion mnully. b In the Server field, select n instnce, or type the instnce nme (servernme \instncenme). c In the Port field, type the port for connecting to the dtbse. d Select Use SQL Server User to ccess the dtbse with specific ccount. If you do not specify n ccount, the user under which the ETL Agent service is running is used to connect to the dtbse. e Click Get List of Dtbses. Either select dtbse from the Dtbse Nme field or type the dtbse nme directly. f Click Test Connection to verify tht the ETL Agent cn connect to the dtbse. For Orcle: In the Server field, type the nme of the server where the dtbse is running. b In the Port field, type the port for connecting to the dtbse. c In the Connection Type field, select either of the following: Bsic Connect through the Orcle Cll Interfce TNS Use n lis entry from tnsnmes.or file d Enter the User Nme nd Pssword credentils to connect to the dtbse. e f In the Service Nme field, type the globl dtbse nme in the formt dtbse_nme.dtbse_domin. In the Trget Schem field, type the schem. g Click Test Connection to verify tht the ETL Agent cn connect to the dtbse 5 Click Wrehouse dtbse in the Kofx Reporting pne. Either click Copy Configurtion to copy the settings from the Stging dtbse pne nd skip to step 7, or follow step 6 to configure the wrehouse dtbse mnully. 6 To configure the wrehouse dtbse mnully. in the Server Type field, select either Orcle or MS SQL Server. For MS SQL Server: Click Lod SQL Servers on the Dtbse tb to serch for ll Microsoft SQL Server instnces on the network. Skip this step to type the connection informtion mnully. b In the Server field, select n instnce, or type the instnce nme (servernme \instncenme). c In the Port field, type the port for connecting to the dtbse. d Select Use SQL Server User to ccess the dtbse with specific ccount. If you do not specify n ccount, the user under which the ETL Agent service is running is used to connect to the dtbse. e Click Get List of Dtbses. Either select dtbse from the Dtbse Nme field or type the dtbse nme directly. 26 Kofx Reporting Administrtor's Guide
Configurtion f Click Test Connection to verify tht the ETL Agent cn connect to the dtbse. For Orcle: In the Server field, type the nme of the server where the dtbse is running. b In the Port field, type the port for connecting to the dtbse. c In the Connection Type field, select either of the following: Bsic Connect through the Orcle Cll Interfce TNS Use n lis entry from tnsnmes.or file d Enter the User Nme nd Pssword credentils to connect to the dtbse. e f In the Service Nme field, type the globl dtbse nme in the formt dtbse_nme.dtbse_domin. In the Trget Schem field, type the schem. g Click Test Connection to verify tht ETL Agent cn connect to the dtbse 7 Click ETL Settings in the Kofx Reporting pne to disply the ETL Agent configurtion settings. Use the Run dily from nd To fields, to restrict the time when the ETL Agent nlyzes dt from the stging dtbse, trnsforms it, nd stores it to the dt wrehouse. b In the Wit time between jobs (minutes) field, specify how long the ETL Agent should wit before strting nother round of dt trnsfer from the stging dtbse to the wrehouse dtbse. The defult vlue is 60 minutes. c In the Purge intervl for field detil dt (dys) field, specify how mny dys the ETL Agent should wit before deleting field detil dt (tble field_ccum_fct) from the dt wrehouse. The defult is 5 dys. d In the URL field, type the URL for the WSA Receiver or ESB in the centrl site. The ETL Agent polls these sites for reporting dt. You cn dd multiple entries. When using Windows NLB, do not use the URL of the NLB cluster; dd the URLs of ll computers in the cluster. 8 Click Worksttions in the Kofx Reporting pne to disply the list of client computers tht hve sent informtion to this ETL Agent. 9 Click Sve on the Home tb to sve the configurtion. Configuring Advnced Settings of ETL Agent The ETL Agent hs n internl configurtion file tht generlly does not need modifiction. Use these dvnced prmeters to customize performnce nd for troubleshooting. The configurtion file is locted in the ETL Agent progrm files directory, by defult: %Progrm Files%\Kofx\Reporting\ETLAgent\Kofx.Reporting.ETLAgent.exe.config The ETL Agent configurtion file includes the following prmeters: Kofx Reporting Administrtor's Guide 27
Configurtion Prmeter PurgeFieldDtBtchSize DtbseCmdTimeoutSec MQ2StgingServiceEnbled ETLServiceEnbled ETLBtchSize WSABtchSize DeleteStgingDtBtchSize Description Deleting lrge dt from indexed tbles cn be expensive, therefore the ETL Agent deletes dt in btches of given size. This prmeter determines how mny rows re deleted in single trnsction when purging old field dt. The ETL Agent continues to delete dt in btches until ll dt is deleted. The defult vlue should be pproprite for most dtbses. Defult = 10000 This prmeter controls the number seconds SQL commnd cn tke before timing out. The defult vlue should be pproprite for most dtbses. Defult = 600 Set this prmeter to Flse to disble sving WSA dt in the stging dtbse. Use this prmeter for debugging. Defult = True Set this prmeter to Flse to disble processing dt from the stging dtbse into the wrehouse. Use this prmeter for debugging. Defult = True This prmeter controls the number of messges tht re processed t one time when processing dt from the stging dtbse to the wrehouse. The defult vlue should be pproprite for most dtbses, however, for very lrge btches (for exmple, if n verge btch contins 100 documents nd ech document contins 100 pges), you my need to decrese this vlue. Defult = 10000 This prmeter controls the number of messges tht re processed t one time when processing dt from the WSA dtbse to the stging dtbse. The defult vlue should be pproprite for most dtbses, however, for very lrge btches (for exmple, if n verge btch contins 100 documents nd ech document contins 100 pges), you my need to decrese this vlue. Defult = 10000 Deleting lrge dt from indexed tbles cn be expensive, therefore the ETL Agent deletes dt in btches of given size. This prmeter determines how mny rows re deleted in single trnsction when purging processed stging dt. The ETL Agent continues to delete dt in btches until ll dt is deleted. The defult vlue should be pproprite for most dtbses. Defult = 50000 28 Kofx Reporting Administrtor's Guide
Configurtion Prmeter MxMQ2StgingItertionsNum DeleteStgingDtOlderThnDys DropIndexesOnMq2Stging Description This prmeter determines how mny times the WSA to stging dtbse process runs, until the system checks if it is time to run n ETL job. Defult = 10 This prmeter determines how mny dys the stging dt stys in the dtbse before it is deleted. By defult the dt is deleted immeditely fter being processed. Use this prmeter for debugging. Defult = -1 Do not chnge the defult setting. When this prmeter is set to True, the ETL Agent drops indexes in the stging dtbse when loding dt into the stging dtbse nd then recretes the indexes to extrct dt before n ETL job. Defult = True 1 Edit the Kofx.Reporting.ETLAgent.exe.config file with text editor. 2 Sve the chnges nd close the file. 3 Restrt the ETL Agent service to mke the chnges effective. Configuring Kofx Applictions Enble support for Kofx Reporting in your Kofx pplictions (for exmple, Kofx Cpture). 1 Instll comptible version of the Kofx ppliction. See the Kofx Reporting Relese Notes for updted informtion bout supported versions. 2 Enble reporting in the Kofx ppliction if necessry. See the documenttion for your specific product for instructions. 3 Specify the URL for the trnsport entry point (WSA Sender or ESB). Kofx pplictions must know the URL for the trnsport entry point to strt sending reporting dt. Kofx pplictions red the URL from specil configurtion file, Reporting.Client.Configurtion.xml. Use one of the following: WSA Sender writes its URL to the configurtion file during instlltion (refer to Instlling WSA). WSA Sender writes its URL to the configurtion file during configurtion (refer to Configuring WSA Advnced Settings, Advnced tb). Edit the configurtion file with text editor nd type the URL. Strt Kofx.Reporting.Configurtion.Client.exe nd type the URL. (For exmple, <Kofx>\CptureSS\Servlib\Bin\Kofx.Reporting.Configurtion.Client.exe, lthough the pth my vry depending on the ppliction.) This generl procedure might not pply for ll Kofx pplictions. See the documenttion for your specific Kofx ppliction. Also, see Kofx Product Support for Kofx Reporting, vilble on the Kofx Support web. Kofx Reporting Administrtor's Guide 29
Configurtion Configuring Microsoft Messge Queuing 1 On the centrl site, crete new queue. Kofx Reporting supports trnsctionl queues. Authentiction nd privcy level re not supported. 2 On the centrl site, instll the Messge Queuing Server nd WSA Receiver. The WSA Receiver on the centrl site only reds from locl trnsctionl MSMQ queue. 3 On the ppliction site, instll the Messge Queuing Server nd WSA Sender. The WSA Sender on the ppliction site sends messges to remote trnsctionl queue locted on the centrl site. 4 Configure the WSA Sender nd the WSA Receiver. See Configuring WSA for detiled instructions. In the Generl Settings tb, set Trnsport to MSMQ; configure the MQ User nd Pssword, nd set the Centrl Queue to the queue creted in step 1. For exmple: DIRECT=OS:.\privte$\PrivteQueueNme DIRECT=OS:Computer_Nme\PublicQueueNme DIRECT=OS:Computer_Nme\privte$\PrivteQueueNme DIRECT=TCP:IP_Address\PublicQueueNme DIRECT=TCP:IP_Address\privte$\PrivteQueueNme DIRECT=HTTP://URL_Address/msmq/PublicQueueNme DIRECT=HTTPS://URL_Address/msmq/privte$/PrivteQueueNme DIRECT=HTTPS://URL_Address/msmq/PublicQueueNme DIRECT=HTTPS://URL_Address/msmq/privte$/PrivteQueueNme b In the MQ tb of the WSA Sender, you cn enble support for the ded letter queue (DEADXACT). To use HTTP/HTTPS, instll nd configure Internet Informtion Services (IIS) on the WSA Receiver. See the MSMQ documenttion. The HTTP/HTTPS protocol is only supported for sending messges to MSMQ, tht is, on the ppliction site. It is not supported for receiving messges from MSMQ on the centrl site. Messges sent from the WSA Sender to remote trnsctionl queue re first stored in locl outgoing queue (creted utomticlly). MSMQ utomticlly trnsfers the messges to the destintion remote queue. Messges tht cnnot be delivered to the destintion queue re utomticlly moved by MSMQ to the locl MSMQ system trnsctionl ded letter queue (DEADXACT) on the WSA Sender nd the property CLASS contins the reson for the filure (for exmple, remote queue does not exist, remote server not rechble nd so forth). The WSA Sender service hs built-in mechnism tht checks periodiclly in the bckground for the DEADXACT queue nd retry mechnism tht tkes the messges from the DEADXACT queue nd requeues them into the outgoing queue. Configuring IBM WebSphere Messge Queuing Kofx recommends tht you use dedicted Queue Mnger for Kofx Reporting. It is possible reuse n existing Queue Mnger, however, if the WSA is configured for "Check 30 Kofx Reporting Administrtor's Guide
Configurtion Ded Letter Queue", the Queue Mnger will tke ll the messges from the ded letter queue, including messges tht my not belong to Kofx Reporting. 1 Configure the centrl site. See Configuring the Centrl Site for IBM WebSphere Messge Queuing. 2 Do one of the following: If you instll MQ Server on the ppliction site, proceed with Configuring the Appliction Site (with MQ Server). If you instll MQ Client on the ppliction site, proceed with Configuring the Appliction Site (with MQ Client). Configuring the Centrl Site for IBM WebSphere Messge Queuing 1 On the centrl site, instll MQ Server nd the WSA Receiver. 2 Configure the the MQ Server: Crete queue mnger, for exmple REPORTING.QUEUE.MANAGER. Enble the Crete server-connection chnnel. Crete listener configured for TCP/IP. Specify the nmes of the locl queue nd locl ded letter queue (you crete these queues in steps b nd c). b Crete locl queue, for exmple 2REPORTING.QUEUE. Set Defult persistence to Persistent. c To hve WSA check the ded letter queue, crete locl ded letter queue, for exmple REPORTINGDEADLETTER.QUEUE using the SYSTEM.DEAD.LETTER.QUEUE templte. Set the Defult persistence to Persistent. d Crete receiver chnnel, for exmple SEND_REC_CHANNEL. 3 Configure the WSA Receiver: In the Generl Settings tb, set Trnsport to IBM WebSphere MQ. Configure the MQ User nd Pssword nd set Centrl Queue to REPORTING.QUEUE.MANAGER:2REPORTING.QUEUE. b Optionlly configure WSA to check the ded letter queue. See Configuring WSA for detiled instructions. Configuring the Appliction Site (with MQ Server) 1 On the ppliction site, instll MQ Server nd the WSA Sender. 2 Configure the MQ Server: Crete queue mnger, for exmple, REPORTING.CLIENT.QUEUE.MANAGER with locl nd ded letter queues. b To mnge the server on the ppliction site from the centrl site, dd remote queue mnger, for exmple REPORTING.CLIENT.QUEUE.MANAGER nd connect the remote queue mnger to MQ Server in the centrl site. c Crete locl trnsmission queue, for exmple REPORTING.TRANSMISSION.QUEUE. Set Defult persistence to Persistent nd set Usge to Trnsmission. d Use the SYSTEM.DEFAULT.REMOTE.QUEUE templte to crete remote queue definition, for exmple REPORTING.REMOTE.QUEUE. Set the Defult persistence Kofx Reporting Administrtor's Guide 31
Configurtion to Persistent. Set the remote queue s the locl queue of the centrl MQ Server. Set the queue mnger to the reporting queue mnger of the centrl MQ Server. Set the trnsmission queue to the previously creted trnsmission queue. e Crete sender chnnel, for exmple SEND_REC_CHANNEL. Use the sme nme s the receiver chnnel on the centrl site. Set the connection nme to the nme/ip ddress of the centrl MQ Server. Set the trnsmission queue to the previously creted trnsmission queue. 3 Configure the WSA Sender: In the Generl Settings tb, set Trnsport to IBM WebSphere MQ. Configure the MQ User nd Pssword nd set Centrl Queue to REPORTING.CLIENT.QUEUE.MANAGER:REPORTING.REMOTE.QUEUE. b Optionlly configure WSA to check the ded letter queue. If you use the ded letter queue, mke sure there is ded letter queue defined for the queue mnger on the ppliction site. See Configuring WSA for detiled instructions. Configuring the Appliction Site (with MQ Client) 1 On the ppliction site, instll MQ Client nd the WSA Sender. 2 Configure the MQ Server on the centrl site: Crete client-connection chnnel, for exmple REPORTING.CONN.CH. Set the queue mnger to the reporting queue mnger for the centrl MQ Server. Set the connection nme to the nme of the MQ Server computer. b Crete server-connection chnnel. Use the sme nme s the client-connection chnnel. On the MCA tb, specify the ID of the remote user tht uses MQ Client to send dt. c Copy the file C:\Progrm Files\IBM\WebSphere MQ\Qmgrs\REPORTING! QUEUE!MANAGER\@ipcc\AMQCLCHL.TAB from the MQ Server computer to the MQ Client computer, C:\Progrm Files\IBM\WebSphere MQ (ssuming defult instlltion pths). 3 Configure the WSA Sender: In the Generl Settings tb, set Trnsport to IBM WebSphere MQ. Configure the MQ User nd Pssword, nd set Centrl Queue to REPORTING.QUEUE.MANAGER:2REPORTING.QUEUE. b Optionlly configure WSA to check the ded letter queue. If you use ded letter queue, mke sure there is ded letter queue defined for the queue mnger on the ppliction site. See Configuring WSA for detiled instructions. Configuring the MQ Cluster MQ Server on the centrl site cn be configured to run in cluster. These smple steps re for cluster of three queue mngers on two computers: The first computer hs one queue mnger. This queue distributes the lod to the two queue mngers on the second computer. The second computer hs two queue mngers. Ech queue mnger hs its instnce of WSA Receiver. 1 On the first computer, crete one queue mnger with two locl queues. 32 Kofx Reporting Administrtor's Guide
Configurtion 2 On the second computer, crete two queue mngers, ech with two locl queues. 3 Optionlly, dd ll queue mngers to single MQ Explorer. 4 Crete queue mnger cluster (for exmple REPORTINGCLUSTER). Add ll queue mngers to the cluster. 5 On queue mngers 2 nd 3, crete cluster queue (for exmple REPORTING.CLUSTER.QUEUE) nd configure it to be shred in cluster REPORTINGCLUSTER. Set the defult bind type to Not fixed. 6 On queue mnger 1, crete client-connection chnnel nd server-connection chnnel with the sme nme. 7 Copy the file C:\Progrm Files\IBM\WebSphere MQ\Qmgrs\REPORTING!CL1! QUEUE!MANAGER\@ipcc\AMQCLCHL.TAB from the first computer to the MQ Client computer, C:\Progrm Files\IBM\WebSphere MQ (ssuming defult instlltion pths). 8 On the MQ Client computer on the ppliction site, edit the WSA Sender configurtion file nd set the Centrl Queue to REPORTING.CL1.QUEUE.MANAGER:REPORTING.CLUSTER.QUEUE. 9 On the second clustered computer, edit the WSA Receiver configurtion nd set the Centrl Queue to REPORTING.CL2.QUEUE.MANAGER:REPORTING.CLUSTER.QUEUE for the first instnce nd REPORTING.CL3.QUEUE.MANAGER:REPORTING.CLUSTER.QUEUE for the second instnce. Configuring WSA Follow the steps in this section to configure either the WSA Receiver or the WSA Sender. 1 On the Strt menu, nvigte to the Kofx Reporting group nd strt either WSA Receiver Configurtion or WSA Sender Configurtion. 2 Do one of the following: For HTTP trnsport, follow the steps in Configuring WSA for HTTP Trnsport. For messge queue trnsport, follow the steps in Configuring WSA for Messge Queue Trnsport. Configuring WSA for HTTP Trnsport 1 Click the Generl Settings tb. 2 In the Trnsport field, select HTTP. The settings for the sender nd receiver must mtch. 3 For the WSA Senders, in the Centrl URL field, specify the URL of the WSA Receiver in the centrl site. To run WSA Receivers with NLB, use the NLB IP ddress nd port. Note Do not enter the URL of the WSA Sender in this field. 4 Continue with the dvnced prmeters of WSA. See Configuring WSA Advnced Settings. Kofx Reporting Administrtor's Guide 33
Configurtion Configuring WSA for Messge Queue Trnsport 1 On the Configurtion pge, click Advnced. 2 Click the Generl Settings tb. In the Trnsport field, select MSMQ or IBM WebSphere MQ. The settings for the WSA Sender nd the WSA Receiver must mtch. b In the MQ User field, enter the domin nd user ID in the formt Domin\UserId, or enter the SID for queue ccess. This Windows user must hve the user right "logon s service". c In the MQ Pssword field, enter the pssword for the user. d In the Centrl Queue field, specify the queue. For exmple: IBM MQSeries: REPORTING.CLIENT.QUEUE.MANAGER:REPORTING.REMOTE.QUEUE MSMQ: DIRECT=TCP:10.20.30.40\MyQueue 3 Configure the del letter queue to monitor messges tht could not be delivered. Click the MQ tb. Select Check Ded Letter Queue. b In the Ded Letter Queue Check Intervl field, specify in seconds how often the ded letter queue should be exmined. c In the Ded Letter Queue Retries field, specify how mny retries should be mde for messges in the ded letter queue. d Select RejectMsgOnMqError to reject messge when the messge queue cnnot be written. If not rejected, messges re stored in the outbound sttus ctive queue. Administrtors cn rectivte or delete the messges. See Mnging Filed Messges Mnully. 4 Continue with the dvnced prmeters of WSA. See Configuring WSA Advnced Settings. Configuring WSA Advnced Settings Configure the WSA dvnced settings for: Troubleshooting or configuring trces Secure communiction using SSL Rectivtion of filed messges WSA pssword protection NLB for WSA Receivers WSA storge mngement Performnce tuning If you do not use ny of these options, skip to step 10. 1 On the Configurtion pge, click Advnced. 2 Click the Generl Settings tb. In the Storge Size field, enter the mount of disk spce WSA reserves for messges. b In the Storge File field, enter the nme nd loction of the storge file. 34 Kofx Reporting Administrtor's Guide
Configurtion c The Instnce Nme field displys nme of the WSA instnce. d For WSA Senders, in the Senders (up to 10) field, enter the number of prllel processes responsible for sending dt to the WSA Receiver. Using higher vlue increses performnce, but requires more system resources. 3 Click the HTTP Settings tb. In the Locl Port field, specify the port of the locl web server. The defult is 25480 for ppliction sites nd 25481 for centrl sites. Modify the port number if necessry to resolve port conflicts. b In the Locl IP Address field, optionlly specify the IP ddress of the locl web portl interfce. The web portl offers monitoring functions for troubleshooting. c For WSA Senders, in the Locl server nme field, specify the nme of the locl server, s it is known to the client pplictions, for exmple, the nme by which client computers know the server. d In the Listener Threds field, enter the mximum number of concurrent web service/ HTTP connections for this WSA instnce. e f For WSA Senders, in the Proxy server field, enter the nme or IP ddress of the centrl proxy server. In the Proxy port field, enter the port of the proxy server. g Optionlly, select SSL Active to enble secure communiction. 4 If you enbled SSL, click the SSL Certificte tb nd enter the configurtion vlues. 5 To configure logging, click the Trce tb. For more informtion bout log files, see Mnging Logs in WSA. In the Trce Level field, enter the trce level (0..100). Using higher vlue provides more informtion, but my impct performnce. b In the Messge Trce Size field, enter the messge-size limit to trce trffic between components: 0 = off 1 = single line per messge More thn 1 = size limit in bytes c In the Size of Trce File field, enter the mximum size of trce files in KB. d In the Number of Trce Files field, enter the mximum number of generted trce files. When ll files re full, the system overwrites the oldest file. e Select Append Trce to ppend new trce dt to the existing trce file when the ppliction restrts. 6 Click the Store tb. In the Object Fill Trget field, specify the trget percentge for object fill storge clenup. b In the Disk Fill Trget field, specify the trget percentge for the disk fill for storge clenup. c For WSA Receivers, in the OutboxRectivte field, specify the number of minutes to wit until unsuccessfully retrieved messges from the outbound folder of WSA Kofx Reporting Administrtor's Guide 35
Configurtion Receiver storge re rectivted so tht the ETL Agent cn rettempt to retrieve the messges. Note Set this prmeter to 0 to disble utomtic rectivtion. Opertors cn still mnully ctivte filed messges. See Mnging Filed Messges Mnully for more informtion. 7 Click the Security options tb. To restrict ccess to WSA monitor nd remote configurtion, in the Users field, select dmin. Otherwise, select no pssword protection nd continue t step c. b In the Admin pssword field, type the pssword for the dmin user. c To completely disble remote configurtion, select DisbleRemoteConfig. WSA cn now only be configured loclly. 8 Click the Lod Blncing Settings tb. In the Lod Blncer Support field, the lod blncer. NLB is only vilble for WSA Receivers. To disble NLB Port Control, select None. This does not disble NLB if you hve configured it. To enble port control, select Win-NLB nd Ext-LB. For Windows NLB, select Windows NLB. For externl lod blncers, select Externl LB. b In the Lod Blncer Port field, type the port tht web service clients cn use to ccess lod-blnced WSA Receivers. c In the Lod Blncing IP Address field, type the IP ddress of the locl interfce used for web service ccess. If you hve multiple network crds on your computer, you cn dedicte one for web service ccess. 9 Click the Advnced tb. In the Client Config File field, specify the pth nd file nme where WSA Sender should sve its connection informtion. This file is used by Kofx pplictions for connecting to Kofx Reporting. Only vilble for WSA Sender. E.g., Kofx Cpture might use the following pth nd nme: C:\ProgrmDt\Kofx\Cpture\Config\Reporting.Client.Configurtion.xml (Windows Vist, 7, 8, Windows Server 2008, 2012) C:\Documents nd Settings\All Users\Appliction Dt\Kofx\Cpture\Config \Reporting.Client.Configurtion.xml (Windows XP, Windows Server 2003) 10 Click Sve to sve the configurtion dt to disk. 11 Click Exit nd restrt service. Configuring Enterprise Service Bus Enterprise service bus (ESB) is one of the possible trnsport options for reporting dt between ppliction site nd centrl reporting site. Refer to Trnsport Through Third-Prty ESB. The Kofx Reporting Integrtion SDK includes n exmple integrtion with Sonic ESB 8.0. Refer to Instlling the Integrtion SDK. With defult options, the smple 36 Kofx Reporting Administrtor's Guide
Configurtion integrtion document cn be found here: <progrms>\kofx\reporting\integrtion SDK \IntegrtionWithSonicESB_8.docx. The following high-level procedure lists the min steps to perform when integrting with n ESB. 1 Prepre the Kofx Reporting WSDL file. The WSA.wsdl is prt of the Integrtion SDK, in the zip file ESB8_Scripts.zip. Edit the line <sop:ddress loction="http://172.20.148.146:9123/sonic/reporting" /> with text editor. Type the URL tht should be serviced by your ESB project. 2 Crete new ESB project nd import the Kofx Reporting WSDL into ESB integrtion tool. 3 Implement the Kofx Reporting web services interfce on the ESB. On the ppliction site, the following web services must be implemented: BulkSend2 - Kofx Reporting API invokes this service to feed reporting informtion into ESB Ping - verifies connectivity On the centrl site, the following web services must be implemented: ReceiveMessges2 - The ETL Agent invokes this service to retrieve number of messges which re written to the stging dtbse ConfirmMessges2 - The ETL Agent invokes this service fter processing the dt retrieved with ReceiveMessges2 Ping - verifies connectivity 4 Configure the Kofx pplictions, e.g. Kofx Cpture, to send their reporting dt to the URL set in step 1. 5 Configure the ETL Agent to retrieve the reporting dt from the URL of the ESB in the centrl site (prmeter URL in the ETL Settings tb). Refer to Configuring the Centrl Site. Configuring WSA Remotely You cn use Kofx Reporting - Configurtion tool for remote configurtion of WSA. Only subset of prmeters cn be configured remotely. To ccess ll prmeters, follow the steps in Configuring WSA. 1 Strt Configurtion from the Kofx Reporting group in the Windows Strt menu. 2 Click Configure WSA Server in the Kofx Reporting pne. 3 In the URL field, type the URL of WSA instnce, for exmple http://loclhost:25480. Click Connect. If you re using NLB, specify the port of the WSA instnce, not the NLB port. 4 If WSA pssword protection is enbled, log on using the user nme dmin nd pssword. 5 Edit the settings s necessry. Click Advnced to disply dditionl prmeters. See the online help for more informtion bout the prmeters. 6 Click Sve on the WSA Server tb to confirm the chnges nd restrt the WSA instnce. Kofx Reporting Administrtor's Guide 37
Configurtion 38 Kofx Reporting Administrtor's Guide
Chpter 5 Opertion nd Mintennce This chpter provides informtion bout Kofx Reporting dily opertions, including: Monitoring WSA Sttus Mnging Filed Messges Mnully Deleting old dt from dtbses (stging dtbses, or wrehouse dtbses) Mnging MS SQL Dtbses Mnging Orcle Dtbses Mnging Log Files Monitoring WSA Sttus WSA provides monitoring interfce with the following min functions: Monitoring WSA sttus (for troubleshooting) Configuring WSA Viewing messges in the WSA Storge Mnging Filed Messges Mnully 1 On the Strt menu, nvigte to the Kofx Reporting group nd strt WSA Monitor. 2 If you enbled WSA pssword protection in the Configuring WSA Advnced Settings section (Security options tb), log on s dmin. 3 On the menu, click Sttus to disply the sttus of WSA nd its internl components nd connections for troubleshooting. WSA Storge Ech WSA hs n internl storge where it temporrily stores reporting dt. The storge cn be ccessed using WSA Monitor. WSA Sender storge folders: The Inbound Sttus > Active folder shows messges received from Kofx pplictions before they re delivered to the WSA Receiver. Messges from the MSMQ ded letter queue re lso stored here. The Inbound Sttus > Processed folder shows messges delivered to WSA Receiver. Undeliverble messges re stored here if n dministrtor deletes them from the Inbound Sttus > Active folder. The outbound storge folders re not used. Kofx Reporting Administrtor's Guide 39
Opertion nd Mintennce WSA Receiver storge folders: The Inbound Sttus > Active folder shows messges received from WSA Sender before ETL Agent ttempts to retrieve them. Also, messges tht the ETL Agent rejects nd schedules for lter retry re stored here. Messges re moved to the Outbound Sttus > Active folder when the ETL Agent ttempts to retrieve them. Successfully confirmed messges re stored in the Outbound Sttus > Processed folder. Rejected messges return to Inbound Sttus > Active. Tip Strict browser security settings cn restrict the ccess to some storge fields. For best experience, llow JvScript nd dd the IP ddress to the trusted sites list. Mnging Filed Messges Mnully Follow the steps this section to mnully mnge messges tht could not be delivered from WSA Receiver to ETL Agent. Usully, retries re done utomticlly nd mnul ction is not necessry. You cnnot configure the retry behvior from WSA Sender to WSA Receiver. Use the prmeter OutboxRectivte to control the retry behvior from WSA Receiver to ETL Agent in the Store tb of the WSA configurtion (refer to Configuring WSA Advnced Settings). The defult time between retries is 15 minutes. Setting the prmeter to 0 disbles retries (not recommended). If you disble utomtic rectivtion, or if the delivery fils for prolonged mount of time, the WSA storge my get full. If the WSA storge is full, n dministrtor cn delete or rectivte messges in the storge. Deleting Messges Cution Deleting messges will result in loss of reporting dt. 1 On the Strt menu, nvigte to the Kofx Reporting group nd strt either the WSA Receiver Monitor or the WSA Sender Monitor. 2 Click Outbound > Active to disply list of messges. For the WSA Sender, lso check the Inbound > Active list. 3 Select the messge or messges to delete. 4 Click Delete. Note If you leve the storge window open in your browser for severl minutes, the view my time out. Plese click Refresh before deleting messges. Deleting messge my fil if the messge is locked for delivery (for exmple, on the WSA Sender, the messge is being trnsferred to the WSA Receiver). If the delivery fils, messge is eventully unlocked nd you cn ttempt to delete it gin. Stop the polling service to prevent locking messges. 40 Kofx Reporting Administrtor's Guide
Opertion nd Mintennce Rectivting Messges For HTTP trnsport, retries re performed very quickly nd mnul rectivtion in the WSA Sender is not necessry. Becuse there is no utomtic rectivtion for messge queues, you my need to mnully rectivte messges. 1 On the Strt menu, nvigte to the Kofx Reporting group nd strt the WSA Receiver Monitor. 2 Click Outbound > Active to disply list of messges. 3 Select the messge or messges to rectivte. 4 Click Rectivte. Deleting Dt from the Wrehouse Dtbse Run the dtbse script sp_delete_hist_oper_dt to purge old reporting dt from the dtbse. The tble etl_job_detils is not mnged by this stored procedure. This tble contins log entries for dignostics; dministrtors cn truncte it mnully if needed. 1 Stop the ETL Agent service. 2 Log on to dtbse mngement tool, such s Microsoft SQL Server Mngement Studio or Orcle SQL Developer. 3 Run the stored procedure sp_delete_hist_oper_dt. This exmple deletes ll dt older thn 1 November 2011, 00:00:00. For MS SQL: sp_delete_hist_oper_dt 10000, 2011, 11 For Orcle: CALL sp_delete_hist_oper_dt(10000, 2011, 11) 4 Restrt the ETL Agent service. Tip Deleting dt from the dtbse cn be time-consuming opertion (especilly in Orcle dtbses). Updting tble nd index sttistics before deleting cn improve the performnce: EXEC dbms_stts.gther_schem_stts('schem_nme', cscde=>true); Deleting Old Dt from Stging Dtbse The reporting dt in the stging dtbse is mnged utomticlly. By defult, processed records re deleted immeditely. To chnge the defult, edit the ETL Agent dvnced configurtion (see Configuring Advnced Settings of ETL Agent). However, you cnnot delete the Worksttion tble. Kofx Reporting Administrtor's Guide 41
Opertion nd Mintennce Mnging MS SQL Dtbses Microsoft SQL dtbses utomticlly crete log files tht contin historicl chnges in the dtbse. Depending on your dtbse configurtion, these log files cn potentilly fill the hrd drive. If you select Simple s the Recovery model, mke sure tht you truncte the log files. For exmple, you cn use similr SQL sttement to perform this ction mnully: -- recovery model must be "simple" -- Shrink (truncte) the log file to 100 MB. USE <dtbsenme> DBCC SHRINKFILE (<dtbsenme>_log, 100); GO Mnging Orcle Dtbses For optiml performnce of the reporting components, optimizer sttistics should be vilble in the dtbse. Lern more bout mnging optimizer sttistics for Orcle 11g dtbse here: http://docs.orcle.com/cd/b28359_01/server.111/b28274/stts.htm. Log Files Kofx Reporting provides log files for troubleshooting. Log files re stored in the ppliction / progrm dt folder of ll users. The exct pth (<pth>) depends on the operting system: C:\ProgrmDt\Kofx\Reporting (Windows Vist, Windows Server 2008 nd lter) C:\Documents nd Settings\All Users\Appliction Dt\Kofx\Reporting (Windows XP nd Windows Server 2003) Mnging Logs in WSA 1 On the Strt menu, nvigte to the Kofx Reporting group nd strt either WSA Receiver Configurtion or WSA Sender Configurtion. 2 Click Advnced to disply dditionl configurtion options. 3 Edit the settings in the Trce tb. The defult vlues (TrceLevel 10 nd MessgeTrceSize 1) provide bsic trce informtion tht is often sufficient without negtively impcting performnce. Troubleshooting vlues (TrceLevel 40 nd MessgeTrceSize 100000) provide more informtion; these settings re more pproprite for duplicting error situtions in controlled environments. 4 Click Sve. 5 Click Exit nd restrt service. 6 Review the log files in <pth>\wsa-receiver\log or <pth>\wsa-sender\log. 42 Kofx Reporting Administrtor's Guide
Opertion nd Mintennce Mnging Logs in ETL Agent The Windows user under which the ETL Agent service runs must hve the "performnce log user" right. If n ETL Agent running under n dmin or system user cretes log file nd lter the service is modified to run under regulr user, log files cnnot be written. Either grnt the regulr user write ccess to the logs, or delete the existing log files. The trce file is written using the Windows system locle setting. To disply regionl chrcters correctly, mke sure tht the ppliction/editor displying the log files uses the Windows defult encoding nd chrcter set. 1 Nvigte to the folder <pth>\kofxreportingetlagent\logconfig\. 2 Open log4net.config in text editor. 3 Edit the line strting with <level vlue=. Use ERROR for error output only, INFO for norml opertion, DEBUG for troubleshooting. The defult vlue is INFO. Exmple: <level vlue="error" /> 4 Restrt the ETL Agent service for the chnges to tke effect. 5 Review the log files in <pth>\kofxreportingetlagent\log. Kofx Reporting Administrtor's Guide 43
Opertion nd Mintennce 44 Kofx Reporting Administrtor's Guide