Perceptive Intelligent Capture Project Migration Tool. User Guide. Version: 2.0.x

Transcription

1 Perceptive Intelligent Capture Project Migration Tool User Guide Version: 2.0.x Written by: Product Knowledge, R&D Date: May 2015

2 2015 Lexmark International Technology, S.A. All rights reserved. Lexmark is a trademark of Lexmark International Technology, S.A., or its subsidiaries, registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark.

3 Table of Contents What is Perceptive Intelligent Capture Project Migration Tool... 4 About this manual... 4 Intended audience... 4 Content Overview... 4 Project Migration... 5 Migrate Projects to another project version... 6 Supported Project Versions... 6 Basic Concepts and Techniques... 6 The User Interface... 6 Analysis... 7 Select the Source Project... 7 Analyze the Source Project... 7 Upgrade... 9 Select the Template Project... 9 Upgrade Project... 9 Cross Version Upgrade Best Practices Working with Violation records and Reports Example Analysis violation Wrong ERR definitions in INI file: Example Analysis violation Scripting violation Example Upgrade failure DB Upgrade Known problems and solutions Additional inserted INI file parameters in DB upgrade

4 What is Perceptive Intelligent Capture Project Migration Tool The Project Migration Tool allows upgrading Application Development packaged projects to the recent project version. The current Project migration tool supports the upgrade of released Perceptive Intelligent Capture for Invoices (PICI) projects. The upgrade takes care of all project related items like the INI file, the learn set, custom scripting, and customization of the Perceptive Intelligent Capture project objects. About this manual Intended audience This document addresses users who intend to maintain Perceptive Intelligent Capture packaged solutions. Working with Project Migration Tool requires experience of Microsoft Windows operating system and of Perceptive Intelligent Capture solutions. Content Overview This document contains the following sections. The Project Migration section describes the prerequisites and process of a project migration. The Basic Concepts and Techniques section informs about the user interface and the basic concepts for working with the Perceptive Intelligent Capture Project Migration Tool. This section also contains a functional description of the used controls. The Migration 4

5 Best Practices section Project Migration A Perceptive Intelligent Capture packaged project is going to be migrated, if either the installed Perceptive Intelligent Capture product suite is upgraded or newer features for the packaged project are required. The Project Migration Tool helps to migrate all the customizations of the project into the new version. 5

6 Migrate Projects to another project version The source project has to be available with its learn set and INI file. Additionally a fresh downloaded project has to be accessible with the learn set and the INI file that represents the template of the migration target version. If the migration target version requires a configuration database, create or upgrade the database structure before the usage of the Project Migration tool. SQL scripts for creating or upgrading the target database are available with the download of the target version project. The migration process consists of two steps to ensure a successful migration. In the first Analysis step, the Project Migration Tool looks for any violation in customization. Only supported project versions that have passed the Analysis step, can be migrated. If a project fails in the Analysis step, a detailed report is provided to assist in correcting the violations before another migration trial. Supported Project Versions The current version of the Project Migration Tool supports only released versions of the Perceptive Intelligent Capture for Invoices (PICI) Business Solutions. The supported builds are: PICI 100x series: 1006D, 1007B, 1007BA, 1007CA, 1007CB, 1007D, 1007E, 1007F and 1007G PICI 2.x series: 2103, 2203, 2204, 2301, 2302, 2401 and 2501 Basic Concepts and Techniques The User Interface The user interface reflects the easy-structured migration process. There are only four user interactions required for the migration of a project: 1. Selecting the source project 2. Analyzing the source project 3. Selecting the migration template project 4. Upgrade the project Each of these steps has a tab in the user interface. Additionally, reports about analysis and upgrade are available in the Reports tab. 6

7 It is always possible to switch between these tabs. A tab has no controls, if required steps are not completed. In that case, appropriate information is displayed in the selected tab. Navigation is possible through: Controls Previous, Next and Exit buttons Menu commands (for example, File\Exit, View\Switch to ) Keyboard shortcuts Definitions in View menu The language selection of the display language is also available in the View menu. The Help menu provides the opportunity to display the list of supported builds. The Project Migration Tool is - related to the current releases of packaged projects for Perceptive Intelligent Capture - always up-to-date. Analysis The Analysis requires two user interactions. Select the Source Project Insert the file name path to the SDP file into the text field or click the Select Project button to browse through the file system. The Next button is enabled after inserting path information and the Analyze Source Project tab displays the analysis controls. Analyze the Source Project Click the Analyze Project button to trigger the analysis of the source project. There are two analysis groups: 7

8 The Pre-Requisites group In this section 1. The project will be loaded to check, if the project path leads to a valid supported project. 2. The availability of the learn set will be checked, based on the settings of the loaded project. 3. The source build number will be determined. The tool compares the build number taken from the project scripts with the list of supported builds. 4. The tool analyzes the INI file for existence and violations. The Classes Analysis group The Analysis procedure checks each script in the loaded source project for violations of the scripting rules for packaged projects. After the analysis processing, the user interface visualizes the results by highlighting the group: Green highlight: All items of the group have passed the analysis Red highlight: At minimum one item has failed in the analysis Each single analysis item has a record within the group. An item that has passed the analysis shows an Information icon in the row header. An item that has failed the analysis step shows a Violation icon. A double click on an item shows a message box with brief information. To retrieve more information switch to the Reports tab. 8

9 Upgrade The Upgrade requires two user interactions. Select the Template Project Insert the file name path to the SDP file into the text field or click the Select Template Project button to browse through the file system. The Next button is enabled after inserting path information and the Upgrade Project tab displays the upgrade controls. Note that a template project is a project download of a released version having an unchanged learn set and INI file. The assignment of the template project addresses the target version. Upgrade Project Click the Upgrade Project button to trigger the upgrade of the source project. There are three upgrade groups. The Pre-Requisites group In this section 1. The template project will be loaded to check if the project path leads to a valid supported project. 2. The target build number will be determined. The Tool compares the build number taken from the project scripts with the list of supported builds. 3. The tool analyzes, if the INI file exists. 4. The availability of the learn set will be checked, based on the settings of the loaded project. 5. Based on source and template build, the tool decides if a database upgrade is required or not. If required, the database connection details dialog is displayed. 6. Finally, the process creates the directory structure of the target project as a sub directory of the source project with a copy of the template project in it. 9

10 The Classes Script Upgrades group For all scripting pages, the script upgrade copies the customized scripting sections from the source project into the target project. The Transfer Customizations group In addition to the customizations in the project scripts, the source project may have also customizations in the project design. The upgrade process moves all these customizations to the target project: 1. Merge Classification Engines Changes in the Classification settings of the source project classes merge with the target project s settings. 2. Merge Fields Property changes of the source project field properties merge with the target field properties. 3. Copy additional fields New inserted fields in the source projects copy into the target project. 4. Move Verification forms Modified and new source project class forms move into the target project. Moved default forms become the default forms for target project classes. 5. Copy Additional Classes Newly created classes in the source project are copied into the target project. All related fields and Verification Forms are copied together with the classes. 6. Transfer OCR settings The source project s OCR Settings replace the OCR settings of the target project. 7. Assign Authentication Settings User and group settings created in the source project are copied into the target project. 8. Transfer Project Settings Project settings of the source project replace the target project settings. 9. Merge Learn Sets User added documents in the source learn set are added to the target learn set. The Target project learns from the enhanced target learn set. 10. Upgrade INI file (to database) Depending on the database upgrade determination (see Upgrade Pre-Requisites step 5), the source INI file values overwrite target INI file values, if database upgrade is not required. If database upgrade is required, the source INI file values overwrite the target INI file values and database values. 10

11 Cross Version Upgrade A Cross Version Upgrade is an upgrade from a version without database configuration into a version that uses database configuration. Such an upgrade differs from a regular upgrade by displaying the database configuration dialog during step 5 of the Pre-Requisites group and the processing of the database upgrade in step 10 of the Transfer Customizations group. Database Connection If a detected cross version update requires database access, a message box will appear. Accepting this message displays the database configuration dialog. Perceptive Intelligent Capture packaged projects support Microsoft SQLServer and Oracle database server as project configuration databases. Inserting the required database connection details will enable the Test Connection button, which attempts to establish a database connection using the entered details. A message box shows the connection test results. A click on the OK button continues the database upgrade configuration. If the connection test fails for any reason, there are two opportunities: A click on the Abort Migration button stops the complete upgrade process. The Project Migration Tool will report a failed upgrade. A click on the Skip DB Upgrade button allows the upgrade process to continue. The project is then migrated, but not the INI file. If the database connection configuration was successful, the upgrade process compares the database build with the upgrade target build. If the builds do not match, there are opportunities to Repeat the connection configuration, to Abort the upgrade process or to Skip the database upgrade and continue with the project upgrade. 11

12 Database Upgrade Configuration Business solutions that support multi-tenant processing require the configuration in a database. For each client the configuration assigns profiles for different features. The Project Migration Tool can create a new client into the database or overwrite an existing client. The dialog is set by default to overwrite the existing client 0. A click on the OK button allows the upgrade process to continue. A click on the Abort button stops the complete upgrade process. The Project Migration Tool reports a failed upgrade. A click on the Skip button continues with the upgrade process. In that case, the project is migrated, but not the INI file. 12

13 Best Practices Working with Violation records and Reports Clicking on a record that appears in either Analysis or Upgrade will provide a brief information about the processing step in a message box. Processing steps log detailed information into the Reports tab. Separate reports have been written for Analysis, Project Upgrade and INI/DB Upgrade. After completion of the Analysis step, the analysis report will be saved into the source project directory. The project and INI/DB upgrade reports will be saved into the target project directory, when the Upgrade process is completed. Example Analysis violation Wrong ERR definitions in INI file: In Analysis report: INI File: BW Invoices.ini ========================= - Invalid customized Error index found in INI: '164' - Invalid customized Error index found in INI: '182' - Invalid customized Error index found in INI: '198' - Invalid customized Error index found in INI: '200' - Invalid customized Error index found in INI: '899' The source INI file contains customized Error Index within the protected range (0-899) The listing shows all customized error label definitions, which are against the packaged project rules. Solution: Change the indexes to an index above 900 and correct the scripting usage according to the changes. 13

14 Example Analysis violation Scripting violation In Analysis report: Violations found for class 'PROJECT LEVEL'. Detailed analysis for 'Project Level' script Routine changed [21]: 'Public Sub ScriptModule_Initialize' Command changed [23]: Orginal: 'Call BWScriptModule_Initialize(ModuleName)' Customized: 'Dim Migration As String' Command changed [25]: Orginal: 'End Sub' Customized: 'Call BWScriptModule_Initialize(ModuleName)' Command inserted [28]: End Sub Command deleted: 'Private Sub ScriptModule_PreImport' Command inserted [78]: 'Private Sub ScriptModule_UpdateSystemSecurity' The report shows detailed information about scripting violations for each scripting page. The violations are listed for each scripting page in the form of the type and the line number of the violation (square brackets). Each Command changed [] insert is followed by the original line code and the customized line code. Solution: Correct the script according to the listing. Hint: Correct from bottom to top of the listing in order to keep the line numbers in sync. Example Upgrade failure DB Upgrade In INI/DB Upgrade report: Start Transaction: 'Upgrade' ============================================================== Execute: DELETE FROM BRWFLD WHERE ProfileID=0 65 rows affected Execute: DELETE FROM BRWEXPTax WHERE EXPProfileID=0 4 rows affected Execute: DELETE FROM BRWEXPLines WHERE EXPProfileID=0 33 rows affected Execute: DELETE FROM BRWEXPHeader WHERE EXPProfileID=0 61 rows affected: : : All SQL commands are logged into the report. : : Execute: INSERT INTO BRWSAP (ProfileID,ConnectToSAP,UseUnicodeConnection, FIInvoiceObject,FICreditObject) VALUES (0,'N0',0,,'FIIINVOICE','FIICREDIT') Transaction: 'Upgrade' Cancelled Rollback initiated, reason: Conversion failed when converting the varchar value 'N0' to data type bit. If a SQL command fails during transaction, the transaction is cancelling and is rolled back. The last listed SQL command in the report is the one which caused the failure. The report shows the reason for failing at the end of the transaction report. 14

15 Solution: Investigate the reported failure reason related to the source INI file. In the example above, the transaction fails while inserting values into the BRWSAP table. The reason is that the value N0 cannot be converted into a bit data type. Comparing the value N0 with the insert statement shows that N0 relates to the second column ConnectToSAP. 1. Find the parameter ConnectToSAP in the SAP_ section in INI file. 2. Correct the value N0 to NO ( O instead of zero). 3. Save the INI file 4. Redo the Analysis Known problems and solutions Additional inserted INI file parameters in DB upgrade New source INI file parameters added to a new INI section always will be migrated to the target INI file (e.g. CUS_VL_NewOption ). New source INI file parameters added to an existing section only will be migrated, if the parameter is an indexed parameter. Indexed means either an index number is a part of the parameter name or the parameter is indexed by a field name. A new parameter: ERR_VL_901 will be inserted into the BRWERR table as a new record. EXP_VL_DBHCNewExportHeaderField will be inserted into the BRWEXPHeader table as a new record. EXP_VL_NewExportOption will not be written into the BRWEXP table. The problem is that a customized parameter like EXP_VL_NewExportOption will disappear. The solution is to copy such parameters manually from the source to the target INI file after the migration. 15