data exchange service - docuphase

Data Exchange Service

Advanced User Manual

Version 6.1

DocuPhase Corporation

1499 Gulf to Bay Boulevard, Clearwater, FL 33755

Tel: (727) 441-8228 – Fax: (727) 444-4419

Email: [email protected]

Web: www.DocuPhase.com

http://www.idatix.com/

Data Exchange Service Advanced User Manual 6.1 of 20

Copyright © 2000 – 2017, DocuPhase Corporation, All rights reserved.

All rights reserved. No part of the contents of this publication may be reproduced,

transmitted, transcribed, stored in a retrieval system, or translated into any

language in any form without written consent from DocuPhase Corporation.

This software product, including the manual and media, is copyrighted and contains

proprietary information that is subject to change without notice. The software may

be used or copied only in accordance with the terms of the license agreement.

DocuPhase is a registered trademark of DocuPhase Corporation. All other trademarks

are acknowledged as the exclusive property of their respective owners.

Version 6.1 – 1.23.2017


Table of Contents

Introduction ................................................................................ 4

Welcome to Data Exchange Service ............................................. 4

Purpose and Assumptions .......................................................... 4

Foundational Terminology .......................................................... 4

Client Support Services Contact Information ................................. 6

Data Exchange Service Product Overview ....................................... 7

Key Functionality .................................................................... 7

Routing of Documents to the Data Exchange Service ................... 8

Configure Data Exchange Service ................................................. 11

Understanding the Config.xml .................................................... 12

Multi-Query Data Exchange Example .......................................... 15

Data Sync Task Editor – Test Capability ...................................... 19

Appendix A: Data Exchange Service Installation ............................ 20

Prerequisites & Minimum Requirements ...................................... 20


Introduction

Welcome to Data Exchange Service

The DocuPhase Data Exchange Service is a status-driven utility that copies data

between databases using standard ODBC connections and SQL queries.

Data can be pushed into or pulled out of these databases providing a method for

automating the indexing process as documents are captured and sent to the

DocuPhase Repository.

Data Exchange Service is a Windows Service that runs in the background on the

installed machine and the operations it performs are determined by an XML

configuration file that specifies what to do with each DocuPhase document it

processes.

Data Exchange Service requires no user interaction other than initial configuration,

start and stop operations. However, the Data Exchange Editor also provides a

designer-interface and functionality for interactively testing database-network

connections that will be used by Data Exchange to verify that these connections are

operational.

Purpose and Assumptions

This manual has been written for the advanced administrative user to prepare them

to install, configure and use the Data Exchange Service product.

The following are assumptions made with regard to the reading audience for this

guide:

The reader has received at least one week of DocuPhase provided training.

The reader has used the DocuPhase DocuPhase software product for a period

of no less than one month.

Foundational Terminology

DSN: A Database Source name (DSN) is an object with a data structure that

contains information about a specific source for data such as a database that an

Open Database Connectivity (ODBC) driver uses to connect to it. A DSN stores

information such as:

Name of the data source

Directory of the data source

Name of a driver which can access the data source

User ID for database access (supplied by Data Exchange config.xml)

User password for database access (supplied by Data Exchange config.xml)

The site network administrator creates a separate DSN for each relevant data

source. To connect to a particular data source, programs with ODBC capabilities like

Data Exchange, ScanDox or BarCoder can be configured using the DSN name as a

simple way to establish a network connection to the required database.


Index: In DocuPhase, an Index is similar to a label found on a traditional paper file

folder’s tab. Index fields stored on DocuPhase database records are used to

describe each document of images or media files that are linked to these records.

Index fields contain values that are used in search criteria to locate documents,

describe a documents type and status as well as other information that is used by all

products in the DocuPhase Platform.

Index fields in the DocuPhase database may be entered (i.e., indexed), viewed and

edited by users and automation with the appropriate permissions.

However, one or many index fields may be associated with an electronic document or

image stored in DocuPhase which greatly improves the search and retrieval power of

electronic technology over traditional file cabinets with a single index employing

manual filing and retrieval methods.

Indexing: Data entry by manual or automatic database lookup as a means to

complete DocuPhase document index fields is an activity called indexing.

Data Exchange is one of the DocuPhase methods for performing automatic database

lookup and automatically updating DocuPhase index fields for the current document

being processed.

After completion of the entry for all required index field and possibly more or all

indexes, a document or file may be submitted to DocuPhase for storage,

management and protection.

SQL: Structured Query Language (SQL) is a database computer language designed

for accessing and managing data in Relational Database Management Systems

(RDMS) with its origins based upon a relational algebra developed by Edgar F. Codd

in 1970.

The term is officially pronounced as “S-Q-L”, but is also referred to as “Sequel”.

SQL has evolve along with Open Database Connectivity Standards (ODBC) to be the

“interface of choice” for connecting and integrating with SQL-compliant databases

across local and wide-area networks.

Object Status: The Object Status index field is a built-in system index used by

DocuPhase and other components in its product suite to identify the current state of

each document in DocuPhase. The Object Status field contains one letter or numeric

digit and is primarily used to route documents among components based on its

current value setting.

Administrators and installers of the DocuPhase solution have the flexibility to assign

Object Status index field codes as the incoming status for components and routings

upon successful or failure results.

The Object Status index can also be used in DocuPhase Search Criteria.

XML: Extensible Markup Language (XML) is a set of rules for encoding documents in

machine-readable form. The design goal for XML is to emphasize simplicity,

generality, and usability over the Internet plus it is widely used for the

representation of arbitrary data structures, for example in web services and

configuration files such as used by Data Exchange.


Client Support Services Contact Information

DocuPhase is committed to providing quality service and support for our customers.

If you are experiencing difficulty with your DocuPhase software, please let us hear

from you so we can help.

Client Support Services are provides as part of your Maintenance Program. Enhanced

support programs are available upon request. The standard support feature set

includes:

Product Updates and Upgrades

Telephone and Email support during local business hours

Remote Connect Support during local business hours

You may:

Contact us by email at [email protected].

Reach us by phone at (727) 441-8228.

Reach us by fax at (727) 444-4419.

Find us online at www.DocuPhase.com/support.

mailto:[email protected]

http://www.idatix.com/support


Data Exchange Service Product Overview

The DocuPhase Data Exchange operates as a service module that primarily performs

lookup operations on external databases to obtain index values that it uses to update

index fields for documents in DocuPhase. However, it can also be used to update

external databases when required and authorized.

Key Functionality

Data Exchange Service provides the following key features:

The ability to both Access and Update information in external databases and

the DocuPhase database using Microsoft ODBC Standards for Open Database

Connectivity and SQL Standards.

Key index fields that have been previously indexed can be used to retrieve

additional related index values from external ODBC/SQL databases containing

operational data used by your organization.

The retrieved index information is used by Data Exchange to update

corresponding index fields in the DocuPhase database; thereby, indexing

additional index fields for the current document being processed.

Data Exchange is able to determine the appropriate operations for the current

document’s document type and application type by interpreting specifications

provided by the DocuPhase administrator user in the Config.xml file for the

Data Exchange Service.

When required, the Config.xml file can be configured with specifications that

will use the information obtained to update external databases other tha

DocuPhase when suitably configured with appropriate SQL commands and

database access codes.

Data Exchange, in its normal background operation, does not have a user-interface,

but relies on configuration specifications defined using XML in a Config.xml file by a

DocuPhase administrator user.

However, the Data Exchange Editor component provides a new designer-interface

and functionality for interactively testing database-network connections that will be

used by Data Exchange to verify that these connections are operational.


Routing of Documents to the Data Exchange Service

As various DocuPhase products, including Data Exchange, are configured to

determine how documents are processed and routed based on the Object Status

index field, other Status index fields and hot folders.

Fixed Object Status Codes:

C - Corrupted Document in Archive

E - Submit or Searchable in DocuPhase

I - Routed to Individual or Group InBox

P - Routed as Pending Indexing

X - Soft-Deleted Document in Archive

Y - Source Document in Archive that is

Replaced by its Split-Out Documents

Standard Object Status Codes:

A - Routed to Extractor

M - Routed to Multi-Function Service

R – Routed to Data Exchange

V – Routed to RapidDoc (a legacy product or used for other purposes)

The Fixed Object Status Code assignments are hard-coded and fixed in the system

so they must be used as assigned.

However, the Standard Object Status Codes used by administrators for each

installation are flexible allowing single-character code values to be re-assigned and

other letters and digits which may also be used by making the proper configuration

settings.

For purposes of examples in this manual, these fixed and standard Object Status

Code values will be used.

The following diagram provides an example of the DocuPhase document routing

concept where a scanned document has its Object Status index field updated at each

step in the path to take it from ScanDox to Xtractor; then to Data Exchange and

finally submission as an indexed document in DocuPhase.


In the above example design, the following functions take place in sequence:

P-Status: Using ScanDox for purposes of this example, we will assume that

the ScanDox profile selected will retain the Barcoder cover page on the front

of each document scanned so that the Index information can be accurately

and automatically read in step 2 (Xtractor) once the document is successfully

processed and released or uploaded after scanning and any indexing by

ScanDox with an A-Status.

A-Status: Xtractor receives the TIFF document to perform the OCR and

Barcode reading operations to identify the document and the other operations

that have been configured for it to perform for this type of document. The

configuration for this type of document specifies:

On Success: the Object Status is set to “R” for Data Exchange

processing.

On Failure: the Object Status is set to “P” to allow manual re-indexing

and review by an operator.

R-Status: Data Exchange receives the document for database Look-up and

Index Field update processing based on the configuration defined for this

document’s DocuPhase Application.

On Success: the Object Status is set to “E” for Submission or return to

DocuPhase as a searchable document.

On Failure: the Object Status is set to “P” to allow manual re-indexing

and review by an operator.

E-Status: The document is submitted to DocuPhase making it part of the

searchable documents protected and secured by DocuPhase, if it is not

already submitted.

E

ScanDox Xtractor

iDox

Multi-Function Service

“iDox-In”Hot Folder

InBoxes

A B C

RapidDox

iSynergy

Data Exchange

iSynergy

Scan or Drag & DropDocument Files

P

M

A

E

R

An Example of Flexible Routing for Captured Documents

AmongiDatix Products & Services

ViaHot Folders & Object Status Codes

I

E C-Status – Corrupt Content Image/File

--- Inactive Archive in iSynergy ---

On Success

On Success

On Success

iSynergyIndexing Page

P

C-Status – Corrupt Content Image/File

C

Scan or Drag & DropDocument Files DocuPhase

Indexing Page

ScanDox

iDox


Note: The example above illustrates the use of “Cascading Status” result

codes which dynamically determine the routing of a document during its

lifecycle in DocuPhase.

As each case is configured in each of the components by the installation and

DocuPhase administrator staff, a success and failure status is defined or

defaulted for each component and its cases. As the document is processed

and its routing follows a path dynamically determined by the success and

failure status codes that result – so flows the document.

Likewise, the documents received and processed by iDox successfully can be routed

to Data Exchange for database operations by using the R-Status routing.

In the next section, the specifications needed to configure Data Exchange are

described using XML to create its Config.xml file that defines what operations will be

performed on each external databases.

The Administrator User will need to configure the following:

Use the Microsoft Control Panel network configuration tools to define and

name the Database Source Name (DSN) objects that will be used by Data

Exchange to access DocuPhase and External Databases, unless they already

exist.

Note: The same DSN objects for a site may be used by the client’s

applications as well as Data Exchange, ScanDox or BarCoder which have

ODBC capabilities.

Object Status Routings XML Specifications for:

Incoming Status (e.g., R)

Outgoing Status (e.g., E)

Error Status (e.g., P)

ODBC DSN Name to Connect with Databases in XML:

DocuPhase Database

Remote Database DSNs to Connect with External Client Databases

Indicate whether the SQL Command via ODBC is:

A “Push” Command (e.g., such as an SQL Execute Statement) or

A “Pull” Command (e.g., such as a Lookup Select SQL Statement)

SQL Statements for External Database Lookups and operations in XML can

include:

SQL Select Statements

SQL Update Statements

SQL Insert Statements

SQL Execute Statements

Mapping of Corresponding Database Fields and DocuPhase Index Fields in

XML:

The External Client Database is referred to as the “RemoteField”

The DocuPhase Index Field is referred to as the “DocuPhaseField”


Configure Data Exchange Service

Data Exchange Service is configured by editing the config.xml file located in the

directory where the program executable files are installed.

Each portion of the config.xml file begins with a tag identifying the start of the line,

or lines, contained within that portion. Likewise, each portion finishes with a tag

identifying the end.

The following is an example of a typical config.xml file.


Understanding the Config.xml

The following information has been provided to give a detailed explanation of the

Data Exchange Service example config.xml.

Element Data Exchange Config.xml Description

Section

One

Required:

States the type of configuration format, (xmlns=), the type of query, (<query

type="pull"), and a brief description of the purpose of the query,

(name="Retrieve DocuPhase indexes from Remote Data ">).

Section

Two

Optional:

This section is currently not in use.

Section

Three

Required:

This section is configured to identify the status codes for the records that the

Data Exchange Service looks for in the DocuPhase database table specified in

section four, (<incomingStatus>R</incomingStatus>).

This section also contains the settings for the status codes that Data

Exchange Services sets the records to for failed queries,

(<errorStatus>P</errorStatus>), and successful ones,

(<outgoingStatus>E</outgoingStatus>).



Section

Four

Required:

Section four contains the settings for configuring the ODBC connection to

connect to the DocuPhase database.

These settings include:

The DSN Name, (<DocuPhasedsn>SQLESpeed</DocuPhasedsn>).

Username, (<DocuPhaseuser>espeed</DocuPhaseuser>).

Password, (<DocuPhasepassword>deepse</DocuPhasepassword>).

DocuPhase Application table name,

(<DocuPhaseapp>_obj_3</DocuPhaseapp>).

Section

Five

Required:

Section five contains the settings for configuring the ODBC connection to

connect to the Remote database.

These settings include:

The DSN Name, (<remotedsn>RemoteDSN</remotedsn>).

Username, (<remoteuser>RemUsr</remoteuser>).

Password, (<remotepassword>RemPass</remotepassword>).



Section

Six

Required:

Section six consists of an SQL query worded to return the required records

from the Remote database, or to perform the required functions on the

remote database. Detailed knowledge of the structure and names of the

tables and fields within the Remote database is essential to word a correct

SQL query.

The query can be any valid SQL statement, including, but not limited to,

Select, Update, Insert, and Execute statements.

Additional assistance with the correct syntax of an SQL query

can be obtained by contacting DocuPhase Customer Support at

[email protected].

mailto:[email protected]


Multi-Query Data Exchange Example

This section provides an XML example of a multi-query Data Exchange Config.xml

specification with explanation.

This example illustrates how multiple ODBC lookup specifications can be placed in

the same Config.xml file to server different purposes for the same DocuPhase

Application as well as different Applications.

The following diagram describes the Remote Client database and the DocuPhase

Index Fields that are maintained in the DocuPhase database.

In this example, all of the operations will query (i.e., “Pull” from) the Remote Client

database to obtain data values to map onto the appropriate DocuPhase index fields

for each type of document to be processed by Data Exchange.

Note: In other situations, Data Exchange can pull and update information in

either direction plus utilize whatever SQL-compliant databases that you

specify in the config.xml file.

The first two query specifications both update indexes in the DocuPhase Payments

Application although the information in each case is pulled from a different table of

the same Remote Client database.

Payments iSynergy Application(_obj_2 DB Table)

IDX_Check_Number – Key Index IDX_Name – Destination Index

HR iSynergy Application(_obj_3 DB Table)

IDX_SSN – Key Index IDX_employee_name – Destination Index IDX_employee_date – Destination Index

Config.xml

Data Exchange

iSynergy(eSpeed)Database

Remote/ExternalClient Database

Checks DB Table: Cknum - Lookup Key ccoName - Source Data

ChecksArchive DB Table: archCknum – Lookup Key archName – Source Data

Employees DB Table: empNum – Lookup Key empName – Source Data empHireDate – Source Data

Example Pulling Data from Remote DB to Update iSynergy Indexesfor the Current Document Processed by Data Exchange

ClientDSN iSynergyDSN

ODBC Access

DocuPhaseDatabase

External/RemoteClient Database

ClientDSN DocuPhaseDSN

Payments DocuPhase Application:

HR DocuPhase Application:

Example Pulling Data from a Remote DB to Update DocuPhase Indexesfor the Current Document Processed by Data Exchange


Each of these specifications are defined as XML-Elements, but they are summarized

in the flowchart below. The same flowchart also summarizes the operations

performed when a document from the DocuPhase HR application is being processed.

In each of the three example cases, the XML-Element specifies the Incoming Status

value and the DocuPhase Application database table name that applies to distinguish

which XML-Element should be applied for the current document.

The NeedsQuotes parameter to the mapping function indicates whether the field

contents needs the use of quotes to insure no translation when assigning the

retrieved data to its corresponding DocuPhase index field.

As you will see in the Config.xml listing shown below, additional XML attributes

define other required parameters that are needed by Data Exchange to complete

each of the three specifications in the Config.xml file that direct its operations.

Note: The data contained within the XML specification has been highlighted in

Bold & Blue font to make it easier to see how the parameters explained above

are specified in XML for the Data Exchange Config.xml file.

Note: During the 6.x iSynergy to DocuPhase transition, ‘iSynergy’ may continue to be used in the place of ‘DocuPhase’ as referenced in the above flowchart and the following XML example.

IncomingStatus= “R” AND

iSynergyApp= “_obj_2”

Query “Type = “pull” name =“1st Retrieval …”

SELECT ccoName FROM Checks WHERE Cknum = {IDX_Check_Number}

mapping RemoteField=“ccoName”iSynergyField=“IDX_Name”NeedsQuotes=“true”

Yes

No

IncomingStatus= “R” AND


Query “Type = “pull” name =“3rd Retrieval …”

SELECT empName, empHireDateFROM Employees WHERE empNum = {IDX_SSN}

mapping RemoteField=“empName”iSynergyField=“IDX_employee_name”NeedsQuotes=“true”

mapping RemoteField=“empHireDate”iSynergyField=“IDX_employee_date”NeedsQuotes=“true”

Yes

No

IncomingStatus= “1” AND


Query “Type = “pull” name =“2nd Retrieval …”

SELECT archName FROM ChecksArchiveWHERE archCknum = {IDX_Check_Number}

mapping RemoteField=“archName”iSynergyField=“IDX_Name”NeedsQuotes=“true”

Yes

No

Exit

Start

ObjectStatus =

“P”

If Error?

ObjectStatus = “E”

Yes

No

Exit

DocuPhaseAppDocuPhaseApp

DocuPhaseApp

DocuPhaseApp

DocuPhaseField=“IDX_Name”NeedsQuotes=“true”

DocuPhaseField=“IDX_Name”NeedsQuotes=“true”

DocuPhaseField=“IDX_employee_date”NeedsQuotes=“true”

DocuPhaseField=“IDX_employee_name”NeedsQuotes=“true”


*** Start of Config.xml Example Specification ***

<configuration xmlns="http://tempuri.org/config.xsd">

<query type="pull" name="1st

Retrieval of DocuPhase indexes from Remote Data">

<incomingStatus>R</incomingStatus>

<errorStatus>1</errorStatus>

<outgoingStatus>E</outgoingStatus>

<DocuPhasedsn>DocuPhaseDSN</DocuPhasedsn>

<DocuPhaseuser>sa</DocuPhaseuser>

<DocuPhasepassword>DocuPhase</DocuPhasepassword>

<DocuPhaseapp>_obj_2</DocuPhaseapp>

<remotedsn>ClientDSN</remotedsn>

<remoteuser>sa</remoteuser>

<remotepassword>DocuPhase</remotepassword>

<connectiontimeout>45</connectiontimeout>

<remotequery>SELECT ccoName FROM Checks WHERE cknum = {IDX_Check_Number}</remotequery>

<mappedFields>

<mapping RemoteField="ccoName" DocuPhaseField="IDX_Name" NeedsQuotes="true" />

</mappedFields>

<checkedFields>

</checkedFields>

</query>

<query type="pull" name="2nd


<incomingStatus>1</incomingStatus>

<errorStatus>P</errorStatus>










<remotequery>SELECT archName FROM ChecksArchive WHERE archCknum = IDX_Check_Number}</remotequery>


<mappedFields>

<mapping RemoteField="archName" DocuPhaseField="IDX_Name" NeedsQuotes="true" />

</mappedFields>

<checkedFields>

</checkedFields>

</query>

<query type="pull" name="3rd


<incomingStatus>R</incomingStatus>

<errorStatus>P</errorStatus>










<remotequery>SELECT empName, empHireDate FROM Employees WHERE empNum = {IDX_SSN}</remotequery>

<mappedFields>

<mapping RemoteField="empName" DocuPhaseField="IDX_employee_name" NeedsQuotes="true" />

<mapping RemoteField="empHireDate" DocuPhaseField="IDX_employee_date" NeedsQuotes="true" />

</mappedFields>

<checkedFields>

</checkedFields>

</query>

</configuration>

*** End of Config.xml Example Specification ***


Data Sync Task Editor – Test Capability

Since the Data Sync Service runs in the background as an automatic unattended

process, the Progression Designer’s Data Sync Editor provides an interactive

interface that allows the Progression designer to test and confirm that the integration

with external SQL databases is working correctly since the Data Exchange service

executes these services in support of Data Sync Tasks at run-time.

The Data Sync Editor in Progression makes it easy to enter literal values and

reference available DocuPhase and external database metadata to create expressions

and SQL queries to execute and test.

The selection of multiple database fields and the creation of conditional SQL queries

create expressions that can be tested and utilized in workflow designs.

For detailed information on the Data Sync Task Editor and its ability to define and

test both ODBC Data Field Requests and Web Services Data Field Requests, see the

Progression Advanced User Manual, sections:

Workflow Building Blocks>Task Definition>Task Types>Data Sync Task


Appendix A: Data Exchange Service Installation

Prerequisites & Minimum Requirements

The following Data Exchange Service installation consideration topics are

documented in the following locations:

Minimum Requirements: See DocuPhase Prerequisites Guide

Prerequisites: See DocuPhase Prerequisites Guide

Data Exchange Service Installation from .MSI:

Data Exchange Service

See: DocuPhase Installation & Upgrade Guide,

Note: The installation process will complete and start the Data Exchange Service.