od 602 ddadmin

Database Deploymentfor OpenDeploy®

Administration Guide

Release 6.0.2

© 1997-2005 Interwoven, Inc. All rights reserved.

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

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

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

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

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

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

Table of Contents

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

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

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

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

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

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

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

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

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

3

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

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

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

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

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

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

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

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

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

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

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

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

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

Table Update Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Specifying How Tables are Updated. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Table Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Database Object Name Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103DAS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Configuring TeamSite Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

4 Database Deployment for OpenDeploy Administration Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

5

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

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

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

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

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

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

Glossary 191

Index 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.

7

Notation Conventions

This manual uses the following notation conventions:

Convention Definition and Usage

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

Click Edit File in the Button Bar.

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

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

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

Monospaced italic

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

iwodstart deployment

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

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

iwodstart

Monospaced bold italic

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

iwodstart deployment

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

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

| Vertical bars separating command-line arguments mean that only one of the arguments can be used.


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.

9


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 catalogs—all 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 user-defined database schemas. XML data residing anywhere in the file system can then be deployed to databases.

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

� Files with associated metadata for use by a search engine.

� Online catalog content along with web presentation templates.

� Documents and personalization data for a portal.

� JSP code and related data for an application server.

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


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 metadatatitle CDATA #REQUIRED>

<!ELEMENT descriptor EMPTY><!ATTLIST descriptorcode CDATA #REQUIREDvocabulary CDATA #REQUIREDlabel 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>



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)

Table 2: Descriptor Table (desc)

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

Mapping the XML Representation to the Database Schema

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

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

Report Symbol (primary key)

Sales in Northern California AG

Sales in Northern California 06

Sales in Northern California A

Sym (foreign key) Vocab Tag

AG Regions Americas

06 FIPS5-2 California

A Territory West

This XML element/attribute… …maps to this table/column

metadata/title md/reportdescriptor/code md/symbol (primary key)descriptor/code desc/sym (foreign key)descriptor/vocabulary desc/vocabdescriptor/label 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>



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.

Figure 1: Data Deployment Architecture

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

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

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

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

TeamSite or Local File

System

Database Tables

RDBMS

Source Type Invocation Method

XML Tuple Producer

Database Tuple

Producer

Database Tuple Writer

XM L Tuple W riter

Database Tables

RDBMS

XML Formatted Files

JDBCTupleXML Parser

JDBC Tuple

Tuple

Destination Type

B1

A

C1 D1

C2 D2

B2

XML

XML Files

Data Deployment Engine

CLT TeamSite Event

Web Services Client

OpenDeploy Base Server

Deployment may go through an OpenDeploy Receiver


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”.

SourceDestination

Database XML

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

TeamSite to XML(see page 66 for more information)

TeamSite Extended Attributes (Metadata)

Metadata to Database(see page 67 for more information)

Metadata to XML(see page 69 for more information)

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

XML to XML(see page 73 for more information)

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

Database to XML(see page 74 for more information)

19

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-Synchronization (DAS).

DAS daemon is configured for iwat or event server triggers.

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

Initializing DAS tables.

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

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

Configuring standalone DataDeploy deployments.

Configure DataDeploy deployment configuration file.

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

home/conf directory, and run it using OpenDeploy.

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

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

Invoking standalone DataDeploy deployments.

Use iwdd.ipl or iwexecdascmd command-line tools.

Use iwodcmd start -k iwdd=internal-deployment-name. See “Invoking DataDeploy Deployments” on page 21 for more information.



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.

Three-tier mode deployments.

Run a DataDeploy daemon on the target host.

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

Synchronized OpenDeploy-DataDeploy deployments.

Deploy and Run (DNR)-based solution.

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

Deploying to wide tables.

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

Task DataDeploy 5.6 OpenDeploy 6.0

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.þ



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.


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 database’s 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 Developer’s 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 Developer’s Guide.

Figure 2: TeamSite Templating Directory Structure

Workarea

templatedata

data_category_1

data_type_1

data_category_2

data_type_2

. . .

. . .

datacapture.cfg data presentation

content_record_1

content_record_2. . .

pres_template_1.tplpres_template_2.tpl. . .

componentstutorials

output



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 template—an XML file called datacapture.cfg—and has inserted it into the book directory. (Each data type must have its own data capture template.)

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

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

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

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

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

Wide Table Mapping and Its Limitations

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

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

� Name0-Name9

� E-Mail0-E-Mail9

� Comments0-Comments9

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

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:

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 Don’s data content record:

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

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

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

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

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

UDS and Normalization of the Data

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


mypath0 WilliamFaulkner

1234-56 Software Inc. Using Data

Chris [email protected]

This book describes...

original


mypath0 WilliamFaulkner

1234-56 Software Inc. Using Data

Chris [email protected]

This book describes...

original

mypath1 Harper Lee 1256-89 Software Inc. Using Tuples

original

Path Author ISBN Publisher Title State

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

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

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

Chris [email protected] This book describes... 1234-56



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 custom-defined groups of columns, using the groups element. These groups are analogous to tables, in database terminology, and are treated as tables by OpenDeploy.

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

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

� For DAS deployments—with the iwsyncdb -initial command.

� For standalone deployments—with 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 group’s attrmap element.

� If a column is designated as a foreign key:

� Its group’s attrmap element must contain a column element whose name matches the name of the child column.

� Its parent group must exist.

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

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

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

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

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

29

Deployment Concepts

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

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

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

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

<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-from-field attribute values (for example, Treatment List/[0-3]/Drug List/[0-4]/Drug) unless you are specifying a replicant field. Use this syntax only for replicant fields to indicate the maximum number of replicants for a given node in the XML tree.

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



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"/>


</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"/>


</attrmap><keys>

<primary-key><key-column name="Symptom"/><key-column name="Disease"/>


<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"/>


</attrmap><keys>

<primary-key><key-column name="Prognosis"/><key-column name="Disease"/>


<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"/>


</attrmap><keys>

<primary-key><column-key name="Treatment"/><column-key name="Disease" />


<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="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>



</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.

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

Prognosis List

Medical Master Vector List

Treatment List

Drug List

Symptom List

N

N

NN 1 1

1

1

1

N

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.

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

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

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

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

� Reads the datacapture.cfg file for each data type.

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

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

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

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

iwsyncdb Command Line:

iwsyncdb-ddgen

ddcfg_uds.template file or

ddcfg_uds_custom.template

3

1

2

4DataDeploy

configuration file X_dd.cfg

dbschema.cfg for data type X

dbschema.cfg for data type Y

DataDeploy configuration file

Y_dd.cfg

datacapture.cfg for data type X

datacapture.cfg for data type Y

templating.cfg


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. Differences—the delta data—are 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 table’s 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 table’s relationship to other tables.

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

Update TypeBase Delta Standalone

TeamSite Source Area

Workarea Supported Supported SupportedStaging Area Supported Not Supported SupportedEdition Supported Not Supported Supported



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 database’s 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 tuple’s key-value pair(s).

� One or more key-value pairs. The key is the name of an attribute. For example, News-Section is the key of the extended attribute News-Section:Sports. The value is the data value for a tuple’s key—Sports, 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 tuple’s status as viewed in TeamSite area 1 (most often the staging area) relative to the tuple in TeamSite area 2 (most often a workarea). A delta table can have tuple states of Original, New, Modified, or NotPresent. The following table shows the scenarios that can cause these states:

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

Wide vs. Narrow Tuples

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

Wide Tuples

A wide tuple is an internal representation of all the data for the source element being deployed. By default, wide tuples deploy into wide tables when deployed to a database. Unlike narrow tuples, wide tuples can be deployed either manually or with DAS. Wide tuples contain exactly one path element and one state element, and any number of key-value pairs. Thus, a file’s 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 OpenDeploy’s internal representation of a wide tuple.

Figure 5: Wide Tuple

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

A delta table tuple state of: Was caused by:

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

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

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

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

Tuple 1

path = docroot/news/front.htmlNews-Section = SportsLocale = SFstate = Original



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:

Figure 6: Wide Tuple with Similar Locale Keys

Base Table Format: Wide Tuples

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

Figure 7: Wide Tuple Default Base Table

Tuple 1

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

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

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

Wide Database Table:

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

Tuple 1 (Wide)

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

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 OpenDeploy’s 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 file’s extended attributes consist of more than one key-value pair.

Figure 8: Narrow Tuples

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

Base Table Format: Narrow Tuples

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

Figure 9: Narrow Tuple Default Base Table

Tuple 1

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

Tuple 2

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

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

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

Tuple 1 (Narrow)

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

Tuple 2 (Narrow)

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

Narrow DatabaseTable:



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 auto-matically updated whenever changes have been submitted to its corresponding staging area or edition from a workarea.

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

Generating an Initial Base Table

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

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

Figure 10: Generating an Initial Base Table

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

SA1

WA1

WA2

WA3

TeamSite OpenDeploy Database

BT1

1 2

3

Tracker Table

Tracker Table

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 relation-ships between base and delta tables

Generating a Delta Table

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

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

Figure 11: Generating a Delta Table

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

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

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

TeamSite DataDeploy Database

DT1

DT2

DT3

BT11 3

2

SA1

WA1

WA2

WA3

Tracker Table



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.

Figure 12: Updating a Base Table

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

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

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

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

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

SA1

WA1

WA2

WA3

DT1

DT2

DT3

BT1

Workflow or DAS 1

1a

6

57

TeamSite DataDeploy Database

Tracker Table

3

4

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.

Figure 13: Sample Table Updates

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

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

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

State 0BT1

Path Key Value StateP1 K1 V1 Orig

DT1Path Key Value State


State 1BT1




P2 K2 V2 New

State 2BT1

Path Key Value StateP1 K1 V1 OrigP2 K2 V2 Orig


P2 K2 V2 NtPres




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 file’s 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 file’s database section.

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

Figure 14: Composite Table Views

State 0WA1


WA2Path Key Value State

P1 K1 V1 Orig

State 1WA1



P1 K1 V1 OrigP2 K2 V2 New

State 2WA1



P1 K1 V1 OrigP2 K2 V2 Orig

45

Deployment Concepts


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 auto-generating dbschema.cfg files, the OpenDeploy user interface greatly simplifies the process of mapping DCTs to database schemas.

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

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.



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.


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.



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.


The mapping screen is displayed (Figure 17).

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.

B

C

A

D

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).



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 table’s 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 directo-ries. The available locations for the path are the following:



Single click to select files.

9. Click OK.



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 type’s 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.


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 parameter—such 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 con-forms 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)



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:



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 follow-ing:



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.



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 creat-ing 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:



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.txtc:/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>


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"/>


</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>



<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-recordsoptions="wide"area="/default/main/branch/WORKAREA/myworkarea">

<path name="templatedata/intranet/weather/data/w1"/></teamsite-templating-records>


<xml-formatted-data file="/tmp/ts2xml.out"><fields>

<field name="Announcement" element="Announcement"/><field name="Day" element="Day"/>

</fields></xml-formatted-data>



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>




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-attributesoptions="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>




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">



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.


<deployment name="teamsite-to-xml"><source>

<teamsite-extended-attributesoptions="full"area="/default/main/STAGING"><path name="."/>


<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>


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"/>



<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>




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"/>



<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>



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 XML-to-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.



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-to-XML deployment, although that feature is not shown here.


<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" />


</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>



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:


<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>


<xml-formatted-data file="/tmp/tupleTable.xml"></xml-formatted-data>



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>




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 element’s 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.



<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>





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:



<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 WHEREA.ID = B.ID ANDA.ID = 10]]>

</db-producer-query></database>





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 element’s 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 element’s table attribute.


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 element’s properties-file attribute as shown in the following example:

<databasename="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=20remarks=truebatchvalue=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.


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>


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.

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.

TeamSite OpenDeploy database

DCR or EAs are modified

OpenDeploy uses DAS

synchronize TeamSite data with database.

TeamSite event server triggers OpenDeploy.

TeamSite data is synchronized on

the database.

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 Location Description

daemon.cfg od-home/etc 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.

database.xml od-home/etc or any user-defined location

Specifies database connection parameters for different databases. See “Editing database.xml” on page 83.

ddcfg_uds.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.

ddcfg_uds.custom.template

od-home/ddtemplate

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.


Configuration Files

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

drop.cfg od-home/ddsyncdb

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.

iw.cfg (installed with TeamSite)

/etc (on UNIX)iw-home/etc (on Windows)

Controls whether renaming, moving, or deleting files will trigger deployment. Also used to enable the Event Subsystem. See “Editing iw.cfg” on page 85 for more information.

odbase.xml 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.

syntracker.cfg od-home/ddsyncdb

Utility configuration file used by the OpenDeploy base server when dropping tables.

File Location Description

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.


Configuration Files

Editing iw.cfg

You must edit the iwserver section of /etc/iw.cfg as follows to support DAS recognition of TeamSite events.

Once configured, DAS will support these events when they are initiated from the TeamSite user interface.

Refer to your TeamSite documentation for more information on configuring iw.cfg.

TeamSite Event Setting in iw.cfg

SyncDestroy log_syncdestroy=yes

SyncRevert log_syncrevert=yes

RenameFSE log_renamefse=yes

SetEA log_setea=no

DeleteEA log_deleteea=no

TeamSite Event Description

CreateBranch A branch has been created.CreateWorkarea A workarea has been created.DeleteEA An extended attribute (EA) has been deleted

from a file.DestroyBranch A branch has been deleted.DestroyEdition An edition has been deleted.DestroyWorkarea A workarea has been deleted.PublishStagingArea A new edition has been published from the staging areaRenameBranch A branch has been renamed.RenameFSE An FSE has been renamed.RenameWorkarea A workarea has been renamedSetEA An EA has been added to/modified on a file.Submit A file or directory has been submitted.SyncCreate A file with EAs has been created.SyncDestroy A file with EAs has been deleted.SyncModify A file with EAs has been modified.SyncRevert A file with EAs has reverted to an earlier

version.Update A file or directory has been updated.

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.


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_vpathfor deploying DCRs and EAs


Configuring DAS Manually

� od-home/bin/iwsyncdb -initial workarea_vpath teamsite/metadatafor deploying only EAs

� od-home/bin/iwsyncdb -initial workarea_vpath category/dcrtypefor 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.

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 Developer’s 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 configura-tion files that it will generate for each data type.

iwsyncdb command

Command Lineiwsyncdb -initial

ddcfg_uds.template file

• deployment configuration files submitted

• Edition published

deployment configuration file

X_dd.cfg

datacapture.cfg for data type X

datacapture.cfg for data type Y

datacapture.cfg for data type Z


Y_dd.cfg


Z_dd.cfg3

1

2

4 5

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 stag-ing 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.

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.

Command Line• iwsyncdb -initial (continued)

OpenDeploy Base Server

• Reads daemon.cfg for startup information

• Runs continuously• Automatically

deploys data when TeamSite trigger events occur

TeamSite Event Subsystem

• TeamSite events registered as DataDeploy triggers

daemon.cfg• OpenDeploy

base server startup information

6

87

RDBMS9


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:

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.

Message Service

Message Service Interface

TeamSite

Publishers

Server

Subscribers

OpenDeploy(DAS)

Event Subsystem

ProxyServletTeamSiteTemplating

Implementation


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.


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 corre-sponds 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 vendor’s 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


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 oper-ating 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 exam-ple:

<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 element’s 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:

� fatal — 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.

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


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.

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.

RDBMS

TeamSite— End user activity results in TeamSite trigger event

iwsyncdb

— Receives and interprets data from TeamSite trigger event— Passes data to OpenDeploy

OpenDeploy

— Determines which deployment configuration file to use— Deploys data to database

3

1

2

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:

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 State PressDate Headline Picture . . .


mypath New 4/17/03 New Candidate Enters Race

cand.gif ...


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:

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.


mypath New 4/17/03 New Candidate Enters Race

cand.gif ...


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.


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 database’s 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: Table name2: Column name3: View name4: 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 database’s object length limits. For example, a typical table might appear as follows:

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.

Type Longid Shortid2 INFORMATION0_PRESENTATIONTITLE IWC_AA6A93A7161

1 INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING IWT_106342E4D4C4

3 INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_VIEW IWV_AEGF12D4E

4 INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_CONSTRAINT IWO_F023AF1290

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 None. Build empty base tables.

Create workarea Build delta tables. None.

Delete branch Delete delta tables. Delete base tables.

Delete workarea Delete delta tables. None.

Modify data content record

Update or insert a new row. None.

Add data content record

Insert a new row. None.

Delete data content record

Insert or update the NOT-PRESENT row. None.

Submit modified data content record

1. The Previous Staging row is propagated to all workareas except the submitting workarea.2. Delete Previous Staging row from submitting workarea.

Update the Staging row.

Submit added data content record

1. The Placeholder row marked NOT-PRESENT is propagated to all workareas except the submitting workarea.2. Delete the Placeholder row from the submitting workarea.


Submit deleted data content record

1. The previous Staging row is 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. None.

Copy to (any area) Rebuild the delta tables. None.


Using DAS

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"

Rename workarea 1. Delete old delta tables.2. Regenerate new delta tables.

None.

Rename branch None. 1. Delete old base tables.2. Regenerate new base tables.

Rename directory Regenerate delta tables. None.

Rename file 1. Delete the row for the old file name.2. Add a row for the new file name.

None.

Move file 1. Delete the row for the old file name.2. Add a row for the new file name.

None.

Delete file 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.

None.

Set metadata Insert or update the row. None.

Revert 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.

TeamSite Event Delta Table Action Base Table Action

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 file’s 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 areaviewWHERE key = News-Section AND value = Sports


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 non-root 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 or

iwsyncdb -resyncbr

Tutorial

This manual includes a tutorial for configuring and using DAS. See Appendix B, “Database Deployment Tutorials” on page 173 for more information.


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.

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.

source database

structured content files

Structured content files are deployed to relational database using JDBC


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.


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.

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.

source target database

Structured content files are deployed to target

Structured content is deployed to database. using JDBC.

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.

Figure 44: Synchronized Database Deployment

source target database

Structured content files are deployed to target

Code and content files are deployed to target. XML content is deployed

to database. using JDBC.



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.

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 server’s database configuration file (database.xml, see next section). See “Deployment Configuration” on page 116 for more information.

� The dnrProperties element’s 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.

source target

target

target

XML content is deployed to database. using JDBC.

Code and content files are deployed to target.



database

Structure content files are deployed to target.

115


Target Servers

The following tasks must be performed on each target OpenDeploy base server or receiver:

� The databaseDeployment element on the target OpenDeploy server’s 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 server’s 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.



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 TeamSite’s 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 TeamSite’s 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.



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.


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 statement’s 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"/>



Deploying Data as Database Objects

</group></dbschema>




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>[email protected]</value></item><item name="Reader Comments"><value>comments</value></item></value><value><item name="Review Reader"><value>james</value></item><item name="Review Reader E-Mail"><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 key-value 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.



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 element’s 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 element’s 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 FiltersYou 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 SubstitutionYou can incorporate regular expressions in data filters and substitutions using the field element’s 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.



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:

� <and> — 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.

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%')



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.

Another way to ignore events published before DAS is started is to specify the format and match 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 element’s 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:

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>

To do this: Include this line in the Substitution section:

Replace all Value field values with the string Newvalue

<field name="value" replace="Newvalue"/>

In the Path field, replace first occurrence of blue with red

<field name="path" match="blue" replace="red"/>

In the Path field, replace all occurrences of blue with red

<field name="path" match="blue" replace="red" global="yes"/>

In the State field, replace the first occurrence of Original with NotPresent

<field name="key" match="Original" replace="NotPresent"/>



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 (where ^ is a concatenator)prefix_$varname^_suffix


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, real-updates 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">


</item><item name="ISBN">


</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>



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)" value-

fromfield="Reviewers" allows-null="no"/></attrmap><keys>

<primary-key><key-column name="Title"/>


</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"/>


</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>



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:

Replicant Values

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.

Title Author ISBN Price

Interwoven Author1 12345 100.00

Title Reviewers

Interwoven R1

Interwoven R2

Interwoven R3

Interwoven R4

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">


</item><item name="Author">


</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][0-

9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]$" /></item><item name="ISBN">


</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/>



</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-from-field 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:

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

Title_in_review Reviewer Reviewer_Expertise

Java Message Service Reviewer 1 Java

Java Message Service Reviewer 1 Assembly

Java Message Service Reviewer 2 C++

Java Message Service Reviewer 2 Java


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 par-ent 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 Java-based 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 whichthe tuple preprocessor method is being called by DataDeploy.This property exists in the cmdLineParams Properties objectpassed to the PreProcessTuple() method by DataDeploy, whenthe 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 tuplein the form of a Hashtable object (keys being the field names). Usercan modify the tuple (adding, modifying deleting key-value pairs) andthen return the modified tuple object back to DataDeploy.

area: Points to the "area" attribute value if the tuple was producedby either <teamsite-templating-records> or <teamsite-extended-attributes> source. null otherwise.

basearea: Points to the "basearea" attribute value if the tuple wasproduced by either <teamsite-templating-records> or <teamsite-extended-attributes> source when a differential extraction type is specified. null otherwise.

The following method is called by DataDeploy when the interface-version 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 interface-version attribute in the DD config file is set to "2.0".



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 hereinput.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 columnsfor (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.



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"/>


</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>






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:od-home/(od-instance)/userlib

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.



*/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 sourceParameters: 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:od-home/(od-instance)/userlib

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-from-callout="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.



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 user-defined 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 Calloutimport com.interwoven.dd100.dd.IWExternalDataSource;

//import other stuff neededimport 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());



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)



{ 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-url–valid values are yes and no.

� value-from-field–valid values are any DCR element or metadata.

� value–valid values are URLs that contain a file: or http: prefix.

� url-content-encoding–valid 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"/>

During deployment, DataDeploy gets the metadata value for the key TeamSite/Metadata/Picture for 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"/>


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 element’s 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 element’s 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 node’s 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"/>


</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>



<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:

<databasename="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 element’s 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-attributesoptions="wide"area="/store2/main/branch1/WORKAREA/wa1"><path name="file2.txt"/>


<database use="oracle" table="not-used"><sql user-action="execute_my_procedure" type="exec-proc">

myproc(1,2)</sql>






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:

� depName — 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

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 file’s 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 ) ASSELECT key, value, path

FROM saWHERE NOT EXISTS

( SELECT *FROM wa_x WHEREwa_x.key = sa.key ANDwa_x.path = sa.path )

UNIONSELECT key, value, pathFROM wa_x WHERE wa_x.state != ’NotPresent’;

SELECT path FROM areaviewWHERE 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 file’s 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’;


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.

<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" />

</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>

<substitution name="GlobalSubstitution"><field name="path" match="fun" replace="bar" /><field name="value" replace="SpecialValue" />

</substitution>

Include file 1

Filter section(global) 2

Substitution section (global) 3

163


<client><deployment name="ea-to-db">

<source><teamsite-extended-attributes

options="differential, wide"area="/default/main/branchx/WORKAREA/$user"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" />

<path filelist="/tmp/SomeFiles" />

</teamsite-extended-attributes></source>

<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"match="^BEFORE(.+)"replace="AFTER$1" />

</substitution><substitution use="GlobalSubstitution" />

Start of Deployment section 5 Start of Source section 6

Location of sourcedata 8

(area)

End of Sourcesection 6

Call globalfilter 2

Source type7

Start of Client section4

Substitutionsection(in-flow) 9

Call global substitution 3


The Sample Configuration File

<destinations

host="DDServer.interwoven.com"port="1357"><database name="myproductiondb"

db="host1:1357:db1"table="table1"vendor="oracle"user="dba"password="ThisIsASecret"timeout="45">

<select><column name="filename"

value-from-field="path" /><column name="InterestingTag"

value-from-field="key" /><column name="info"

value="litData" /></select>

<update type="delta"base-table="RootTable1"state-field="StateInfo">

<column name="RelatedValue"

value-from-field="value" /><column name-from-field="key"

value="present" /></update>

Rows to update 12

Start ofDestinationssection 10

Start of Databasesection and locationof destinationdatabase 11

Update typeand relateddata 13

Columns toupdate 14

165


<sql action="create">



CREATE TABLE table1 (Path VARCHAR(300) NOT NULL,KeyName VARCHAR(300) NOT NULL,Value VARCHAR(4000) ,State VARCHAR(4000) ,CONSTRAINT KVP PRIMARY KEY (Path,KeyName)

)</sql>


</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>


Server section 16

SQLsection 15


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 element’s 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 element’s 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.



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 era designator (Text) AD

y year (Number) 1996

M month in year (Text & Number) July & 07

d day in month (Number) 10

h hour in am/pm (1-12) (Number) 12

H hour in day (0-23) (Number) 0

m minute in hour (Number) 30

s second in minute (Number) 55

S millisecond (Number) 978

E day in week (Text) Tuesday

D day in year (Number) 189

F day in week in month (Number) 2 (2nd Wednesday in July)

w week in year (Number) 27

W week in month (Number) 2

a am/pm marker (Text) PM

k hour in day (1-24) (Number) 24

K hour in am/pm (0-11) (Number) 0

z time zone (Text) Pacific Standard Time

‘ escape for text (Delimiter)

‘’ single quote (Literal) ‘



Examples using the US locale:

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.

Format Pattern Result

"yyyy.MM.dd G 'at' hh:mm:ss z" 1996.07.10 AD at 15:08:56 PDT

"EEE, MMM d, ''yy" Wed, July 10, '96

"h:mm a" 12:08 PM

"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time

"K:mm a, z" 0:00 PM, PST

"yyyyy.MMMMM.dd GGG hh:mm aaa" 1996.July.10 AD 12:08 PM

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.


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:

� Standalone database deployments

� Database Auto-synchronization (DAS)

� 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:

� Install the OpenDeploy base server software. Refer to Chapter 2, “Installation” on page 31 in the OpenDeploy Installation Guide for more information.

� 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.

� 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.

� 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 element’s daemon_port attribute value to 2345.



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 attribute’s 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 descriptionname CDATA #REQUIRED>

<!ELEMENT employees (employee)+><!ELEMENT employee EMPTY><!ATTLIST employeename CDATA #REQUIREDid CDATA #REQUIRED>

Navigate to the following location:

od-home/examples/conf-dd/tutorial

175


There are two directories:

� /conf — contains the DTD shown here and a deployment configuration file.

� /data — contains XML files created for your convenience and follow the DTD shown here.

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.”



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:

� use — specifies which database definition contained in the file database.xml should be used by OpenDeploy for the connection.

� 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.

� 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"/>


</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>



Finally, we will match the open tags:




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:

3. View the details on the deptrecords table. The following information should be dis-played:

4. View the details on the employee table. The following information should be displayed:

table_name

deptrecords

employee

iwdeltracker

iwov_idmaps

DeptId name

00101 Engineering

00102 Marketing

Name id depId

Simson Garfinkel

345 00101

Art Vandalay 506 00101

Mark Jones 209 00102

Jane Smith 245 00102


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.


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 browser-based 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:

� Windows — Y:\default

� 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 file’s 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 oracle-db to microsoft-db. 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 element’s use attribute. The data-deploy-elements element’s filepath attribute value is the full path to the database.xml file. For example:

<data-deploy-elements filepath="od-home/etc/database.xml">

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:

� OpenDeploy uses the ddcfg_uds.template and dbschema.cfg files to generate a configuration file called careers_dd.cfg under templatedata/internet/careers.

� Your workarea is submitted. Therefore, your workarea will not have any changes and will be up to date with STAGING.

� 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.


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:

� basearea — Generates STAGING tables, deploys DCRs to the STAGING table.

� 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 let’s 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_STAGINGDEFAULT_INTERNET_CAREERS_CAREERS_MAIN_WORKAREA_JDOEIWTRACKER JNDI_CONTEXT MESSAGE_HANDLESMESSAGE_ID MESSAGES PERSONNELRECORDSSEEDS SYSTEM_DATA

Now, we can see our STAGING data.

select * from DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING;

Path Department Title Requisition_Num Description Locationtemplatedata\internet\careers\data\career1 EngineeringSenior 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:

� Creating new DCRs

� Deleting DCRs

� Modifying DCRs

� 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:

� 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.


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 Longid1 IWT_FC3BD105F88 DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING1 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.


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:

� NAME — the name of the workarea or STAGING table.

� BASE — the name of the corresponding STAGING table. This only applies to workarea tables. For STAGING tables, this value will be __NO_BASE__.

� UPDATETIME — the time the particular row in the IWTRACKER table was updated.

� BRANCH — the TeamSite branch corresponding to the table.

IWDELTRACKER

The IWDELTRACKER table stores the primary key values for each file asset (a DCR or XML-based 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:

� PATH — the area relative path to the file.

� AREA — the path to the area where the file is located.

� KEYCOLNAME — the name of the primary key column of the actual table receiving the deployment.

� KEYCOLVALUE — the value of the primary key.

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:

� Table name

� Columns

� Constraints

� 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 vendor’s 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:

� TYPE — the type of identifier:

� 1 — table

� 2 — column

� 3 — view

� 4 — constraint

� SHORTID — the unique short ID that OpenDeploy generates.

� LONGIS — the actual name of the identifier.

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.


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 Auto-Synchronization (DAS)

DAS automatically updates the destination database when changes are made to content in TeamSite areas. DAS runs DataDeploy as a 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. User-defined 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 Template (DCT)

An XML file, datacapture.cfg, that defines the form used to 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 (DCR)

An XML file containing formatting information interspersed with 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 file

An OpenDeploy deployment configuration that simply contains a 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 differences—the delta data—are 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 table’s 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.

Deployment 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 Attributes)

A set of data that helps in cataloging, storing, and retrieving files, 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 file’s 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.


Normalization 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.

Path Field A tuple field which is the area relative pathname of the file associated with the tuple’s key-value pair(s).

Replicant 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.

Source Refers to the origin of the data to be deployed; can be an XML file or TeamSite area.

Staging 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.

Standalone Deployment

One of the modes of operation. Used to distribute content to repositories at run time and not by triggers or events.

Standalone Table 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.

State Field 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.

Submit The act of transferring content from a TeamSite workarea to the staging area.

Tracker Table 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.

Tuple 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).

Tuple Preprocessor A user-defined Java class that can be used to supplement a data tuple object before it is deployed.

Two-Tier Usage Configuration

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

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).

Wide Table 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

Wide Tuple 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.

Workarea 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.


Index
Aallowed-hosts element 172architecture 18attributes
configFilePath 111databaseXmlFile 116schemaMapFile (eaData) 117schemaMapFile (xmlData) 117useDatabaseRef 116xmlData 117

Bbase table format 39base tables 41

querying 162updating 43, 100

base updates 35bind element 172

Cclient element 168column element 170composite tables 45concepts

DAS 17database 15DataDeploy 17deployments 17structured content 14

configFilePath attribute 111contents

database schema 15

DDAS 17, 81

configuration 88configuration files 82database.xml 83DataDeploy configuration templates 84drop.cfg 84iw.cfg 85

metadata capture setup 88multiple OpenDeploy instances 82OpenDeploy server configuration 86parameters, specifying 86reports 99requirements 82template type setup 87triggers 104user interface 86

data categories 26data category 125data deployment configuration files

generating 89data organization 37data sources 36data type 53data types 26database auto-synchronization

composite tables 45delta table 42deployment sequence 41initial base table 41iwsyndb.ipl 88table updates 44updating base tables 43workareas 88

database connection properties 77Database Deployment for OpenDeploy Administration

Guideusage 7

database deployments 11architectural overview 18architecture 18DataDeploy module 109standalone 110synchronized 114target-side 113

database element 159, 169database privileges 11database schema 15database schemas

data categories 26

195

data types 26dbschema.cfg 29, 31overview 25rules 29UDS 25user-defined 25wide table 25

database.xmlDAS 83

databaseXmlFile attribute 116DataDeploy 17DataDeploy configuration files 111

running 112DataDeploy configuration templates

DAS 84dataDeploy element 111DataDeploy module 11, 109DataDeploy wrapper file 111data-deploy-elements element 167dbLoader element 116dbschema element 57dbschema.cfg

creation rules 29DCR deployments 13delta tables 42

updating 100delta updates 35deployment element 168deployments

concepts 14DAS 17data organization 37data sources 36database 11database schemas 25DataDeploy 17DCR 13EA 13invocation 12scenarios 35standalone 12synchronized 12table types 35tuples 37UDS 26update types 35usage 12use cases 19wide table 26

destinations element 169discard element 167dlLoaderCustom element 118documentation, OpenDeploy 7, 9drop.cfg

DAS 84

EEA deployments 13eaAndXmlData element 118eaData element 117elements

dataDeploy 111dbLoader 116dlLoaderCustom 118eaAndXmlData 118eaData 117xmlData 117

elements, DTDallowed-hosts 172bind 172client 168column 170database 159, 169data-deploy-elements 167dbschema 57deployment 168destinations 169discard 167exec-deployment 168filter 167for-deployment 172host 172keep 167select 170server 172source 168sql 171substitution 168update 171xml-formatted-data 169

Event Subsystemconfiguration files

eventsubsystem.properties 96event subsystem 91

configuring 92, 95events 91logging 98publishers 91


subscribers 91eventsubsystem.properties 96exec-deployment element 168external data source 151

Ffilter element 167for-deployment element 172

Hhost element 172

Iinternal tables 189

IWDELTRACKER 189IWOV_IDMAPS 190IWOV_LOB 190IWTRACKER 189

invocation 12iw.cfg

DAS 85TeamSite mount point, alternate 86, 112

IWDELTRACKER internal table 189IWOV_IDMAPS internal table 190IWOV_LOB internal table 190iwsyncdb.ipl 88IWTRACKER internal table 189

Kkeep element 167

Llogging

event subsystem 98TeamSite event 105

MMetaTagger 13

Nnarrow tuples 38, 40

base table format 40notation conventions 8

Oonline help 9OpenDeploy

DAS 81

DataDeploy module 11documentation 7, 9online help 9

OpenDeploy Administration Guide 9notation conventions 8

OpenDeploy Installation Guide 9OpenDeploy Reference 9OpenDeploy Release Notes 9

Rreal updates 160replicants 133

comma separated lists 133deploying 133deploying multiple 141order columns 133

Sschema mapping 15schemaMapFile (eaData) attribute 117schemaMapFile (xmlData) attribute 117select element 170server element 172source element 168sql element 171standalone database deployments 110

alternate mount point 112configuration 111DataDeploy configuration file 111execution 111server configuration 110

standalone deployments 12standalone tables

querying 162standalone updates 36structured content

storing 15XML 14

substitution element 168substitutions

global 168in-flow 169

synchron ized deployments 114synchronized deployments 12

Ttable types 35table updates 44tables, internal 189

197

target-side database deployments 113deployment configuration 116server configuration 115synchronized 114

TeamSite 13TeamSite event logging 105TeamSite Templating 13To 86tuples 37

metadata 37narrow 38, 40

defined 192state 37wide 38, 39

Uupdate element 171update types 35

base updates 35delta update 35standalone updates 36

useDatabaseRef attribute 116user defined schemas

configuration files 34implementation 29normalization of data 28

user-defined schema 26user-defined schemas 25

Wwide table

limitations 27wide table schemas 25wide tuples 38

base table format 39

XxmlData attribute 117xmlData element 117xml-formatted-data element 169