Database Deploymentfor OpenDeploy

Administration Guide

Release 6.0.2

1997-2005 Interwoven, Inc. All rights reserved.

No part of this publication (hardcopy or electronic form) may be reproduced, translated into another language, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc. and may only be used in accordance with the terms of the license agreement. If this software or documentation directs you to copy materials, you must first have permission from the copyright owner of the materials to avoid violating the law which could result in damages or other remedies.

Interwoven, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, iManage, LiveSite, MediaBin, MetaCode, MetaFinder, MetaSource, OpenTransform, Primera, TeamPortal, TeamXML, TeamXpress, VisualAnnotate, WorkKnowledge, WorkDocs, WorkPortal, WorkRoute, WorkTeam, the respective taglines, logos and service marks are trademarks of Interwoven, Inc., which may be registered in certain jurisdictions. All other trademarks are owned by their respective owners. Some or all of the information contained herein may be protected by patent numbers: US # 6,505,212, EP / ATRA / BELG / DENM / FINL / FRAN / GBRI / GREC / IREL / ITAL / LUXE / NETH / PORT / SPAI / SWED / SWIT # 1053523, US # 6,480,944, US# 5,845,270, US #5,384,867, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, BEL #480941, BRAZ #PI9007504-8, CAN #2,062,965, DENM / EPC / FRAN / GRBI / ITAL / LUXE / NETH / SPAI / SWED / SWIT #480941, GERM #69020564.3, JAPA #2968582, NORW #301860, US #5,065,447, US #6,609,184, US #6,141,017, US #5,990,950, US #5,821,999, US #5,805,217, US #5,838,832, US #5,867,221, US #5,923,376, US #6,434,273, US #5,867,603, US #4,941,193, US #5,822,721, US #5,845,270, US #5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, GERM #69902752.7or other patents pending application for Interwoven, Inc.

This Interwoven product utilizes third party components under the following copyrights with all rights reserved: Copyright 1997 Eric Young; Copyright 1995-1999, The Apache Group (www.apache.org); Copyright 1999, ExoLab Group; Copyright 1999-2001, Intalio, Inc. If you are interested in using these components for other purposes, contact the appropriate vendor.

Interwoven, Inc.803 11th Ave. Sunnyvale, CA 94089

http://www.interwoven.comPrinted in the United States of America

Release 6.0.2Part #90-25-00-602-300March 2005

Table of Contents

About This Book 7Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Other OpenDeploy Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

OpenDeploy Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9OpenDeploy Administration Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9OpenDeploy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9OpenDeploy Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Online Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1: Introduction 11Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Required Database Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Introductory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

XML for Defining Structured Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Database for Storing Structured Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Mapping the XML Representation to the Database Schema. . . . . . . . . . . . . . . . . . . . . 15Deploying XML to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Use Case Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Migration Notes for DataDeploy 5.6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Migration Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20DataDeploy Administration User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Invoking DataDeploy Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21iwsyncdb.cfg File Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Discontinued DataDeploy Commands and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Running DataDeploy in Threadperbranch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23OpenDeploy-DataDeploy Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . 23DataDeploy Module Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Required Locations for Deployment Configuration and Schema Files . . . . . . . . . . . . . . 23Running DAS with DataDeploy 5.6 and OpenDeploy 6.0 on the Same Host . . . . . . . . . 24New Usage of TuplePreprocessor and ExternalDataSource . . . . . . . . . . . . . . . . . . . . . 24

Chapter 2: Deployment Concepts 25User-Defined Database Schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25An Example: UDS vs. Wide Table Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Implementation of a UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Sample Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Update and Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Data Organization and Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Deployment Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

Chapter 3: Configuration Files 47Mapping a Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Mapping a Database Schema with the Browser-Based User Interface . . . . . . . . . . . . . . 47Updating an Existing Database Schema File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Mapping a Database Schema with iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Creating the DataDeploy Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Using the Browser-Based User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Using the iwsyncdb -ddgen Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Deploying Multiple XML-Formatted Files as a List of Filelists. . . . . . . . . . . . . . . . . . . 62

Sample Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63TeamSite to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63TeamSite to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66TeamSite Extended Attributes to Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67TeamSite Extended Attributes to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69TeamSite and TeamSite Extended Attributes to Database . . . . . . . . . . . . . . . . . . . . . . 70XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72XML to XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Database to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Specifying Database Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Database Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Deploying Metadata to UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Changing Default Datatype Size on Internal Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 4: Database Auto-Synchronization 81Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Using Multiple Instances of OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Editing database.xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Editing Deployment Configuration File Templates and drop.cfg . . . . . . . . . . . . . . . . . 84Editing iw.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

OpenDeploy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Configuring DAS in the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Specifying DAS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86DAS Setup for Template Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87DAS Setup for Metadata Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Configuring DAS Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Running iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

The Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Configuring the Event Subsystem with the Browser-Based User Interface. . . . . . . . . . . 92Configuring the Event Subsystem Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Logging Options for Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Generating DAS Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Using DAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Table Update Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Specifying How Tables are Updated. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Table Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Database Object Name Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103DAS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Configuring TeamSite Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054 Database Deployment for OpenDeploy Administration Guide

Database Virtualization Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106DAS and Metadata Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

DAS Out-of-Sync Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Chapter 5: DataDeploy Deployments 109Standalone Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Server Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Database Deployment Configuration and Execution . . . . . . . . . . . . . . . . . . . . . . . . 111Specifying an Alternate TeamSite Mount Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Target-Side Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Server Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Chapter 6: Advanced Features 121Deploying Data as Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Deploying Data as Database Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Deploying Data as Database Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Filters and Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Setting Up Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Setting Up Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Deploying Replicants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Replicant Order Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Deploying Comma Separated Lists of Values as Replicants . . . . . . . . . . . . . . . . . . . . 133Deploying Multiple Replicants from Multiple Nesting Levels . . . . . . . . . . . . . . . . . . 141

Enhancing Deployment Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141External Tuple Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141External Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Deploying URL Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Miscellaneous Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Deploying Custom Data Content Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Encoding Database Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Real Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Executing a Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Executing Arbitrary Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Appendix A: Sample Configuration File 163The Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163The Sections of the Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

1. Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672. Filter Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673. Substitution Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684. Client Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685. Deployment Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686. Source Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687. Source Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688. Location of Source Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695

9. Substitution Section (In-Flow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

10. Destinations Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16911. Database Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16912. Rows to Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17013. Update Type and Related Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17114. Columns to Update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17115. SQL Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17116. Server Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Appendix B: Database Deployment Tutorials 173Standalone Deployment Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

OpenDeploy Base Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Deployment Example: Custom XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . 175

DAS Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Event Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181TeamSite Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Behavior On Other Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Appendix C: Database Deployment Internal Tables 189IWTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189IWDELTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189IWOV_IDMAPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190IWTMP_LOB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Glossary 191

Index 1956 Database Deployment for OpenDeploy Administration Guide

About This Book

Database Deployment for OpenDeploy Administration Guide is a guide for configuring and running OpenDeploy to deploy structured content to a database within the OpenDeploy environment. Certain database deployment tasks require the licensing of the DataDeploy module.

If you are using OpenDeploy in conjunction with TeamSite, you should also know TeamSite functionality and terminology. Many of the operations described in this manual require root or Administrator access to the OpenDeploy server host. If you do not have root or Administrator access to the OpenDeploy server host, consult your system administrator.

This manual uses the term Windows to indicate any supported version of the Microsoft Windows operating system, such as Windows NT or Windows 2000.

This manual uses the term UNIX to indicate any supported flavor of the UNIX operating system.

Windows: Users should be familiar with either IIS or Netscape Web servers, and with basic Windows server operations such as adding users and modifying Access Control Lists (ACLs).

UNIX: Users of this manual should be familiar with basic UNIX commands and be able to use an editor such as emacs or vi.

It is also helpful to be familiar with regular expression syntax. If you are not familiar with regular expressions, consult a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.7

Notation Conventions

This manual uses the following notation conventions:

Convention Definition and Usage

Bold Text that appears in a GUI element (for example, a menu item, button, or element of a dialog box) and command names are shown in bold. For example:

Click Edit File in the Button Bar.

Italic Book titles appear in italics. Terms are italicized the first time they are introduced.Important information may be italicized for emphasis.

Monospace Commands, command-line output, and file names are in monospace type. For example:

The iwodstart command-line tool starts an OpenDeploy deployment task.

Monospaced italic

Monospaced italics are used for command-line variables.For example:

iwodstart deployment

This means that you must replace deployment with your values.Monospaced bold Monospaced bold represents information you enter in response to

system prompts. The character that appears before a line of user input represents the command prompt, and should not be typed. For example:

iwodstart

Monospaced bold italic

Monospaced bold italic text is used to indicate a variable in user input. For example:

iwodstart deployment

means that you must insert the values of deployment when you enter this command.

[] Square brackets surrounding a command-line argument mean that the argument is optional.

| Vertical bars separating command-line arguments mean that only one of the arguments can be used.8 Database Deployment for OpenDeploy Administration Guide

Other OpenDeploy DocumentationOther OpenDeploy Documentation

In addition to this Database Deployment for OpenDeploy Administration Guide, OpenDeploy includes the following documentation components:

OpenDeploy Installation Guide

OpenDeploy Administration Guide

OpenDeploy Reference

OpenDeploy Release Notes

Online help

OpenDeploy Installation Guide

OpenDeploy Installation Guide is a manual that contains installation, and server and host configuration information for OpenDeploy.

OpenDeploy Administration Guide

OpenDeploy Administration Guide is a guide to configure and run OpenDeploy deployments. . It is primarily intended for webmasters, system administrators, and those involved in deploying content between development servers and production servers.

OpenDeploy Reference

OpenDeploy Reference is a manual that contains reference material on topics such as configuration DTDs, command-line tools (CLTs) and ports. Use this manual to find information on a specific reference topic quickly and easily.

OpenDeploy Release Notes

OpenDeploy Release Notes contains supplemental and late-breaking information regarding OpenDeploy not found in the other documentation. Refer to the OpenDeploy Release Notes for information regarding supported platforms, installation requirements, new features and enhancements, and known issues.

Online Help

OpenDeploy includes online help topics associated with each window in the OpenDeploy user interface. You can access the associated help topic by clicking the Help link in the upper right-hand corner of the window. The help topic will appear in a separate browser window that you can move and resize. You can display a navigation panel that provides you access to all the help topics by clicking the Show Navpane button. This panel provides you the ability to access help topics through the contents, index, and by using keyword searching. 9

10 Database Deployment for OpenDeploy Administration Guide

COpenDeploy must have the following privileges when accessing a database: insert

update

delete

create table

create view

query permissionshapter 1

Introduction

XML and relational databases have each become important components of applications that define and store structured content. XML can be used to define the structure of various kinds of content, such as metadata, which describe the characteristics of files or content that is rendered by a web application. Relational databases are typically used to support business critical applications, such as airline reservation systems, customer self-help portals, and online retail catalogsall of which rely on dynamic content. The challenge that arises is how to reliably and effectively deploy XML-based content to a database.

OpenDeploy addresses this challenge by enabling the distribution of structured content to databases that support business applications, personalization servers, enterprise portals and search engines. This is accomplished through the OpenDeploy DAS feature and the DataDeploy add-on module. These capabilities bridge the gap between XML and relational databases by mapping and delivering XML content based on any DTD to any relational schema. The entire process is configurable so that no coding is required.

Installation

Database Auto-Synchronization (DAS) is an integrated feature of the OpenDeploy base server. DataDeploy is a licensed add-on module to the OpenDeploy base server. Both of these capabilities are described later in this chapter. Refer to Enabling the DataDeploy Module on page 68 in the OpenDeploy Installation Guide for details about enabling the DataDeploy module.

Required Database Privileges11

IntroductionInvocation

DAS is invoked through TeamSite events using the Event Subsystem. See Chapter 4, Database Auto-Synchronization on page 81 for more information on DAS.

Database deployments using the DataDeploy module are performed in the same manner as other OpenDeploy deployments:

From the browser-based user interface.

From the command line using iwodcmd start. Note that if you are using the -k "key=value" option, use of the parameter iwdd is required to invoke DataDeploy deployment. The parameter iwdd is reserved for performing a deployment of a DataDeploy configuration.

As a Web services call using ContentServices for OpenDeploy.

Refer to the OpenDeploy Administration Guide for more information on these invocation methods.

Usage

Data deployment supports the following uses:

Standalone XML is flexible enough to define the structure of any content. Using OpenDeploy's data deployment capabilities, user-defined DTDs can be mapped to user-defined database schemas. XML data residing anywhere in the file system can then be deployed to databases.

Synchronized deployment synchronization of file and database assets guarantees the integrity of static and dynamic content. Common examples include:

Files with associated metadata for use by a search engine.

Online catalog content along with web presentation templates.

Documents and personalization data for a portal.

JSP code and related data for an application server.

OpenDeploy provides cross-platform, transactional transfer of file assets to multiple servers. It can also be configured to deliver database content together with file system assets. If any part of the deployment transaction fails, the database and files are automatically rolled back.12 Database Deployment for OpenDeploy Administration Guide

Usage TeamSite content managed within TeamSite may be assigned metadata, also known as extended attributes (EAs). Data deployments can be configured to extract EAs and deploy them to a target database. This allows content creators to synchronize the content in their workareas with the metadata in their development or test database. It is also possible to deploy EAs to production databases, typically at the same time the content they describe is being distributed to production servers.

TeamSite Templating content creation often entails filling out template forms with information that is subsequently rendered by an application. For instance, details about a particular product in an online catalog might be entered into a template form and then displayed by an application in a web page. Content that is captured by templates is considered dynamic because it is filled in automatically by the web application at run time. TeamSite Templating allows the definition of templates that are displayed to content creators. After data is entered into a template, it is saved as an XML-based file called a data content record (DCR). Data deployments can be configured to extract DCRs from the TeamSite repository and deploy them to a target database. If there are associated EAs, they can be deployed as well. DCR deployment maintains synchronization of dynamic content that is managed within TeamSite and is available in development, test, or production databases.

MetaTagger metadata can be defined and captured using MetaTagger. The metadata created using MetaTagger is XML content based on a particular DTD. Data deployments can be configured to deploy this metadata from TeamSite or from a standalone file system to a target database. The ability to automatically map and distribute metadata ensures that search engines, personalization servers and other metadata-based applications have the most up-to-date and accurate content.13

IntroductionIntroductory Concepts

This section illustrates the relationship between XML and relational databases and how OpenDeploy bridges the two. An example is provided that introduces the following data deployment concepts:

XML for defining structured content

Database for storing structured content

Mapping the XML representation to the database schema

Deploying XML to the database

XML for Defining Structured Content

XML is a flexible text format for expressing content structure. The rules that govern the structure of a particular XML representation are typically defined in a DTD, which defines a hierarchy of elements. Each element may contain a list of attributes.

For example, consider the use of metadata for describing a sales report. Metadata can help users easily find the report based on various search criteria. So, the first step is to define the structure of the metadata in a DTD, and to then capture the actual metadata for a particular report using XML. The DTD could be defined as follows:

Essentially, our metadata element has a title attribute and contains one or more descriptor elements. Each descriptor element has a code, vocabulary and label attribute. The corresponding XML for our specific sales report might appear as follows:

14 Database Deployment for OpenDeploy Administration Guide

Introductory ConceptsDatabase for Storing Structured Content

Relational databases are commonly employed as repositories for structured content required by business-critical applications. In our example, metadata is used to drive a search engine. The database schema for our example is organized as follows:

A metadata table stores report names and their symbols.

A descriptor table contains vocabulary and tag details for each symbol.

The tables would appear as follows if populated with the data in our XML example:

Table 1: Metadata Table (md)

Table 2: Descriptor Table (desc)

The metadata table is the primary table and the descriptor table is its child table. The primary and foreign key columns are used for joining the two tables. For example, a search for all reports pertaining to Americas should return Sales in Northern California.

Mapping the XML Representation to the Database Schema

OpenDeploy deploys the deployment of XML-based content into relational databases. This requires a schema mapping that tells OpenDeploy how to write XML elements and attributes into the database tables.

The objective in our metadata example is to map the XML-based attributes to the appropriate columns of the two database tables. In other words:

Report Symbol (primary key)

Sales in Northern California AG

Sales in Northern California 06

Sales in Northern California A

Sym (foreign key) Vocab Tag

AG Regions Americas

06 FIPS5-2 California

A Territory West

This XML element/attribute maps to this table/column

metadata/title md/reportdescriptor/code md/symbol (primary key)descriptor/code desc/sym (foreign key)descriptor/vocabulary desc/vocab15

descriptor/label desc/tag

IntroductionThe schema mapping is an XML file that contains a group element for each database table. You can write your own schema or have OpenDeploy generate one for you. Also, the OpenDeploy browser-based user interface lets you interactively construct the schema.

The following simplified (and therefore syntactically incomplete) excerpt maps the title and code attributes in our metadata example into the root table. The symbol column, which will store the deployed code values, is identified as a primary key.

The next excerpt maps the code, vocabulary, and label attributes to the other table. The designation [0-5] in each attribute mapping signifies that up to six instances of each attribute are permitted in our example. The sym column is identified as a foreign key that is related to the symbol column in the previous table.

16 Database Deployment for OpenDeploy Administration Guide

Introductory ConceptsDeploying XML to the Database

Database deployments can be initiated and executed in various ways. There are two basic modes of operation:

Database Auto-Synchronization (DAS) This is a TeamSite-based feature that enables content developers to maintain consistency between their TeamSite areas and their test database. For example, a user creating metadata for the sales report in our example might need to test whether the search function works as expected before promoting the metadata into the production environment. With DAS, the OpenDeploy base server reacts to TeamSite events that trigger automatic deployments to the test database.

Standalone and target-side database deployments These are deployments that allow XML-based structured content to be securely deployed to production databases and synchronized with file asset deployments. These types of deployment require the DataDeploy module, which enables the OpenDeploy base server to connect either directly to the target database or to an OpenDeploy receiver running close to the database. In our metadata example, the sales report and its associated metadata can be transactionally deployed in tandem. This ensures that the sales report and its associated metadata are kept in sync.

Regardless of which mode is employed, data deployment relies on an XML-based configuration file for determining the source, target, schema mapping and other aspects of the deployment.

For example, a simplified deployment configuration for our metadata example might contain the following specification for the source and target:

...

...

17

IntroductionArchitectural Overview

Figure 1 provides a simplified illustration of the basic data deployment architecture, including how deployments are invoked and how source content is converted into data tuples (the format into which data is transformed and used internally before it is saved as a record in the destination) and written to the destination database tables or XML files.

Figure 1: Data Deployment Architecture

1. A data deployment is invoked (A) by a command line tool (CLT), a web services call, or though a TeamSite event. The actions that follow depend upon whether the source of the content is an XML-based file or a database table.

2. If the source of the content is an XML-based file in a TeamSite or local file system (B1), the XML Tuple Producer parses the XML file and generates a tuple based on this XML content. If the source of the content is a database table (B2), the Database Tuple Pro-ducer reads the table using the JDBC API and generates a tuple based on the tables con-tents.

3. Next, the tuple that was produced in step 2 is passed either to the:

a. DatabaseTupleWriter (C1) if the destination is a database table.The tuple is then mapped into the table format provided by the user. Using JDBC, the tuple is inserted into the destination database tables (D1), or

TeamSite or Local File

System

Database Tables

RDBMS

Source Type Invocation Method

XML Tuple Producer

Database Tuple

Producer

Database Tuple Writer

XM L Tuple W riter

Database Tables

RDBMS

XML Formatted Files

JDBCTupleXML Parser

JDBC Tuple

Tuple

Destination Type

B1

A

C1 D1

C2 D2

B2

XML

XML Files

Data Deployment Engine

CLT TeamSite Event

Web Services Client

OpenDeploy Base Server

Deployment may go through an OpenDeploy Receiver

18 Database Deployment for OpenDeploy Administration Guide

Use Case Matrixb. XMLTupleWriter (C2) if the destination is an XML file.The tuple is then mapped into the XML format provided by the user and is written into the destination XML file (D2).

Use Case Matrix

The following table illustrates the supported use cases for data deployments.A sample configuration for each source-destination combination is Chapter 3, Configuration Files.

SourceDestination

Database XML

TeamSite TeamSite to Database(see page 63 for more information)

TeamSite to XML(see page 66 for more information)

TeamSite Extended Attributes (Metadata)

Metadata to Database(see page 67 for more information)

Metadata to XML(see page 69 for more information)

XML XML to Database(see page 72 for more information)

XML to XML(see page 73 for more information)

Database OpenDeploy and the DataDeploy module are not intended for database-to-database replication. Use the appropriate tool from your database vendor.

Database to XML(see page 74 for more information)19

IntroductionMigration Notes for DataDeploy 5.6

The following notes are for DataDeploy 5.6 users who are migrating to OpenDeploy 6.0.x.

Migration Matrix

The following table summarizes how to perform tasks formerly done using DataDeploy 5.6. This section assumes OpenDeploy 6.0.x is properly installed and configured for database deployment operation. Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for configuring database deployment operation for your OpenDeploy server.

Note that in OpenDeploy 6.0.x, Database Auto-Synchronization (DAS) is provided as a standard feature of the base server and DataDeploy is a licensed add-on module that offers standalone and synchronized database deployments. Refer to Enabling the DataDeploy Module on page 68 in the OpenDeploy Installation Guide for details about enabling the DataDeploy module.

Task DataDeploy 5.6 OpenDeploy 6.0

Database Auto-Synchronization (DAS).

DAS daemon is configured for iwat or event server triggers.

Run DAS deployments from a single base server instance of OpenDeploy. Only event server triggers are supported. No support for iwat triggers.Refer to Chapter 4, Database Auto-Synchronization on page 81 in the Database Deployment for OpenDeploy Administration Guide for more information.

Initializing DAS tables.

Use iwsyncdb.ipl -initial workareavpath [-nomdc] [dcrtype] command-line tool.

Use iwsyndb -initial workareavpath [-nomdc] [dcrtype] command-line tool. Refer to iwsyncdb on page 45 in the OpenDeploy Reference for more information.

Configuring standalone DataDeploy deployments.

Configure DataDeploy deployment configuration file.

Use one of the following methods: Place legacy DataDeploy configuration in od-

home/conf directory, and run it using OpenDeploy.

Include reference to DataDeploy configura-tion file in OpenDeploy deployment configu-ration file using the dataDeploy element.

Refer to Standalone Database Deployments on page 110 in the Database Deployment for OpenDeploy Administration Guide for more information.

Invoking standalone DataDeploy deployments.

Use iwdd.ipl or iwexecdascmd command-line tools.

Use iwodcmd start -k iwdd=internal-deployment-name. See Invoking DataDeploy Deployments on page 21 for more information.20 Database Deployment for OpenDeploy Administration Guide

Migration Notes for DataDeploy 5.6DataDeploy Administration User Interface

The DataDeploy browser-based user interface has been incorporated into an enhanced OpenDeploy browser-based user interface. A standalone DataDeploy user interface is no longer supported with this release.

Invoking DataDeploy Deployments

You can run your existing DataDeploy deployment configuration using one of the following methods:

From the Start Deployment window in the browser-based user interface. You must include the following value:

iwdd=internal-deployment-name

in the Parameters text box, where internal-deployment-name refers to a named deployment element in the DataDeploy configuration file.

Using the iwodcmd start command-line tool:

iwodcmd start OpenDeploy_configuration -k iwdd=internal-deployment-name

As a scheduled deployment configured either in the browser-based user interface, or from the command line using the iwodcmd schedadd command-line tool.

Note that the parameter iwdd is reserved for performing a deployment of a DataDeploy configuration.

iwsyncdb.cfg File Deprecated

The iwsyncdb.cfg file is no longer used by OpenDeploy. Those attributes that had been contained in the iwsyncdb.cfg file are now located in the OpenDeploy base server configuration file (by default odbase.xml). Refer to Database Deployments on page 141

Three-tier mode deployments.

Run a DataDeploy daemon on the target host.

Run a base server or receiver on the target, with the databaseDeployment element enabled in the sending and receiving OpenDeploy server configuration files, and the dbLoader element included in the deployment configuration.

Synchronized OpenDeploy-DataDeploy deployments.

Deploy and Run (DNR)-based solution.

Synchronize deployments using the dbLoader element in the deployment configuration. Refer to Synchronized Deployments on page 114 in the Database Deployment for OpenDeploy Administration Guide for more information.

Deploying to wide tables.

Supported. Wide table is supported, but it is recommended you migrate to UDS.

Task DataDeploy 5.6 OpenDeploy 6.021

in the Database Deployment for OpenDeploy Administration Guide for more information.

IntroductionDiscontinued DataDeploy Commands and Scripts

The following DataDeploy command and scripts have been discontinued:

iwdd.ipl

iwexecdascmd

iwsyndb.ipl

The following sections provide details.

iwdd.ipl and iwexecdascmd

Use the iwodcmd start command-line tool to run DataDeploy configurations (see above) instead of the iwdd.ipl script and the iwexecdascmd command-line tool.

Log output that formerly went to stdout using iwdd.ipl now is contained in the following log file:

od-home/log/ddmodule.log

iwsyncdb.ipl

The Perl script iwsyndb.ipl has been discontinued, and has been replaced by the following scripts:

Windows iwsyncdb.bat

UNIX iwsyncdb.sh

The following features previously associated with the iwsyncdb.ipl script are no longer supported by the updated iwsyncdb.bat and iwsyncdb.sh scripts:

Registration of iwat-based event triggers. DAS deployments now must be triggered using the TeamSite event server.

Ability to start and stop the DAS and DataDeploy daemons. DAS and DataDeploy capabilities are now integrated into the OpenDeploy Base Server and Receiver.

Ability to install and uninstall the DataDeploy daemon. There is no longer a separate daemon for DataDeploy.22 Database Deployment for OpenDeploy Administration Guide

Migration Notes for DataDeploy 5.6Running DataDeploy in Threadperbranch Mode

Refer to Determining the Runmode on page 142 in the OpenDeploy Installation Guide for more information on this feature.

OpenDeploy-DataDeploy Synchronized Deployments

OpenDeploy 6.0.x uses a new method for the synchronized deployment of files and database assets. The legacy Deploy and Run-based method is no longer officially supported. However, the legacy method should still work using OpenDeploy 6.0.x and DataDeploy 5.6 until you have converted your synchronized deployments to use the new method. Refer to Synchronized Deployments on page 114 in the Database Deployment for OpenDeploy Administration Guide for an overview of the new method.

DataDeploy Module Options

You must perform the following tasks to configure an OpenDeploy server to use the DataDeploy module:

1. Enable the databaseDeployment element in the OpenDeploy servers configuration files (by default odbase.xml or odrcvr.xml). Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for more information.

2. Restart the OpenDeploy server. Refer to Starting OpenDeploy on page 17 in the OpenDeploy Administration Guide for more information.

Required Locations for Deployment Configuration and Schema Files

With this release, database deployment configuration and database schema files must reside in one of the following locations on the OpenDeploy server if you want to manage your deployments using the browser-based user interface:

od-home/conf

TeamSite mount point

When you are creating and configuring database deployment configurations and database schemas using the browser-based user interface, clicking the Browse button will display only these locations. This is a change from previous releases of DataDeploy, where these files could reside anywhere on the host.23

IntroductionIf you are not using the browser-based user interface, database schema files can reside anywhere on the host. Database deployment configuration files can also reside anywhere on the host, but if they reside outside the od-home/conf directory, a wrapper must be included in the deployment configuration specifying the location of the DataDeploy configuration file. See Referencing a DataDeploy Configuration File Within an OpenDeploy Configuration on page 111 for more information.

Running DAS with DataDeploy 5.6 and OpenDeploy 6.0 on the Same Host

If you have both DataDeploy 5.6 and OpenDeploy 6.0.x on the same host, you cannot run DAS on both software releases at the same time. Instead, you must take one of the following actions:

Do not enable DAS on your OpenDeploy 6.0.x base server, or

Ensure that the DataDeploy 5.6 DAS daemon is not running when you run DAS on your OpenDeploy 6.0.x base server.

Running the DataDeploy 5.6 DAS daemon and enabling the OpenDeploy 6.0.x DAS feature on the same host is not supported.

New Usage of TuplePreprocessor and ExternalDataSource

The sample files and task steps associated with the Tuple Preprocessor and External Data Source features have changed. See Enhancing Deployment Data on page 141 for more information.24 Database Deployment for OpenDeploy Administration Guide

Cschemas. This is advantageous because a normalized database is more flexible and contains less data redundancy. Other advantages of normalization include: Relationships between tables are easier to understand.

Tables are easier to query.

Data integrity is better maintained through referential constraints. hapter 2

Deployment Concepts

This chapter covers some basic deployment concepts that are useful to understand as you configure OpenDeploy for database deployments and execute deployments:

The benefits and implementation of user-defined database schemas (UDS).

A sample deployment scenario that demonstrates update types, data sources, data organization and tuples, and the typical steps in a deployment sequence.

User-Defined Database Schemas

A schema is the organization or structure for a relational database, including the layout of tables and columns. OpenDeploy enables the mapping of XML-based structured content to a database schema and supports the automated deployment of content into a database based on the mapping. For more information on how to map a database schema when configuring a database deployment, see Mapping a Database Schema on page 47.

Overview

One of the deployment approaches that OpenDeploy supports is wide table mapping, where structured content is deployed to a single row in a database table. Such a deployment maps the values in an XML file to a column.

However, OpenDeploy favors user-defined database schemas (UDS) over wide table mapping because UDS facilitates database normalization. Normalization is the process of logically breaking down a databases tables and schema into smaller, more manageable tables. User-defined database schemas can map a given record to rows in multiple tables that you can define with foreign and primary keys. The resultant tables have normalized data 25

Deployment ConceptsTo deploy data content records using user-defined database schemas, the records must be based on the Interwoven DTD or on customized data capture template DTDs. For more information on data content records, refer to the TeamSite Templating Developers Guide.

Data can be deployed using user-defined database schemas manually or automatically using DAS. The example in the following section describes deployment using DAS. For more information on DAS, see Chapter 4, Database Auto-Synchronization on page 81.

An Example: UDS vs. Wide Table Mapping

The example in this section discusses the benefits of user-defined database schemas and the limitations of wide table mapping for mapping to multiple tables. The example is based on a use case for creating XML-structured content through data capture templates in TeamSite Templating.

Data Categories and Data Types

To understand the example, it is important to note that TeamSite Templating uses a data storage hierarchy based on directories that contain data categories and types, as is shown in Figure 2. Data categories contain one or more data types and data types are analogous to subcategories. For more information about this hierarchy and the terms specific to template usage, see the TeamSite Templating Developers Guide.

Figure 2: TeamSite Templating Directory Structure

Workarea

templatedata

data_category_1

data_type_1

data_category_2

data_type_2

. . .

. . .

datacapture.cfg data presentation

content_record_1

content_record_2. . .

pres_template_1.tplpres_template_2.tpl. . .

componentstutorials

output26 Database Deployment for OpenDeploy Administration Guide

User-Defined Database SchemasOverview of the Example

For this example, the OpenDeploy administrator is Pat, who has used a data storage hierarchy to create the following categories: Internet and Intranet. The Internet category has seven data types: auction, book, careers, medical, periodic, pr, and yacht.

Pat has also configured the following:

She has created a data capture templatean XML file called datacapture.cfgand has inserted it into the book directory. (Each data type must have its own data capture template.)

She has configured this data capture template so that it will generate a form containing various fields that a user must complete or select.

She has created a replicant element in the data capture template corresponding to the book data type; this element will create a button in the data capture form. Content contributors must complete this form to create a data content record, which can then be submitted. In this example, Pat has used the replicant element to create a Reviewers button that a content contributor clicks each time he wishes to specify an additional reviewer.

She has configured the data capture template so that a user can specify up to 10 reviewers.

Each reviewer element has the following subelements: Name, E-Mail, and Comments.

Note: Pat would need to perform additional configuration to set up TeamSite Templating and OpenDeploy, but because the focus of this example is the UDS configuration, we will assume that this has already been done.

Wide Table Mapping and Its Limitations

When Pat uses wide table mapping for the deployment of data content records, she creates tables in the database by using the command-line tool iwsyncdb -initial. The datacapture.cfg file determines the column-heading names. This results in table headings in the destination database that look like this:

The ellipses (...) in the column headings indicate that OpenDeploy creates additional column headings for each replicant field, up to the maximum number of fields indicated in the data capture template. In this example, Pat indicated a maximum of 10 fields for the Reviewers replicant by giving the max attribute a value of 10. Therefore, each Reviewers subelement would contain 10 headings:

Name0-Name9

E-Mail0-E-Mail9

Comments0-Comments9

Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State27

Deployment ConceptsUnder the wide table approach, when content contributors submit a data content record with replicant information, OpenDeploy sends the data content record to a wide table in a database. For the first data content record, created by user Chris, OpenDeploy creates the following row:

Assume another user, Don, submits a second data content record to the same data type, book, and that he does not specify any reviewers. After he submits the data content record, OpenDeploy adds a new row in the table. OpenDeploy then inserts information from Dons data content record:

Such data structures, created by mapping data to wide tables, present the following challenges:

Tables can become so wide that they violate database limits, causing deployments to fail.

When data is intended for an application, an administrator may need to use native database techniques (such as stored procedures or triggers) to transform the data from the wide table model into the required schema.

Some key-value pairs will have no values because referential integrity is not being enforced.

Data stored in such tables is not normalized. If users at create additional data content records using the wide table architecture, administrators will only be able to assume that the Path column contains unique information.

UDS and Normalization of the Data

To address the issues resulting from wide table mapping, Pat could instead use a user-defined database schema and map the data content records to multiple tables. This deployment approach allows her to normalize the data. The following tables show a normalized table hierarchy for the previous example:

Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State

mypath0 WilliamFaulkner

1234-56 Software Inc. Using Data

Chris chris@xyz.com

This book describes...

original

Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State

mypath0 WilliamFaulkner

1234-56 Software Inc. Using Data

Chris chris@xyz.com

This book describes...

original

mypath1 Harper Lee 1256-89 Software Inc. Using Tuples

original

Path Author ISBN Publisher Title State

mypath0 William Faulkner 1234-56 Software Inc. Using Data original

mypath1 Harper Lee 1256-89 Software Inc. Using Tuples original

Name0... E-Mail0... Comments0... ISBN

Chris chris@xyz.com This book describes... 1234-5628 Database Deployment for OpenDeploy Administration Guide

User-Defined Database SchemasImplementation of a UDS

When implementing a user-defined database schema, you must create a dbschema.cfg file to specify the mapping of fields from XML files (such as data content records) into custom-defined groups of columns, using the groups element. These groups are analogous to tables, in database terminology, and are treated as tables by OpenDeploy.

Note: In addition to the dbschema.cfg file for each data type to be deployed, OpenDeploy uses a template configuration file, ddcfg_uds.template (or ddcfg_uds_custom.template if deploying custom DCRs), which defines a skeletal configuration for automating UDS deployments through DAS.

After the dbschema.cfg files and, if required, a ddcfg_uds.template or ddcfg_uds_custom.template file have been created, DataDeploy configuration files that are associated with the UDS must be created. This can be done as follows:

For DAS deploymentswith the iwsyncdb -initial command.

For standalone deploymentswith the database deployment UI.

The following sections explain the process of implementing a UDS for DAS deployments.

Rules for Creating dbschema.cfg Files

The following rules must be obeyed when creating a dbschema.cfg file:

Do not use duplicate column names within a group/attrmap element.

Do not use duplicate group names within a dbschema element.

If a column is designated as a primary key within a group, a column element for that key must exist within that groups attrmap element.

If a column is designated as a foreign key:

Its groups attrmap element must contain a column element whose name matches the name of the child column.

Its parent group must exist.

Its parent groups attrmap element must contain a column whose name matches the name of the parent-group attribute of the child groups foreign-key.

A foreign key must have the same data-type attribute (for example, varchar) as its parent key.

A column that is defined as a primary key cannot contain null values.

Only use user-defined database schemas for database destinations, not database sources. In other words, only use the dbschema element inside a database element when the database element is inside a destinations element.

Do not use narrow tuples. The options attribute for the teamsite-templating-records or teamsite-extended-attributes element inside the source element must be set to wide.29

Deployment Concepts If the update-type attribute in the database element is set to delta, each group element inside the dbschema element must have a base-table attribute.

Specify a primary key for all non-leaf groups in the dbschema.cfg file. A group becomes a leaf group if its name is not used inside any part of the parent-group element.

Do not use the select and update elements inside a database element if the database element contains a dbschema element. On the other hand, if a database element does not contain a dbschema element, database must contain select and update elements.

If an attrmap element inside a group element has more than one column definition whose value-from-field attribute is set to a replicant field, the value for the specified value-from-field must have the same root element. For example, the Treatment and Drug fields in the following example must have the same root element (Treatment List):

...

Do not use the syntax that appears similar to regular expressions in the value-from-field attribute values (for example, Treatment List/[0-3]/Drug List/[0-4]/Drug) unless you are specifying a replicant field. Use this syntax only for replicant fields to indicate the maximum number of replicants for a given node in the XML tree.

The length of column names specified in the dbschema.cfg file for each data type must be less than or equal to what is allowed by your database vendor. OpenDeploy will not map long column names to internally generated identifiers to comply with database column name length limitation.30 Database Deployment for OpenDeploy Administration Guide

User-Defined Database SchemasSample dbschema.cfg File

The following sample dbschema.cfg file obeys the rules described in the preceding section. This file maps the example medical data capture template that is distributed with TeamSite Templating:

31

Deployment Concepts

32 Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

The preceding mapping would result in the database table relationships shown in Figure 3, where N is a variable representing the number of rows in a table that contain a given data type. A 1-to-N relationship represents a one-to-many relationship.

Figure 3: Database Table Relationships Created by Sample dbschema.cfg File

Prognosis List

Medical Master Vector List

Treatment List

Drug List

Symptom List

N

N

NN 1 1

1

1

1

N33

Deployment ConceptsCreating UDS-Based Configuration Files

After the requisite dbschema.cfg files and a ddcfg_uds.template or ddcfg_uds_custom.template file have been created, the iwsyncdb -ddgen command can be used to create DataDeploy configuration files that are associated with the UDS. Figure 4 shows an overview of this process. For more details, see Mapping a Database Schema with iwsyncdb on page 55.

Figure 4: Using iwsyncdb to Create DataDeploy Configuration Files with Associated UDS

1. The user executes the iwsyncdb command with the -ddgen option.

2. The command invokes a script which does the following:

Determines the data types being deployed by reading the templating.cfg file.

Reads the datacapture.cfg file for each data type.

Reads the dbschema.cfg file for each data type and checks that consistency rules are not violated.

3. The script then reads ddcfg_uds.template or ddcfg_uds_custom.template, which is used as a base format for the DataDeploy configuration file.

4. DataDeploy configuration files are generated based on the data types read by the iwsyncdb script.

Note: If any of the files in steps 2 and 3 are not found, an error is returned.

iwsyncdb Command Line:

iwsyncdb-ddgen

ddcfg_uds.template file or

ddcfg_uds_custom.template

3

1

2

4DataDeploy

configuration file X_dd.cfg

dbschema.cfg for data type X

dbschema.cfg for data type Y

DataDeploy configuration file

Y_dd.cfg

datacapture.cfg for data type X

datacapture.cfg for data type Y

templating.cfg34 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioSample Deployment Scenario

This section describes what happens when you execute a TeamSite to database deployment. This type of deployment is used as an example because it is a common use case that best illustrates how to configure and execute data deployments.

A sample configuration file for a TeamSite to database deployment is provided in Appendix A, Sample Configuration File on page 163. Other deployment scenarios such as TeamSite to XML, XML to XML, and so on, are essentially variations of the TeamSite to database deployment (see Use Case Matrix on page 19 for all source-destination deployment combinations). Sample configuration files for these scenarios are provided and described briefly in Sample Configuration Files on page 63.

The result of a TeamSite to database deployment is an updated table in the destination database. Such deployments can differ in terms of the following:

The type of table that is created or updated.

The data source in TeamSite.

The organizational structure OpenDeploy uses to deploy to the destination database.

The actual sequence of events that comprise the deployment.

Update and Table Types

The table that is created in the destination database will be a base table, delta table, or standalone table, depending on which type of update you instruct OpenDeploy to perform. Update types are named for the type of table they modify. For example, a delta update modifies a delta table, and so on.

Note: You can execute base and delta table updates manually (from the command line) or as part of an automated deployment through DAS. When DAS is configured, certain TeamSite events automatically trigger deployment.

Details about each update type are as follows:

Base update data is extracted from a TeamSite workarea, staging area, or edition, and is deployed to a base table containing full (as opposed to delta) data. The most common sources of data for a base table are staging areas and editions. Whenever a base table is generated, an entry for that table is recorded in a tracker table residing in the database.

Delta update in the TeamSite server, data from a workarea is compared with the data in a staging area or edition. Differencesthe delta dataare identified and deployed to a delta table on the destination system. This table contains only the delta data from the workarea; it does not contain full static data about every item in the workarea (the delta tables associated base table should exist from a previous deployment). The relationship between the workarea data and the data in its parent area (a staging area or edition) is updated in the tracker table residing in the database. 35

Deployment Concepts Standalone update data is extracted from a TeamSite workarea, staging area, or edition and is deployed to a standalone table. A standalone update differs from a base update in that it does not generate an entry in the tracker table.

Note: Data synchronization in the database system, OpenDeploy must keep a record of which delta tables are associated with which base tables, assuming you are using DAS. This is necessary so that delta tables from multiple workareas that are associated with a single base table from a staging area will remain synchronized when changes from one workarea are submitted to the staging area. This relationship is maintained by the tracker table residing in the same database as the base and delta tables.

Data Sources

When you deploy data from TeamSite to a database, you can specify that it come from a TeamSite workarea, staging area, or edition. Of these three, workarea data is the only type that can be deployed using all of the three types of update (base, delta, or standalone). When deploying staging area or edition data, set update-type to base if you plan subsequent delta table generation, or set update-type to standalone if you do not need to track the tables relationship to other tables.

The following table shows which data sources are supported for each type of update:

Update TypeBase Delta Standalone

TeamSite Source Area

Workarea Supported Supported SupportedStaging Area Supported Not Supported SupportedEdition Supported Not Supported Supported36 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioData Organization and Tuples

For each deployment, OpenDeploy extracts data from the source that you specify and organizes this data internally as tuples.Tuples can then be deployed into a specified destination as defined in your DataDeploy configuration file(s). Tuples are deployed to a database in different ways, depending on the databases organizational structure, or schema. OpenDeploy deploys data to databases using three different organizational structures:

User-defined database schemas (which result in multiple tables when deployed to a database; any given data content record may be mapped to multiple tables). This is the preferred method. For more information about this option, see User-Defined Database Schemas on page 25.

Wide tables (either wide or narrow tuples can be deployed to wide tables).

Narrow tables (which result when narrow tuples are deployed to a database).

Tuple Metadata and State

All TeamSite tuples contain the following metadata:

Exactly one path element, which is the area relative path name of the file associated with the tuples key-value pair(s).

One or more key-value pairs. The key is the name of an attribute. For example, News-Section is the key of the extended attribute News-Section:Sports. The value is the data value for a tuples keySports, in this example.

Exactly one state element, which describes the status of the tuple. Possible values are Original, New, Modified, and NotPresent.

When a base table (representing a staging area) is initially populated, all tuples (entries) will have the state of Original. Over the life of the base table, after submissions to the staging area, new tuples are added in the table and these tuples will have the state of New. If a particular tuple in a workarea is changed and submitted to the staging area, and if that tuple already exists in the base table, the tuple will have a state of Modified. 37

Deployment ConceptsIn a delta table, the state is the tuples status as viewed in TeamSite area 1 (most often the staging area) relative to the tuple in TeamSite area 2 (most often a workarea). A delta table can have tuple states of Original, New, Modified, or NotPresent. The following table shows the scenarios that can cause these states:

Note: The tuples in standalone tables do not have a state.

Wide vs. Narrow Tuples

The following sections discuss wide tuples and narrow tuples and their role in the deployment process.

Wide Tuples

A wide tuple is an internal representation of all the data for the source element being deployed. By default, wide tuples deploy into wide tables when deployed to a database. Unlike narrow tuples, wide tuples can be deployed either manually or with DAS. Wide tuples contain exactly one path element and one state element, and any number of key-value pairs. Thus, a files extended attribute data can be represented in a single wide tuple even if the file has more than one extended attribute set.

Figure 5 shows OpenDeploys internal representation of a wide tuple.

Figure 5: Wide Tuple

In a wide tuple, OpenDeploy eliminates the key = and value = labels for the key and value data, instead using the format key = value for each key-value pair. This arrangement simplifies the creation of a wide base table as described in Base Table Format: Wide Tuples on page 39.

A delta table tuple state of: Was caused by:

Original Merging delta data from another workarea into a base table through a base update (such as when submitting the other workarea data to a staging area).

New Generating a new tuple through a delta update (such as when adding a new extended attribute to a file in a workarea).

Modified Updating a delta table through a delta update.NotPresent Data existing in a base area but not in a workarea (such as when the

data is deleted from the workarea, or when data is newly added to the base area from a different workarea).

Tuple 1

path = docroot/news/front.htmlNews-Section = SportsLocale = SFstate = Original38 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioSupport for wide tuples requires that all extended attribute keys be unique. For example, a file cannot have two keys named Locale. (To satisfy this requirement, TeamSite uses a numeric suffix for key names that would otherwise not be unique. For example, if the file docroot/news/front.html has two Locale keys with the values SF and Oakland, the keys are named Locale/0 and Locale/1.) The resulting wide tuple is shown in Figure 6:

Figure 6: Wide Tuple with Similar Locale Keys

Base Table Format: Wide Tuples

By default, wide tuples deploy into wide tables, in which key values from the tuple are placed in separate columns. The result is a table (Figure 7) in which a single file record contains individual key value columns:

Figure 7: Wide Tuple Default Base Table

Tuple 1

path = docroot/news/front.htmlNews-Section = SportsLocale/0 = SFLocale/1 = Oaklandstate = Original

File News-Section Locale0 Locale1 Statedocroot/news/front.html Sports SF Oakland Original

Key-Value List for docroot/news/front.html:

Wide Database Table:

News-Section=Sports, Locale/0=SF, Locale/1=Oakland

Tuple 1 (Wide)

path = docroot/news/front.htmlNews-Section = SportsLocale/0 = SFLocale/1 = Oaklandstate = Original39

Deployment ConceptsNarrow Tuples

Narrow tuples are not a common way to deploy data due to structural constraints. Narrow tuples contain exactly one path, key, value, and state element.

Figure 8 shows OpenDeploys internal representation of two narrow tuples. Tuple 1 is for the News-Section:Sports extended attribute for the file docroot/news/front.html. Tuple 2 is for the Locale:SF extended attribute for the same file. Because a narrow tuple can contain only one key-value pair, DataDeploy must create multiple tuples (two in this case) if a files extended attributes consist of more than one key-value pair.

Figure 8: Narrow Tuples

Note: You cannot deploy data content records using narrow tuples. DAS only accepts wide tuples.

Base Table Format: Narrow Tuples

By default, deploying narrow tuples creates a base table (Figure 9) in a database containing columns for Path, Key, Value, and State.

Figure 9: Narrow Tuple Default Base Table

Tuple 1

path = docroot/news/front.htmlkey = News-Sectionvalue = Sportsstate = Original

Tuple 2

path = docroot/news/front.htmlkey = Localevalue = SFstate = Original

Path Key Value Statedocroot/news/front.html News-Section Sports Originaldocroot/news/front.html Locale SF Original

Key-Value List for docroot/news/front.html: News-Section=Sports, Locale=SF

Tuple 1 (Narrow)

path = docroot/news/front.htmlkey = News-Sectionvalue = Sportsstate = Original

Tuple 2 (Narrow)

path =docroot/news/front.htmlkey = Localevalue = SFstate = Original

Narrow DatabaseTable:40 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioIt is possible to deploy narrow tuples into a wide table by configuring DataDeploy to use wide tuples. When you do, the tuples are deployed to a wide table by default. You can also deploy narrow tuples to a wide table by manually configuring a set of SQL commands in the DataDeploy configuration file. These SQL commands then execute automatically during the deployment.

Deployment Sequence

The most common sequence of events when deploying in DAS mode from TeamSite to a database is as follows:

1. Generating an initial base table of a staging area or edition.

2. Generating a delta table for each workarea associated with the staging area or edition from step 1.

3. Configuring TeamSite to invoke OpenDeploy so that the base table from step 1 is auto-matically updated whenever changes have been submitted to its corresponding staging area or edition from a workarea.

This section describes these steps, which are part of automated deployment through DAS.

Generating an Initial Base Table

Usually, the first action you instruct OpenDeploy to perform is the creation of an initial base table for a staging area or an edition.

Figure 10 shows the creation of a base table BT1 from a staging area SA1 on a TeamSite branch such as /default/main/branch1.

Figure 10: Generating an Initial Base Table

1. Invoke OpenDeploy from the command line, specifying the deployment configuration file that contains the necessary parameters. OpenDeploy reads the configuration file and

SA1

WA1

WA2

WA3

TeamSite OpenDeploy Database

BT1

1 2

3

Tracker Table

Tracker Table41

extracts all data from SA1.

Deployment Concepts2. Based on additional information in the configuration file, OpenDeploy creates base table BT1 in the destination database, populating it with the data from Step 1.

3. OpenDeploy creates the tracker table (or updates it if it already exists) to track relation-ships between base and delta tables

Generating a Delta Table

After creating the initial base table, you need to generate one or more delta tables based on the workareas associated with the base tables staging area.

Figure 11 shows the creation of a delta table DT1 from a workarea WA1. It assumes that a base table for SA1 has already been generated, and that WA1 is a workarea of staging area SA1. Based on the preceding conditions, the following sequence of events occurs.

Figure 11: Generating a Delta Table

1. Invoke OpenDeploy from the command line, specifying the deployment configuration file that contains the necessary parameters. OpenDeploy compares the data in WA1 with the same data in SA1 to determine the tuple differences between the two areas.

2. OpenDeploy creates DT1, using the delta data it determined in Step 1. If there is no delta data, it creates an empty delta table.

3. OpenDeploy updates the tracker table to record that DT1 is a child of BT1.

TeamSite DataDeploy Database

DT1

DT2

DT3

BT11 3

2

SA1

WA1

WA2

WA3

Tracker Table42 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioUpdating a Base Table

After creating the initial base and delta tables, you can configure TeamSite workflow or set up DAS to automatically update a base table whenever changes in a workarea are about to be submitted to a staging area (Figure 12). This example assumes the following:

You plan to submit a file list (rather than the entire workarea) from workarea WA2 to staging area SA1.

A base table BT1 already exists for staging area SA1.

Delta tables DT1 through DT3 already exist for all workareas (WA1 through WA3) associated with staging area SA1.

A tracker table already exists to establish and track the relationships between the base and delta tables.

Figure 12: Updating a Base Table

1. If the submission occurs as part of a TeamSite workflow job, the TeamSite workflow subsystem obtains a list of files to be submitted from WA2 to SA1. This list of files is then passed to OpenDeploy (1a in Figure 12). If DAS is configured, OpenDeploy obtains the list of files to be submitted.

2. OpenDeploy compares the file list items in WA2 with the same items in SA1 to deter-mine the tuple differences between the two areas. (These differences will be recorded in BT1 later in Step 5).

3. OpenDeploy checks the tracker table to determine the children of BT1.

4. Original rows from BT1 are propagated to DT1 and DT3 (but not to DT2). This ensures that the original rows in BT1 are not lost, but instead are stored as now-obso-lete data in its child delta tables.

5. OpenDeploy updates BT1 with the data derived earlier in Step 2.

SA1

WA1

WA2

WA3

DT1

DT2

DT3

BT1

Workflow or DAS 1

1a

6

57

TeamSite DataDeploy Database

Tracker Table

3

4

243

Deployment Concepts6. OpenDeploy removes from DT2 all rows whose path and key values are identical to those being submitted from WA2 to SA1. This ensures that items not being submitted from WA2 to SA1 are retained in DT2.

7. The workflow subsystem completes the submission of the file list to SA1.

Table Updates

Table updates for a scenario fitting this model would proceed as shown in Figure 13. For simplicity, the tables shown here have column headings identical to the tuple items Path, Key, Value, and State. In most situations, the columns will have other names. Because the term key has a specific meaning in many database languages, do not use key as a column heading.

Figure 13: Sample Table Updates

1. State 0: In their starting state, all tables are synchronized. Because there are no differences between SA1, WA1, and WA2, there is no delta data. Therefore, DT1 and DT2 are empty.

2. State 1: Workarea WA2 is changed locally with new data P2, K2, and V2, but the changes are not submitted to staging area SA1. Because the changes are not submitted, you must execute a delta update so that delta table DT2 reflects the new data in WA2. During this delta update, OpenDeploy identifies the differences between SA1 and WA2 and records these differences (the delta data) in DT2. In this scenario the delta tables already exist and therefore only need to be updated.

3. State 2: Workarea WA2 (complete with its changes from previous State 1) is submitted to staging area SA1. In the configuration file for this deployment, Path and Key were named as the basis-for-comparison columns. Therefore, OpenDeploy compares the State 1 values of these columns in BT1 and DT2, sees that they are different, and deter-mines that the row from DT2 State 2 should append rather than replace the data in BT1. DT1 has the new values shown here because WA1 now differs from SA1. If necessary, a Get Latest operation in WA1 would bring WA1 into sync with SA1.

State 0BT1

Path Key Value StateP1 K1 V1 Orig

DT1Path Key Value State

DT2Path Key Value State

State 1BT1

Path Key Value StateP1 K1 V1 Orig

DT1Path Key Value State

DT2Path Key Value State

P2 K2 V2 New

State 2BT1

Path Key Value StateP1 K1 V1 OrigP2 K2 V2 Orig

DT1Path Key Value State

P2 K2 V2 NtPres

DT2Path Key Value State44 Database Deployment for OpenDeploy Administration Guide

Sample Deployment ScenarioHad State 1 DT2 contained a P1 K1 V2 row, it would have replaced rather than appended the original BT1 row. In that case, the original BT1 row would have been propagated to DT1, after which P1 K1 V2 would have replaced P1 K1 V1 in BT1. A subsequent Get Latest in WA1 would bring WA1 into sync with SA1, and the data in DT1 would be deleted). DT2 is empty because WA1 is once again in sync with SA1.

This is the ending state that would exist if you completed the steps described in Updating a Base Table on page 43.

Composite Table Views

Composite table views provide a way to view data pertaining to a workarea in the context of the staging area it is associated with. In essence, they show what the staging area would look like if the workarea were submitted. See Database Virtualization Views on page 106 for more information.

There are three ways that you can create table views:

Through SQL commands that you execute manually to query the database after it is created.

Through SQL commands named in the user-action attribute of the DataDeploy configuration files sql element. You run these commands by executing a SQL-specific deployment that you specify through the command line options iwdd-op=do-sql and user-op=anyname.

By setting the table-view attribute in the DataDeploy configuration files database section.

The following composite views (Figure 14) for workareas WA1 and WA2 would result from the scenarios described in the previous sections. The composite for WA1 is the result of querying BT1 and DT1 using the appropriate SQL statements. Likewise, the composite for WA2 is the result of querying BT1 and DT2.

Figure 14: Composite Table Views

State 0WA1

Path Key Value StateP1 K1 V1 Orig

WA2Path Key Value State

P1 K1 V1 Orig

State 1WA1

Path Key Value StateP1 K1 V1 Orig

WA2Path Key Value State

P1 K1 V1 OrigP2 K2 V2 New

State 2WA1

Path Key Value StateP1 K1 V1 Orig

WA2Path Key Value State

P1 K1 V1 OrigP2 K2 V2 Orig45

Deployment Concepts46 Database Deployment for OpenDeploy Administration Guide

CThe ability to map content based on any DCT or DTD to a user-defined database schema provides great flexibility to users who require that data from TeamSite be deployed to

normalized tables. By eliminating the need to edit XML and providing a tool for auto-generating dbschema.cfg files, the OpenDeploy user interface greatly simplifies the process of mapping DCTs to database schemas.

To create user-defined schemas, elements in a DCT or DTD are mapped to columns in database tables. In the context of the OpenDeploy user interface, these tables are referred to as groups.hapter 3

Configuration Files

Before a deployment can be invoked and executed, you must configure it by doing the following:

Map a database schema (if your deployment destination is a database).

Create and then customize the DataDeploy configuration file(s).

Specify database connection parameters in a database configuration file (only for deployments with a database destination).

This chapter discusses the creation of database schemas, DataDeploy configuration files, and database configuration files and also how a configured deployment can be invoked. The information here applies both to DAS and to deployments using the DataDeploy module, both of which are described in subsequent chapters in this book.

Mapping a Database Schema

Mapping the user-defined database schema is the first step in configuring a deployment. Chapter 2 discusses the importance and architecture of the UDS. The following sections detail the two methods for creating the database schema: the administration UI and iwsyncdb.

Mapping a Database Schema with the Browser-Based User Interface

The OpenDeploy browser-based user interface supports mapping data capture templates (DCTs) that are based on the Interwoven DTD standards or a custom DTD to a user-defined database schema. 47

Configuration FilesProcess Flow

The following is an outline of end-user and system actions that take place when data capture files are mapped to database schemas:

1. The user logs into the browser-based user interface and navigates to the Map DCT/DTD to Database Schema window.

2. The user sets the mapping parameters by specifying the following:

Source specify which file is to be used as the source for the mapping and whether that file is a datacapture.cfg file (DCT based on Interwoven 4.5/5.0 standards) or a custom DTD.

Destination specify whether to map to a new schema or to an existing one.

Database specify the type of database.

Map Type specify whether to begin the process with a new, blank map or an auto-generated new map. Auto-generated maps provide a convenient starting point because groups are automatically created from the elements of the source file. These groups and their elements can be modified.

3. The user creates groups and maps elements in the source file to columns in those groups.

Note the following:

Each schema must contain exactly one root group, which is the parent to all other groups in the schema. It is recommended that users create and save the root group before creating other groups because the user interface populates drop-down menus w