Od 602 Ddadmin

Database Deployment for OpenDeploy Administration Guide Release 6.0.
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.com Printed in the United States of America Release 6.0.2 Part #90-25-00-602-300 March 2005
Table of Contents
About This Book 7
Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Other OpenDeploy Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 OpenDeploy Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 OpenDeploy Administration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 OpenDeploy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 OpenDeploy Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Online Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Chapter 1: Introduction
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required Database Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introductory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML for Defining Structured Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database for Storing Structured Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping the XML Representation to the Database Schema. . . . . . . . . . . . . . . . . . . . . Deploying XML to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use Case Matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migration Notes for DataDeploy 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migration Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DataDeploy Administration User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking DataDeploy Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iwsyncdb.cfg File Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Discontinued DataDeploy Commands and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . Running DataDeploy in Threadperbranch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy-DataDeploy Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . DataDeploy Module Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required Locations for Deployment Configuration and Schema Files . . . . . . . . . . . . . . Running DAS with DataDeploy 5.6 and OpenDeploy 6.0 on the Same Host . . . . . . . . . New Usage of TuplePreprocessor and ExternalDataSource . . . . . . . . . . . . . . . . . . . . .
11
11 11 12 12 14 14 15 15 17 18 19 20 20 21 21 21 22 23 23 23 23 24 24
Chapter 2: Deployment Concepts

User-Defined Database Schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . An Example: UDS vs. Wide Table Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation of a UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Update and Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Organization and Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
25 25 26 29 35 35 36 37 41
Chapter 3: Configuration Files

Mapping a Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping a Database Schema with the Browser-Based User Interface . . . . . . . . . . . . . . Updating an Existing Database Schema File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping a Database Schema with iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the DataDeploy Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Browser-Based User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the iwsyncdb -ddgen Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Multiple XML-Formatted Files as a List of Filelists. . . . . . . . . . . . . . . . . . . Sample Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite Extended Attributes to Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite Extended Attributes to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite and TeamSite Extended Attributes to Database . . . . . . . . . . . . . . . . . . . . . . XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML to XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Database Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Metadata to UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Default Datatype Size on Internal Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
47 47 55 55 57 58 62 62 63 63 66 67 69 70 72 73 74 77 78 78 79
Chapter 4: Database Auto-Synchronization
81
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Using Multiple Instances of OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Editing database.xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Editing Deployment Configuration File Templates and drop.cfg . . . . . . . . . . . . . . . . . 84 Editing iw.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 OpenDeploy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Configuring DAS in the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Specifying DAS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 DAS Setup for Template Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 DAS Setup for Metadata Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Configuring DAS Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Running iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 The Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Configuring the Event Subsystem with the Browser-Based User Interface. . . . . . . . . . . 92 Configuring the Event Subsystem Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Logging Options for Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Generating DAS Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using DAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Table Update Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Specifying How Tables are Updated. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Table Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Database Object Name Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 DAS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Configuring TeamSite Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Database Deployment for OpenDeploy Administration Guide
Database Virtualization Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DAS and Metadata Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DAS Out-of-Sync Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
106 107 108 108 110 110 111 112 112 113 114 115 116 121 121 123 124 124 130 133 133 133 141 141 141 148 155 157 157 159 160 160 161 163 167 167 167 168 168 168 168 168 169 169
5
Chapter 5: DataDeploy Deployments
109
Standalone Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Deployment Configuration and Execution . . . . . . . . . . . . . . . . . . . . . . . . Specifying an Alternate TeamSite Mount Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Target-Side Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6: Advanced Features
121
Deploying Data as Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Data as Database Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Data as Database Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filters and Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Replicants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replicant Order Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Comma Separated Lists of Values as Replicants . . . . . . . . . . . . . . . . . . . . Deploying Multiple Replicants from Multiple Nesting Levels . . . . . . . . . . . . . . . . . . Enhancing Deployment Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Tuple Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying URL Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Miscellaneous Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Custom Data Content Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encoding Database Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Real Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing a Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing Arbitrary Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix A: Sample Configuration File
163
The Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Sections of the Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Filter Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Substitution Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. Client Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. Deployment Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. Source Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. Source Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Location of Source Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. Substitution Section (In-Flow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10. Destinations Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Database Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Rows to Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13. Update Type and Related Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14. Columns to Update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. SQL Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16. Server Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
169 169 170 171 171 171 172
Appendix B: Database Deployment Tutorials

Standalone Deployment Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Base Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Example: Custom XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . DAS Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Behavior On Other Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
174 174 175 181 181 182 187 188
Appendix C: Database Deployment Internal Tables

IWTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWDELTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWOV_IDMAPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWTMP_LOB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
189
189 189 190 190
Glossary Index
191 195
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.
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. Book titles appear in italics. Terms are italicized the first time they are introduced. Important information may be italicized for emphasis. Commands, command-line output, and file names are in monospace type. For example: The iwodstart command-line tool starts an OpenDeploy deployment task. Monospaced italics are used for command-line variables.For example:
iwodstart deployment
Italic
Monospace
Monospaced italic
Monospaced bold
This means that you must replace deployment with your values. 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.
Other OpenDeploy Documentation
Other 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.
10
Chapter 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 Privileges

OpenDeploy must have the following privileges when accessing a database: insert update delete create table create view query permissions
11
Introduction
Invocation
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 userdefined 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
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
Introduction
Introductory 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:
<!ELEMENT metadata (descriptor+)> <!ATTLIST metadata title CDATA #REQUIRED> <!ELEMENT descriptor EMPTY> <!ATTLIST descriptor code CDATA #REQUIRED vocabulary CDATA #REQUIRED label CDATA #REQUIRED>
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:
<metadata title="Sales in Northern California"> <descriptor code="AG" vocabulary="Regions" label="Americas"/> <descriptor code="06" vocabulary="FIPS5-2" label="California"/> <descriptor code="A" vocabulary="Territory" label="West"/> </metadata>
14
Database 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)
Report Symbol (primary key)
Sales in Northern California AG Sales in Northern California 06 Sales in Northern California A Table 2: Descriptor Table (desc)
Sym (foreign key) Vocab Tag
AG 06 A
Regions FIPS5-2 Territory
Americas California West
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:
This XML element/attribute
metadata/title descriptor/code descriptor/code descriptor/vocabulary descriptor/label
maps to this table/column
md/report md/symbol (primary key) desc/sym (foreign key) desc/vocab desc/tag

15
Introduction
The 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.
<group name="metadata" table="md" root-group="yes"> <attrmap> <column name="report" value-from-attribute="metadata/0/title"/> <column name="symbol" value-from-attribute="metadata/0/descriptor/[0-5]/code"/> </attrmap> <keys> <primary-key> <key-column name="symbol"/> </primary-key> </keys> </group>
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.
<group name="descriptor" table="desc" root-group="no"> <attrmap> <column name="sym" value-from-attribute="metadata/0/descriptor/[0-5]/code"/> <column name="vocab" value-from-attribute="metadata/0/descriptor/[0-5]/vocabulary"/> <column name="tag" value-from-attribute="metadata/0/descriptor/[0-5]/label"/> </attrmap> <keys> <foreign-key parent-group="metadata"> <column-pair parent-column="symbol" child-column="sym"/> </foreign-key> </keys> </group>
16
Deploying 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:
<deployment> <source> <xml-source area="C:/my_xml_files" area-type="os-filesystem" xml-type="custom" > <path name="." /> </xml-source> </source> <destinations> <database use=...> <dbschema> <group name="metadata" table="md1" root-group="yes"> ... </group> <group name="descriptor" table="desc2" root-group="no"> ... </group> </dbschema> </database> </destinations> </deployment>
17
Introduction
Architectural 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.
Source Type Invocation Method
CLT TeamSite Event Web Services Client
Database Tables
Destination Type
A
TeamSite or Local File System
Data Deployment Engine
XML Files
B1
XML Parser
C1
XML Tuple Producer
Tuple
Database Tuple Writer
D1
JDBC
RDBMS
Database Tables
B2
C2
JDBC
RDBMS
Deployment may go through an OpenDeploy Receiver
e pl Tu
XML Formatted Files
D2
X M L T uple W riter
XML
Database Tuple Producer
Tuple
OpenDeploy Base Server
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 Producer reads the table using the JDBC API and generates a tuple based on the tables contents. 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
18
Use Case Matrix
b. 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. Source
TeamSite
Destination
Database XML
TeamSite to Database (see page 63 for more information) Metadata to Database TeamSite Extended Attributes (Metadata) (see page 67 for more information) XML to Database XML (see page 72 for more information) Database OpenDeploy and the DataDeploy module are not intended for database-todatabase replication. Use the appropriate tool from your database vendor.
TeamSite to XML (see page 66 for more information) Metadata to XML (see page 69 for more information) XML to XML (see page 73 for more information) Database to XML (see page 74 for more information)
19
Introduction
Migration 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- DAS daemon is Synchronization configured for iwat (DAS). or event server triggers.
Initializing DAS tables.
Use iwsyncdb.ipl
initial workareavpath [nomdc] [dcrtype]
command-line tool. Configuring standalone DataDeploy deployments. Configure DataDeploy deployment configuration file.
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 AutoSynchronization on page 81 in the Database Deployment for OpenDeploy Administration Guide for more information. Use iwsyndb -initial workareavpath [nomdc] [dcrtype] command-line tool. Refer to iwsyncdb on page 45 in the OpenDeploy Reference for more information.
Invoking standalone DataDeploy deployments.
Use one of the following methods: Place legacy DataDeploy configuration in odhome/conf directory, and run it using OpenDeploy. Include reference to DataDeploy configuration file in OpenDeploy deployment configuration file using the dataDeploy element. Refer to Standalone Database Deployments on page 110 in the Database Deployment for OpenDeploy Administration Guide for more information. Use iwodcmd start Use iwdd.ipl or -k iwdd=internal-deployment-name. See iwexecdascmd command-line tools. Invoking DataDeploy Deployments on page 21 for more information.
20
Task
DataDeploy 5.6
OpenDeploy 6.0
Three-tier mode Run a DataDeploy Run a base server or receiver on the target, with deployments. daemon on the target the databaseDeployment element enabled in host. the sending and receiving OpenDeploy server configuration files, and the dbLoader element included in the deployment configuration. Synchronized Deploy and Run Synchronize deployments using the dbLoader OpenDeploy(DNR)-based element in the deployment configuration. DataDeploy solution. Refer to Synchronized Deployments on deployments. page 114 in the Database Deployment for OpenDeploy Administration Guide for more information. Deploying to Supported. Wide table is supported, but it is recommended wide tables. you migrate to UDS. DataDeploy 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 in the Database Deployment for OpenDeploy Administration Guide for more information.
21
Introduction
Discontinued 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
Running 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
Introduction
If 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
Chapter 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 schemas. 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.
25
Deployment Concepts
To 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. Workarea templatedata
tutorials data_category_1 data_category_2
...
components
output
data_type_1
data_type_2
...
datacapture.cfg
data
content_record_1 content_record_2 ...
presentation
pres_template_1.tpl pres_template_2.tpl ...
Figure 2: TeamSite Templating Directory Structure
26
Overview 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:
Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State
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
27
Deployment Concepts
Under 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:
Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State
Chris chris@ xyz.com This book describes... original
mypath0 WilliamFaul 1234-56 Software Inc. Using kner Data
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:
Path Author ISBN Publisher Title
Name0... E-Mail0... Comments0... State Chris chris@ xyz.com This book describes... original original
mypath0 WilliamFaul 1234-56 Software Inc. Using kner Data mypath1 Harper Lee 1256-89 Software Inc. Using Tuples
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 userdefined 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
mypath0 mypath1
Author
William Faulkner Harper Lee
ISBN
1234-56 1256-89
Publisher
Software Inc. Software Inc.
Title
Using Data Using Tuples
State
original original
Name0...
Chris
E-Mail0...
chris@xyz.com
Comments0...
This book describes...
ISBN
1234-56
28
Implementation 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 customdefined 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.
ddcfg_uds_custom.template
After the dbschema.cfg files and, if required, a ddcfg_uds.template or 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-templatingrecords 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):
<group name="drug_list"> <attrmap> <column name="Treatment" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Treatment" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease " /> <column name="Drug" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Drug List/[0-4]/Drug" is-replicant="yes"/> </attrmap> ... </group>
Do not use the syntax that appears similar to regular expressions in the value-fromfield 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
Sample 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:
<dbschema> <group name="medical_master" root-group="yes"> <attrmap> <column name="Disease" data-type="varchar(100)" value-from-field="Disease" allows-null="no"/> <column name="LatinName" data-type="varchar(100)" value-from-field="Latin" allows-null="no"/> <column name="Type" data-type="varchar(15)" value-from-field="Type" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Disease"/> </primary-key> </keys> </group> <group name="vector_list" root-group="no"> <attrmap> <column name="Vector" data-type="varchar(40)" value-from-field="Vector List/[0-5]/Vector" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Vector"/> <key-column name="Disease"/> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column="Disease"/> </foreign-key> </keys> </group> <group name="symptom_list" root-group="no"> <attrmap> <column name="Symptom" data-type="varchar(100)" value-from-field="Symptom List/[0-5]/Symptom" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Symptom"/> <key-column name="Disease"/> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column= "Disease" child-column="Disease"/> </foreign-key> </keys> </group>
31
Deployment Concepts
<group name="prognosis_list" root-group="no"> <attrmap> <column name="Prognosis" data-type="varchar(100)" value-from-field="Prognosis List/[0-3]/Prognosis" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Prognosis"/> <key-column name="Disease"/> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column= "Disease" /> </foreign-key> </keys> </group> <group name="Treatment_list" root-group="no"> <attrmap> <column name="Treatment" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Treatment" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <column-key name="Treatment"/> <column-key name="Disease" /> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column= "Disease" /> </foreign-key> </keys> </group> <group name="drug_list" root-group="no"> <attrmap> <column name="Treatment" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Treatment" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> <column name="Drug" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Drug List/[0-4]/Drug" is-replicant="yes"/> </attrmap> <keys> <primary-key> <key-column name="Drug" /> <key-column name="Disease"/> <key-column name="Treatment"/> </primary-key> <foreign-key parent-group="Treatment_list" /> <column-pair parent-column="Disease" child-column="Disease" /> <column-pair parent-column="Treatment" child-column="Treatment" /> </foreign-key>
32
</keys> </group> </dbschema>
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.
Prognosis List N N Symptom List 1 1 Medical Master 1 N Treatment List 1 N Drug List 1 N Vector List
Figure 3: Database Table Relationships Created by Sample dbschema.cfg File
33
Deployment Concepts
Creating 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.
templating.cfg
datacapture.cfg for data type X dbschema.cfg for data type X
datacapture.cfg for data type Y dbschema.cfg for data type Y
2 1
Command Line: iwsyncdb -ddgen
DataDeploy configuration file X_dd.cfg
iwsyncdb
DataDeploy configuration file Y_dd.cfg
3
ddcfg_uds.template file or ddcfg_uds_custom.template
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.
34
Sample 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:
Base TeamSite Source Workarea Staging Area Area Edition Update Type Delta Standalone
Supported Supported Supported
Supported Not Supported Not Supported
Supported Supported Supported
36
Data 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, NewsSection 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 Concepts
In 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:
A delta table tuple state of: Was caused by:
Original New Modified NotPresent
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). Generating a new tuple through a delta update (such as when adding a new extended attribute to a file in a workarea). Updating a delta table through a delta update. 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).
Note:
Wide vs. Narrow Tuples
The tuples in standalone tables do not have a state.
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.
Tuple 1 path = docroot/news/front.html News-Section = Sports Locale = SF state = Original 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.
38
Support 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:
Tuple 1
path = docroot/news/front.html News-Section = Sports Locale/0 = SF Locale/1 = Oakland state = Original
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:
Key-Value List for

docroot/news/front.html:
News-Section=Sports, Locale/0=SF, Locale/1=Oakland
Tuple 1 (Wide)
path = docroot/news/front.html News-Section = Sports Locale/0 = SF Locale/1 = Oakland state = Original
Wide Database Table: File
News-Section Locale0 Locale1

SF Oakland
State
Original
docroot/news/front.html Sports
Figure 7: Wide Tuple Default Base Table
39
Deployment Concepts
Narrow 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.
Tuple 1
path = docroot/news/front.html key = News-Section value = Sports state = Original
Tuple 2
path = docroot/news/front.html key = Locale value = SF state = Original
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.
Key-Value List for
docroot/news/front.html: News-Section=Sports, Locale=SF
Tuple 1 (Narrow)
path = docroot/news/front.html key = News-Section value = Sports state = Original
Tuple 2 (Narrow)
path =docroot/news/front.html key = Locale value = SF state = Original
Narrow Database Table: Path
Key
Value
Sports SF
State
Original Original
docroot/news/front.html News-Section docroot/news/front.html Locale
Figure 9: Narrow Tuple Default Base Table
40
It 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 automatically 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.
TeamSite
OpenDeploy
Database
1
SA1 WA1 WA2 WA3 Figure 10: Generating an Initial Base Table
2
BT1 Tracker Table
Tracker Table
1. Invoke OpenDeploy from the command line, specifying the deployment configuration file that contains the necessary parameters. OpenDeploy reads the configuration file and extracts all data from SA1.
41
Deployment Concepts
2. 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 relationships 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.
TeamSite
DataDeploy
Database
SA1
1
WA1 WA2 WA3
3 2
BT1 DT1 DT2 DT3 Tracker Table
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.
42
Updating 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.
TeamSite
DataDeploy
Database BT1
5
SA1 WA1 WA2 WA3

2
6
Workflow or DAS 1
DT1 DT2 DT3

4
Tracker Table
1a
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 determine 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-obsolete data in its child delta tables. 5. OpenDeploy updates BT1 with the data derived earlier in Step 2.
43
Deployment Concepts
6. 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.
State 0
BT1 Path Key Value State P1 K1 V1 Orig DT1 Key Value State Path P1
State 1
BT1 Key Value State K1 V1 Orig DT1 Key Value State Path P2 Key K2 Path P1 P2
State 2
BT1 Key Value State K1 V1 Orig K2 V2 Orig DT1 Value State V2 NtPres
Path
Path
Path
DT2 Key Value State
Path P2
DT2 Key Value State K2 V2 New
Path
Key
DT2 Value State
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 determines 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.
44
Had 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.
State 0
Path P1 Key K1 WA1 Value State V1 Orig WA2 Value State V1 Orig Path P1
State 1
Key K1 WA1 Value V1 WA2 Value V1 V2 State Orig Path P1
State 2
Key K1 WA1 Value V1 WA2 Value V1 V2 State Orig
Path P1
Key K1
Path P1 P2
Key K1 K2
State Orig New
Path P1 P2
Key K1 K2
State Orig Orig
Figure 14: Composite Table Views
45
Deployment Concepts
46
Chapter 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. The 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 autogenerating 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.
47
Configuration Files
Process 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 with the group and column names of saved groups. It is helpful if users have that root group information available when they create subsequent groups. When creating columns, users must (a) select an element from the source file, (b) select the column into which the element is copied, and (c) copy the element into that column. This select-and-copy method ensures that item names in schemas are identical to item names in the source file. Changing item names would prevent DataDeploy from deploying DCRs correctly. Additionally, the select-and-copy method ensures the transfer of other important invisible data from the source file to the schema. The OpenDeploy user interface does not validate user input. If users enter invalid input, OpenDeploy will display errors at deployment time. 4. When a group and corresponding columns have been specified, the user saves the group. It is then displayed in the Mapped Tables pane of the user interface. 5. When the user finishes creating or editing groups, he views the resulting dbschema.cfg file and saves it to the desired location.
48
Setting Mapping Parameters
To set the general parameters for mapping a datacapture.cfg file or a custom DTD, follow these steps: 1. Select Configurations > Schema Mapping to display the Map DCT/DTD to Database Schema window (Figure 15).
Figure 15: Map DCT/DTD to Database Schema Window
2. Select the OpenDeploy server on which you are setting the mapping parameters from the Selected Server list. 3. Select one of the following choices from the Source list: Data Capture Template if the file is a datacapture.cfg file. Custom DTD if the file is a DTD. This selection implies that a non-Interwoven DTD will be specified. 4. Enter the path to the file in the File box. You can also click Browse and navigate to the location. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt) od-home/conf directory (conf) Double click to browse directories. Single click to select files. 5. Select New Schema or Existing Schema from the Destination list to indicate the type of schema to which you are mapping. 6. Select the type of database where your schema will be mapped from the Database list. 7. Select one of the following choices from the Map Type list: Auto if you want to use an auto-generated map as a starting point. Manual if you want to create a new, blank map.
49
Configuration Files
8. Click Create Map. The result depends on the selections you made when you set the mapping parameters: If you chose to create a new schema, the Map Source File to a New Database Schema screen is displayed. See Creating a New Database Schema File on page 51. If you chose to edit an existing schema, the database connection screen is displayed. See Mapping to an Existing Database Schema on page 50.
Mapping to an Existing Database Schema
To map to an existing schema, follow these steps: 1. Set the mapping parameters according to your needs (see Setting Mapping Parameters on page 49). Ensure that the Destination parameter is set to Existing Schema. 2. Click Create Map. The database connection screen (in this example, for Oracle) is displayed (Figure 16).
Figure 16: Database Connection Window (for Oracle)
3. Perform one of the following tasks: 4. For Oracle enter the system identifier in the System Identifier (SID) box. 5. For other databases enter the database name (for example, Microsoft SQL server or DB2) in the Name box. 6. Enter your database user name in the User box. 7. Enter your password in the Password box. 8. Enter the name of the host on which the database is located in the Host box. 9. Enter the port number to which the database server is listening in the Port box. 10. Click Connect. A status dialog box is displayed as the system connects to the database. A temporary connection is made to retrieve the database tables. After the tables are retrieved, the mapping tool is displayed and the connection is terminated.
50
11. In the mapping tool, select the table to map. Fields in the mapping tool are populated with the properties of that table. See the description of the mapping tool (section B of the UI) in Creating a New Database Schema File on page 51.
Creating a New Database Schema File
To create a new schema file (dbschema.cfg): 1. Set the mapping parameters according to your needs (see Setting Mapping Parameters on page 49). Ensure that the Destination parameter is set to New Schema. 2. Click Create Map. The mapping screen is displayed (Figure 17).
C A B
Figure 17: Map Data to a New Database Schema Window
The screen contains the following panels: Panel A The Data Source panel displays the elements of the XML source file in a tree format. XML nodes contain nested elements, and are indicated by folder icons. Click the arrow next to a node to display its nested elements.
51
Configuration Files
If you have chosen a custom DTD as the source file, Replicant buttons are displayed next to replicant elements in the source tree. Click these buttons to open a dialog box (Figure 18) allowing you to view the existing values that specify the minimum and maximum instances of the replicant, and to set different minimum and maximum values. When you save different values, the new values are transferred to the dbschema.cfg file. After you save the group, click View dbschema.cfg to verify that your changes are reflected there.
Figure 18: Mapping a Custom DTD and Specifying the Replicant Instances
Select elements in panel A and copy them to input boxes in panel B to map those elements to columns in a group. Some elements are not mappable (Replicant, for example); those elements cannot be selected. Panel B The Map Data Source to a New Database Schema panel (Figure 19) contains the buttons and input boxes allowing you to specify how elements from the source file map to columns in the groups you create.
Figure 19: Map Data Source to a New Database Schema Panel
Elements can be copied from panel A to panel B. Also, saved mappings listed in panel C can be edited when they are populated into panel B (see Panel C).
52
Panel C When you save groups that you create in panel B, they are displayed in tree format in the Mapped Tables panel. Groups listed in panel C are hyper linked so that when you click on a group, panel B is populated with the mappings in that group.
If you save (or remove) a group and it is not immediately displayed in the Mapped Tables panel, right click in that panel and choose Refresh from the Internet Explorer
context menu. When that panel is refreshed the group is displayed.

Panel D
This panel contains these buttons: Save: Saves your mappings. Reset Map: Clears the input fields. Remove Group from Map: Removes selected groups from the schema. View dbschema.cfg: Displays the actual XML file, dbschema.cfg, that is the result of your mappings. 3. Create a root group. The root group is the parent to all other tables in the schema. Each schema must contain exactly one root table. It is recommended that you create and save a root group first because that enables the user interface to populate the drop-down menus with that tables group and column names. To specify a group as the root table, select the Root Group of the Schema check box. 4. Create additional groups according to your needs: a. Enter a name for the group in the Group Name box, or copy an element from the data source to that box. b. Create columns by copying elements to the Item Name and Column Name fields as described in Process Flow on page 48 and specify the following: Column Name The name of the column. Primary Key Whether the data stored in that column is a primary key. Foreign Key Whether the data stored in that column is a foreign key. Foreign Key Parent Group The parent group of the data if it is a foreign key. This drop-down menu contains the group names of groups in the schema that have been saved. Foreign Key Parent Column The parent column of the data if it is a foreign key. This drop-down menu contains the column names of groups that have been saved. Data Type/Length The data type and maximum length of data in that column. Date Format The format in which date data is stored in that column (for example, dd-mm-yyyy). Not Null Whether the column data can be null.
53
Configuration Files
Is-URL Whether the column data is a URL. If the column data is specified as
a URL, DataDeploy deploys the content where that URL points, not the URL itself. c. Click the Append Mapping or Delete Mapping buttons to add or delete columns from a group. 5. When you complete a group, click Save. The group is displayed in the Mapped Tables pane. If it is not immediately displayed there, right click in that panel and choose Refresh from the Internet Explorer context menu. When the Mapped Tables panel is refreshed the group is displayed. 6. When you have finished creating and saving groups, click View dbschema.cfg. The dbschema.cfg file is displayed (Figure 20).
Figure 20: Display of the generated file
7. Save the dbschema.cfg file by clicking the Save button (located at the bottom of the main window). The Select File dialog is displayed. 8. Browse to the location where you want to save the file. Double click to browse directories. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt) od-home/conf directory (conf) Single click to select files. 9. Click OK.
54 Database Deployment for OpenDeploy Administration Guide
Updating an Existing Database Schema File
If you chose to work with existing tables, the Map Data Source to an Existing Schema window (Figure 21) appears. Here you can user interface lets you select the table you want. When you select a table, its properties are displayed in the fields of the mapping tool:
Figure 21: Map Data Source to an Existing Database Schema Panel
Mapping a Database Schema with iwsyncdb An alternative to creating a schema with the administration UI is to use iwsyncdb, which lets you create and validate dbschema.cfg files.
Note:
The command options described in the following sections do not support creation or validation of a dbschema.cfg file for a metadata capture configuration file. See DAS and Metadata Deployment on page 107 if you intend to deploy metadata through DAS.
Creating dbschema.cfg Files
Use the following command to create dbschema.cfg files for all templating data types in a given workarea or, optionally, for a particular data type in a particular data category:
iwsyncdb -dbschemagen workareavpath [-dtdfile path_to_DTD] [dcrtype] [-dcfile path_to_data_capture_file] [-force] [-DeployAll]
Details are as follows: This command generates dbschema.cfg files for each data type configured in iw-home/local/config/templating.cfg under the specified workarea workareavpath. For data types that are configured to use custom DTDs, the command looks for a workareavpath/dcrtype/typename.dtd file. Data types that do not have a datacapture.cfg file are skipped. The optional dcrtype setting causes the creation of a dbschema.cfg file for a single data type (rather than all data types in workareavpath). The -force option overwrites any existing dbschema.cfg files.
55
Configuration Files
The -DeployAll option maps all items defined in DCT and ignores database attribute settings. The -dtdfile option generates a dbschema.cfg file for the DTD residing in the file system. You must specify the full path to the associated DTD with this option. The -dcfile option generates a dbschema.cfg file for the DCT residing in the file system. You must specify the full path to the data capture file with this option. Refer to iwsyncdb on page 45 in the OpenDeploy Reference for more information on the iwsyncdb command.
Validating dbschema.cfg Files
You can validate dbschema.cfg files by using:

iwsyncdb -ddgen or -initial iwsyncdb -validate
Note:
By default, iwsyncdb -validate is called as part of both the -ddgen and -initial options in iwsyncdb. Validation errors are recorded in a file called iwvalidate_dbschema.log in the DataDeploy log directory.
Validation of dbschema.cfg Files Using iwsyncdb -ddgen or -initial

Both of these options ensure that dbschema.cfg files are properly configured. These options perform this validation by calling iwsyncdb -validate. If iwsyncdb -validate detects invalid dbschema.cfg files, the process is terminated and the errors are recorded in the iwvalidate_dbschema.log file in the DataDeploy log directory. If a dbschema.cfg file is missing, this log file will not record this as an error.
Validation of dbschema.cfg Files Using iwsyncdb -validate

You can perform validation of dbschema.cfg files for: A workareavpath or a particular data type under workareavpath. A file specified with a complete path name.
Validating by Using workareavpath
The syntax for performing validation of files in a workareavpath is as follows:

iwsyncdb -validate workareavpath [dcrtype]
This command validates the dbschema.cfg files for data types configured in iw-home/local/config/templating.cfg under the specified workarea workareavpath. The optional dcrtype argument specifies that the iwsyncdb command will validate a single data types dbschema.cfg file (rather than all data types dbschema.cfg files under workareavpath). If a particular data type does not have a dbschema.cfg file, that type is skipped and no errors are generated.
56
Creating the DataDeploy Configuration File
Validating by Using a Complete Path Name
The syntax for performing validation of a file specified by a complete path name is as follows:
iwsyncdb -validate dbschema_file_name
This command validates the file specified by dbschema_file_name. The dbschema_file_name argument must specify a complete path to a file that contains the dbschema element.

A DataDeploy configuration file is an XML file that can have any name. It specifies how and where data is to be deployed. A DataDeploy installation can contain any number of configuration files. The most common scenario is for a system to contain multiple DataDeploy configuration files, one for each specific type of deployment. Configuration files are structured with a hierarchy of sections, each letting you control a different deployment parametersuch as deployment type, details about source and destination data, filters, substitutions, and so on. For a sample configuration file that displays many of these parameters, see Appendix A, Sample Configuration File on page 163. The following sections detail two methods for automatically generating a configuration file: the administration UI and the iwsyncdb -ddgen command. A configuration file that is generated by these methods is basic and probably will not include all of the parameters that your deployment needs. If your deployment does need additional parameters to be set in its configuration file, you can create the file manually or use one of the automatic methods and then customize it. In either case, all manual configuration must conform to the structure and syntax of the DataDeploy DTD (od-home/dtd/conf/ddcfg.dtd).
Note:
All configuration files generated by DataDeploy are UTF-8 encoded. Ensure that you save those files as UTF-8 if you edit them. On Windows systems, you can use Notepad or Wordpad to edit those files because those text editors support opening and saving files that are UTF-8 encoded.
57
Configuration Files
Using the Browser-Based User Interface To create the DataDeploy configuration file using the user interface, following these steps: 1. Select Configurations > DataDeploy Configuration to display the Specify Parameters for Data Source window (Figure 22).
Figure 22: Configuration File: Specify Parameters for Data Source Window
2. Select the OpenDeploy server on which the DataDeploy configuration is being run from the Selected Server list. 3. Select TeamSite File System from the Area Type list if the data to be deployed resides in TeamSite. Otherwise, select the file system of the OpenDeploy server (the name of the each server appears in the list.) 4. Select Interwoven DCRs from the XML Data Type list if the deployment data conforms to the Interwoven DTD. Otherwise, select Custom Defined if the data conforms to a custom-defined DTD. 5. Click Next. A continuation of the previous window appears, depending on whether you selected a TeamSite file system (Figure 23) or an OpenDeploy server file system (Figure 24).
Figure 23: Specify Parameters for Data Source Window (cont.) (TeamSite)
58
Figure 24: Specify Parameters for Data Source Window (cont.) (OpenDeploy Server File System)
6. Enter the vpath to the workarea in the Area: Vpath of Area box, or the directory on local disk from which you want to deploy data in the Directory on OpenDeploy Server box. You can also click Browse and navigate to the location. The available locations for the vpath are the following: TeamSite mount point (Y: or /iwmnt) od-home/conf directory (conf) 7. Select whether the data to be deployed is located in a Directory, Filelist, or File from the Location list. 8. Click Next. A continuation of the previous window appears (Figure 25).
Figure 25: Create DataDeploy Configuration File: Specify Parameters for Data Source Window (cont.) Part 2
9. Enter the location (relative to the TeamSite vpath area or file system location) of the data you want to deploy in the Path box, or click Browse and navigate to the location. Enter a period (.) if you do not want to specify a exact location within your TeamSite vpath area or file system location. 10. Specify one of the following Visit Directory options: deep the directory and all its subdirectories that you specify are searched recursively. shallow only the top level of the chosen directory is searched. no no search for deployment data takes place in the location you specified. Note that this item only appears if Directory was specified as the data location in the previous screen. 11. Click Next.
59
Configuration Files
12. The Enter Destination Attributes window appears (Figure 26).
Figure 26: Enter Destination Attributes Window
13. Enter the dbschema.cfg file you want to use in the Dbschema file box, or click Browse and navigate to that location. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt) od-home/conf directory (conf) If you saved a dbschema.cfg file during the current browser session through the Map Database section, the location of that file is displayed in the box. 14. Enter a name for the deployment in the Deployment name box. The default name is basearea. 15. Select the type of database from the Select database vendor list. 16. Click Next. The Enter Database Connection Data window (in this example, for Oracle) appears (Figure 27).
Figure 27: Enter Database Connection Data Window (Oracle)
17. Enter the system identifier (Oracle only) or the database name (all other databases) in the System Identifier (SID) box or Database Name box, respectively. 18. Enter your user name in the User box. 19. Enter your password in the Password box. 20. Enter the name of the host where the database resides in the Host box. 21. Enter the port number where the database resides in the Port box.
60
22. (Optional) Check the Enforce Referential Integrity check box if you want to enforce the constraints set by the primary and foreign keys during deployment and while creating tables. 23. Click View Configuration File. The DataDeploy configuration file is displayed. Figure 28 is a sample file. Files generated from your input might look different:
Figure 28: Sample Generated DataDeploy Configuration File
Modifications made to the file in this window cannot be saved. Modify the file through the previous steps, or through the TeamSite WebDesk interface. 24. Click Save to save the generated DataDeploy configuration file. 25. The Select File dialog box is displayed. Browse to the location where you want to save the file and click OK. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt) od-home/conf directory (conf) After you have saved the DataDeploy configuration file you can click Deployment Setup to continue by executing a deployment.
61
Configuration Files
Using the iwsyncdb -ddgen Command TeamSite-to-database deployments that are deploying DCR files created in TeamSite Templating can be configured with a DataDeploy configuration file autogenerated by the iwsyncdb -ddgen command. The syntax is as follows:
iwsyncdb -ddgen workareavpath dcrtype
where dcrtype provides data_category/data_type. This generates the following DataDeploy configuration file:
workareavpath/templatedata/data_category/data_type/data_type_dd.cfg.
Deploying Multiple XML-Formatted Files as a List of Filelists In the DataDeploy configuration file you can specify multiple xml-formatted-files by using the filelist attribute in the xml-formatted-data element. In the following example:
<deployment name="basearea"> <source> <xml-formatted-data filelist="C:/temp/xmlfilelist.txt"/> </source> <destinations> ... </deployment> xmlfilelist.txt is a text file containing a list of file paths where each path references a file
containing xml formatted data.

xmlfilelist.txt: --------------c:/temp/xmldata1.dump.txt c:/temp/xmldata2.dump.txt xmldata1.dump.txt ----------------<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <xml-tuple-data version="2.0.0"> <data-tuple> <tuple-field name="Reviews/0"></tuple-field> <tuple-field name="Plot Summary">ps</tuple-field> <tuple-field name="ISBN">ABCDEF</tuple-field> <tuple-field name="Author">venkat</tuple-field> <tuple-field name="Cover Picture">pic4</tuple-field> <tuple-field name="Reviews/0/Review Reader">b4r1</tuple-field> <tuple-field name="Reviews/0/Review Reader E-Mail">b4r1email </tuple-field> <tuple-field name="TeamSite/Templating/DCR/Type">internet/book </tuple-field> <tuple-field name="Price">10.00</tuple-field>
62
Sample Configuration Files
<tuple-field name="Reviews/0/Reader Comments"> 0x000x000x000x000xa0xb</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="Publication Date">1999-01-01</tuple-field> <tuple-field name="path">templatedata\internet\book\data\book5 </tuple-field> <tuple-field name="Cover">Paperback</tuple-field> <tuple-field name="Title">book4</tuple-field> </data-tuple> </xml-tuple-data>

The following sections display sample configuration files, each of which applies to and contains the parameters needed for a specific deployment type. For a sample configuration file that displays and describes a more general set of parameters, see Appendix A, Sample Configuration File on page 163. TeamSite to Database The following sample configuration file shows how to set parameters for a typical TeamSite to database deployment. This sample illustrates deploying a TeamSite DCR file to a table in UDS format.
<data-deploy-configuration> <data-deploy-elements filepath="/usr/od-home/conf/db.xml"/> <client> <deployment name="basearea"> <source> <teamsite-templating-records options="wide" area="/default/main/branch1/WORKAREA/wa1"> <path name="templatedata/internet/book/data" visit-directory = "deep" /> </teamsite-templating-records> </source> <destinations> <database use="mydb1" update-type="standalone"> <dbschema> <group name="book" table="book" root-group="yes"> <attrmap> <column name="IW_State" data-type="varchar(255)" value-from-field="state"/> <column name="Path" data-type="varchar(255)" value-from-field="path"/> <column name="Title" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/>
63
Configuration Files
<column name="Cover_Picture" data-type="VARCHAR(255)" value-from-field="Cover Picture" allows-null="yes" is-url="no"/> <column name="Author" data-type="VARCHAR(40)" value-from-field="Author" allows-null="no" is-url="no"/> <column name="Publication_Date" data-type="DATETIME" value-from-field="Publication Date" data-format="yyyy-MM-dd" allows-null="no" is-url="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-from-field="ISBN" allows-null="no" is-url="no"/> <column name="Cover" data-type="CHAR(9)" value-from-field="Cover" allows-null="no" is-url="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no" is-url="no"/> <column name="Plot_Summary" data-type="VARCHAR(255)" value-from-field="Plot Summary" allows-null="yes" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> <key-column name="ISBN"/> </primary-key> </keys> </group> <group name="Reviewers" table="Reviewers" root-group="no"> <attrmap> <column name="ISBN" data-type="VARCHAR(20)" value-from-field="ISBN" allows-null="no" is-url="no"/> <column name="Title" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Review_Reader" data-type="VARCHAR(255)" value-from-field="Reviews/[0-2]/Review Reader" allows-null="no" is-url="no" is-replicant="yes"/> <column name="Review_Reader_E_Mail" data-type="VARCHAR(255)" value-from-field="Reviews/[0-2]/Review Reader E-Mail" allows-null="yes" is-url="no" is-replicant="yes"/> <column name="Reader_Comments" data-type="VARCHAR(255)" value-from-field="Reviews/[0-2]/Reader Comments" allows-null="yes" is-url="no" is-replicant="yes"/> </attrmap>
64
<keys> <primary-key> <key-column name="ISBN"/> <key-column name="Title"/> <key-column name="Review_Reader"/> </primary-key> <foreign-key parent-group="book"> <column-pair parent-column="Title" child-column="Title"> </column-pair> <column-pair parent-column="ISBN" child-column="ISBN"> </column-pair> </foreign-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
65
Configuration Files
TeamSite to XML The following file configures a typical deployment from a TeamSite DCR to an XML file. The xml-formatted-data tag has a single attribute, file, which specifies the absolute path and file name of the destination file. A destinations section can have any number of xml-formatted-data elements, or a combination of xml-formatted-data and database elements.
<data-deploy-configuration> <client> <deployment name="teamsite-to-xml"> <source>  <teamsite-templating-records options="wide" area="/default/main/branch/WORKAREA/myworkarea"> <path name="templatedata/intranet/weather/data/w1"/> </teamsite-templating-records> </source> <destinations> <xml-formatted-data file="/tmp/ts2xml.out"> <fields> <field name="Announcement" element="Announcement"/> <field name="Day" element="Day"/> </fields> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
The XML file that results from invoking the above deployment:
<xml-tuple-data version="2.0.0"> <data-tuple> <tuple-field name="state">Original</tuple-field> <tuple-field name="path">templatedata\intranet\weather\data\a4 </tuple-field> <tuple-field name="Announcement">Its a hot and sunny day </tuple-field> <tuple-field name="Day">Monday</tuple-field> </data-tuple> </xml-tuple-data>
66
TeamSite Extended Attributes to Database The following example illustrates a sample configuration file for deploying TeamSite extended attributes (metadata) to a database, using the user-defined database schema (UDS) feature. This example is applicable to the sample file for metadata capture, installed as:
IWHOME/local/config/datacapture.cfg.example
<data-deploy-configuration> <data-deploy-elements filepath="/usr/local/od-home/etc/database.xml"/> <client> <deployment name="eauds"> <source>  <teamsite-extended-attributes options="wide" area="/default/main/branch1/WORKAREA/workarea1"> <path filelist="/tmp/fileswithea.lst"/> </teamsite-extended-attributes> </source> <destinations> <database use="sybase-sqlanywhere" update-type="standalone" state-field="state"> <dbschema> <group name="eauds_master" root-group="yes"> <attrmap> <column name="path" data-type="VARCHAR(255)" value-from-field="path" allows-null="no"/> <column name="state" data-type="VARCHAR(255)" value-from-field="state" allows-null="no"/> <column name="Title" data-type="VARCHAR(60)" value-from-field="TeamSite/Metadata/Title" allows-null="no"/> <column name="Description" data-type="VARCHAR(100)" value-from-field="TeamSite/Metadata/Description" allows-null="no"/> <column name="Type" data-type="VARCHAR(30)" value-from-field="TeamSite/Metadata/Type" allows-null="no"/> <column name="Category" data-type="VARCHAR(40)" value-from-field="TeamSite/Metadata/Category" allows-null="no"/> <column name="Languages" data-type="VARCHAR(60)" value-from-field="TeamSite/Metadata/Languages" allows-null="no"/> <column name="Source" data-type="VARCHAR(50)" value-from-field="TeamSite/Metadata/Source" allows-null="no"/> <column name="LaunchDate" data-type="DATETIME" data-format="yyyy-MM-dd" value-from-field="TeamSite/ Metadata/Launch Date" allows-null="no"/> <column name="ExpirationDate" data-type="DATETIME" data-format="yyyy-MM-dd" value-from-field="TeamSite/ Metadata/Expiration Date" allows-null="no"/>
67
Configuration Files
<column name="Keywords" data-type="VARCHAR(100)" value-from-field="TeamSite/Metadata/Keywords" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
Note:
If you remove column elements that are mapped to path, you must set the delete-tracker attribute to yes in the database element.
For deletions to work correctly, one of the following conditions must be met: All group elements contain a column child element with its name attribute set to path and mapped to a path value. Only the root group contains a column element with a name attribute set to path and mapped to a path value. The delete-tracker attribute is set to yes in the database element. For example:
<database db="localhost:2638" user="DBA" password="SQL" vendor="sybase" update-type="standalone" delete-tracker="yes" state-field="state">
68
TeamSite Extended Attributes to XML The following file configures a typical deployment from TeamSite extended attributes (metadata) to an XML file. The xml-formatted-data tag has a single attribute, file, which specifies the absolute path and file name of the destination file. A destinations section can have any number of xml-formatted-data elements, or a combination of xml-formatted-data and database elements.
<data-deploy-configuration> <client> <deployment name="teamsite-to-xml"> <source>  <teamsite-extended-attributes options="full" area="/default/main/STAGING"> <path name="."/> </teamsite-extended-attributes> </source> <destinations> <xml-formatted-data file="/u/temp/someTable.xml"/> </destinations> </deployment> </client> </data-deploy-configuration>
The following sample file shows the default format of a typical XML destination file:
<xml-tuple-data version="2.0"> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">small</tuple-field> <tuple-field name="key">size</tuple-field> </data-tuple> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">blue</tuple-field> <tuple-field name="key">color</tuple-field> </data-tuple> </xml-tuple-data>
69
Configuration Files
TeamSite and TeamSite Extended Attributes to Database A deployment data source can be a mix of XML files (or DCR's) and extended attributes. To include extended attributes in a deployment, set the include-extended-attributes attribute to yes in the xml-source or teamsite-templating-records elements. This is shown in the following example:
<data-deploy-configuration> <data-deploy-elements filepath="C:/Interwoven/OpenDeployNG/etc/database.xml" /> <client> <deployment name="basearea"> <source>  <xml-source include-extended-attributes="yes" custom="yes" options="wide,full" area="/default/main/WORKAREA/wa" area-type="ts-filesystem" xml-type="custom"> <path name="templatedata/internet/book/data" visit-directory="deep" /> </xml-source> </source> <destinations> <database use="oracle-db" state-field="state" update-type="standalone" enforce-ri="yes" /> <dbschema> <group name="book" table="deployany_bookmdc" root-group="yes"> <attrmap> <column name="MyPath" data-type="varchar(255)" value-from-field="path"/> <column name="Title" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Cover_Picture" data-type="VARCHAR(255)" value-from-field="Cover Picture" allows-null="yes" is-url="no"/> <column name="Author" data-type="VARCHAR(40)" value-from-field="Author" allows-null="no" is-url="no"/> <column name="Publication_Date" data-type="DATE" value-from-field="Publication Date" data-format="yyyy-MM-dd" allows-null="no" is-url="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-from-field="ISBN" allows-null="no" is-url="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no" is-url="no"/> <column name="Plot_Summary" data-type="VARCHAR(255)" value-from-field="Plot Summary" allows-null="yes" is-url="no"/> <column name="Category" data-type="VARCHAR(40)" value-from-field="TeamSite/Metadata/Category" allows-null="yes" is-url="no"/>
70
<column name="Languages" data-type="VARCHAR(60)" value-from-field="TeamSite/Metadata/Languages" allows-null="yes" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="Title" /> <key-column name="ISBN" /> </primary-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
71
Configuration Files
XML to Database The following file configures a typical deployment from an XML file to a database:
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="xml-to-db"> <source>  <xml-formatted-data file="/u/iw/wcuan/billTable.xml"> <fields> <field name="path" element="path"/> <field name="key" element="key"/> <field name="value" element="value"/> <field name="state" element="state"/> </fields> </xml-formatted-data> </source> <destinations> <database use="oracle8_db" table="TableFromXML"> <select> <column name="Path" value-from-field="path"/> <column name="KeyName" value-from-field="key"/> </select> <update> <column name="Value" value-from-field="value"/> <column name="State" value-from-field="state"/> </update> </database> </destinations> </deployment> </client> </data-deploy-configuration>
In this file, the field elements specify which attributes in the source XML file DataDeploy will use when building a tuple for each Path-Key-Value-State item in the file. The element attribute can name any valid element; it is not limited to naming just the path, key, value, or state elements shown here. Note that the xml-formatted-data element is used in this example and also in the XMLto-XML file in the next section. This tag is appropriate for deploying XML files that were generated by DataDeploy. For any other type of XML file, you can use the xml-source element. For more information, refer to Sample Scenarios for Using the xml-source Element on page 184 in the OpenDeploy Reference.
72
XML to XML The following file configures a typical deployment from an XML file to another XML file. This is different than just copying the source file because it includes an in-flow substitution as described in the file comments. You can also include filters when configuring an XML-toXML deployment, although that feature is not shown here.
<data-deploy-configuration> <client> <deployment name="xml-to-xml"> <source>  <xml-formatted-data file="/u/iw/wcuan/billTable.xml" > <fields> <field name="path" element="path" /> <field name="key" element="key" /> <field name="value" element="value" /> <field name="state" element="state" /> </fields> </xml-formatted-data> </source> <substitution>         <field name="path" match="(.*)/WORKAREA/[^/]+/(.*)" replace="$1/STAGING/$2" /> <field name="path" match="EDITION/abcd" replace="/This/Special/Path"/> <field name="key" match="^BEFORE(.+)" replace="AFTER$1"/> </substitution> <destinations> <xml-formatted-data file="/u/temp/someTable.xml"/> </destinations> </deployment> </client> </data-deploy-configuration>
In this file, the field elements specify which attributes in the source XML file DataDeploy will use when building a tuple for each Path-Key-Value-State item in the file.
73
Configuration Files
Database to XML This section describes extracting data tuples from single or multiple database tables and mapping to an XML file.
Extracting Data Tuples from a Single Table
The following file configures a deployment from a database to an XML file, including remapped field column tags:
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="tupleTable"> <fields> <field name="path" column="EPath"/> <field name="key" column="EKeyName"/> <field name="value" column="EValue"/> <field name="state" column="EState"/> </fields> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
The resulting XML output file is as follows:

<xml-tuple-data version="2.0"> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">small</tuple-field> <tuple-field name="key">size</tuple-field> </data-tuple> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">blue</tuple-field> <tuple-field name="key">color</tuple-field> </data-tuple> </xml-tuple-data>
74
Filtering
The previous implementation extracts all rows from the specified table and creates XML output for the required fields. The following implementation allows you to filter the rows to select from the specified table. Use the database elements where-clause attribute to filter table rows. To filter rows, set the where-clause attribute to a string value that specifies the row selection criteria.
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="tupleTable" vendor="oracle" where-clause="Epath='mypath.txt' AND Evalue like 'myvalue%'"> <fields> <field name="path"column="EPath"/> <field name="key"column="EKeyName"/> <field name="value"column="EValue"/> <field name="state"column="EState"/> </fields> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
In this example, DataDeploy executes the following query to extract data tuples:
SELECT * FROM TUPLETABLE WHERE Epath='mypath.txt' AND Evalue like 'myvalue%'
Note:
You cannot use some of the SQL operators (such as > and <) within the string value for the where-clause attribute because doing so may generate XML parser errors. If you must use such operators as part of the where-clause attribute value, use the db-producer-query element, as shown in the next example.
75
Configuration Files
Extracting Data Tuples from Multiple Tables
The previous examples show database-to-XML deployment implementations that only allow you to extract data tuples from a single table. The following implementation allows you to extract data tuples from multiple tables. This implementation uses the db-producer-query element as a subelement of database:
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="not-used"> <db-producer-query> <![CDATA[ SELECT A.C1, A.C2, B.C3, B.C4 FROM TABLE1 A, TABLE2 B WHERE A.ID = B.ID AND A.ID = 10 ]]> </db-producer-query> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
Notes:
To deploy tuples to an XML file, use the db-producer-query element to specify a complete SQL query statement that DataDeploy should use to extract data tuples. Ensure that the entire SQL select query is within a single CDATA node. If more than one CDATA node is specified under db-producer-query, DataDeploy will only use the first node. Use the where-clause attribute for the database element and the db-producer-query subelement inside the database element only if the database element is a subelement of the source element. If you specify the db-producer-query subelement, DataDeploy ignores the database elements table and where-clause attribute values. If you do not specify a where-clause attribute value and a db-producer-query subelement, DataDeploy will select all rows from the table specified in the database elements table attribute.
76
Specifying Database Connection Properties
Specifying Database Connection Properties

Database connection parameters are specified in the database element of the deployment configuration file. In addition to the basic database connection parameters such as user and password, additional database connection parameters can be specified in a properties file. The path to the properties file is specified in the database elements properties-file attribute as shown in the following example:
<database name="oracle9i" db="host:1521:utf8db" user="username" password="password" properties-file="od-home/conf/additionalprops.txt" vendor="oracle"/>
The contents of the properties file is a set of name-value pairs, as shown in the following example:
prefetch=20 remarks=true batchvalue=25
If connection properties such as user and password are present in both the database element and the properties file, the values present in the properties file will be honored. To use databases not certified by Interwoven, you need to specify the jdbc-driver and protocol-url attributes in the database element. The jdbc-driver attribute gives the name of the JDBC driver class as specified by the vendor that will be loaded by OpenDeploy. For example:
jdbc-driver="com.mysql.jdbc.Driver"
The protocol-url attribute specifies the database URL of the form

jdbc:subprotocol:subname
for the particular database vendor. For example:

protocol-url="jdbc:mysql"
To use a non-certified database with OpenDeploy, make sure you specify vendor="rdbms".
77
Configuration Files
Database Configuration File

The database configuration file is an XML-based file containing all the database-related attributes. This file resides in the following location:
od-home/etc/database.xml
You can specify database connection parameters for different databases in a common database configuration file and specify the path to this file in the data-deploy-elements section of the DataDeploy configuration file. Then a database can be referenced by specifying its name in the use attribute of the database element in the DataDeploy configuration file. The following example illustrates a generic entry for a database in the common database configuration file:
<database name="mydbinstance" db="dburl" user="my_db_username" password="my_dbpasswd" vendor="vendorname"> </database>
See the DataDeploy Release Notes for specific entries for each of the currently supported databases.
Deploying Metadata to UDS

You can deploy TeamSite metadata into a user-defined database schema with a standalone deployment by completing the following steps: 1. Ensure that the update-type attribute in the database section of your DataDeploy configuration file has the value of standalone. The update-type attribute has a default value of standalone if you have not explicitly set the value of this attribute. 2. Generate a default dbschema.cfg file for a metadata datacapture.cfg file that is located in iw-home/local/config by entering the following command at the prompt:
iwsyncdb -mdcdbschemagen [-force]
This command generates a dbschema.cfg file in the following path:

iw-home/local/config/dbschema.cfg.
3. Insert the contents of the generated dbschema.cfg file into the database section of your DataDeploy configuration file. 4. Run the deployment.
78
Changing Default Datatype Size on Internal Tables
Changing Default Datatype Size on Internal Tables

Certain databases do not support the default datatype sizes of internal tables used for database deployments:
iwtracker
used to keep track of base tables and delta tables created by DAS. iwdeltracker used to track row deletions. iwov_idmaps used to store an internal short name for the identifier when the length of the identifier execeeds the limit imposed by the database server. The following types of names are affected: Table names Column names View names Constraint names For example, on MySQL running on a Windows host, a reduced VARCHAR size is required. Using the create_table_overrides.xml file, you can modify these internal tables by changing the size of the VARCHAR columns in the CREATE TABLE statements. An example version of this file (create_table_overrides.xml.example) resides in the following location:
od-home/examples/etc
Make a copy of the example file without the .example extension and update the datatype size as appropriate. You cannot alter the column names, table names, column order, and datatype.
79
Configuration Files
The following sample shows the configuration of the create_table_overrides.xml file:

<sql-statements-override> <create> <table name="iwtracker"> <sql-statement> CREATE TABLE IWTRACKER ( NAME VARCHAR(255) NOT NULL, BASE VARCHAR(255) NOT NULL, BRANCH VARCHAR(255) NOT NULL, UPDATETIME VARCHAR(255) NOT NULL ) </sql-statement> </table> <table name="iwdeltracker"> <sql-statement> CREATE TABLE IWDELTRACKER ( PATH VARCHAR(255) NOT NULL, AREA VARCHAR(255) NOT NULL, KEYCOLNAME VARCHAR(255) NOT NULL, KEYCOLVALUE VARCHAR(255) NOT NULL ) </sql-statement> </table> <table name="iwov_idmaps"> <sql-statement> CREATE TABLE IWOV_IDMAPS ( TYPE INT NOT NULL, SHORTID VARCHAR(255) NOT NULL, LONGID VARCHAR(255) NOT NULL ) </sql-statement> </table> <table name="iwdephistory"> <sql-statement> CREATE TABLE IWDEPHISTORY ( CONFIGNAME VARCHAR(255) NOT NULL, AREA VARCHAR(255) NOT NULL, DEPLOYMENTNAME VARCHAR(255) NOT NULL, FILENAME VARCHAR(255) NOT NULL, ACTIONCODE INT NOT NULL ) </sql-statement> </table> </create> </sql-statements-override>
80
Chapter 4
Database Auto-Synchronization
The OpenDeploy base server facilitates the database auto-synchronization (DAS) feature. DAS is a deployment mode used in the TeamSite development environment to keep metadata and dynamic content synchronized with a database that typically resides on an integration or testing server. Specific user events, such as making a change to templating content, trigger data deployments directly from the source content repository to the target database. For optimal performance, DAS should be configured to work with the Event Subsystem, which lets you filter the events that DAS receives. The ability to filter events greatly improves the scalability and reliability of DAS. After you configure DAS, TeamSite data content records (DCRs) or extended attributes (EAs) are automatically deployed to a database whenever a TeamSite user performs any one of the following tasks: Creates, changes, or deletes a data content record through the TeamSite Templating UI. Creates, changes, or deletes a TeamSite branch, area, or file containing extended attributes through the TeamSite UI. Figure 29 shows the sequence of events associated with DAS.
database
TeamSite DCR or EAs are modified TeamSite event server triggers OpenDeploy.
OpenDeploy OpenDeploy uses DAS synchronize TeamSite data with database.
TeamSite data is synchronized on the database.
Figure 29: DAS
The modification of TeamSite DCRs or EAs results in a TeamSite event that triggers the DAS feature in OpenDeploy. OpenDeploy deploys the modified items to a database, where they can be used in the TeamSite development environment without impacting any production content.
81
Requirements
DAS is an integral part of OpenDeploy. You do not need any additional software to configure and run this feature. DAS only works in conjunction with TeamSite. You cannot use it with any other tool or file management system. Using DAS requires the following products: OpenDeploy TeamSite TeamSite Templating (if DCRs are to be deployed using DAS). If TeamSite Templating is not installed and configured for the area being deployed, only metadata is deployed. Using Multiple Instances of OpenDeploy If you are running multiple instances of the OpenDeploy base server, you can only use DAS with one of the instances. Refer to Running Multiple Instances of OpenDeploy on page 60 in the OpenDeploy Installation Guide for more information on this feature.
Configuration Files
The following table lists those file that control the operation of DAS.
File
daemon.cfg
Location
od-home/etc
Description
database.xml
od-home/etc
or any userdefined location

ddcfg_uds. template od-home/ ddtemplate
Configuration file used by the OpenDeploy base server for start-up. You do not need to modify daemon.cfg before running DAS. However, you can optionally add allowed-hosts and bind tags to daemon.cfg to further control access to the database server. Specifies database connection parameters for different databases. See Editing database.xml on page 83.
ddcfg_uds. custom. template
od-home/ ddtemplate
Template for a database deployment configuration file used to deploy data to user-defined schemas. See Editing Deployment Configuration File Templates and drop.cfg on page 84 for more information. Template for a database deployment configuration file used to deploy data from custom DCRs to user-defined schemas. See Editing Deployment Configuration File Templates and drop.cfg on page 84 for more information.
82
Configuration Files
File
drop.cfg
Location
od-home/ ddsyncdb
Description
iw.cfg
(installed with TeamSite)

odbase.xml
syntracker.cfg
Utility configuration file used by the OpenDeploy base server when dropping tables. You must configure drop.cfg as described in Editing Deployment Configuration File Templates and drop.cfg on page 84 before running DAS. /etc Controls whether renaming, moving, or deleting files (on UNIX) will trigger deployment. Also used to enable the Event iw-home/etc Subsystem. See Editing iw.cfg on page 85 for more (on Windows) information. od-home/etc databaseDeployment element and its associated child elements and attributes. Controls name and port number for the OpenDeploy base server host, and the running mode. Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for more information. od-home/ Utility configuration file used by the OpenDeploy base ddsyncdb server when dropping tables.
These files are installed automatically when you install OpenDeploy, with the exception of iw.cfg. These files must be edited as described in this section before you can configure DAS either through the browser-based user interface or manually with the iwsyncdb command.
Note:
iw.cfg is
installed with TeamSite. To avoid overwriting existing daemon.cfg and ddcfg_uds.template files, the OpenDeploy installation procedure creates daemon.cfg.example and ddcfg_uds.template.example files. If you are performing a first-time installation, the OpenDeploy installer copies these files without the .example suffix.
See the sections following the table for instructions about configuring these files and scripts with your site-specific information. Editing database.xml The database.xml file specifies database connection parameters for different databases. (See Database Configuration File on page 78 for more information). You must set the following attributes in each database element in database.xml:
name db user password vendor
83
For example, the following settings in database.xml cause DataDeploy to connect to an Oracle 8i database server as marketing (using the password al450) and deploy data to the marketingdb database on port 1521 of the server dbserver1, if myproductiondb is being used:
<data-deploy-elements> <database name="myproductiondb" db="dbserver1:1521:marketingdb" user="marketing" password ="al450" vendor="ORACLE"/> </data-deploy-elements>
Editing Deployment Configuration File Templates and drop.cfg To change the destination database, you must edit the configuration file templates that apply to your deployments (ddcfg_uds.template or ddcfg_uds.custom.template) and drop.cfg. In each appropriate template and drop.cfg, you must change the use attribute within each occurrence of the database element to correspond to the new destination database. This database must be specified in the database.xml file that the template(s) and drop.cfg are referencing. For example, if the new destination database is mydb1, change each occurrence of the use attribute to the following:
<database use="mydb1">
After you modify the configuration file templates, you need to regenerate the deployment configuration file by running iwsyncdb -initial.
84
Configuration Files
Editing iw.cfg You must edit the iwserver section of /etc/iw.cfg as follows to support DAS recognition of TeamSite events.
TeamSite Event
SyncDestroy SyncRevert RenameFSE SetEA DeleteEA
Setting in iw.cfg
log_syncdestroy=yes log_syncrevert=yes log_renamefse=yes log_setea=no log_deleteea=no
Once configured, DAS will support these events when they are initiated from the TeamSite user interface.
TeamSite Event
CreateBranch CreateWorkarea DeleteEA
Description
DestroyBranch DestroyEdition DestroyWorkarea PublishStagingArea RenameBranch RenameFSE RenameWorkarea SetEA Submit SyncCreate SyncDestroy SyncModify SyncRevert
A branch has been created. A workarea has been created. An extended attribute (EA) has been deleted from a file. A branch has been deleted. An edition has been deleted. A workarea has been deleted. A new edition has been published from the staging area A branch has been renamed. An FSE has been renamed. A workarea has been renamed An EA has been added to/modified on a file. A file or directory has been submitted. A file with EAs has been created. A file with EAs has been deleted. A file with EAs has been modified. A file with EAs has reverted to an earlier version. A file or directory has been updated.
Update
Refer to your TeamSite documentation for more information on configuring iw.cfg.
85
Specifying an Alternate TeamSite Mount Point
If you are not using the default TeamSite mount point, you must perform additional modification of the iw.cfg file. Refer to Specifying an Alternate TeamSite Mount Point on page 83 in the OpenDeploy Installation Guide for more information.
OpenDeploy Server Configuration

Running DAS operations requires that the OpenDeploy base server configuration file (by default odbase.xml) be configured for database deployment operations. Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for more information
Configuring DAS in the User Interface

You can perform the following DAS tasks from the browser-based user interface: Specify parameters for DAS. Configure DAS to deploy DCRs. Configure DAS to deploy EAs. Specifying DAS Parameters To specify the DAS parameters, follow these steps: 1. Enter DAS > DAS Configuration to display the Specify Parameters for DAS Setup window (Figure 30).
Figure 30: DAS: Specify Parameters for DAS Setup Window
2. Select the OpenDeploy server from the Selected Server list. 3. Enter the path to the appropriate workarea in the Workarea box, or click Browse to navigate to the location.
86
Configuring DAS in the User Interface
4. Check the DAS Setup for Template Types box to deploy DCRs. 5. Check the DAS Setup for Metadata box to deploy extended attributes (metadata). 6. Click Next to continue. The boxes that you check indicate what actions occur when some or all of the following TeamSite events occur: Creations, changes, or deletions of a DCR through the TeamSite Templating user interface. Creations, changes, or deletions of a TeamSite branch, area, or file containing extended attributes through the command line. Creations, changes, or deletions of a TeamSite branch, area, or file containing extended attributes through the TeamSite file system interface. DAS Setup for Template Types If you checked the DAS Setup for Template Types box in the Specify Parameters for DAS Setup window and clicked Next, the DAS Setup for Template Types window is displayed (Figure 31):
Figure 31: DAS Setup for Template Types Window
Here you have the option of selecting the DCR type from DCR Type list. You can also overwrite existing dbschema.cfg and *_dd.cfg files by checking its associated box. Click Execute to start the DAS module. After the DAS setup has completed, you can view the DataDeploy log by clicking its associated button.
87
DAS Setup for Metadata Capture If you checked the DAS Setup for Metadata box in the Specify Parameters for DAS Setup window and clicked Next, the DAS Setup for Metadata Capture window is displayed (Figure 32):
Figure 32: DAS Setup for Metadata Capture Window
You can also overwrite existing dbschema.cfg and *_dd.cfg files by checking its associated box. Click Execute to start the DAS module. As with the DAS Setup for Template Types, you can view the DataDeploy log by clicking its associated button.
Configuring DAS Manually

You can configure DAS manually without using the browser-based user interface through the iwsyncdb command. Running iwsyncdb This section describes how to run the iwsyncdb command, which performs the following activities: Generates the dbschema.cfg file if DAS is set up. Generates configuration files for use by DAS. Submits the generated database deployment configuration files to the staging area and publishes an edition based on the updated staging area. Creates initial base and delta tables in the destination database for the updated TeamSite areas. The following subsections and diagrams explain these activities in detail.
Configuring DAS for a Workarea
To configure DAS for a specific workarea, run the following command:

od-home/bin/iwsyncdb -initial workarea_vpath
for deploying DCRs and EAs
88
Configuring DAS Manually
od-home/bin/iwsyncdb -initial workarea_vpath teamsite/metadata
for deploying only EAs

od-home/bin/iwsyncdb -initial workarea_vpath category/dcrtype
for deploying only a specific DCR type. For workarea_vpath, specify the full vpath to the TeamSite workarea. For example, you would enter the following if the TeamSite Templating is set up for branch b1 and workarea w1 on the default/main branch, and od-home is /usr/iw-home/datadeploy:
/usr/iw-home/datadeploy/bin/iwsyncdb -initial /default/main/ b1/WORKAREA/w1
Generating Database Deployment Configuration Files
Figure 33 shows how database deployment configuration files are generated, submitted, and published when iwsyncdb is run. It shows the sequence of events that occurs when the iwsyncdb -initial command is executed to configure DAS with wide tables.
datacapture.cfg for data type X datacapture.cfg for data type Y datacapture.cfg for data type Z
2 1
deployment configuration file X_dd.cfg
Command Line iwsyncdb -initial
iwsyncdb command
deployment
deployment configuration file Y_dd.cfg deployment configuration file Z_dd.cfg
configuration files submitted Edition published
3
ddcfg_uds.template file
Figure 33: Generation of Data Deployment Configuration Files
1. The iwsyncdb
-initial command
is executed from the command line.
2. The iwsyndb script reads the datacapture.cfg file for each data type that exists in workarea_vpath specified in Step 1. For example, if the TeamSite Templating directory in workarea_vpath contains the data types X, Y, and Z, iwsyncdb reads the datacapture.cfg file corresponding to each data type. See the TeamSite Templating Developers Guide for details about data types and the datacapture.cfg file. 3. The script uses ddcfg_uds.template as the base format of the deployment configuration files that it will generate for each data type.
89
4. Based on ddcfg_uds.template and the datacapture.cfg files for each data type, the script creates configuration files for each data type X_dd.cfg, Y_dd.cfg, and Z_dd.cfg. These files configure a TeamSite-to-database deployment. The mdc_dd.cfg file is also created so that the OpenDeploy base server remains synchronized with other TeamSite features. 5. The newly generated database deployment configuration files are submitted to the staging area, and an edition based on the updated staging area is published.
Note:
If iwsycndb succeeds in generating configuration files for the data types (data_type_dd.cfg), but fails to connect to your database, changes to database attributes in the ddcfg_uds.template file will not be propagated to the data_type_dd.cfg files. If this occurs, edit all data_type_dd.cfg files or use iwsyncdb -force to overwrite the data_type_dd.cfg files.
Other DAS Setup Activities
Figure 34 shows how the remaining DAS setup activities take place when the iwsyncdb command runs.
TeamSite Event Subsystem TeamSite events registered as DataDeploy triggers daemon.cfg
OpenDeploy
Command Line iwsyncdb -initial (continued) OpenDeploy Base Server base server startup information
Reads
daemon.cfg for startup information Runs continuously Automatically deploys data when TeamSite trigger events occur
RDBMS
Figure 34: Other DAS Setup Activities
6. The iwsyncdb command registers a default set of TeamSite events as triggers that will automatically initiate deployment. See DAS Triggers on page 104 for details about which events are registered as triggers. 7. The iwsyncdb command initiates DAS.
90
The Event Subsystem
8. OpenDeploy reads the daemon.cfg file, which contains additional daemon startup information. The daemon finishes its startup, and runs continuously until iwsyncdb -initial is invoked to configure DAS for another branch. 9. The OpenDeploy base server creates the following in the destination database: Initial wide base tables for the branch. Initial delta tables and views for the workarea. DAS is now configured and ready for use. The only time you need to repeat any configuration step is when you enable a different database, user, or password. If you add new templating branches, workareas, or files through the TeamSite UI, DAS automatically generates the necessary deployment configuration files and initial tables.
The Event Subsystem

The Event Subsystem is packaged and installed with TeamSite and can be used to deliver messages (events) to and from OpenDeploy with TeamSite as an event publisher and OpenDeploy as a subscriber. To do this, the Event Subsystem stores and queues events, and it lets you filter which of these events OpenDeploy receives. The Event Subsystem uses a standard model of message delivery, which is based on three concepts: Events synonymous with message. Events are the result of changes, end-user actions, or occurrences in a Publisher program. For example, TeamSite server events include (but are not limited to):
CreateBranch Submit SyncDestroy
Events have names and properties, such as user, role, and timestamp, that are represented in the Event Subsystem as attribute/value pairs. OpenDeploy can be set up to perform functions after a TeamSite event occurs. For example, OpenDeploy can be configured to deploy data directly after end users submit content to TeamSite staging areas. Publishers applications that send events to the Event Subsystem. The Event Subsystem then passes the events to Subscribers that have registered to receive them. Subscribers applications that register with the Event Subsystem to receive events. Subscribers can filter events so that they receive only the ones they need.
91
Figure 35 illustrates how the Event Subsystem works:

Publishers TeamSite Server TeamSite Templating Event Subsystem Subscribers OpenDeploy (DAS)
ProxyServlet
Message Service Interface Message Service Implementation
Figure 35: How the Event Subsystem Works
The following software must be installed and configured before using the Event Subsystem (refer to the OpenDeploy Release Notes for the latest product release compatibility information): TeamSite. OpenDeploy installed on the same system as TeamSite and configured to use DAS. JDBC 2.0 compatible driver. Use JDBC type 4 drivers from i-net software if you are using Microsoft SQL Server 2000. The i-net driver is packaged with OpenDeploy and resides in the following location:
od-home/drivers/UNA2000.jar.
Configuring the Event Subsystem with the Browser-Based User Interface You can perform the following tasks from the Configure Event Subsystem section: Update iw.cfg to enable Event Subsystem configuration. Update the configuration files required by the Event Subsystem. Set up the database tables required by the Event Subsystem to persist events in the database.
92
The Event Subsystem
To configure the Event Subsystem, follow these steps: 1. Select DAS > Event Server Configuration to display the Event Server Configuration: Select Database window (Figure 36).
Figure 36: Event Subsystem Configuration: Select Database Window
2. Select the database that is required for persisting events from the Database Vendor list and click Next. The Event Subsystem Configuration: Set Up Database window for that database appears (Figure 37).
Figure 37: Event Subsystem Configuration: Set Up Database Window
3. Specify the following database attributes in the setup window for the database you selected: Host the name of the database host. Listener Port the port number on which the database server is listening. Database Name (all except Oracle) the name of the database where the tables will be created. Database SID (Oracle only) an attribute specific to Oracle databases, same as Database Name. User Name the name of the user who has permissions to create tables in the specified database. Password the database password for the specified user.
93
Path to JDBC Driver the default JDBC driver path specified, points to the
JDBC driver shipped with DAS. This attribute can be changed to a user-specified driver. 4. Click Next. The Event Subsystem configuration files jmsconfig.xml and eventsubsystem.properties are now updated. Existing configuration files are copied to jmsconfig.xml.old and eventsubsystem.properties.old. The following warning is displayed (Figure 38):
Figure 38: Warning Message
5. Click OK to continue. If the database contains tables with names similar to those required by the Event Subsystem, the Event Subsystem Configuration: Create Tables for Event Subsystem Repository window appears (Figure 39).
Figure 39: Event Subsystem Configuration: Create Tables for Event Subsystem Repository Window
This window contains the table names are listed, and provides you with an option to Drop and Recreate Tables or Keep Existing Tables. If the existing tables match those required by the Event Subsystem, click Keep Existing Tables. Otherwise, it is recommended that the tables be dropped and recreated by clicking either Drop and Recreate Tables or Back, and choosing a different database.
94
The Event Subsystem
6. Select DAS > Start/Stop Event Server to display the Event Server Configuration: Start/Stop the Event Server window (Figure 40).
Figure 40: Event Server Configuration: Start/Stop the Event Server Window
7. Click the Stop Event Server button (if the Event Subsystem is already running) and then restart it by clicking Start Event Server button. 8. Restart JmsProxyServlet to ensure that the servlet engine starts publishing to the Event Subsystem by entering the following TeamSite commands at the prompt.
iwreset iwreset -ui
Configuring the Event Subsystem Manually To configure the Event Subsystem to work with DAS, do the following: Enable the Event Subsystem. Set up a database for event persistence. Set up the Event Subsystem and DAS to publish deployment results. Set up event filters (optional--see Filters and Substitutions on page 124).
Enabling the Event Subsystem
To enable the Event Subsystem: 1. Open one of the following files, depending on your operating system, using your favorite text editor: Windows iw-home/etc/iw.cfg or UNIX /etc/iw.cfg
95
2. Add the following line to the event_subsystem section:

es_enable=true
It is important that the value is true and not yes. Once enabled, the Event Subsystem can be configured either manually or using the OpenDeploy browser-based user interface.
Setting Up a Database for Event Persistence
Event persistence must be managed by a RDBMS. To set up RDBMS-based persistence, follow these steps: 1. Make a copy of the following file:
iw-home/eventsubsystem/conf/jmsconfig_rdbms.xml.example
and give the copied file the following name:

iw-home/eventsubsystem/conf/jmsconfig.xml
2. Open the copied file using your favorite text or XML editor. 3. Remove the comment tags from the RdbmsDatabaseConfiguration section that corresponds to the RDBMS to use. The RdbmsDatabaseConfiguration section is located in the DatabaseConfiguration section of that file. The following code sample shows the commented RdbmsDatabaseConfiguration section for an Oracle database:

Change the values for the driver, url, username, and password attributes according to your needs. 4. Set the jdbc_classpath variable in the following file to the location of your database vendors JDBC driver:
iw-home/eventsubsystem/conf/eventsubsystem.properties
For example: Windows jdbc_classpath=c:\\drivers\\oracle\\classes12.zip or UNIX jdbc_classpath=/var/drivers/oracle/lib/classes12.zip
96
The Event Subsystem
5. Create and register database tables before you start the Event Subsystem. A number of SQL scripts that let you create and register the tables are included with OpenDeploy and reside in the following location:
iw-home/eventsubsystem/conf/ddl/create_dbvendor.sql
Run the script that corresponds with the database to use. You can execute the SQL script using a client utility supplied by the database vendor. For example, if you are using an Oracle database, use SQL*Plus. If you are using Microsoft SQL Server, use Query Analyzer. If you are running this script for the first time, the Event Subsystem tables may not be present and you will receive an error message. Ignore the error message and continue executing the script. 6. Start the Event Subsystem using one of the following methods, depending on your operating system: (Windows) Select Control Panel > Services > InterwovenEventSubsystem. (UNIX) Run the iw-home/private/bin/iweventsubd script. 7. Restart JmsProxyServlet to ensure that the servlet engine starts publishing to the Event Subsystem by entering the following commands at the prompt.
iwreset iwreset -ui
Setting Up the Event Subsystem and DAS to Publish Deployment Results
If DAS is being used with the Event Subsystem for the first time use the OpenDeploy browser-based user interface to configure the Event Subsystem. This will also set up DAS to publish deployment results. If you have already used DAS with the Event Subsystem, and you would like to enable the DAS Reports feature, you need to manually configure the Event Subsystem and DAS by performing the following steps: 1. Open the following file using your favorite text or XML editor:
iw-home/eventsubsystem/conf/jmsconfig.xml
2.
Add
a Datadeploy_History topic line in the AdministeredDestinations section:
<AdministeredTopic topicName="Datadeploy_History"/>
Your AdministeredDestinations section should look like the following:

<AdministeredDestinations> <AdministeredTopic topicName="TeamSite_User"/> <AdministeredTopic topicName="TeamSite_System"/> <AdministeredTopic topicName="TeamSite_Workflow"/> <AdministeredTopic topicName="Datadeploy_History"/> </AdministeredDestinations>
3. Stop and restart the Event Subsystem.
97
4. Open the following file using your favorite text editor:

od-home/etc/daemon.cfg
5. Add the attribute das-publisher="yes" in the event-subsystem element, for example:

<event-subsystem das-publisher="yes"> <jmsserver> ... </event-subsystem>
6. Stop and restart DAS. Logging Options for Event Subsystem You can change the logging level for the event subsystem by modifying the LoggerConfiguration elements logLevel attribute in the following configuration file:
iw-home/eventsubsystem/conf/jmconfig.xml
For example:
<LoggerConfiguration fileName="openjms.log" logLevel="error" type="ConsoleLogger"/>
You can choose one of the following logging level options: designates very severe error events that will presumably lead the application to abort. error designates error events that might still allow the application to continue running. info designates informational messages that highlight the progress of the application at coarse-grained level. This is the option used if an invalid option (any option other than the ones listed here) is specified. debug (default) designates fine-grained informational events that are most useful to debug an application. Both debug and info messages are written to the log files.
fatal
The fatal and error options do not generate log messages unless an actual error occurs. During startup and shutdown, no messages occur unless there is a problem. Although the configuration suggests that the log file is named openjms.log, the event subsystem actually logs information into the following files: Windows eventsubd_out.log and eventsubd_err.log UNIX eventsubd.log
98
Generating DAS Reports
Generating DAS Reports

After you have configured the Event Subsystem and DAS to publish deployment results, you can generate deployment reports for DAS. DAS reports are generated similar to other OpenDeploy reports. Refer to DAS Custom Reports on page 294 in the OpenDeploy Administration Guide for more information.
Using DAS
After DAS is configured, it is transparent to TeamSite Templating end users. Therefore, there are no additional tasks that an end user must perform to use DAS. The following diagram shows how DAS automatically updates the necessary tables when a TeamSite trigger event occurs. See the diagram key following the diagram for details about each step.
TeamSite
End user activity results in TeamSite trigger event
iwsyncdb
Receives and interprets data from TeamSite trigger event Passes data to OpenDeploy
2
OpenDeploy
Determines which deployment configuration file to use Deploys data to database
RDBMS
3
Figure 41: Using DAS
1. TeamSite Templating end-user activity (that is, any activity shown in DAS Triggers on page 104) results in a TeamSite event trigger. The event trigger starts the iwsyncdb command and sends the changed data to the script. If the Event Subsystem is configured, the TeamSite trigger event directly triggers the OpenDeploy base server, without starting iwsyncdb. 2. The iwsyncdb command sends the data content record to the DataDeploy daemon. The daemon determines which database deployment configuration file(s) to use for the deployment. For TeamSite events (for example, Create Branch) that are not specific to a single file, the daemon uses the templating.cfg file to determine which data types (and therefore which database deployment configuration files) are affected by the TeamSite event.
99
For example, in the case of a Create Branch TeamSite event, the OpenDeploy reads templating.cfg to determine which data types exist in the branch. OpenDeploy then uses the database deployment configuration files for each affected data type when deploying the new data to the database. For events that are file-specific (for example, renaming a file), the daemon uses the information from the TeamSite event information module to determine which file is affected and which database deployment configuration file to use. 3. OpenDeploy uses the appropriate database deployment configuration files to update the affected base and delta tables in the database. Table Update Examples This section describes how the base and delta tables described in the preceding section change as data is deployed. This example shows a hypothetical update to a data content record. In this example: The data category is internet. The data type is pr (press release). The branch is b1. The workarea is w1. When the initial wide base table is created it contains a Path column, a State column, and columns for each item in the data content record. In this starting state, the table does not yet contain any values. Assume that the first three items are PressDate, Headline, and Picture. You may omit the State column from any table. It is unlikely that you would need to omit it from a delta table. Some scenarios could necessitate omitting it from a base table. The resultant wide table looks like this:
Path State PressDate Headline Picture ...
When the initial delta table is created, it contains the same columns as the initial base table, in addition to values for each item:
Path mypath State New PressDate 4/17/03 Headline New Candidate Enters Race Picture ...
cand.gif ...
100
Using DAS
When the data content record is submitted, its delta table values are transferred to the base table, and its own cells are cleared, as shown in the following two tables:
Path mypath State New PressDate 4/17/03 Headline New Candidate Enters Race Picture cand.gif ... ...
Path
State
PressDate
Headline
Picture
...
Specifying How Tables are Updated You can specify how OpenDeploy updates tables. OpenDeploy can update tables in the following ways: By deleting existing rows and inserting new ones (default). By executing a series of UPDATE SQL statements. That method is referred to as real updates. DAS supports the deployment of wide tuples and tuples mapped to UDS, but it does not support the deployment of narrow tuples. Thus, you cannot use DAS to deploy to narrow tables. Two attributes in the database element in database deployment configuration files enable you to specify which kind of update OpenDeploy performs:
enforce-ri real-update
If you need to modify such fields, you must clear the value, then save and deploy the DCR. Then insert the new value, save the DCR, and deploy it. Databases report constraint violation errors if child tables reference the field values you are deleting. Therefore, you must also delete the corresponding rows in child tables. To do that automatically, set the ri-constraint-rule attribute to "ON DELETE CASCADE". Recreate the rows when you insert the new value for the parent table.
DATE, DATETIME, TIMESTAMP, CLOB,
and BLOB data types are always updated regardless of
whether the data has been modified.
101
Table Naming Conventions Base and delta tables use the following naming convention:
storename_datacategory_datatype__branchname_areaname
This naming convention includes using double underscores between datacategory_datatype and branchname_areaname. Accordingly, tables for DCR/Templating data-types would be named the following:
STORENAME_DATATYPE__ACTUALAREA
where ACTUALAREA would be MAIN_BRANCHNAME_STAGING for staging area tables and MAIN_BRANCHNAME_WORKAREA_WANAME for workarea tables. For example, if you are deploying from area /store1/main/branch1/WORKAREA/wa1 for data category intranet and data type weather, the table names would be: For the staging area STORE1_INTRANET_WEATHER__MAIN_BRANCH1_STAGING For workarea STORE1_INTRANET_WEATHER__MAIN_BRANCH1_WORKAREA_WA1 For metadata for the same area, the table names would be: For the staging area STORE1_TEAMSITE_METADATA__MAIN_BRANCH1_STAGING For workarea STORE1_TEAMSITE_METADATA__MAIN_BRANCH1_WORKAREA_WA1
Note:
The DAS table naming conventions are subject to change, so do not use the DAS table names in your production environment. Create synonyms or aliases for the DAS tables and use those names instead of DAS-generated table names.
For UDS tables, there is an additional group name nested between the data type and branch name:
storename_datacategory_datatype__groupname__branchname_areaname
For example:
STORE1_INTRANET_WEATHER__FORECASTERS__MAIN_BRANCH1_STAGING
Note that the group name is separated by two underscores (__) on each side.
102
Using DAS
Database Object Name Lengths To overcome the maximum database object name length imposed by database servers, OpenDeploy builds a mapping table called IWOV_IDMAPS in the destination database. For each object name that exceeds the maximum length limit for the database, this mapping table establishes a relationship between the original object name and a generated name conforming to the databases object name length limits. The generated name is then used in place of the original object name in all database transactions. This implementation allows table names, column names, constraint names, and view names to contain any number of characters. Note that this table is also used for standalone deployments when object names exceed the maximum length. The IWOV_IDMAPS table contains the following three columns:
Type Longid Shortid
The Type column defines types as follows:

1: 2: 3: 4: Table name Column name View name Constraint name
The Longid column contains the entire character string for the object as it appears in the original source file. The Shortid column contains the generated name conforming to the databases object length limits. For example, a typical table might appear as follows:
Type Longid
2 1 3 4
INFORMATION0_PRESENTATIONTITLE INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_VIEW INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_CONSTRAINT
Shortid
IWC_AA6A93A7161 IWT_106342E4D4C4 IWV_AEGF12D4E IWO_F023AF1290
Because different databases support different maximum object name lengths, the threshold for when a Shortid name is generated depends on the database vendor or type. OpenDeploy uses the values set for the max-id-length attribute to determine this threshold. When deploying to an IBM DB2 database, OpenDeploy maps table, column, and view names only when a name exceeds 128 characters, and maps constraint names only when they exceed 18 characters.
103
If you construct an SQL statement that performs an activity on a table that was created by OpenDeploy, and if that table contains any database objects whose names exceed the maximum length, the SQL statement must first reference the mapping table to determine the actual (Longid) object name(s). This requirement applies to all SQL statements, including those not executed through OpenDeploy. DAS Triggers DAS interprets the following TeamSite events as deployment triggers. The event can be initiated from the TeamSite UI, the TeamSite file system interface, or the command line. Whenever one of these events occurs, the delta and base tables are updated as shown in the following table. For delta table updates, only the tables affected by the triggering TeamSite event are updated.
TeamSite Event Delta Table Action Base Table Action
Create branch Create workarea Delete branch Delete workarea Modify data content record Add data content record Delete data content record
None. Build delta tables. Delete delta tables. Delete delta tables. Update or insert a new row. Insert a new row.
Build empty base tables. None. Delete base tables. None. None. None.
Insert or update the NOT-PRESENT row. None. Update the Staging row.
Submit modified data 1. The Previous Staging row is content record propagated to all workareas except the submitting workarea. 2. Delete Previous Staging row from submitting workarea. Submit added data 1. The Placeholder row marked NOTPRESENT is propagated to all workareas content record except the submitting workarea. 2. Delete the Placeholder row from the submitting workarea. Submit deleted data 1. The previous Staging row is content record propagated to all workareas except the submitting workarea. 2. Delete the previous Staging row from the submitting workarea. Get latest (workarea) Rebuild the delta tables. Copy to (any area) Rebuild the delta tables.
Update the Staging row.
Update the Staging row.
None. None.
104
Using DAS
TeamSite Event
Delta Table Action
Base Table Action
Rename workarea Rename branch
1. Delete old delta tables. 2. Regenerate new delta tables. None.
None. 1. Delete old base tables. 2. Regenerate new base tables. None. None.
Rename directory Rename file
Move file
Delete file
Set metadata Revert
Regenerate delta tables. 1. Delete the row for the old file name. 2. Add a row for the new file name. 1. Delete the row for the old file name. 2. Add a row for the new file name. If a row for the file exists in the base table, the row in the delta table is marked NOT-PRESENT. If no row existed in the base table, the row in the delta table is deleted. Insert or update the row. Use the data from the earlier version of the file (selected in the TeamSite graphical user interface) to update or insert a new row.
None.
None.
None. None.
Configuring TeamSite Event Logging By default, all TeamSite events are recorded in the following log files: Windows iw-home/local/logs/iwevents.log or Solaris var/adm/iwevents.log If you see degraded system performance due to enabling certain TeamSite events, you can turn off logging for any of the TeamSite events shown in the table in Editing iw.cfg on page 85. Use the following event names when you disable logging:
RenameFSE SyncDestroy SyncRevert
For example, to prevent Rename events from being recorded, set the following in iw.cfg:
iwevents_exclude="RenameFSE"
105
You can also use (Perl 5) regular expressions with the following syntax to further control event logging:
renamefse_filter="REGEX"
For example, to specify that only Rename events occurring in the workarea bill are logged:
[iwserver] renamefse_filter="/default/main/WORKAREA/bill"
This entry sets regular expressions, one of which must match the event line (as seen in iwevents.log) for an event to be logged. If these are empty or absent, all corresponding events are logged.
Note:
When viewing log files that have been created in a multibyte environment, ensure that you use an appropriate text editor to view them.
Database Virtualization Views DAS can create virtualization views for a workarea that are similar in behavior to TeamSite virtualization. When you query these views, if a file in a workarea is the same as the file in the staging area, the view retrieves the record corresponding to that file from the staging area or base tables. If a file in a workarea has been updated but not submitted to the staging area, then the database record for that particular file will be retrieved from the workarea or delta table. The virtualization view created by DAS is for a specific workarea. To enable the automatic creation of virtualization views by DAS, set the flag table-view attribute to yes in the deltagen deployment section of the database deployment configuration file for a specific data type type/type_dd.cfg. For example, internet/book/book_dd.cfg). The CREATE VIEW command in the following example is the default schema that executes when table-view is set to yes in the database deployment configuration files database element.
CREATE VIEW areaview AS SELECT * FROM stagingtable WHERE NOT EXISTS (SELECT * FROM WAtable WHERE WAtable.Path= stagingtable.Path ) UNION ALL SELECT * FROM WATable WHERE WATable.IW_State != 'NotPresent'
To query from the view:

SELECT path FROM areaview WHERE key = News-Section AND value = Sports
106
Using DAS
The virtualization view uses a column mapped to a state value in the WHERE clause of the view definition. However, the iwsyncdb -ddgen command run during DAS initialization automatically adds a column for the state value only for the root group in the generated template_type_dd.cfg file. To create virtualization views for all tables defined in the deployment (including non-root groups): 1. Generate or manually create the dbschema.cfg file for the data type. 2. For all the non-root groups, add a column element to map the state value, for example:
<column name="IW_state" data-type="VARCHAR(255)" value-from-field="state" allows-null="no"/>
3. Open the following file using your favorite text editor: (If deploying Interwoven-style DCRs) od-home/ddtemplate/ ddcfg_uds.template or (If deploying custom DCRs) od-home/ddtemplate/
ddcfg_uds_custom.template
4. Add the table-view attribute to the database element for the deltagen deployment, for example:
<database use="usename" ... table-view="yes">
5. Issue the iwsyncdb -ddgen command for the workarea and template type for which you performed the preceding setup. 6. After running iwsyncdb -initial to register all the tables create views for the nonroot groups use the CREATE VIEW command as explained earlier. DAS and Metadata Deployment DAS can be enabled to deploy TeamSite metadata. Perform the following steps to use DAS with metadata capture: 1. Navigate to the following location:
od-home/ddtemplate
2. Rename the file mdc_ddcfg_uds.template.example to mdc_ddcfg_uds.template. 3. Configure the appropriate database sections. 4. Ensure that you also set up iw-home/local/config/datacapture.cfg. 5. If deploying metadata using UDS, run the following command:
od-home/bin/iwsyncdb -mdcdbschemagen
This generates the following file:

iw-home/local/config/dbschema.cfg
107
To deploy TeamSite metadata into a UDS in DAS mode, follow these steps: 1. Generate a default dbschema.cfg file for a metadata datacapture.cfg file that is located at iw-home/local/config/datacapture.cfg by entering the following command at the prompt:
iwsyncdb -mdcdbschemagen [-force]
2. Create an mdc_ddcfg_uds.template file in the od-home/ddtemplate directory. 3. Enter the following command at the prompt:
iwsycdb -mdcddgen [-force]
An iw-home/local/config/mdc_dd.cfg file is created.
DAS Out-of-Sync Conditions

The following scenarios are not supported by DAS and will cause out-of-sync conditions with the database:
Scenario 1: Using the iwextattr command-line tool to add or delete extended attributes
on a file if DAS is set up for extended attributes with wide tables.

Scenario 2: Manipulating a data content record (for example, renaming, editing, moving, deleting, and so forth) from the command line or file system interface. Scenario 3: Shutting down the OpenDeploy and then performing any kind of extended attribute or file manipulation. In this situation, you must either restart OpenDeploy or perform a manual resynchronizing deployment, for example by running the following command at the prompt:
iwsyncdb -resyncwa iwsyncdb -resyncbr
or
Tutorial
This manual includes a tutorial for configuring and using DAS. See Appendix B, Database Deployment Tutorials on page 173 for more information.
108
Chapter 5
DataDeploy Deployments
This chapter describes methods and configuration of data asset deployment using the optional DataDeploy module. You must license the DataDeploy module to perform any of the tasks listed in this chapter. Refer to Enabling the DataDeploy Module on page 68 in the OpenDeploy Installation Guide for details about enabling the DataDeploy module. Using the DataDeploy module, you can perform the following data asset deployments: Standalone database deployments deployment of data assets from a base server to a database. Target-side database deployments deployment of data assets as files from a base server to an OpenDeploy target. Upon receipt of the data asset files, they are subsequently moved to a database. Included in target-side database deployments are synchronized deployments that move code and content files to their targets simultaneously. These types of database deployments are on-demand, non event-driven deployments. They differ from automated (DAS) deployments in a number of ways: Database deployments do not require the presence of TeamSite. DAS deployments do, on the other hand, because they are triggered by events occurring in TeamSite. With database deployments, table naming conventions can be defined by the user, but with DAS, table names are generated based on the vpaths and data types involved (see Table Naming Conventions on page 102). The names and locations of the database deployment configuration files can be defined by the user. With DAS, the configuration files must be located in the TeamSite file system and must be named based on the templating data type involved. The rest of this chapter describes the different methods and configurations for configuring and performing database deployments. You should first familiarize yourself with how to the database deployment configuration tasks described in Chapter 3, Configuration Files on page 47 before continuing with this chapter.
109
Standalone Database Deployments

A standalone database deployment accesses structured content (TeamSite metadata, TeamSite DCRs or arbitrary XML) residing on the source, and subsequently moves the content of these files to a supported relational database using JDBC.
structured content files Structured content files are deployed to relational database using JDBC
source
database
Figure 42: Standalone Database Deployment
Figure 42 shows an OpenDeploy source that has a repository containing structured content files. When the deployment is run, the deployment configuration references a separate DataDeploy configuration file also residing on the source. The DataDeploy configuration file contains the information and settings needed to access the structured content, and copy the contents to a relational database. Standalone deployments typically are used when you want to directly deploy structured content right into a database. Usually the database is near the source content, inside the same firewall. Popular use cases include writing templating data or metadata into the database. Standalone database deployments are similar to DAS, except that instead of a TeamSite event triggering a deployment, you can run the deployment at the time and method of your choosing, such as from the browser-based user interface, through a command-line tool, and through the deployment scheduling feature. You also can deploy any type of structured content, not just those associated with TeamSite. Server Configuration Only OpenDeploy base servers can perform standalone database deployments. The OpenDeploy base server must have its database deployment functionality enabled in its base server configuration file. Refer to the section on Database Deployments on page 141 in the OpenDeploy Installation Guide for more information.
110
Standalone Database Deployments
Database Deployment Configuration and Execution You can configure and run a standalone database deployment using one of the following methods: Running an OpenDeploy configuration that references the appropriate DataDeploy configuration file. Running the DataDeploy configuration file directly.
Referencing a DataDeploy Configuration File Within an OpenDeploy Configuration
You can include a reference to the DataDeploy configuration file in a standard OpenDeploy deployment configuration file using the dataDeploy element:
<deploymentConfiguration> <dataDeploy configFilePath="path_to_DataDeploy_config_file"/> <logRules ... /> </deploymentConfiguration>
This type of configuration is known as a DataDeploy wrapper file. The dataDeploy element contains the configFilePath attribute, whose value specifies the full path to the appropriate DataDeploy configuration file. This method is useful if you have legacy DataDeploy configuration files residing within the TeamSite directory. For example:
<dataDeploy configFilePath="/usr/DataDeploy/conf/datadeployment.cfg"/>
DataDeploy configurations files referenced in this manner can reside anywhere on the host file system, and contain the .cfg, as well as the .xml, file extension. See Creating the DataDeploy Configuration File on page 57 for more information. Note that other than the logRules element, the OpenDeploy configuration file includes only the dataDeploy element and its configFilePath attribute. No other OpenDeploy elements or attributes can reside in the deployment configuration. You can run the OpenDeploy deployment using any 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.
111
Running the DataDeploy Configuration Directly
You also can run a DataDeploy configuration directly, either in the Start Deployment window in the OpenDeploy browser-based user interface, or using the iwodcmd start command from the command line:
iwodcmd start DataDeploy_configuration -k iwdd=internal-deployment-name
Any DataDeploy configuration you want to run must reside in the od-home/conf directory, and have the .xml extension. If you move a legacy DataDeploy configuration file into the conf directory, you must change its .cfg extension to .xml. You can also use OpenDeploy scheduling tools to DataDeploy configurations from the /conf directory. Specifying an Alternate TeamSite Mount Point If you are deploying from a TeamSite source file location, and you are not using the default TeamSite mount point, you must perform additional modification of the iw.cfg file. Refer to Specifying an Alternate TeamSite Mount Point on page 83 in the OpenDeploy Installation Guide for more information. Tutorial This manual includes a tutorial for configuring and running standalone database deployments. See Appendix B, Database Deployment Tutorials on page 173 for more information.
112
Target-Side Database Deployments

Target-side database deployments move structured content (TeamSite metadata, TeamSite DCRs, or arbitrary XML) from an OpenDeploy source to an OpenDeploy target (either another base server or receiver). After receiving the deployed content, the receiver subsequently deploys the content into a supported relational database using JDBC. The deployment configuration includes additional information that specifies how the content to be written into the database. Figure 43 shows how a target-side database deployment works. Structured content files are deployed in the same manner as code and content files. If the deployment is comparison based, a comparison of both types of files occurs, and only the appropriate files are deployed. When the deployed files are received, the structured content is deployed to a relational database. The database type and mapping schema are referenced by the deployment configuration from other configuration files present on the source.
Structured content files are deployed to target
Structured content is deployed to database. using JDBC.
source
target
database
Figure 43: Target-Side Database Deployment
Deploying structured content in this manner allows OpenDeploy to reside closer to the target database, such as on the same LAN. Additionally, target-side database deployments allow you to take advantage of many OpenDeploy features, including the following: Fan-out transactional deployment, which allows synchronization of files and database content. Encrypted data transfer for secure deployment between OpenDeploy servers. Data compression for reduced network traffic between OpenDeploy servers.
113
Synchronized Deployments Synchronized target-side database deployments guarantee the collective integrity of structured content destined for a database with code and content files. Common examples include: Files with associated metadata for use by a search engine. Online catalog details along with web presentation templates. Documents and personalization data for a portal. JSP code and related data for an application server. OpenDeploy provides a secure, flexible, and scalable solution for the cross-platform, transactional transfer of file assets to multiple servers. It can be configured to call DataDeploy to reliably and securely deliver database content along with file system assets. If any part of the deployment transaction fails, the database and files are automatically rolled back. Figure 44 shows an OpenDeploy source that has both structured content and standard code and content files. When the deployment is run, all the files are deployed to their separate target file locations, with structured content subsequently being deployed to the relational database.
Code and content files are deployed to target. Structured content files are deployed to target source target
XML content is deployed to database. using JDBC.
database
Figure 44: Synchronized Database Deployment
114
Synchronized deployments can deploy files to multiple OpenDeploy targets as a fan-out deployment (Figure 45). However, only one target can be specified for the receipt of data asset files that are to be written to a database.
Code and content files are deployed to target. target Code and content files are deployed to target. Structure content files are deployed to target. source Code and content files are deployed to target. target target database XML content is deployed to database. using JDBC.
Figure 45: Synchronized Database Fan-out Deployment
Server Configuration Both OpenDeploy base servers and receivers can be recipient targets of synchronized database deployments. The following sections describe the requirements for source and target servers participating in a target-side database deployment.
Source Server
The following tasks must be performed on a source OpenDeploy base server: The DataDeploy module must be enabled. Refer to Enabling the DataDeploy Module on page 68 in the OpenDeploy Installation Guide for more information on installing and licensing the DataDeploy module. The databaseDeployment element in the source base server configuration file (by default odbase.xml) must be enabled. Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for more information. The deployment configuration must include the dbLoader element. This element references a database schema file, and also references the defined database element in the servers database configuration file (database.xml, see next section). See Deployment Configuration on page 116 for more information. The dnrProperties elements infoStreamFormat attribute value must be set to manifest. Refer to Specifying the Deployment Information Stream Format on page 119 in the OpenDeploy Installation Guide for more information.
115
Target Servers
The following tasks must be performed on each target OpenDeploy base server or receiver: The databaseDeployment element on the target OpenDeploy servers configuration file (by default odbase.xml or odrcvr.xml) must be enabled. Refer to Database Deployments on page 141 in the OpenDeploy Installation Guide for more information. The servers database configuration file (database.xml) must contain a defined database element corresponding to the database type being used. Refer to Database Configuration File on page 78 in the Database Deployment for OpenDeploy Administration Guide for more information. Deployment Configuration The deployment of database assets as part of a file deployment is specified by the inclusion of the dbloader element within the pathSpecification element of the deployment configuration:
<pathSpecification> ... <dbLoader useDatabaseRef="mydatabase" databaseXmlFile="/targethost/database.xml"> ... </dbLoader> ... </pathSpecification>
The dbLoader element includes the following attributes:

useDatabaseRef specify a particular database included as part of the set specified by
the database XML file. For example:

<dbLoader useDatabaseRef="mydatabase" ...> databaseXmlFile
specify the full path to the database XML file, where database connection parameters for different databases are listed. For example:
<dbLoader useDatabaseRef="mydatabase" databaseXmlFile="/targethost/database.xml">
If no value is specified, the default value is used:

databaseXmlFile="od-home/etc/database.xml"
where od-home is OpenDeploy home directory on the target.
116
Within the dbLoader element, you must indicate which of the two methods of database asset deployment by specifying one of the following elements:
xmlData
indicates that those files being deployed are XML files whose contents are to be deployed to a database. For example:
<dbLoader useDatabaseRef="mydatabase" databaseXmlFile="/targethost/database.xml"> <xmlData schemaMapFile="/myschemas/schemaForXmlType1.cfg" xmlType="interwoven"/> </dbLoader> eaData
indicates that those files being deployed have associated TeamSite extended attributes that are to be deployed to a database. For example:
<dbLoader useDatabaseRef="mydatabase" databaseXmlFile="/targethost/db.xml"> <eaData schemaMapFile="/usr/local/iw-home/local/config/ dbschema.cfg"/> </dbLoader>
Both the xmlData and eaData elements contain the same schemaMapFile attribute, which specifies the full path to the DataDeploy database schema file. For example:
schemaMapFile="/source/allschemas/map1.cfg"
This file contains the settings required to write the deployed database assets to the target database. The xmlData element also contains the xmlType attribute. Specify one of the following values for this attribute:
interwoven the DCRs use the Interwoven style, as indicated by the dcr-type attribute having the value iwov in TeamSites templating.cfg file. custom the XML or DCR files are based on the user's custom-defined style, as indicated as indicated by the dcr-type attribute having the value xml in TeamSites templating.cfg file.
Refer to the TeamSite documentation for more information on configuring the templating.cfg file.
117
You can also indicate that those files being deployed are XML files whose contents are to be deployed to a database, and that also have associated TeamSite extended attributes, by specifying the eaAndXmlData element under the dbLoader element. Within the eaAndXmlData element you can specify both the xmlData and eaData elements, for example:
<dbLoader useDatabaseRef="mydatabase" databaseXmlFile="/targethost/db.xml"> <eaAndXmlData> <xmlData schemaMapFile="/myschemas/schemaForXmlType1.cfg"/> <eaData schemaMapFile="/usr/local/iw-home/local/config/ dbschema.cfg"/> </eaAndXmlData> </dbLoader>
Specifying DataDeploy Configuration Elements
You can include certain DataDeploy configuration elements in the deployment configuration using the dbLoaderCustom element within either the xmlData or eaData elements. You can configure any of the following DataDeploy configuration elements and their respective child elements as a PCDATA string within the dbLoaderCustom element:
external-tuple-processor filter substitution
For example:
<xmlData schemaMapFile="/path/to/type1.schema" xmlType="custom"> <dbLoaderCustom> <![CDATA[ <external-tuple-processor class-name="myTppClass" interface-version="2.0"/> <filter> <keep> <or> <field name="key" match="city"/> <field name="value match="paris"/> </or> </keep> </filter> <substitution> <field name="key" match="BEFORE" replace="AFTER"/> </substitution> <substitution use="globalFromTargetDatabaseXml"/> ]]> </dbLoaderCustom> </xmlData>
Any other DataDeploy elements other than ones listed here are ignored.
118
Structured Content Deployments
If you are only deploying structured content to a database, simply configure the deployment with the structured file repository as the source file location. The dbLoader element and its associated attributes and child elements still must be configured.
Synchronized Deployment
If you are performing a synchronized deployment of code and content files with database content, you can configure the source file locations files in one of the following methods: Configure separate definitions for the file and database asset legs, for example:
<deploymentConfiguration> ... <definition name="OpenDeploy_files"> ... </definition> <definition name"DataDeploy_files"> ... <dbLoader ...> ... </dbLoader> ... </definition> ... </deploymentConfiguration>
Configure separate path specifications within the same source file location, for example:
<remoteDiff area="/default/main/WORKAREA/jdoe/files"> <pathSpecification <path name="."/> </pathSpecification> <pathSpecification> <path name="data_assets"/> <targetRules area="od-home/tmp/files/data_assets"> ... </targetRules> <dbLoader ...> ... </dbLoader> </pathSpecification> </remoteDiff>
Note that this method of configuration requires that all files reside within the specified source file system, and that the structured content files be in a distinct location from the other files. In this example, the code and content files destined for target file servers resides in the specified source file location:
/default/main/WORKAREA/jdoe/files
while the structured content files destined for the target database reside in a subdirectory:
/default/main/WORKAREA/jdoe/files/data_assets
119
Additionally, because this configuration is deploying two separate sets of files, they must also be kept distinct on the target. Therefore, a target override (the targetRules element) is included in the data asset deployment path specification, which directs the structured content files to the target override location:
od-home/tmp/files/data_assets
The remaining files are deployed to the target file location specified within the target element.
120
Chapter 6
Advanced Features
This chapter describes some of the advanced features that OpenDeploy provides. The following sections detail how to deploy data as database objects, set up filters and substitutions, deploy replicants, enhance deployment data, and use other miscellaneous features.
Deploying Data as Database Objects

This section details how to deploy data as database triggers and database stored procedures. Deploying Data as Database Triggers The database element supports the trigger child element, which allows you to deploy key-value pairs that are treated as database triggers. The trigger child element resides in the first nesting level within the database element, and lets you write a database trigger using standard SQL syntax as supported by the current database. OpenDeploy registers the trigger with the database by deploying it as an extended attribute (EA) or any other XML field. The syntax to specify a database trigger is as follows:
<trigger> <fieldname prefix="trigger_prefix" /> </trigger>
where trigger_prefix is any case-insensitive string which can be either a TeamSite EA or a value in an XML or DCR file.OpenDeploy examines each tuple for key-value pairs in which the key name starts with any of the specified prefix values. For example, for values whose keyname starts with Trig to be treated like database triggers, the trigger section in the database configuration would look like:
<trigger> <fieldname prefix="Trig" /> </trigger>
121
Advanced Features
OpenDeploy examines each tuple for key-value pairs in which the key starts with the specified prefix value. If found, the value for that key is treated as a database trigger. OpenDeploy does not validate the value for a CREATE TRIGGER statements syntax and semantics. OpenDeploy looks for the trigger name and the table on which the trigger is being created. If a trigger exists with the same name on the same table, it is dropped and recreated. The following examples illustrate the configuration file for deploying a DCR field as a trigger, and the corresponding DCR file where the CREATE TRIGGER statement is specified:
<data-deploy-configuration> <data-deploy-elements filepath="od-home/etc/database.xml"/> <client> <deployment name="mydep2"> <exec-deployment use="basearea"/> </deployment> <deployment name="basearea"> <source> <teamsite-templating-records options="wide" area="/default/main/branch1/WORKAREA/wa"> <path name="templatedata/internet/book/data/book2" visit-directory="deep"/> </teamsite-templating-records> </source> <destinations>  <database use="oracledb" update-type="standalone"> <trigger> <fieldname prefix="Reviews/1/Review Reader E-Mail"/> </trigger> <dbschema> <group name="book" table="triggertest" root-group="yes"> <attrmap> <column name="IW_State" data-type="varchar(255)" value-from-field="state"/> <column name="MyPath" data-type="varchar(255)" value-from-field="path"/> <column name="Title" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Cover_Picture" data-type="VARCHAR(255)" value-from-field="Cover Picture" allows-null="yes" is-url="no"/> <column name="Author" data-type="VARCHAR(40)" value-from-field="Author" allows-null="no" is-url="no"/> ... </attrmap> <keys> <primary-key> <key-column name="Title"/> <key-column name="ISBN"/> </primary-key> </keys>
122
Deploying Data as Database Objects
</group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
DCR File:
<!DOCTYPE record SYSTEM "dcr4.5.dtd"> <record name="book2" type="content"><item name="Title"><value>patriot games</value></item><item name="Cover Picture"><value>cvr.gif</value></ item><item name="Author"><value>Tom Clancy</value></item><item name="Publication Date"><value>1999-01-01</value></item><item name="ISBN"><value>zcxcv1234</value></item><item name="Cover"><value>Paperback</value></item><item name="Price"><value>44.99</value></item><item name="Plot Summary"><value>summary1</value></item><item name="Reviews"><value><item name="Review Reader"><value>John</value></item><item name="Review Reader E-Mail"><value>jj@aol.com</value></item><item name="Reader Comments"><value>comments</value></item></value><value><item name="Review Reader"><value>james</value></item><item name="Review Reader EMail"><value>create trigger test_trigger on triggertest after insert as insert into mytrig values (999) </value></item><item name="Reader Comments"><value>comments2</value></item></value></item></record>
Deploying Data as Database Stored Procedures The database child element also supports the stored-procedure child element, which allows you to deploy key-value pairs that are treated as a stored procedure. The stored-procedure child element resides in the first nesting level within the database element, and lets you write a stored procedure using standard SQL syntax as supported by the current database. You can store the procedure in the database by deploying it as an extended attribute or any other XML field with OpenDeploy. Syntax is as follows:
<stored-procedure> <fieldname prefix="any_prefix_1"/> <fieldname prefix="any_prefix_2"/> <fieldname prefix="any_prefix_n"/> </stored-procedure>
The value of any_prefix can be any case-insensitive character string. OpenDeploy examines each tuple for key-value pairs in which the key name starts with any of the specified prefix values. For each match, the value for that key is treated like a database stored procedure; that is, OpenDeploy does not validate the syntax of the value of the keyvalue pair. Instead, OpenDeploy passes the value to the database, the key-value pair is not inserted into the table, and errors (if any) are returned to the user. If creation of a stored procedure fails and if the tuple contains non-stored procedure key-value pairs, the entire deployment is aborted.
123
Advanced Features
Filters and Substitutions

This section details the setting up of both filters and substitutions. Note that you cannot use parameter substitutions in the match attribute for any filter or substitution you create. Setting Up Filters The types of filters that OpenDeploy allows are: data filters, category and DCR type filters, and event filters to be used by DAS.
Data Filters
Data filters let you explicitly state which tuples will be deployed. To set up a data filter a filter section, such as the following example, must be added to the configuration file:
<filter name="MyFilter">  <keep>    <or> <field name="path"match="dir2/subdir/index.html"/> <field name="path"match="dir1/*.html"/> <and>  <field name="key"match="guard"/> <field name="value"match="IGNORE"/> </and> </or> </keep> <discard>    <or> <field name="path"match="dir1/ignoreme.html"/> <field name="key"match="unneededKey"/> <field name="state"match="DELETED"/> </or> </discard> </filter>
As shown in this example, the keep section contains criteria for selecting which tuples will be deployed, and the discard section contains criteria for those which will not be deployed. Both sections use field tags. All field tags must contain at least one name/match attribute pair. When you deploy from TeamSite, name must be either key, value, path, or state. When you deploy from a source other than TeamSite, name can be any be any field name that is valid in the source area. The match attribute names a targeted value for name.
124
A filter defined and located before the deployment section of the configuration file will be global. Global filters do not become active until they are called by the filter elements use attribute between the source and destinations sections of the configuration file. For a sample configuration file that displays the order of these sections, see Appendix A, Sample Configuration File on page 163. Note that filters can also be defined in an include file and then be called by the use attribute. If a configuration file does not contain a filter section, all tuples are deployed (limited only by the type of update being performed). A configuration file can contain any number of global filter sections.
DCR Type and Category Filters
In addition to global data filtering, you can perform filtering specific to DCR types and data categories to prevent DAS or command line operations (iwsyncdb options) from being performed on the selected categories or types. DCR type and category filtering can be configured for use either with or without the Event Subsystem. This section discusses filtering with the Event Subsystem. For use without the Event Subsystem, see Configuring DAS Manually on page 88. The following is an example filter specified in daemon.cfg:
<filter name="DCRFilter"> <ignoredcr> <type category-name="internet" name="yacht"/> <type category-name="internet" name="book"/> <category name="intranet"/> <category name="teamsite"/> </ignoredcr> </filter>
The filter elements name attribute value is fixed as DCRFilter and should not be changed. A single instance of the ignoredcr element contains all the elements representing filters. Each DCR filter is specified by an instance of the type element. Each category filter is specified by an instance of the category element. You can have any number of instances of type and category elements in any combination.
DCR Filters
The type element and its category-name and name attributes are combined to specify a single DCR filter. You can specify any number of instances of the type element within the single instance of the ignoredcr element. For example, the following type element entry results in the filtering of the DCR type internet/yacht:
<type category-name="internet" name="yacht"/>
Category Filters
You can filter an entire category by adding an instance of the category element. Specify the category as a value for the name attribute. For example, the following category element entry results in the filtering of the category intranet:
<category name="intranet"/>
125
Advanced Features
As with DCR types, you can exclude multiple categories by adding an additional category element for each excluded category.
Using Regular Expressions for Filtering and Substitution

You can incorporate regular expressions in data filters and substitutions using the field elements name-pattern attribute. The name-pattern attribute value is a perl5 regular expression that can be matched against a group of tuples for filtering, or to replace character strings or entire fields for substitutions. Use this feature as an alternative to listing a separate name attribute for each item to want matched. The following example shows how the name-pattern attribute regular expression is used for filtering.
<filter name="regexfilter"> <discard> <or> <field name-pattern="Reviews/.*/Review Reader" match="b1r1"/> </or> </discard> </filter>
In this example, those tuples included in the regular expression Reviews/.*/Review Reader are matched to the value b1r1 and discarded. The following example shows how the name-pattern attribute regular expression is used for substitution.
<substitution name="GlobalSubstitution"> <field name-pattern="Reviews/.*/Review Reader" match="b1r1" replace="Reviwer0"/> </substitution>
Here, like with the filtering example, the name-pattern attribute regular expression retrieves a group of strings or fields. Those that match the value b1r1 are replaced by the value Reviwer0.
126
Event Filters for DAS
You can set up event filters in od-home/etc/daemon.cfg so that DAS receives only the TeamSite events that you want it to receive. OpenDeploy translates the filtering criteria you specify into a SQL statement which it uses to subscribe to the Event Subsystem for TeamSite events. If no filters are specified, DAS automatically implements a timestamp filter based on the time that DAS started. That is, if no filters have been established and DAS is started, DAS receives all events published since it was started and ignores all previous events.
Sample Filter Section in daemon.cfg

The following is a sample event filter:
<filter name="EventsFilter"> <keep> <and>  <field name="timestamp" format="mm-dd-yyyy hh:mm:ss" match="08-01-2001 10:30:00"/> <in> <field name="name" match=" ('Submit', 'CreateWorkarea', 'SyncCreate', 'DestroyWorkarea')"/> </in> <or> <like> <field name="user" match="_ob"/> </like> <or> <field name="role" match="master"/> </or> </and> </keep> <discard> <and> <like> <field name="area" match="%default%"/> </like> </and> </discard> </filter>
Note the keep and discard sections in the preceding sample filter. Those sections contain the filtering criteria. The keep section contains the rules for filtering events that must be processed by DAS. The discard section contains the rules for filtering events that need not be processed by DAS.
127
Advanced Features
Both sections can contain the following subsections that represent boolean and SQL operators: Events that satisfy all criteria listed in this section are kept (or discarded if used in the <discard> section). <or> Events that satisfy at least one of the criterion listed in this section are kept (or discarded if used in the <discard> section). <in> Used to create a list-based criterion. Events that match at least one of the listed items satisfies the criterion. For example, the sample filter shown above keeps any of the following events would satisfy the <in> criterion: Submit, CreateWorkarea, SyncCreate, or DestroyWorkarea. <notin> Used to create a list-based criterion for events that are to be excluded. Do not use <notin> in a <discard> section; use <in> there instead. <like> Used to create a wildcard-based criterion. You can use the following wildcard characters when specifying the value for the match attribute in <like> and <notlike> subsections: The % character is used to represent any sequence of characters The _ character is used to represent any single character.
<and>
For example, note the <like> subsections in the sample filter shown above: Only a three character user name where the last two characters are ob would satisfy the first <like> criterion, and a TeamSite area name of any length that includes the string default would satisfy the second <like> criterion. <notlike> Used to create a wildcard-based criterion for events that are to be excluded. Do not use <notin> in a <discard> section; use <like> there instead. Each section (or subsection) must contain at least one name and match attribute/value pair. The name attribute refers to the property name. The value of the match attribute specifies the characteristics of the property to use as a filtering criterion. OpenDeploy would translate this example filter into the following SQL statement:
( timestamp > 1004050050851 and name IN ('Submit', 'CreateWorkarea', 'SyncCreate', 'DestroyWorkarea') and user like '_ob' or role = 'master' and area NOT LIKE '%default%')
128
The following sample event filter is a more specific example of filtering on an area.
<filter name="EventsFilter"> <keep> <and> <like> <field name="area" match="%default/main/br%"/> </like> </and> <and> <like> <field name="area" match="%templatedata/internet/book%"/> </like> </and> </keep> </filter>
This filter will pass any events that occur in the br branch under /default/main and also occur in the internet/book category and type under the templatedata directory. Note that the area has been split into two 'and' clauses because the event splits the area into two sections as shown below:
/default/main/br1/WORKAREA/wa /templatedata/internet/book/data/book1
Both 'and' clauses are not required as filtering can be done on only one of the sections. It depends on the level of desired filtering. Also note the use of forward slashes (/). Since the area is a TeamSite area, forward slashes should be used even if TeamSite is installed on Windows.
Filtering Events by Timestamp

By default DAS ignores all events published prior to its start time. If you want DAS to receive events that were published before it was started, you must establish a timestamp filter. In the match attribute of the field element, specify the time after which you want to start filtering events. For example, assume that DAS was started on 08/02/2001. Using the preceding sample filter, DAS would receive events published on and after 10:30:00 the previous day.
match
Another way to ignore events published before DAS is started is to specify the format and attributes as notused and now, respectively. See the commented timestamp field in the preceding sample filter for an example.
129
Advanced Features
Setting Up Substitutions Substitutions let you configure OpenDeploy to automatically replace character strings or entire fields in a table. A substitution can be set up to apply globally, to specific parts of a deployment (in-flow), or to a parameter string.
Global Substitutions
A substitution defined and located before the deployment section of the configuration file will be global. Global substitutions do not become active until they are called by the substitution elements use attribute between the source and destinations sections of the configuration file. For a sample configuration file that displays the order of these sections, see Appendix A, Sample Configuration File on page 163. Note that substitutions can also be defined in an include file and then be called by the use attribute. A configuration file can contain any number of global substitution sections. Global substitutions use field tags that must contain at least one name/replace attribute pair. As with filters, name is either key, value, path, or state. The replace attribute is the new string that will overwrite the existing string or field. Two additional attributes, match and global, are optional. Common usage examples are as follows:
To do this: Include this line in the Substitution section:
<field name="value" replace="Newvalue"/> <field name="path" match="blue" replace="red"/> <field name="path" match="blue" replace="red" global="yes"/> <field name="key" match="Original" replace="NotPresent"/>
Replace all Value field values with the string Newvalue In the Path field, replace first occurrence of blue with red In the Path field, replace all occurrences of blue with red In the State field, replace the first occurrence of Original with
NotPresent
The following is a sample substitution. It can be used by any deployment. It replaces the first occurrence of the string fun in the path field with bar, and completely replaces the value field with the string SpecialValue.
<substitution name="GlobalSubstitution"> <field name="path" match="fun" replace="bar"/> <field name="value" replace="SpecialValue"/> </substitution>
130
In-Flow Substitutions
In-flow substitutions let you define substitution rules that apply only to specific parts of a deployment. OpenDeploy supports in-flow substitutions within the deployment and destinations elements. For example, if the in-flow substitution shown below were nested one level inside of a deployment element named ea-to-db, it would apply only to the ea-to-db deployment. You can also nest in-flow substitutions one level inside destinations elements, in which case the substitution applies only to a specific destination. A configuration file can contain any number of in-flow substitution sections. The following sample substitution uses Perl 5 regular expression syntax for match values. In this sample, any path that contains the string WORKAREA/.../ will have the string replaced by STAGING/; any path that contains EDITION/abcd will be replaced with /This/Special/ Path, and any tuple whose key starts with 'BEFORE' will be changed to begin with AFTER.
<substitution> <field name="path" match="(.*)/WORKAREA/[^/]+/(.*)" replace="$1/STAGING/$2"/> <field name="path" match="EDITION/abcd" replace="/This/Special/Path" /> <field name="key" match="^BEFORE(.+)" replace="AFTER$1" /> </substitution>
In-flow substitutions have the same syntax as global substitutions. In addition, in-flow substitutions support a global attribute that lets you control whether the substitution applies to all occurrences or just the first occurrence of the matching pattern. If global is set to no, the substitution applies only to the first occurrence. If it is set to yes, the substitution applies to all occurrences. For example:
<substitution name="SubForThisTarget"> <field name="BField" match="from_a" replace="to_b" global="yes"/> </substitution>
131
Advanced Features
Parameter Substitutions
Any parameter string in a configuration file can be named using a parameter substitution. Syntax is as follows:
"varname=varvalue"
After a string is defined on the command line, all occurrences of $varname in the configuration file named on the command line are substituted with the string varvalue. Do not use the following terms for varname:
cfg deployment iwdd-op remote-host remote-port
Examples of parameter substitution within a configuration file are as follows:

prefix_string_$varname $varname^_suffix_string prefix_$varname^_suffix
(where ^ is a concatenator)
132
Deploying Replicants
This section details how to deploy replicant order numbers and comma separated lists of values as replicants. Replicant Order Columns The column element supports a replicant-order-column attribute so that replicant order numbers can be deployed. OpenDeploy inserts order values starting from 1. Order values are automatically adjusted when replicant fields are updated or deleted. Tables can contain multiple replicant order columns. At least one other column definition in the group element must contain an is-replicant attribute that is set to yes.
Note:
Do not specify the name of the replicant order column as order because that is a SQL reserved word.
To create a replicant order column, define a column element in a group element that is in a dbschema element of the DataDeploy configuration file as shown in this example:
<column name="rep_order" data-type="INTEGER" value-from-field="not-used" allows-null="yes" replicant-order-column="yes"/>
1. Specify the value of the replicant-order-column attribute as yes. 2. Specify the value of the value-from-field attribute as not-used, or as an invalid field name. 3. Specify other attributes (data-type, name) as usual.
Note:
When a replicant order column in a group is made a key column for the group, the group must contain a column that maps the path attribute value. Otherwise, realupdates are not supported.
Deploying Comma Separated Lists of Values as Replicants Multiple values entered into a field of a data capture form are often stored in the resulting DCR as a comma separated list of values rather than as separate item elements within a replicant item. The comma separated lists can be from a replicant or a non-replicant field and the values in such lists can be deployed as replicant values. That is, those values can be deployed into multiple rows in a table rather than into a single row. This is accomplished by using the list-field and list-to-replicant attributes of the column element in a database schema definition. When these two attributes are present, OpenDeploy processes the data before the actual deployment takes place and expands the list of values.
133
Advanced Features
Non-Replicant Values
Assume that a DCR created from the following DCT is to be deployed. Note that a comma separated list of reviewers can be entered for the Reviewers item.
<data-capture-requirements type="content" name="book">  <ruleset name="Book Information"> <description> This allows for the entry of details relating to a book. </description> <item name="Title"> <database data-type="VARCHAR(100)"/> <text required="t" maxlength="100"/> </item> <item name="Author"> <database data-type="VARCHAR(40)"/> <text required="t" maxlength="40"/> </item> <item name="ISBN"> <database data-type="VARCHAR(20)"/> <text required="t" maxlength="20"/> </item> <item name="Price"> <description>dollars and cents</description> <database data-type="REAL"/> <text required="t" maxlength="7" validation-regex="^[0-9]+\.[0-9]{2}$"/>  </item> <item name="Reviewers"> <description>Reviewer names separated by comma</description> <database data-type="VARCHAR(255)"/> <text required="t" maxlength="255"/> </item> </ruleset> </data-capture-requirements>
134
The following database schema definition is generated for this DCT when you run iwsyncdb -dbschemagen:
<dbschema> <group name="book" root-group="yes"> <attrmap> <column name="Title" data-type="VARCHAR(100)" value-fromfield=" Title" allows-null="no"/> <column name="Author" data-type="VARCHAR(40)" value-fromfield=" Author" allows-null="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-fromfield=" ISBN" allows-null="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no"/> <column name="Reviewers" data-type="VARCHAR(255)" valuefromfield="Reviewers" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> </dbschema>
DCRs created and deployed by using the preceding DCT and associated database schema would create a single table in the database as follows:
Title Author ISBN Price Reviewers
Interwoven
Author1
12345
100.00
R1,R2,R3,R4
135
Advanced Features
To deploy the same data such that the comma separated list of reviewers is stored in a separate table as replicant values, modify the database schema as follows:
<dbschema> <group name="book" root-group="yes"> <attrmap> <column name="Title" data-type="VARCHAR(100)" value-fromfield=" Title" allows-null="no"/> <column name="Author" data-type="VARCHAR(40)" value-fromfield=" Author" allows-null="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-fromfield=" ISBN" allows-null="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> <group name="reviewers" root-group="no"> <attrmap> <column name="Title" data-type="VARCHAR(100)" value-fromfield="Title" allows-null="no"/> <column name="Reviewers" data-type="VARCHAR(255)" list-to-replicant="yes" list-field="Reviewers" value-from-field="Reviewers/[0-4]/Reviewer" is-replicant="yes" allows-null="yes"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> <key-column name="Reviewers"/> </primary-key> <foreign-key parent-group="book"> <column-pair parent-column="Title" child-column="Title"/> </foreign-key> </keys> </group> </dbschema>
136
In the preceding modified database schema, an additional group element represents the additional table that contains the list of reviewers. Note that the Reviewers column definition in that group contains list-field and list-to-replicant attributes. The list-field attribute contains the comma separated list of values, and the list-to-replicant indicates to OpenDeploy that it must transform that list into multiple values before deployment. A deployment based on the preceding modified database schema would look like this:
Title Author ISBN Price
Interwoven
Title
Author1
Reviewers
12345
100.00
Interwoven Interwoven Interwoven Interwoven

Replicant Values
R1 R2 R3 R4
To deploy a comma separated list of replicants as another set of replicants (each source replicant is deployed to multiple rows in a table), use the DCT and database schema with table mapping as shown in the following example. In this example, the replicant field Select_expertise is used. It is a multi-select item in the DCT within the replicant item Reviews, where each book reviewer instance can have multiple expertise values.
137
Advanced Features
<data-capture-requirements type="content" name="book">  <ruleset name="Book Information"> <description> This allows for the entry of details relating to a book. </description> <item name="Title"> <database data-type="VARCHAR(100)"/> <text required="t" maxlength="100"/> </item> <item name="Author"> <database data-type="VARCHAR(40)"/> <text required="t" maxlength="40"/> </item> <item name="Publication Date"> <description>date format is YYYY-MM-DD</description> <database data-type="DATE" data-format="yyyy-MM-dd"/> <text required="t" maxlength="10" validation-regex="^[0-9][09][0-9][0-9]-[0-1][0-9]-[0-3][0-9]$" /> </item> <item name="ISBN"> <database data-type="VARCHAR(20)"/> <text required="t" maxlength="20"/> </item> <item name="Cover"> <database data-type="CHAR(9)"/> <radio required="t"> <option selected="t" value="Paperback" label="Paperback"/> <option value="Hardback" label="Hardback"/> </radio> </item> <item name="Price"> <description>dollars and cents</description> <database data-type="REAL"/> <text required="t" maxlength="7" validation-regex="^[0-9]+\.[0-9]{2}$"/> </item> <item name="Plot Summary"> <database deploy-column="f"/> <textarea/> </item> <item name="Reviews"> <database deploy-column="f"/> <replicant min="0" max="20"> <item name="Review Reader"> <text/> </item> <item name="Select_expertise"> <select required="f" size="4" multiple="t"> <option label="C++ Programmer" value="cplusplus"/> <option label="Java Programmer" value="java"/> <option label="Assembly Programmer" value="assembly"/> <option label="Cobol Programmer" value="cobol"/> </select> </item> <item name="Review Reader E-Mail"> <text/>
138
</item> <item name="Reader Comments"> <textarea/> </item> </replicant> </item> </ruleset> </data-capture-requirements>
The following database schema definition is generated for this DCT:

<group name="Reviews" table="expertise_table" root-group="no"> <attrmap> <column name="Title_in_review" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Reviewers" data-type="VARCHAR(255)" value-from-field="Reviews/[0-4]/Review Reader" allows-null="no" is-url="no" is-replicant="yes"/> <column name="Reviewer_Expertise" data-type="VARCHAR(255)" list-to-replicant="yes" value-from-field="Reviews/[0-4]/Selectlist/[0-5]/selectval" list-field="Reviews/[0-4]/Select_expertise" is-replicant="yes" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="Title_in_review"/> <key-column name="Reviewers" /> </primary-key> <foreign-key parent-group="book"> <column-pair parent-column="Title" child-column="Title_in_review"> </column-pair> </foreign-key> </keys> </group>
In the preceding database schema column, Reviewer_Expertise represents the comma separated replicant item Select_expertise, which needs to be specified in the list-field attribute: list-field="Reviews/[0-4]/Select_expertise" The values from this list will be mapped to the virtual field specified in the value-fromfield attribute, which is: value-from-field="Reviews/[0-4]/Selectlist/[0-5]/ selectval". In addition, the attribute list-to-replicant needs to be set to "yes" to indicate that a replicant comma separated list has to be mapped to another replicant.
139
Advanced Features
Each instance of the comma separated replicant Select_expertise maps to multiple rows in the database table. The database table for the preceding schema would be as follows:
Title_in_review Reviewer Reviewer_Expertise
Java Message Service Java Message Service Java Message Service Java Message Service
Reviewer 1 Reviewer 1 Reviewer 2 Reviewer 2
Java Assembly C++ Java
Additionally, the following rules for mapping must be followed: 1. The virtual field specified for a column that maps list fields should have a similar node structure if the table contains columns mapped to replicants. For example:
<column name="Title_in_review" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Reviewers" data-type="VARCHAR(255)" value-from-field="Reviews/[0-4]/Review Reader" allows-null="no" is-url="no" is-replicant="yes"/> <column name="Reviewer_Expertise" data-type="VARCHAR(255)" list-to-replicant="yes" value-from-field="Reviews/[0-4]/Selectlist/[0-5]/selectval" list-field="Reviews/[0-4]/Select_expertise" is-replicant="yes" allows-null="no" is-url="no"/>
The Reviewer_Expertise column maps the replicant Reviews/[0-4]/Select_expertise, which is a comma separated list. The column Reviewers maps a regular replicant item. The value-from-field attribute for the Reviewer_Expertise column should have the same root node structure and thus it starts with Reviewers/[0-4], which is the same as the mapping for Reviewers. Essentially, the normal replicant mappings and virtual field mappings should appear to OpenDeploy as if they are part of the same branch in the XML tree structure. If this naming convention is not followed, OpenDeploy will fail to traverse the tree and will produce no rows. 2. The replicant level of the mapped value-from-field should be one level greater than the field it is being mapped from, which is specified in the list-field attribute. For example, in the preceding database schema definition, value-from-field is one level higher than list-field:
list-field="Reviews/[0-4]/Select_expertise value-from-field="Reviews/[0-4]/Selectlist/[0-5]/selectval
140
Enhancing Deployment Data
Deploying Multiple Replicants from Multiple Nesting Levels OpenDeploy can deploy multiple replicants from multiple nesting levels which are mapped to the same table, without custom code having to be written. However, the following rules need to be followed: 1. When multiple replicants from any level are mapped to the same table, they must have the same maximum occurrence count.For example:
"Treatment List/[0-5]/Treatment", "Prognosis List/[0-5]/Prognosis"
where Treatment and Prognosis each have a maximum occurrence count of 0-5. 2. When multiple replicants from a level that is not the innermost level are mapped to the same table, multiple child replicants cannot be mapped to the same table unless its parent replicants are also mapped.

This section details how to enhance deployment data with the external tuple preprocessor and external data source features and also how to deploy content pointed to from a URL. External Tuple Preprocessor This section is intended for advanced users. If you intend to implement this feature, you must install the appropriate Java Development Kit (JDK) and have good working knowledge of the following: Java programming Java Development Kit (JDK) Java Database Connectivity (JDBC) Refer to JDK on page 30in the OpenDeploy Release Notes for the supported versions of the JDK. OpenDeploy supports the dynamic modification of data before it is deployed. The data retrieved by OpenDeploy from the source can be modified or augmented through a Javabased tuple preprocessing callout before it is deployed to a destination. This definition can also be found in the IWExternalTupleProcessor.java file residing in the following location:
od-home/examples/conf-dd/tuple-pre-processor
141
Advanced Features
The Java interface definition for this callout is displayed here:

import java.util.Hashtable; /* IWExternalTupleProcessor
Java interface definition that user implements to augument/supplement/ instrument a data tuple object, before it gets deployed by DataDeploy. User must implement PreProcessTuple method. */
public interface IWExternalTupleProcessor { /* Property name to obtain the name of the deployment for which the tuple preprocessor method is being called by DataDeploy. This property exists in the cmdLineParams Properties object passed to the PreProcessTuple() method by DataDeploy, when the interface-version is set to 2.0 in the <external-tuple-processor> tag. */ public static final String kCurrentDeploymentName = "IWCurrentDeploymentName"; /* PreProcessTuple The only method in the interface. DataDeploy supplies the data tuple in the form of a Hashtable object (keys being the field names). User can modify the tuple (adding, modifying deleting key-value pairs) and then return the modified tuple object back to DataDeploy. area: Points to the "area" attribute value if the tuple was produced by either <teamsite-templating-records> or <teamsite-extendedattributes> source. null otherwise. basearea: Points to the "basearea" attribute value if the tuple was produced by either <teamsite-templating-records> or <teamsiteextended-attributes> source when a differential extraction type is specified. null otherwise. The following method is called by DataDeploy when the interfaceversion attribute in the DD config file is either set to "1.0" or not set. */ public Hashtable PreProcessTuple(Hashtable tuple, String area, String basearea); /* The following method is called by DataDeploy when the interfaceversion attribute in the DD config file is set to "2.0".
142
The argument cmdLineParams contains: 1) the command line parameters specified while invoking standalone deployments, or 2) arguments generated by the iwsyncdb CLT / Event Server subscriber (in DAS mode) All command line parameters are stored as key-value pairs in the Properties object. For example, given the following invocation line, iwodcmd start <your_dd_dep> iwdd=<internal_subdep> mytable=<your_tab> to get the "mytable" value specified in the command line while invoking a standalone deployment, call cmdLineParams.getProperty("mytable"). */ public Hashtable PreProcessTuple(Hashtable tuple, String area, String basearea, Properties cmdLineParams); }
Sample Callout Implementation
OpenDeploy includes the IWExternalProcessorExample.java file, which is a sample implementation of IWExternalTupleProcessor. This file resides in the following location:
The IWExternalProcessorExample.java file is displayed here:

import com.interwoven.dd100.dd.IWExternalTupleProcessor; import java.sql.*; import java.util.*; public class TupleProcessorExample implements IWExternalTupleProcessor { // default constructor. nothing to do here for this // example implementation. Typically, user might want to // initialize resources that would be required to retrieve // related information. For example, establishing database // connection etc. public TupleProcessorExample() { } // implement the method defined in the IWExternalTupleProcessor // interface. This method is called when interface-version attribute // for the external-tuple-processor element in the DD config file is // either set to "1.0" or not set. public Hashtable PreProcessTuple(Hashtable input, String area, String basearea) { return ProcessTuple(input); } // implement the method defined in the IWExternalTupleProcessor // interface. This method is called when interface-version attribute
143
Advanced Features
// // // //
for the external-tuple-processor element in the DD config file is set to "2.0". This method provides visibility to the command line arguments specified by the user while invoking standalone deployments via the CLT.
public Hashtable PreProcessTuple(Hashtable input, String area, String basearea, Properties cmdLineParams) { if (cmdLineParams != null){ String deploymentName = cmdLineParams.getProperty( IWExternalTupleProcessor.kCurrentDeploymentName); System.out.println("PreProcessTuple() method called for " + "Deployment [" + deploymentName + "]."); } return ProcessTuple(input); }
private Hashtable ProcessTuple(Hashtable input) { // the input tuple contains path to the file, it's state value // and other user set extended attributes, in this example it would // be the book_id value // get the book_id value String book_id = (String) input.get("book_id"); // once we get the book_id, go to the database and retrieve the // related information. I am not typing the full code here for // retrieving the related information. // let's just assume that the related information we retrieved // has author, ISBN, price single-valued attributes. we add them // to the tuple here input.put("author","venkat"); input.put("ISBN", "12345"); input.put("price", "123.33"); // also assume that the related information has repeating-value // attributes reviewers and reviewer-email. let's assume we have // five reviewers and their email addresses to be added to the tuple // see the associated dd config file how these fields are mapped // to database table columns for (int i = 0; i < 5; i++){ input.put("Reviews/"+i+"/Name","reviewer"+i); input.put("Reviews/"+i+"/EMail","reviewer_email"+i); } return input; } }
This sample demonstrates how a user-written Java class can supplement data that would be deployed using DataDeploy. It assumes that you created a document in the TeamSite file system and set metadata on the file. The only Extended Attribute set on the document is called book_id.
144 Database Deployment for OpenDeploy Administration Guide
Assuming that information related to the book_id value is present in another repository, you want to deploy that information using DataDeploy. This class assumes that the related information is present in another database/ table and retrieves such information from those tables and adds it to the data tuple. When DataDeploy invokes the PreProcessTuple method in this class, the Hashtable tuple object contains path, state and book_id values only. DataDeploy loads a Tuple preprocessor class only once during a deployment. This Java file should be compiled using JDK1.3 or later. CLASSPATH should include the following file:
od-home/lib/ddcombo.jar
After a successful compilation, you package your Java class files into a .jar file, and place it in the following directory:
od-home/(od-instance)/userlib
You must then restart the OpenDeploy server.

Specifying a Java Class Name for Tuple Preprocessing
OpenDeploy includes the sample DataDeploy configuration file tuple_processor.cfg.example which shows how to specify a Java class name for tuple preprocessing. This file resides in the following location:
This sample configuration file demonstrates how to configure a user-written Java class that would be invoked by DataDeploy before deploying a data tuple. The tuple_processor.cfg.example file is displayed here:
<data-deploy-configuration> <external-tuple-processor class-name="TupleProcessorExample"/> <client>   <deployment name="ea-to-db"> <source>  <teamsite-extended-attributes options="full,wide" area="/default/main/br1/WORKAREA/wa1"> <path name="test1.txt" /> </teamsite-extended-attributes> </source>
145
Advanced Features
<destinations> <database db="localhost:1521:oracledb" user="user" password="password" vendor="oracle" update-type="standalone"> <dbschema> <group name="book_master" root-group="yes" table="book_master"> <attrmap> <column name="path" data-type="varchar(255)" value-from-field="path" allows-null="no"/> <column name="author" data-type="varchar(255)" value-from-field="author" allows-null="no"/> <column name="ISBN" data-type="varchar(255)" value-from-field="ISBN" allows-null="no"/> <column name="book_id" data-type="varchar(255)" value-from-field="book_id" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="book_id"/> </primary-key> </keys> </group> <group name="book_detail" root-group="no" table="book_detail"> <attrmap> <column name="book_id" data-type="varchar(255)" value-from-field="book_id" allows-null="no"/> <column name="Reviewer_name" data-type="varchar(255)" value-from-field="Reviews/[0-4]/Name" allows-null="no" is-replicant="yes"/> <column name="Reviewer_Email" data-type="varchar(255)" value-from-field="Reviews/[0-4]/EMail" allows-null="no" is-replicant="yes"/> </attrmap> <keys> <primary-key> <key-column name="book_id"/> <key-column name="Reviewer_name"/> </primary-key> <foreign-key parent-group="book_master"> <column-pair parent-column="book_id" child-column="book_id"/> </foreign-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
146
Using the Tuple Preprocessor Callout
To use the tuple preprocessor callout, follow these steps: 1. Write a Java class that implements the IWExternalTupleProcessor Java interface. Implement the PreProcessTuple() methods as required by the interface definition. 2. Compile the Java class and unit test it. 3. Package your Java class files into a .jar file, and place it in the following directory:
4. Create the DataDeploy configuration file. 5. Specify the external-tuple-processor element and the value of the class-path attribute in that configuration file as shown in the preceding example. 6. If you want OpenDeploy to invoke the following version of the PreProcessTuple method:
public Hashtable PreProcessTuple(Hashtable input, String area, String basearea,Properties cmdLineParams) ()
set the interface-version attribute to 2.0 in external-tuple-processor as follows:

<external-tuple-processor class-path= "com.interwoven.datadeploy.myclassname" interface-version="2.0"/>
It is recommended that you use the interface-version 2.0. Irrespective of the value set for the interface-version attribute, you must implement both versions of the PreProcessTuple() method to successfully compile the Java class you implement. 7. If you have defined substitution or filter elements in a deployment as well as an external-tuple-processor tag, you can control when OpenDeploy should invoke the TuplePreprocessor class by setting the exec-sequence attribute as follows: If you want OpenDeploy to invoke the TuplePreProcessor class before substitutions and filters are executed, specify the exec-sequence attribute as:
<external-tuple-processor classpath="com.interwoven. datadeploy.myclassname" exec-sequence="before-stages"/>
If you want OpenDeploy to invoke the TuplePreProcessor class after substitutions and filters are executed, specify the exec-sequence attribute as:
<external-tuple-processor classpath="com.interwoven. datadeploy.myclassname"exec-sequence="after-stages"/>
By default, OpenDeploy invokes the TuplePreProcessor class before substitutions and filters are executed. 8. Restart the OpenDeploy server instance.
147
Advanced Features
External Data Source This section is intended for advanced users. If you intend to implement the External Data Source feature, you must install the appropriate Java Development Kit (JDK) and have good working knowledge of the following: Java programming Java Development Kit (JDK) Java Database Connectivity (JDBC) Refer to JDK on page 30in the OpenDeploy Release Notes for the supported versions of the JDK. Dynamic values that are computed at transaction time and values from an external data source may be included in database deployments. This lets you extend deployment capabilities by programmatically producing values for inclusion in the deployment. For instance, such values can be used to generate a sequence of numbers that are inserted into a primary key column. The External Data Source feature supports deployments with user-defined schemas only. The External Data Source feature cannot be used with deployments to databases that use wide table format. External Data Source can be used when the following are deployed in either standalone or DAS mode: Metadata DCRs Custom DCRs The External Data Source feature is implemented in the form of a programmatic interface. The interface definition is as follows. Additionally, the Java class for the IWExternalDataSource interface is installed in the following location:
od-home/examples/conf-dd/callout
package com.interwoven.dd100.dd; import java.sql.*; import java.util.*; public interface IWExternalDataSource { public static final int kOpCodeInsert = 1; public static final int kOpCodeUpdate = 2; public static final int kOpCodeDelete = 3; public static final int kOpCodeQuery = 4; public static final double kProtocolVersion10 = 1.0; public abstract double GetProtocolVersion(); /* Implementation of this method must return 1.0 or kProtocolVersion10. If this method returns any other value or null deployment will be terminated abnormally.
148
*/ public abstract String GetExternalValue(Connection conn, String tableName, String columnName, int opCode, Hashtable tuple, boolean isReplicant); /* The main interface method that will be invoked by DataDeploy to get the value for a column that has been marked to have data generated/returned from an external source Parameters: conn - database connection. This is not the same connection that DataDeploy uses to perform the deployment. tableName - name of the table that has the column to contain externally generated value columnName - name of the column for which value is to be generated by the external source opCode - indicates type of operation that will be performed by DD on the table 1 - insert 2 - update 3 - delete 4 - query (SELECT) tuple - hashtable that contains the values for other columns. column name is the lookup key. isReplicant - true if the column for which value requested is mapped to a replicant field - false otherwise This function should always return the intended value for the column as a String. DataDeploy would perform appropriate conversion of the String depending on the target column's datatype. Important: Implementation of this method should take care of re-entrancy. This method may be invoked by DataDeploy multiple times for the same opcode. For example, when DataDeploy inserts a row into the database, there is a preparation stage and there is a second stage that performs actual insert. This method should return the same value in both the cases. One way of achieving that is to look at the "path" attribute value in the tuple object, in conjunction with the opCode value. When this method is being called when DataDeploy needs to select the row, because the original value was supplied by this method, it needs to check the database to identify the value correctly and return it to DataDeploy. Note that any modifications to the key-value pairs in the tuple object aren't propagated or used by DataDeploy as it supplies only a copy of the tuple object rather than the object that it uses to perform the deployment. Similarly, the Connection object supplied to this method is not the same connection that DataDeploy uses to perform the deployment. For DAS deployments, the tableName value supplied to this method would be the 'mapped'value if the actual table name exceeded the length that the database supports. This method can query the IWOV_IDMAPS table to get the original name for the supplied mapped name. */ }
149
Advanced Features
OpenDeploy loads your Java class only once, even if that same class is being used to generate values for multiple columns in various tables. It is the responsibility of the callout implementation to determine, according to the parameters supplied to the GetExternalValue() method, which values are returned. After you have implemented the Java class as described earlier, you must perform the following tasks: 1. Write a Java class that implements the preceding interface (for example, both the abstract methods GetExternalValue() and GetProtocolVersion()). See the comments interspersed throughout the preceding definition for the syntax and semantics of these two methods. 2. Compile the Java class and unit test it. During this phase od-home/lib/ddcombo.jar must be included in the CLASSPATH of the compile line. 3. Package your Java class files into a .jar file, and place it in the following directory:
4. Add a column element that defines the column for the dynamic (or external) value to one of the following files: The DataDeploy configuration file that will be used for deployments. The dbschema.cfg file if you want to use External Data Source with deployments that use UDS. Using the following example External Data Source interface, such a column element would look like this:
<column name="column1" data-type="VARCHAR(100)" value-fromcallout="iwov:dd:java:com.interwoven.datadeploy.sample. IWDataDeploySample"/>
Note that iwov:dd:java is a prefix that must precede the class and package name, here represented by com.interwoven.datadeploy.sample.IWDataDeploySample. 5. Restart the OpenDeploy server instance.
150
Sample Implementation of the External Data Source Interface
The sample implementation of the External Data Source interface, IWDataDeploySample.java, is available in the following location:
od-home/examples/conf-dd/callout
This is a sample implementation to demonstrate how DataDeploy can interact with a userdefined Java class to supply a value for a column during database deployment. You should compile this Java file using JDK1.1 or later. Include the following path in the CLASSPATH:
od-home/lib/ddcombo.jar
If you are using an Integrated Development Environment, refer to manuals of that product on how to set the CLASSPATH. Once the implementation compiles successfully, you must create a Java Archive for this class file and include the name of that archive in the CLASSPATH before invoking DataDeploy. For a description of the interface, refer to the IWExternalDataSource.java file, which is co-located with the IWDataDeploySample.java file. You must have od-home/lib/ddcombo.jar file in the CLASSPATH or it must be specified in the -classpath argument to javac.
package com.interwoven.datadeploy.sample;
//import the Interface definition for the Java Callout import com.interwoven.dd100.dd.IWExternalDataSource; //import other stuff needed import java.sql.*; import java.util.*;
public class IWDataDeploySample implements com.interwoven.dd100.dd.IWExternalDataSource { // we will use a random generator to generate unique values // for each DCR //that gets deployed private static Random fRandom = null; // we will use a hashtable to store the values with // 'tableName' value as the key // and TableData object as the value private static Hashtable fValues = null; //Constructor public IWDataDeploySample() {
151
Advanced Features
//nothing to do at this time } /* GetProtocolVersion Implementation of the interface method to establish handshake with DataDeploy */ public double GetProtocolVersion() { /* currently only supported interface protocol version is 1.0 */ return com.interwoven.dd100.dd.IWExternalDataSource.kProtocolVersion10; } /* GetExternalValue Implementation of the interface method to supply values */ public String GetExternalValue(Connection conn, String tableName, String colName, int opCode, Hashtable tuple, boolean isReplicant) { String path = (String) tuple.get("path"); //check our internal cache for any previously supplied //valuefor the given combination of tablename, colname //and path value String retVal = CheckCache4ExistingValue(tableName,colName,path); if (retVal == null){ //not in the cache //check the table itself. In case of an update we //have to supply the existing value retVal = CheckTable4ExistingValue(conn,tableName,colName,path); if (retVal == null || retVal.length() == 0){//no vaue in the target table //generate a new value retVal = generateNewValue(); } //add the newly generated value to our cache AddToCache(tableName,colName,path,retVal); } return retVal; } /* generateNewValue Generate a new value. We use a Random generator in this example. Alternatively the value could be coming from another source. For example from a SEQUENCE in the case of Oracle database server. */ private String generateNewValue() { if (fRandom == null){ fRandom = new Random(); } Integer i = new Integer(fRandom.nextInt());
152
return i.toString(); } /* CheckCache4ExistingValue Check if we have already generated a value for the current combination of tablename, column name and path. */ private String CheckCache4ExistingValue(String tableName, String colName, String path) { String result = null; if (fValues == null){ fValues = new Hashtable(); } TableData tableData = (TableData) fValues.get(tableName); if (tableData == null){ tableData = new TableData(tableName); fValues.put(tableName,tableData); } result = tableData.getValue(colName,path); return result; } /* AddToCache Add the current combination to cache. */ private void AddToCache(String tableName, String colName, String path, String colValue) { if (fValues == null){ fValues = new Hashtable(); } TableData tableData = (TableData) fValues.get(tableName); if (tableData == null){ tableData = new TableData(tableName); fValues.put(tableName,tableData); } tableData.putValue(colName,colValue,path); } /* CheckTable4ExistingValue Check the target table for any existing value for the current combination */ private String CheckTable4ExistingValue(Connection conn, String tableName, String colName, String path) { String query = "SELECT " + colName + " FROM " + tableName + " WHERE PATH = ?"; String result = ""; try { PreparedStatement stmt =
153
Advanced Features
conn.prepareStatement(query); stmt.setString(1,path); ResultSet rs = stmt.executeQuery(); if (rs.next()){ result = rs.getString(1); } rs.close(); stmt.close(); } catch (SQLException ex){ System.out.println("Exception:" + ex.getMessage()); result = ""; } return result; }
//maintains individual column values that we supply, per //table and per path private class TableData { private String fTableName = null; //'path' level cache private Hashtable fValues = null; /* Constructor */ public TableData(String tableName) { fTableName = tableName; fValues = new Hashtable(); } /* getValue Get any existing value for the given combination */ public String getValue(String colName, String path) { String result = null; Hashtable forPath = (Hashtable) fValues.get(path); if (forPath != null){//no cache for this path, allocate a new one result = (String)forPath.get(colName); } return result; } /* putValue Store the combination */ public void putValue(String colName, String value, String path)
154
{ Hashtable forPath = (Hashtable) fValues.get(path); if (forPath == null){//no cache for this path, allocate a new one forPath = new Hashtable(); fValues.put(path,forPath); } forPath.put(colName,value); } } }
Deploying URL Content You can deploy content pointed to from a URL in the following scenarios: When DCRs and TeamSite metadata are deployed in standalone or DAS mode with user-defined schemas. When custom DCRs are deployed in standalone or DAS mode with user-defined schemas. When DCRs and TeamSite metadata are deployed in wide table format. The column element supports the use of these attributes to enable deployment of content that is pointed to by a URL:
is-urlvalid values
are yes and no. value-from-fieldvalid values are any DCR element or metadata. valuevalid values are URLs that contain a file: or http: prefix. url-content-encodingvalid value is encoding method, such as UTF-8. Additionally, Binary Large Objects (BLOBs) and Character Large Objects (CLOBs) are supported data types. The following examples and descriptions illustrate how to construct column elements for deploying content pointed to from a URL:
Example 1
<column name="picture" data-type="BLOB" is-url="yes" value-from-field="TeamSite/Metadata/Picture"/>
Picture for
During deployment, DataDeploy gets the metadata value for the key TeamSite/Metadata/ the file being deployed and treats that value as a URL. DataDeploy then reads the content pointed to by that URL and deploys the content to the picture column which is of data type BLOB.
155
Advanced Features
Example 2
<column name="picture" data-type="BLOB" is-url="yes" value="file:///C:/TEMP/MYPHOTO.GIF"/>
During deployment, DataDeploy reads the content of the file C:\TEMP\MYPHOTO.GIF and deploys it to the picture column which is of data type BLOB.
Example 3
<column name="page" data-type="CLOB" is-url="yes" value="http://www.interwoven.com/index.html"/>
During deployment, DataDeploy reads the content of file index.html from the HTTP server www.interwoven.com and deploys it to the page column which is of data type CLOB.
Example 4
<column name="picture" data-type="BLOB" is-url="yes" value-from-field="PressRelease/Picture"/>
During deployment, OpenDeploy gets the value for the item PressRelease/Picture from the DCR being deployed and treats that value as a URL. It then reads the content pointed to by that URL and deploys the content to the picture column which is of data type BLOB.
Example 5
<column name="mytextdata" data-type="VARCHAR(4000)" is-url="yes" value="file:///C:/TEMP/MYTEXT.TXT"/>
During deployment, OpenDeploy reads the content of the file C:\TEMP\MYTEXT.TXT and deploys that content to the mytextdata column whose data type is VARCHAR(4000). In this case, the content of the file is assumed to be less than or equal to 4000 bytes.
Example 6
To deploy the content from the URL www.interwoven.com/index.html using UTF-8 encoding, the column element and its attributes would be:
<column name="urlcontent" data-type="CLOB" value-from-field="http://www.interwoven.com/index.html" is-url="yes" url-content-encoding="UTF-8"/>
156
Miscellaneous Advanced Features

This section details various other advanced features that are supported by OpenDeploy. Deploying Custom Data Content Records You can deploy DCRs based on custom DTDs into user-defined database schemas. Custom DCRs cannot be deployed using the wide table format, however. The following attributes in the DataDeploy configuration file enable this feature: The custom attribute for the teamsite-templating-records element. To deploy custom DCRs, you must set the value of that attribute to "yes". The value-from-element and value-from-attribute attributes for the column element. These attributes allow you to specify whether a column maps to an element (node) or an attribute of the node. For example, assume that the following data from a custom DCR is to be deployed to a user-defined database schema:
<press-release> <head> <title>title1</title> <byline author="Chris" location="location1"/> </head> <body> <heading>heading1</heading> <paragraph>para1></paragraph> </body> </press-release>
To map an elements value to a column (for example, the value for title), the column element in the DataDeploy configuration file would look like this:
<column name="title" data-type="VARCHAR(100)" value-from-element="press-release/0/head/0/title/0"/>
To map the value of an elements named attribute to a column (for example, the value for the author attribute), the column element in the DataDeploy configuration file would look like this:
<column name="author" data-type="VARCHAR(100)" value-from-attribute="press-release/0/head/0/byline/0/author"/>
Note the /o/ succeeding each element name. Those are instance indicators that specify which instance of the nodes value or attribute is mapped. You must specify the maximum number of instances (replicants) for a given node element. Arbitrarily large values can be specified when the maximum number of replicants allowed is unknown.
157
Advanced Features
Using the same example custom DCR snippet as above, mapping values of replicant elements (in this case, heading and paragraph) would look like this:
<column name="heading" data-type="VARCHAR(100)" value-from-element="press-release/0/body/0/heading/[0-5]" is-replicant="yes"/>
To map the values of replicant element attributes:

<column name="paragraph" data-type="VARCHAR(100)" value-from-attribute="press-release/0/body/0/paragraph/[0-5]" is-replicant="yes"/>
The dbschema.cfg file created for the PressRelease custom DTD example shipped with TeamSite Templating would look like:
<dbschema> <group name="pr_master" table="pr_master" root-group="yes"> <attrmap> <column name="Path" data-type="varchar(255)" value-from-field="path"/> <column name="state" data-type="varchar(25)" value-from-field="state"/> <column name="title" data-type="varchar(100)" value-from-element="press-release/0/head/0/title/0"/> <column name="author" data-type="varchar(100)" value-from-attribute="press-release/0/head/0/byline/0/ author"/> <column name="location" data-type="varchar(15)" value-from-attribute="press-release/0/head/0/byline/0/ location"/> </attrmap> <keys> <primary-key> <key-column name="title"/> </primary-key> </keys> </group> <group name="pr_body" table="pr_body"> <attrmap> <column name="heading" data-type="varchar(40)" value-from-element="press-release/0/body/0/heading/[0-5]" is-replicant="yes"/> <column name="paragraph" data-type="varchar(100)" value-from-element="press-release/0/body/0/paragraph/[0-5]" is-replicant="yes"/> <column name="title" data-type="varchar(100)" value-from-element="press-release/0/head/0/title/0"/> </attrmap>
158
<keys> <primary-key> <key-column name="title"/> <key-column name="heading"/> <key-column name="paragraph"/> </primary-key> <foreign-key parent-group="pr_master" ri-constraint-rule=" ON DELETE CASCADE "> <column-pair parent-column="title" child-column="title"/> </foreign-key> </keys> </group> </dbschema>
Encoding Database Passwords DataDeploy configuration files store database passwords as clear text by default. However, the -encodepassword and -decodepassword options in iwsyncdb can be used, respectively, to encode and decode database passwords specified in the database section of configuration files such as database.xml. This option sets a new attribute in the database element indicating that the file contains an encoded password, for example:
<database name="database-entry" db="database-url" user="username" password="passwd" password-encoded="yes" vendor="vendorname"/>
To encode a password attribute, run iwsyncdb with the encodepassword option. For example:
iwsyncdb -encodepassword <path-to-database-xml-file>
To decode an encoded password attribute run iwsyncdb with the decodepassword option. For example:
iwsyncdb -decodepassword <path-to-database-xml-file>
159
Advanced Features
Real Updates By default, OpenDeploy performs updates by deleting existing rows and then inserting new rows into the database tables. Alternatively, instead of this delete followed by insert sequence, you can configure OpenDeploy to perform real updates. A real update is when OpenDeploy executes a series of UPDATE SQL statements. Real updates can only be performed if referential integrity is not being enforced (that is, the database elements enforce-ri attribute must not be set to "yes" in the configuration file). If referential integrity is being enforced, OpenDeploy will only perform default (deletes followed by inserts) updates, because relational databases do not allow the modification of values or fields that are mapped to a primary/foreign key column due to constraint violation errors. If the enforce-ri attribute is not set or set to "no", real updates are performed by setting the real-update attribute to "yes" in the database element. It is important to note that with real updates you still cannot use UPDATE values for columns that are designated as primary or foreign keys. Executing a Stored Procedure You can execute a database stored procedure by using the sql tag. A sample configuration file to execute a procedure called myproc, which takes two numeric arguments, is shown here:
<data-deploy-configuration> <data-deploy-elements filepath="/usr/od-home/etc/database.xml"/> <client> <deployment name="dep1"> <source> <teamsite-extended-attributes options="wide" area="/store2/main/branch1/WORKAREA/wa1"> <path name="file2.txt"/> </teamsite-extended-attributes> </source> <destinations> <database use="oracle" table="not-used"> <sql user-action="execute_my_procedure" type="exec-proc"> myproc(1,2) </sql> </database> </destinations> </deployment> </client> </data-deploy-configuration>
160
To execute a stored procedure called myproc2 that takes one numeric argument and a string argument, the sql tag definition would look like:
<sql user-action="execute_my_procedure" type="exec-proc"> myproc2(1,'argument2') </sql>
After you define the configuration file, you can execute the stored procedure by invoking DataDeploy as follows:
iwodcmd start depName -k iwdd=subDepName -k iwdd-op=do-sql -k user-op=option
where: specifies the name of the deployment being run. subDepName specifies the name of the deployment defined in the deployment configuration file. user-op=option specifies the user-action attribute value associated with the sql element in the DataDeploy configuration file. The following command executes the myproc stored procedure for the preceding example:
iwodcmd start ddDeployment -k iwdd=dep1 -k iwdd-op=do-sql -k user-op=execute_my_procedure depName
Executing Arbitrary Queries This section describes how to query tables through SQL commands that you execute manually after deployment. Methodology differs depending on table type.
Note:
You can also embed SQL commands in the DataDeploy configuration files sql element. These commands execute automatically during deployment and do not require you to manually query the database.
161
Advanced Features
Querying Delta Tables
To query a delta table, you can first create a view consisting of a complex query and then apply a simple query on the view. For example:
CREATE VIEW areaview ( key, value, path ) AS SELECT key, value, path FROM sa WHERE NOT EXISTS ( SELECT * FROM wa_x WHERE wa_x.key = sa.key AND wa_x.path = sa.path ) UNION SELECT key, value, path FROM wa_x WHERE wa_x.state != NotPresent; SELECT path FROM areaview WHERE key = News-Section AND value = Sports
The CREATE VIEW command in this example is the default DataDeploy schema that executes when table-view is set to yes in the DataDeploy configuration files database element.
Querying Base and Standalone Tables
You can use simple SQL statements specifying key-value pair criteria when querying a base or standalone table. For example:
SELECT path FROM staging WHERE key = News-Section AND value = Sports;
162
Appendix A
Sample Configuration File

The Sample Configuration File
This appendix provides a sample deployment configuration file that displays many of the major sections that a typical file might contain (deployment, destination, source, client, filter, substitution, and so on). This file is only an example, however, and it may not match the specific requirements of your configuration. When creating your configuration file, you should use the element and attribute definitions provided in the DTD in Appendix A.
 Include file 1 <data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <filter name="MyFilter">  <keep>    <or> <field name="path" match="dir2/subdir/index.html" /> <field name="path" match="dir1/*.html" /> <and>  <field name="key" match="guard" /> <field name="value" match="IGNORE" /> Filter section </and> </or> (global) 2 </keep> <discard>    <or> <field name="path" match="dir1/ignoreme.html" /> <field name="key" match="unneededKey" /> <field name="state" match="DELETED" /> </or> </discard> </filter> <substitution name="GlobalSubstitution">     <field name="path" match="fun" replace="bar" /> <field name="value" replace="SpecialValue" /> </substitution>
Substitution section (global)
163
<client>   Start of Deployment section 5 <deployment name="ea-to-db"> <source> Start of Source section 6   Start of  Client  4 section  <teamsite-extended-attributes options="differential, wide" area="/default/main/branchx/WORKAREA/$user" Source type7 base-area="/default/main/branchx/STAGING"> <path name="dir1/index.html" visit-directory="no" /> <path name="dir2/subdir" visit-directory="shallow" />     <path name="$path" visit-directory="deep" />   End of Source  <path filelist="/tmp/SomeFiles" /> section 6 </teamsite-extended-attributes> </source>
Location of source data 8 (area)
Call global filter 2
 <filter use="MyFilter" /> <substitution>         <field name="path" match="(.*)/WORKAREA/[^/]+/(.*)" replace="$1/STAGING/$2" /> <field name="path" match="EDITION/abcd" replace="/This/Special/Path" /> <field name="key" Call global match="^BEFORE(.+)" replace="AFTER$1" /> substitution 3 </substitution>  <substitution use="GlobalSubstitution" />
Substitution section (in-flow) 9
164
The Sample Configuration File

--> --> --> --> --> --> --> -->
Rows to update 12
--> --> --> --> --> -->
Update type and related data 13
--> --> --> --> --> --> --> -->
Columns to update 14
165
    <sql action="create">    SQL CREATE TABLE table1 ( section 15 Path VARCHAR(300) NOT NULL, KeyName VARCHAR(300) NOT NULL, Value VARCHAR(4000) , State VARCHAR(4000) , CONSTRAINT KVP PRIMARY KEY (Path,KeyName) ) </sql> </database> </destinations> </deployment> </client> <server>   <bind ip="204.247.118.99" port="1949" />  <allowed-hosts> <host addr="ddclient.interwoven.com" /> <host addr="204.247.118.33" /> </allowed-hosts>  <for-deployment name="ea-to-db"> <database db="host1:1357:db1" user="scott" password="tiger" /> </for-deployment> </server> </data-deploy-configuration>
Server section
16
166
The Sections of the Sample Configuration File

The preceding sample configuration file contains 16 separate sections, each of which is labeled and numbered. Here, by number, each of these sections is explained and their usage is described: 1. Include File You can use data-deploy-elements to name a file containing data to include by reference. The file named in data-deploy-elements can contain any number of database, filter, and substitution elements. It must use the same syntax for these elements that the main deployment configuration file uses. If mutually exclusive attributes are set in the include file and the main deployment configuration file, all are used in the deployment. If conflicting attributes are set in the two files, those set in the main deployment configuration file take precedence. 2. Filter Section (Global) Filters let you explicitly state which tuples will be deployed. The keep section contains criteria for selecting which tuples will be deployed, and the discard section contains criteria for those which will not be deployed. Both sections use field tags. All field tags must contain at least one name/match attribute pair. When you deploy from TeamSite, name must be either key, value, path, or state. When you deploy from a source other than TeamSite, name can be any be any field name that is valid in the source area. The match attribute names a targeted value for name. A filter defined in the nesting level shown here and located before the Deployment section will be global. Global filters do not become active until they are called by the filter elements use attribute between the Source and Destinations sections using the syntax shown later in the sample file. Note that filters can also be defined in an include file and then be called by the use attribute. If a configuration file does not contain a filter section, all tuples are deployed (limited only by the type of update being performed). A configuration file can contain any number of global filter sections. A configuration file can also contain in-flow filters within a destinations section (see 10. Destinations Section on page 169). For more information about global filtering, see Setting Up Filters on page 124.
167
3. Substitution Section (Global) Substitutions let you configure DataDeploy to automatically replace character strings or entire fields in a table. Substitutions use field tags that must contain at least one name/replace attribute pair. As with filters, name is either key, value, path, or state. The replace attribute is the new string that will overwrite the existing string or field. Two additional attributes, match and global, are optional. A substitution defined in the nesting level shown here and located before the Deployment section will be global. Global substitutions do not become active until they are called by the substitution elements use attribute between the Source and Destinations sections using the syntax shown later in the sample file. Note that substitutions can also be defined in an include file and then be called by the use attribute. A configuration file can contain any number of global substitution sections. For more information about global substitutions, see Global Substitutions on page 130. 4. Client Section The client section lets you specify a set of client-specific parameters and activities. 5. Deployment Section The deployment section is where you assign a name to each deployment, and specify deployment source, destination, and update type. You can have any number of deployment sections in a configuration file, and each must have a unique name. The name shown here, ea-to-db, is the name you would specify on the command line when you invoke DataDeploy. The deployment section is required in all configuration files. The exec-deployment subelement lets you execute one or more deployments that are defined elsewhere in the same configuration file. Syntax is as follows:
<exec-deployment use="basearea" />
where basearea refers to the name of a deployment as defined in the name attribute in a deployment element. 6. Source Section The source section resides one nesting level inside the deployment section. It is where you name the type of data to extract from TeamSite and the location(s) of that data. Each deployment section must have exactly one source section. 7. Source Type The first nesting level within the source element contains a subelement defining what type of data is to be extracted from TeamSite.
168
8. Location of Source Data The area attribute defines the TeamSite workarea, staging area, edition or path in the local file system from which DataDeploy will extract data. This attribute is required in all deployment sections. The value of area should be the vpath name of a TeamSite area or path in the local file system containing the changes you intend to deploy. 9. Substitution Section (In-Flow) In-flow substitutions let you define substitution rules that apply only to specific parts of a deployment. DataDeploy supports in-flow substitutions within the deployment and destinations elements. For example, the in-flow substitution shown in the sample configuration file is nested one level inside of the deployment element, and therefore applies only to the ea-to-db deployment. You can also nest in-flow substitutions one level inside destinations elements, in which case the substitution applies only to a specific destination. In-flow substitutions have the same syntax as global substitutions. In addition, in-flow substitutions support a global attribute that lets you control whether the substitution applies to all occurrences or just the first occurrence of the matching pattern. For more information about in-flow substitutions, see In-Flow Substitutions on page 131. 10. Destinations Section The destinations section resides one nesting level inside the deployment section. It is where you name the destination system(s), timeout value, database, and table, and is also where you define the update type. Each deployment section can have any number of destinations sections, allowing you to designate multiple destinations in a single configuration file. 11. Database Section The first subelement in the destinations section defines the type of destination for the data. This subelement can be either database or xml-formatted-data, depending on whether the destination is a database or an XML file. When deployment is to a database, the database tag and its name and db attributes are required in all deployment sections. A destinations section can have any number of database subelements or a combination of database and xml-formatted-data subelements. For more information on the attributes and child elements of the database element, refer to database on page 188 in the OpenDeploy Reference.
169
12. Rows to Update The select section is where you select database rows to update with data from the current tuple. It is also where you can specify a data type for the deployed data other than the default VARCHAR 255 (you can also set the data type in the Update section; see 13. Update Type and Related Data on page 171). You identify rows by stating one or more matching criteria for column values in that row. For example, you can select a row whose values in columns named color and size are respectively red and small. Column-matching criteria are set through the column tag. Each database section must have exactly one select section, and each select section must contain at least one column tag.
Note on SimpleDateFormat
Use the following symbols to specify the data-format attribute value in the column element if the data-type attribute is set to DATE or DATETIME:
Symbol Meaning Presentation Example
G y M d h H m s S E D F w W a k K z
era designator year month in year day in month hour in am/pm (1-12) hour in day (0-23) minute in hour second in minute millisecond day in week day in year day in week in month week in year week in month am/pm marker hour in day (1-24) hour in am/pm (0-11) time zone escape for text single quote
(Text) (Number) (Text & Number) (Number) (Number) (Number) (Number) (Number) (Number) (Text) (Number) (Number) (Number) (Number) (Text) (Number) (Number) (Text) (Delimiter) (Literal)
AD 1996 July & 07 10 12 0 30 55 978 Tuesday 189 2 (2nd Wednesday in July) 27 2 PM 24 0 Pacific Standard Time
170
Examples using the US locale:

Format Pattern "yyyy.MM.dd G 'at' hh:mm:ss z" "EEE, MMM d, ''yy" "h:mm a" "hh 'o''clock' a, zzzz" "K:mm a, z" "yyyyy.MMMMM.dd GGG hh:mm aaa" Result
1996.07.10 AD at 15:08:56 PDT Wed, July 10, '96 12:08 PM 12 o'clock PM, Pacific Daylight Time 0:00 PM, PST 1996.July.10 AD 12:08 PM
You can also obtain a description of the SimpleDateFormat Java class from the Sun Java API documentation Web site:
http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html
13. Update Type and Related Data The update section is where you select the type of update, reference table (if applicable), and the table column(s) to update. Update type can be delta, base, or standalone (the default). A delta update requires two attributes, base-table and state-field. The base-table attribute names the base table that will be modified after the delta table (named earlier in the database section) is updated. The state-field attribute names which tuple item will be interpreted as state information. Each database section must have exactly one update section. 14. Columns to Update In the update section, you must also select at least one column to update from the row(s) you specified earlier in the select section. You select columns by naming matching criteria in column tag attributes just as you did in the select section. 15. SQL Section The optional sql section lets you create SQL commands that override system defaults and execute automatically during deployment. The sql element supports three attributes: action, user-action, and type.
171
16. Server Section The server section lets you specify a set of server-specific parameters. The bind tag lets you specify where on the server machine the DataDeploy server will listen. Each server section must have exactly one bind section. In a bind section, the port attribute is always required, while the ip attribute is required only if the server machine has more than one available IP address. The optional allowed-hosts element lets you specify which hosts are allowed to connect to the DataDeploy server. If you include an allowed-hosts element, its host subelement must have an addr value in the form of an alphanumeric machine name or an IP address. The optional for-deployment element lets you define several client attributes just as you did in the database section.
172
Appendix B
Database Deployment Tutorials

This document contains tutorials that demonstrate basic use cases for the database deployment feature of OpenDeploy. A database deployment deploys data from some source to a destination. The source is typically XML-based structured content. The destination is usually a database but could also include XML files (in a specific OpenDeploy format). Refer to Use Case Matrix on page 19 for possible combinations. There are three categories of deployments:
T
Standalone database deployments T Database Auto-synchronization (DAS) T Target-side database deployments, including synchronized deployment of files and data. Target-side database deployments are beyond the scope of this tutorial, but are described in Target-Side Database Deployments on page 113. A standalone deployment is a deployment that happens only once, when you manually start the deployment. For example, to populate a set of database tables with some XML data, you would execute an OpenDeploy database deployment. The tables will get populated, and then the deployment is completed. It is a one time only deployment of data to the database. Standalone deployments require that the DataDeploy module be enabled on the OpenDeploy base server. DAS deployments involve TeamSite. In TeamSite you have a STAGING area and workareas. A DAS deployment will create database tables representing the contents of the STAGING area and workareas. The A or Auto in DAS means that when you change your workarea or STAGING area content, the corresponding database tables will automatically get updated. You do not have to manually start a new deployment for each workarea or STAGING change. Specifically, you start a DAS deployment one time, and then all subsequent changes such as modified DCR, will automatically get deployed to the database. This is explained in more detail in the DAS tutorial. In the first tutorial, we will do a standalone deployment of XML data to a database table. In the second, we will do a DAS deployment of TeamSite DCRs to a database.
173
Before we get started, you must perform the following tasks:

T
Install the OpenDeploy base server software. Refer to Chapter 2, Installation on page 31 in the OpenDeploy Installation Guide for more information. T For the standalone tutorial, enable the DataDeploy module. Refer to Enabling the DataDeploy Module on page 68 in the OpenDeploy Installation Guide for more information. T Obtain access to one of the databases supported by OpenDeploy. Refer to Supported Databases for Data Deployments on page 21 in the OpenDeploy Release Notes for more information. For these tutorials, we are using the Microsoft SQL server database. You should have administrator level access to SQL Server. Create a new database instance using the SQL Server console. Also get the user name, password, hostname, port, and name of the instance. T For the DAS tutorial, a compatible version of TeamSite is also required, along with FormsPublisher (formerly TeamSite Templating). Refer to Release Compatibility on page 30 in the OpenDeploy Release Notes for compatibility information. Refer to your TeamSite documentation for installation and usage information.
Standalone Deployment Tutorial

The following section describes configuring and performing standalone database deployments. OpenDeploy Base Server Setup This section assumes your OpenDeploy base server is not already set up for database deployments. If it is, you can skip to the next section. To activate database deployments, perform the following steps: 1. Open the following file:
od-home/etc/odbase.xml
using your favorite text editor, and uncomment out the databaseDeployment node. 2. Set the databaseDeployment elements daemon_port attribute value to 2345.
174
3. Open the following file:

od-home/etc/database.xml
This file contains the database parameters that OpenDeploy will use to connect to different databases. Search for microsoft-db. Edit this node with the parameters for your SQL Server database. If you are using a database other than SQL Server, make the respective changes for the equivalent element for that database. Typically you will only need to change the following attributes:
db user password
The db attributes format is:

db="hostname:port?database=mydb"
where mydb is the name of your database instance. For example:

<database name="microsoft-db" db ="localhost:1433?database=mydb" user="user1" password="mypassword" vendor="microsoft-inetuna" max-id-length="128"/>
This example uses the una2000.jar driver that is included with OpenDeploy. 4. Restart the OpenDeploy base server. Deployment Example: Custom XML to Database In this example, we will start with a DTD for employee records and create some XML records based on this DTD. Our goal is to deploy these records to a set of database tables. Then we will create a configuration file for the deployment. Once we have this configuration file, we will invoke OpenDeploy and specify this file through the command line interface.
Create XML Records
The tutorial uses the following DTD:

<!ELEMENT deptRecords (dept, employees)> <!ELEMENT dept (deptId, description)> <!ELEMENT deptId (#PCDATA)> <!ELEMENT description EMPTY> <!ATTLIST description name CDATA #REQUIRED> <!ELEMENT employees (employee)+> <!ELEMENT employee EMPTY> <!ATTLIST employee name CDATA #REQUIRED id CDATA #REQUIRED>
Navigate to the following location:

od-home/examples/conf-dd/tutorial
175
There are two directories:

T
contains the DTD shown here and a deployment configuration file. T /data contains XML files created for your convenience and follow the DTD shown here.
/conf
Create the dbchema File
The next step is to create a database schema. The schema describes the set of tables that OpenDeploy will create in the database for our deployment. In OpenDeploy, we will refer to a dbschema which is an XML file describing the database schema (table name, column names, column sizes, etc) that will store our data. See User-Defined Database Schemas on page 25 for the rules to create the dbschema. Navigate to the od-home/bin directory and run the following command to create a default schema:
iwsyncdb dbschemagen dtdfile od-home/examples/conf-dd/ tutorial/conf/employee.dtd
This will generate a file called dbschema.cfg in the same directory as the DTD. Open this file and you will see that the DTD was interpreted and is represented by two tables, deptRecords and employees. See Execute the Deployment on page 179 for examples of the table structure. Note that you can also map a DTD to an existing database schema by hand-editing a dbschema file or using the OpenDeploy browser-based user interface.
Create the Configuration File
The next step is to create the deployment configuration file. We will include the dbschema file into the configuration file. The database deployment configuration file is an XML file that specifies the source of the data to deploy and the destination for the data. You can read more detail in the OpenDeploy manual. Our deployment example utilizes a simple configuration file described here: The first section is as follows:
<data-deploy-configuration> <data-deploy-elements filepath="od-home/etc/database.xml"/> <client> <deployment name="deployment1"> <source> <xml-source area="od-home/examples/conf-dd/tutorial" area-type="os-filesystem" xml-type="custom"> <path name="data" visit-directory="deep"/> </xml-source> </source>
In this code sample, the filepath attribute under data-deploy-elements is set to the location of the database.xml file that we edited earlier. In the deployment element, the name attribute is the name of your deployment. Here it is named deployment1.
176
The source section contains information about the data that OpenDeploy will deploy. The xml-source element indicates that the source of our data is XML files. (An alternative to xml-source is the teamsite-templating-records element, which we will use in the DAS tutorial.) The area attribute is set to the location of the source data. The area-type attribute is set to os-filesystem to indicate that the XML data resides on the regular filesystem. (The other setting is ts-filesystem for the TeamSite file system.) The xml-type attribute is set to custom to indicate that we have used a custom DTD (as opposed to a specially formatted Interwoven DTD) to create our XML records. The path element gives more detail about where the XML records reside. The name attribute is the location relative to the area (specified earlier) where the records are located. In our case, the records actually reside in the /data directory. Alternatively, we could have set area to be od-home/examples/conf-dd/tutorial/data and set the path attribute to .. visit-directory is set to deep which indicates that OpenDeploy should recursively go through all the sub directories in this location to get the data records. Next we will add the destination information:
<destinations> <database use="microsoft-db" delete-tracker="yes" enforce-ri="no">
The database element contains the following attributes:

T
use specifies which database definition contained in the file database.xml should be used by OpenDeploy for the connection. T delete-tracker indicates whether OpenDeploy should create an internal system table called IWDELTRACKER. This table is used to track primary key values which is necessary when OpenDeploy retrieves, updates, or deletes rows.
The delete-tracker attribute value is no if you have defined a column named Path in your tables. When OpenDeploy sees a column named Path it will insert the path of the file as the value of the column. Since file paths are always unique, a path value can serve as a primary key for a table. So in this case, the IWDELTRACKER table is not necessary. The delete-tracker attribute is set to yes in this example, since our schema does not have a column named Path. T enforce-ri indicates whether referential integrity should be enforced. Referential integrity refers to the relationships between tables. Tables within a database can be associated with one another via keys. A key simply refers to one or more columns of a database table. A row of one table can be linked to a row of another table by a set of column values (comprising the key) that are common to both rows. For example, in our database schema, the table deptRecords has a primary key made up of the column deptId. The table employees is linked with the deptRecords by making its foreign key the same as the primary key of deptRecords. Notice that the foreign key of employees specifies its parent table as deptRecords and associates its column deptId with the deptId column of deptRecords.
177
Referential integrity ensures that these relationships are maintained such that if you delete a row of a parent table when there is a child table that refers to that same row, the corresponding child table rows will also be deleted. The dbschema element also falls under the database element. Recall that we created the dbschema earlier. So after you run the iwsyncdb dbschemagen command to generate the dbschema, you copy the contents of that dbschema into the deployment configuration file that we are creating here. Once this has been done, we no longer need the original dbschema file for standalone deployment, since the dbschema in included in the main configuration file.
<dbschema> <group name="deptRecords" root-group="yes"> <attrmap> <column name="deptId" data-type="VARCHAR(255)" value-from-element="deptRecords/0/dept/0/deptId/0" allows-null="no" is-url="no"/> <column name="name" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/dept/0/description/ 0/name" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="deptId"/> </primary-key> </keys> </group> <group name="employee" root-group="no"> <attrmap> <column name="name" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/employees/0/employee/ [0-5]/name" is-replicant="yes" allows-null="no" is-url="no"/> <column name="id" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/employees/0/employee/ [0-5]/id" is-replicant="yes" allows-null="no" is-url="no"/> <column name="deptId" data-type="VARCHAR(255)" value-from-element="deptRecords/0/dept/0/deptId/0" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="name"/> <key-column name="deptId"/> </primary-key> <foreign-key parent-group="deptRecords"> <column-pair parent-column="deptId" child-column="deptId"/> </foreign-key> </keys> </group> </dbschema>
178
Finally, we will match the open tags:

</database> </destinations> </deployment> </client> </data-deploy-configuration>
The full file resides in the following location:

od-home/examples/conf-dd/tutorial/conf/ddconfig.xml
Copy this file and place it in the following location:

od-home/conf/DDTutorial
This file must be located within the /conf directory and have the .xml extension. Be sure to make modifications to the file if any names or locations, such as the location of the XML data or database.xml file, are different than this sample file. We now have our database deployment configuration file. The SQL Server database is running, and our XML data is ready. We can now deploy the XML data to the SQL Server database using this configuration file.
Execute the Deployment
To execute the deployment, navigate to the od-home/bin directory and run the following command at the prompt:
iwodcmd start DDTutorial/ddconfig k iwdd=deployment1
where ddconfig is the name of our configuration file (do not specify the .xml extension). iwdd refers to the name of our deployment, which we are calling deployment1. You can also perform this same task using the OpenDeploy browser-based user interface by selecting the deployment and entering iwdd=deployment1 in the Parameters box contained in the Start Deployment window. You should see the deployment complete with no errors. If you see errors, check the logs residing in the following location:
od-home/log/DDTutorial
You will find multiple logs that have deployment1 in the name. The logs should help you resolve any errors. The most relevant log is called src.ddconfig.deployment1.yourhost.to.database.log. Common errors include invalid area and path attributes specified for the source data, and incorrect database connection parameters.
179
Now we will look at the database to see if the tables were created and contain the data from the XML files. 1. Connect to SQL Server through the SQL Server Enterprise Manager. 2. View the tables. The following information should be displayed:
table_name
deptrecords employee iwdeltracker iwov_idmaps 3. View the details on the deptrecords table. The following information should be displayed:
DeptId name
00101 00102
Engineering Marketing
4. View the details on the employee table. The following information should be displayed:
Name id depId
Simson Garfinkel Art Vandalay Mark Jones Jane Smith
345 506 209 245
00101 00101 00102 00102
180
DAS Tutorial
DAS Tutorial
In this section, we will deploy TeamSite data content records (DCRs) from a TeamSite area into a database. Unlike standalone deployments, the DataDeploy module is not needed to use DAS. It is included in the OpenDeploy base server. Before using DAS, TeamSite must be installed and running. As described in the introduction, DAS performs automated deployments. After the initial deployment (which creates the STAGING and workarea tables) has completed, OpenDeploy will be waiting for TeamSite events and will get triggered to execute a deployment based on these events. This behavior requires use of the TeamSite event server. Event Server Setup
Note:
If you are using TeamSite 6.5 or later, the event server is automatically set up. You can skip to the next section. If you are using a version of TeamSite earlier than 6.5, follow the instructions in this section for setting up the event subsystem.
The event server uses a database to persist events. Therefore, we will need to set up a database for use by the event server. Once again, we will use SQL Server. The event server setup requires a few steps. The OpenDeploy browser-based user interface has a function to do the event server setup. To set up the event server using the browser-based user interface, follow these steps: 1. Select DAS > Event Server Configuration to display the Event Server Configuration: Select Database window. 2. Select SQL Server from the Database Vendor list and click Next. The Set Up window for SQL Server appears. 3. Configure the database parameters contained in the Set Up window: Host the name of the database host. Listener Port the port number on which the database server is listening. Database Name the name of the database where the tables will be created. User Name the name of the user who has permissions to create tables in the specified database. Password the database password for the specified user. Path to JDBC Driver the default JDBC driver path specified, points to the JDBC driver shipped with DAS. This attribute can be changed to a user-specified driver. Click Next. This action will create new tables for the event server. If the tables already exist, you will be prompted to either keep them or drop them and recreate new tables. 4. Open a command prompt and navigate to the iw-home/bin directory, where iw-home is your TeamSite home directory.
181
5. Select DAS > Start/Stop Event Server Start to start the Interwoven Event Subsystem service. If you suspect any problems with the event server, check the logs residing in the following location:
iw-home/local/logs/eventsubd_*
6. Run the following commands in order from the command line:

iwreset iwreset -ui
This will restart the proxy servlet. You can also set up the event server manually from the command line instead of through the browser-based user interface. See Configuring the Event Subsystem Manually on page 95 for more information. TeamSite Setup The following sections describe setup tasks for TeamSite when using DAS.
Set Up a TeamSite Area
In our DAS deployment example, we will deploy some DCRs from TeamSite into a set of database tables. Before we start, we have to set up TeamSite. This setup procedure allows us to use the templating examples on any branch. To set up your TeamSite area, follow these steps: 1. Create a new workarea. Refer to your TeamSite documentation for instructions. 2. Copy the templating examples to this workarea. The templating examples reside in the following location:
iw-home/examples/Templating/templatedata
3. Copy the entire templatedata directory to just under your workarea. So your workarea will have a structure similar to that below:
/default/main/WORKAREA/your-workarea/templatedata
For this deployment, we will choose the templating type called internet/careers to work with. If you are using an existing workarea and already had the templating examples set up, delete any files named dbschema.cfg and careers_dd.cfg that you have under templatedata/internet/careers. If this is your first time using these templating examples, then you may have to configure TeamSite to recognize these examples as is described in the next step.
182
DAS Tutorial
4. Open the file templating.cfg, residing in the following location:

iw-home/local/config/templating.cfg
using your favorite text editor, and change all the branch nodes so that the vpath-regex attribute is set to .*, for example:
vpath-regex=".*"
This allows you to use the templating examples on all the TeamSite branches. This file might be named templating.cfg.example instead of templating.cfg. If so, then make a copy of it and rename the copied file templating.cfg.
Create DCRs
Accessing the TeamSite user interface, create two DCRs in your workarea. Select File > New Form Entry. Complete the templating form and save the file. Repeat this process to create a second DCR. The DCRs should be saved to the following location:
templatedata/internet/careers/data
You do not need to submit anything.

Create the dbschema
We are almost ready to start DAS. This can be done through the OpenDeploy browserbased user interface. However, for the purposes of this tutorial, in order to better understand the components of DAS, we will use the OpenDeploy command-line tools. Unlike the standalone example in the previous tutorial, we do not actually have to create the configuration file. DAS will create that for us. We do however have to generate the dbschema file. So as in the standalone case, run the following command to create the dbschema:
iwsyncdb dbschemagen dcfile TeamSite_mountpoint/main/WORKAREA/jdoe/ templatedata/internet/careers/datacapture.cfg
where TeamSite_mountpoint might be one of the following values:

T
Windows Y:\default T UNIX /iwmnt/default It is important that this file is created under templatedata/internet/careers. So after executing this command, check in your workarea to see if this file was created under the careers directory.
183
Set Up the Configuration File
To create the deployment configuration file, OpenDeploy will use one of the template files residing in the following location:
od-home/ddtemplate
There are several templates in this directory. For our example, to deploy DCRs to a set of tables that we have defined in our dbschema, we will use the ddcfg_uds.template. If this files name includes an additional extension, such as .new, remove it. Open the
ddcfg_uds.template file using your favorite text editor. Change all instances of
The value microsoft-db refers to the database node in database.xml that we created above. OpenDeploy uses the database connection data referred to by the database elements use attribute. The data-deploy-elements elements filepath attribute value is the full path to the database.xml file. For example:
<data-deploy-elements filepath="od-home/etc/database.xml">
oracle-db to microsoft-db.
Set Up DAS
We are now ready to start DAS. The first step is to initialize your workarea for DAS. Navigate to the od-home/bin directory and enter the following command at the prompt:
iwsyncdb initial /default/main/WORKAREA/your_workarea internet/careers
By specifying internet/careers, only changes for the careers type in your workarea will trigger DAS. This command causes the following tasks to occur:
T
OpenDeploy uses the ddcfg_uds.template and dbschema.cfg files to generate a configuration file called careers_dd.cfg under templatedata/internet/careers. T Your workarea is submitted. Therefore, your workarea will not have any changes and will be up to date with STAGING. T The STAGING and workarea tables are created, and the STAGING table is populated with the DCRs under careers/data. The last step is performed by OpenDeploy executing two deployments specified in the careers_dd.cfg file. If you open up the careers_dd.cfg file, you will see a configuration file much more complex than the one we created in the standalone tutorial.
184
DAS Tutorial
Notice that there are six different deployment sections. The first four are the ones we are primarily concerned with for DAS. The first two deployments called basearea and deltagen are run during the DAS initialization step we just completed:
T
Generates STAGING tables, deploys DCRs to the STAGING table. T deltagen Generates workarea tables, deploys DCRs to the workarea tables. Since the workarea was submitted by DAS earlier, the workarea should have the same content as STAGING, and hence the workarea table will be empty. Recall, that the workarea tables only show differences between STAGING and the workarea. Now lets look at the log to see what occurred. Open the iwdd_default_main.log file residing in the od-home/logs directory. You will see the results of the basearea and deltagen deployments. We can query the database to check if the contents were deployed:
CONSUMERS DEPTRECORDS DESTINATIONS EMPLOYEE IWDELTRACKER IWOV_IDMAPS DEFAULT_INTERNET_CAREERS_CAREERS_MAIN_STAGING DEFAULT_INTERNET_CAREERS_CAREERS_MAIN_WORKAREA_JDOE IWTRACKER JNDI_CONTEXT MESSAGE_HANDLES MESSAGE_ID MESSAGES PERSONNELRECORDS SEEDS SYSTEM_DATA
basearea
Now, we can see our STAGING data.

select * from DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING; Path Department Title Requisition_Num Description Location templatedata\internet\careers\data\career1 Engineering Senior Software Engineering 3454 UI Designer Sunnyvale
Likewise, we can check the workarea table:

select * from DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_WORKAREA_JDOE;
where JDOE is our workarea name for this test. Notice there is no data in this table. This is because DAS submitted the workarea before doing the basearea deployment. The workarea table only shows differences between STAGING. At this point, STAGING and the workarea are identical.
185
Trigger DAS Deployments
Once DAS is set up, OpenDeploy will react to any changes to the DCR data in STAGING and your workarea such as the following:
T
Creating new DCRs T Deleting DCRs T Modifying DCRs T Submitting DCRs to the STAGING area. TeamSite will generate events through the event server whenever you take one of these actions. OpenDeploy subscribes to these events which will trigger one of the following deployments listed in careers_dd.cfg:
T T
deltaupdate
updates workarea table with any DCR changes made in your
workarea.
submitlist
updates STAGING table when a DCR is submitted
For example, if you edit one of your DCRs but do not submit it, we would expect the workarea table to show the changed record. The following steps demonstrate this behavior: 1. Go to the TeamSite user interface and edit one of your DCRs, changing some data in the templating form. Select the DCR and then select Edit > Edit. 2. Save the DCR but do not submit it. The save will trigger a deltaupdate deployment. 3. Check the workarea table in the database. Now you will see the modified data in this table. 4. Submit the DCR. The submission will trigger the submitlist deployment. The STAGING table will contain the changes and the workarea table will be empty again. Notice that the state column which used to say Original in the STAGING table, now says Modified. 5. Create a new DCR in your workarea, but do not save it. This will trigger a deltaupdate deployment. Check the workarea table. It will have the record with a state of New. 6. Submit the DCR and see that the new record is now in the STAGING table and not in the workarea table. The STAGING and workarea tables are automatically synchronized with the TeamSite areas.
186
DAS Tutorial
7. Delete a DCR and observe the tables. At first, do not submit the change. You will see that the record is removed from the workarea table, but remains in the STAGING table. 8. Submit the deleted DCR. Now you will see that the record was removed from the STAGING table. Behavior On Other Databases If you are using this tutorial on a database other than Microsoft SQL, you will notice that there are no tables named careers as the dbschema suggests. Instead, we see some unconventional names like iwt_13a318ba73. Those names contained here are representative samples. You will probably see different names on your system. The iwt_* tables are actually the tables that contain our data. DAS has to create multiple tables for each table in our schema. Specifically, we need a separate table for STAGING and the workarea. OpenDeploy has a certain naming convention that it uses to create the table name. Instead of just careers, the STAGING careers table will be called the following:
DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING
This allows us to have a unique table name for each workarea and STAGING area. There may be many workareas that all have a careers table, so we can not simply have one careers table. We need unique tables for each area that we are working with. This naming convention of using the branch name, category, type, and area creates a problem however. Database table names are very limited in the maximum length. So we can not have a table name that is too large. Certainly, adding the branch info and templating type info to the table name will exceed the name limit. To overcome this, OpenDeploy creates a mapping table. It internally generates a unique short name for the table. OpenDeploy will create an entry in the iwov_idmaps table mapping the short name to the long name
select * from iwov_idmaps; Type Shortid Longid 1 IWT_FC3BD105F88 DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING 1 IWT_13A318BA73 DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_WORKAREA_JDOE
Here we see what short names correspond to our desired tables. So the STAGING data is in the table DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING.
187
Conclusion
There are more options and features that comprise the database deployment function. These features and options are described in more detail elsewhere in this manual, and in the other OpenDeploy documentation. For example, see Filters and Substitutions on page 124 for more information on that topic. This tutorial should make you comfortable enough to try other types of deployments, such as metadata deployments, and use the other features described in the documentation.
188
Appendix C
Database Deployment Internal Tables

This section describes the internal tables that are used by OpenDeploy when performing database deployments.
IWTRACKER
The IWTRACKER table maps the relationship among STAGING and workarea tables for DAS. The IWTRACKER table contains the following columns:
T
the name of the workarea or STAGING table. T BASE the name of the corresponding STAGING table. This only applies to workarea tables. For STAGING tables, this value will be __NO_BASE__. T UPDATETIME the time the particular row in the IWTRACKER table was updated. T BRANCH the TeamSite branch corresponding to the table.
NAME
IWDELTRACKER
The IWDELTRACKER table stores the primary key values for each file asset (a DCR or XMLbased record) deployed to enable deletions and updates when none of the other target tables contain a mapping to the path value of the file. The path value is the absolute path to the file. It uniquely identifies each file since each file has a unique location. When a target table has a column mapped to the path of the file, OpenDeploy uses that path value to delete or update a row. However, OpenDeploy does not require that tables contain a PATH column. Therefore, if there is no table with a PATH column, the IWDELTRACKER table is created automatically. The IWDELTRACKER table contains the following columns:
T
the area relative path to the file. T AREA the path to the area where the file is located. T KEYCOLNAME the name of the primary key column of the actual table receiving the deployment. T KEYCOLVALUE the value of the primary key.
PATH
189
Database Deployment Internal Tables
A particular file asset may have multiple entries in the IWDELTRACKER table. For example, one file may map to more than one table or a file may contain replicants. Therefore, the IWDELTRACKER table will contain multiple rows with the same PATH and VALUE columns but different values for the primary key name and value. When OpenDeploy processes a deletion or update on a file, it references the IWDELTRACKER table for the primary key values corresponding to that file. Then it can proceed with the delete or update.
IWOV_IDMAPS
The IWOV_IDMAPS table is a lookup table that maps long identifiers used for a database table to short ids. Database vendors have limits on the size of identifiers, most commonly the following:
T
Table name T Columns T Constraints T Views For example, when using DAS, OpenDeploy will create tables that have the VPATH of the workarea embedded in the name. This results in a table name that is quite long and may exceed the database vendors limit for table name size. The IWOV_IDMAPS table is used to store an internally generated short name for the identifier when the length of the identifier exceeds the limits set by the database vendor. The table contains the following columns:
T
the type of identifier: Y 1 table Y 2 column Y 3 view Y 4 constraint T SHORTID the unique short ID that OpenDeploy generates. T LONGIS the actual name of the identifier.
TYPE
OpenDeploy will use the SHORTID column when doing actual database operations.
IWTMP_LOB
The IWTMP_LOB table is by OpenDeploy to temporarily store data that has the datatype of CLOB (character large object) or BLOB (binary large object). You can delete rows from this table when no deployments are running. This table is created only when deploying to an Oracle database.
190
Glossary
This glossary lists terms and their definitions found in this manual. Base Table A table created in the database that represents the data in a TeamSite staging area or edition and contains full (as opposed to delta) data. Base tables act as references for submitted workarea tuple data. Whenever a base table is generated, an entry for that table is recorded in a tracker table residing in the database. Database AutoDAS automatically updates the destination database when changes Synchronization are made to content in TeamSite areas. DAS runs DataDeploy as a (DAS) daemon, and by using various TeamSite events as triggers it initiates deployment directly from the content source to the destination database. The Event Subsystem lets you filter the events that DAS receives. Database Schema The organization or structure for a relational database, including the layout of tables and columns. A schema includes the constraints placed on tables through the use of primary and foreign keys. Userdefined database schemas allow you to map a given record to rows in multiple tables that you can define with foreign and primary keys. The resultant tables have normalized data schemas. Data Capture An XML file, datacapture.cfg, that defines the form used to Template (DCT) capture data content from content contributors using TeamSite Templating. A data capture template is associated with a data category and type. The category and type define the type of data required by the data capture template. The data that a content contributor enters in a data capture template is saved on the TeamSite file system as an XML file in the form of a data content record (DCR). Data Content Record An XML file containing formatting information interspersed with (DCR) data captured by TeamSite Templating from a contributor or through other means. Data content records can be deployed to a database. Delete Tracker Table A table created to track primary key values for the root group in order to retrieve, update, or delete rows that represent a single data content record (DCR). DataDeploy wrapper An OpenDeploy deployment configuration that simply contains a file path to a DataDeploy configuration file, plus logging rules. When the deployment is run, the DataDeploy configuration file is invoked.
191
Delta Table
Tables used to capture differences between TeamSite workareas and staging areas. These 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.
The transferring of content into database tables or other XML files. Each deployment holds attributes that specify what is deployed and to where it is being deployed. Deployment Trigger A TeamSite event that triggers actions by the DAS feature. Destination Refers to where the source content will be deployed. A destination can be an XML file or a database. Edition A frozen, read-only snapshot of content as it exists in TeamSite. An edition contains a copy of all files in a TeamSite staging area at the time it was published. Editions serve as rollback points for projects in development, and they provide permanent archives. Event Subsystem The Event Subsystem allows you to selectively specify the TeamSite events that will trigger DAS deployments. DAS can also be configured to publish its deployment results to the Event Subsystem, which in turn allows the creation of DAS reports. The Event Subsystem is packaged with TeamSite. Filtering A process of refining deployable files based on additional criteria, such as file permission rules or file transfer rules. OpenDeploy allows the use of filters that let you explicitly state which tuples will be deployed. Key-Value Pairs Fields in the tuple. The key is the name of an attribute, the value is the data value for the key. Metadata (Extended A set of data that helps in cataloging, storing, and retrieving files, Attributes) which can be deployed to a database. Metadata stored in TeamSite are also known as Extended Attributes (EA). Narrow Tuple A tuple that contains only two fields in addition to the path and state fields. The names of the fields are key and value. Narrow tuples are not a common way to deploy data due to structural constraints. For example, because a narrow tuple can contain only one key-value pair, OpenDeploy must create multiple tuples if a files extended attributes consist of more than one key-value pair. Also, you cannot deploy data content records using narrow tuples and you cannot automatically deploy narrow tuples with DAS. DAS only accepts wide tuples.
Deployment
192
Normalization
Path Field Replicant
Source Staging Area
Standalone Deployment Standalone Table
State Field
Submit Tracker Table
Tuple
Tuple Preprocessor Two-Tier Usage Configuration
The process of logically breaking down a database and its schema into smaller, more manageable tables. A normalized database is more flexible and contains less data redundancy. Other advantages to normalization include: relationships between tables are easier to understand, tables are easier to query, and data integrity is better maintained through referential constraints. A tuple field which is the area relative pathname of the file associated with the tuples key-value pair(s). A repeatable data field in a TeamSite Templating data capture form that can contain multiple nested items and instances. A contributor can add and remove copies of the replicant as needed while filling in a data capture form. Replicants cannot be linked. Refers to the origin of the data to be deployed; can be an XML file or TeamSite area. An area in TeamSite where a user integrates the contents of a workarea. Users submit read-only copies of files from their workareas to the staging area to integrate with other contributions. One of the modes of operation. Used to distribute content to repositories at run time and not by triggers or events. When OpenDeploy performs a 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. A tuple field that identifies whether the status of the data being deployed is: New: newly created or imported content. Modified: updated or modified content. Not Present: deleted content. Original: content deployed from another area. The act of transferring content from a TeamSite workarea to the staging area. A table created to maintain the synchronization between delta tables from multiple TeamSite workareas and a single base table from a staging area that they are associated with. The format into which data is transformed and used internally before it is saved as a record in the destination. In addition to its state and path fields, a tuple contains either one key-value pair (a narrow tuple) or multiple key-value pairs (a wide tuple). A user-defined Java class that can be used to supplement a data tuple object before it is deployed. A usage configuration that incorporates two systems: the source host where OpenDeploy executes (typically, this is a TeamSite server) and a second host running the relational database server. Two-tier configurations are typically used at sites that do not require firewall protection between the source host and the target database.
193
User-Defined Database Schema
Wide Table
Wide Tuple
Workarea
A schema that is comprised of more than one table whose relationships are defined by primary and foreign keys. Allows mapping of a given record to multiple tables (an alternative to using wide tables). A table in which a single row represents an entire data content record (DCR). Each field in the DCR is mapped to a different column A wide tuple contains multiple key-value fields in addition to state and path. OpenDeploy appends a numerical suffix to field names to maintain field name uniqueness. A virtual copy of content in TeamSite, which may be worked on independently without affecting the work of other contributors. A workarea can be owned by a single user or a number of users together.
194
Index
A allowed-hosts element 172 architecture 18 attributes configFilePath 111 databaseXmlFile 116 schemaMapFile (eaData) 117 schemaMapFile (xmlData) 117 useDatabaseRef 116 xmlData 117 B base table format 39 base tables 41 querying 162 updating 43, 100 base updates 35 bind element 172 C client element 168 column element 170 composite tables 45 concepts DAS 17 database 15 DataDeploy 17 deployments 17 structured content 14 configFilePath attribute 111 contents database schema 15 D DAS 17, 81 configuration 88 configuration files 82 database.xml 83 DataDeploy configuration templates 84 drop.cfg 84 iw.cfg 85 metadata capture setup 88 multiple OpenDeploy instances 82 OpenDeploy server configuration 86 parameters, specifying 86 reports 99 requirements 82 template type setup 87 triggers 104 user interface 86 data categories 26 data category 125 data deployment configuration files generating 89 data organization 37 data sources 36 data type 53 data types 26 database auto-synchronization composite tables 45 delta table 42 deployment sequence 41 initial base table 41 iwsyndb.ipl 88 table updates 44 updating base tables 43 workareas 88 database connection properties 77 Database Deployment for OpenDeploy Administration Guide usage 7 database deployments 11 architectural overview 18 architecture 18 DataDeploy module 109 standalone 110 synchronized 114 target-side 113 database element 159, 169 database privileges 11 database schema 15 database schemas data categories 26
195
data types 26 dbschema.cfg 29, 31 overview 25 rules 29 UDS 25 user-defined 25 wide table 25 database.xml DAS 83 databaseXmlFile attribute 116 DataDeploy 17 DataDeploy configuration files 111 running 112 DataDeploy configuration templates DAS 84 dataDeploy element 111 DataDeploy module 11, 109 DataDeploy wrapper file 111 data-deploy-elements element 167 dbLoader element 116 dbschema element 57 dbschema.cfg creation rules 29 DCR deployments 13 delta tables 42 updating 100 delta updates 35 deployment element 168 deployments concepts 14 DAS 17 data organization 37 data sources 36 database 11 database schemas 25 DataDeploy 17 DCR 13 EA 13 invocation 12 scenarios 35 standalone 12 synchronized 12 table types 35 tuples 37 UDS 26 update types 35 usage 12 use cases 19 wide table 26
196
destinations element 169 discard element 167 dlLoaderCustom element 118 documentation, OpenDeploy 7, 9 drop.cfg DAS 84 E EA deployments 13 eaAndXmlData element 118 eaData element 117 elements dataDeploy 111 dbLoader 116 dlLoaderCustom 118 eaAndXmlData 118 eaData 117 xmlData 117 elements, DTD allowed-hosts 172 bind 172 client 168 column 170 database 159, 169 data-deploy-elements 167 dbschema 57 deployment 168 destinations 169 discard 167 exec-deployment 168 filter 167 for-deployment 172 host 172 keep 167 select 170 server 172 source 168 sql 171 substitution 168 update 171 xml-formatted-data 169 Event Subsystem configuration files eventsubsystem.properties 96 event subsystem 91 configuring 92, 95 events 91 logging 98 publishers 91
subscribers 91 eventsubsystem.properties 96 exec-deployment element 168 external data source 151 F filter element 167 for-deployment element 172 H host element 172 I internal tables 189 IWDELTRACKER 189 IWOV_IDMAPS 190 IWOV_LOB 190 IWTRACKER 189 invocation 12 iw.cfg DAS 85 TeamSite mount point, alternate 86, 112 IWDELTRACKER internal table 189 IWOV_IDMAPS internal table 190 IWOV_LOB internal table 190 iwsyncdb.ipl 88 IWTRACKER internal table 189 K keep element 167 L logging event subsystem 98 TeamSite event 105 M MetaTagger 13 N narrow tuples 38, 40 base table format 40 notation conventions 8 O online help 9 OpenDeploy DAS 81
DataDeploy module 11 documentation 7, 9 online help 9 OpenDeploy Administration Guide 9 notation conventions 8 OpenDeploy Installation Guide 9 OpenDeploy Reference 9 OpenDeploy Release Notes 9 R real updates 160 replicants 133 comma separated lists 133 deploying 133 deploying multiple 141 order columns 133 S schema mapping 15 schemaMapFile (eaData) attribute 117 schemaMapFile (xmlData) attribute 117 select element 170 server element 172 source element 168 sql element 171 standalone database deployments 110 alternate mount point 112 configuration 111 DataDeploy configuration file 111 execution 111 server configuration 110 standalone deployments 12 standalone tables querying 162 standalone updates 36 structured content storing 15 XML 14 substitution element 168 substitutions global 168 in-flow 169 synchron ized deployments 114 synchronized deployments 12 T table types 35 table updates 44 tables, internal 189
197
target-side database deployments 113 deployment configuration 116 server configuration 115 synchronized 114 TeamSite 13 TeamSite event logging 105 TeamSite Templating 13 To 86 tuples 37 metadata 37 narrow 38, 40 defined 192 state 37 wide 38, 39 U update element 171 update types 35 base updates 35 delta update 35 standalone updates 36 useDatabaseRef attribute 116 user defined schemas configuration files 34 implementation 29 normalization of data 28 user-defined schema 26 user-defined schemas 25 W wide table limitations 27 wide table schemas 25 wide tuples 38 base table format 39 X xmlData attribute 117 xmlData element 117 xml-formatted-data element 169
198

Od 602 Ddadmin

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Od 602 Ddadmin

Uploaded by

Copyright:

Available Formats

Database Deployment for OpenDeploy Administration Guide Release 6.0.

Chapter 2: Deployment Concepts

Chapter 3: Configuration Files

Chapter 4: Database Auto-Synchronization

Database Deployment for OpenDeploy Administration Guide

Chapter 5: DataDeploy Deployments

Chapter 6: Advanced Features

Appendix A: Sample Configuration File

169 169 170 171 171 171 172

Appendix B: Database Deployment Tutorials

Appendix C: Database Deployment Internal Tables

Database Deployment for OpenDeploy Administration Guide

About This Book

Monospaced bold italic

Database Deployment for OpenDeploy Administration Guide

Other OpenDeploy Documentation

Other OpenDeploy Documentation

Database Deployment for OpenDeploy Administration Guide

Required Database Privileges

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Regions FIPS5-2 Territory

Americas California West

maps to this table/column

md/report md/symbol (primary key) desc/sym (foreign key) desc/vocab desc/tag

Database Deployment for OpenDeploy Administration Guide

Data Deployment Engine

Deployment may go through an OpenDeploy Receiver

XML Formatted Files

Database Tuple Producer

OpenDeploy Base Server

Figure 1: Data Deployment Architecture

Database Deployment for OpenDeploy Administration Guide

Use Case Matrix

Use Case Matrix

Migration Notes for DataDeploy 5.6

Initializing DAS tables.

initial workareavpath [nomdc] [dcrtype]

Invoking standalone DataDeploy deployments.

Database Deployment for OpenDeploy Administration Guide

Migration Notes for DataDeploy 5.6

The following sections provide details.

Database Deployment for OpenDeploy Administration Guide

Migration Notes for DataDeploy 5.6

Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

Figure 2: TeamSite Templating Directory Structure

Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

Overview of the Example

Wide Table Mapping and Its Limitations

mypath0 WilliamFaul 1234-56 Software Inc. Using kner Data

Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

Sample dbschema.cfg File

Database Deployment for OpenDeploy Administration Guide

User-Defined Database Schemas

</keys> </group> </dbschema>

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

Creating UDS-Based Configuration Files

datacapture.cfg for data type X dbschema.cfg for data type X