Od 71 Ddadmin v01 en

Database Deployment for OpenDeploy Administration Guide
Version 7.1
Document Revision 01 January 2010
Copyright Notice
Notice
This document is a proprietary product of Autonomy and is protected by copyright laws and international treaty. Information in this manual is subject to change without notice and does not represent a commitment on the part of Autonomy. While reasonable efforts have been made to ensure the accuracy of the information contained herein, Autonomy assumes no liability for errors or omissions. No liability is assumed for direct, incidental, or consequential damages resulting from the use of the information contained in this document. The copyrighted software that accompanies this document is licensed to the End User for use only in strict accordance with the End User License Agreement, which the Licensee should read carefully before commencing use of the software. No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner. This document may use fictitious names for purposes of demonstration; references to actual persons, companies, or organizations is strictly coincidental.
Trademarks and Copyrights

Copyright 2010 Autonomy Corporation plc and all its affiliates. All rights reserved. Interwoven, iManage, ConfirmSite, ContentServices, ControlHub, DataDeploy, DeskSite, FileSite, iManage, iManage Universal Search, iManage WorkSite, LiveSite, MediaBin, MetaCode, MetaTagger, OffSite, OpenDeploy, Primera, iManage RecordsManager, Scrittura, TeamPortal, TeamSite, VisualAnnotate, WorkDocs, WorkPortal, WorkRoute, WorkSite, WorkSite Express Search, WorkTeam, the respective taglines, logos and service marks are trademarks of Autonomy Corporation plc and its affiliates, 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, GBRI # 1053523, US # 6,480,944, US# 5,845,270, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, AU 7830068, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, CAN #2,062,965, FRAN / GRBI / SPAI / SWED #480941, GERM #69020564.3, KORS 10-0576487, JAPA #2968582, MX #219522, NZ #516340, SING #109524, SG #89006, SG #89086, SG #74973, SG #85502 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,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, US #6,697,532, US #6,792, 454, US #6,928,149, US #7,092,969 or other patents pending application for Autonomy Corporation plc and its affiliates. All other trademarks are the property of their respective owners.
Notice to Government End Users

If this product is acquired under the terms of a DoD contract: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of 252.227-7013. Civilian agency contract: Use, reproduction or disclosure is subject to 52.227-19 (a) through (d) and restrictions set forth in the accompanying end user agreement. Unpublished-rights reserved under the copyright laws of the United States. Autonomy, Inc., One Market Plaza, Spear Tower, Suite 1900, San Francisco, CA. 94105, US.
Autonomy Corporation plc Cambridge Business Park Cowley Rd Cambridge CB4 0WZ Tel: +44 (0) 1223 448000 Fax: +44 (0) 1223 448001 Email: autonomy@autonomy.com
Contents
About This Book
13
Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 1:
Introduction
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required Database Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introductory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML for Defining Structured Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database for Storing Structured Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping the XML Representation to the Database Schema. . . . . . . . . . . . . . . . Deploying XML to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use Case Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migration Notes for DataDeploy 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migration Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DataDeploy Administration User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking DataDeploy Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iwsyncdb.cfg File Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Discontinued DataDeploy Commands and Scripts . . . . . . . . . . . . . . . . . . . . . . . Running DataDeploy in Threadperbranch Mode . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy-DataDeploy Synchronized Deployments. . . . . . . . . . . . . . . . . . . . DataDeploy Module Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required Locations for Deployment Configuration and Schema Files. . . . . . . . Running DAS with DataDeploy 5.6 and OpenDeploy 6.0 on the Same Host . . . New Usage of TuplePreprocessor and ExternalDataSource . . . . . . . . . . . . . . . .
17
17 18 18 19 20 20 21 21 23 24 26 27 27 28 28 29 29 30 30 31 31 32 32
Chapter 2:
Deployment Concepts
Categories of Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Database Deployment Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source/Destination Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-Defined Database Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
33 34 35 35 35
3
Contents
Sample Deployment Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Update and Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Organization and Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36 37 38 38 43
Chapter 3:
Configuration Files
Mapping a Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping a Database Schema with the Browser-Based User Interface . . . . . . . . Updating an Existing Database Schema File . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping a Database Schema with iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the DataDeploy Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Browser-Based User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the iwsyncdb -ddgen Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Multiple XML-Formatted Files as a List of Filelists. . . . . . . . . . . . . Sample Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite Extended Attributes to Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite Extended Attributes to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeamSite and TeamSite Extended Attributes to Database . . . . . . . . . . . . . . . . . Formatted XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatted XML to Formatted XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML to Formatted XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Database Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Metadata to UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Default Datatype Size on Internal Tables . . . . . . . . . . . . . . . . . . . . . . . . Tablespace Attribute Usage in CREATE TABLE Statements . . . . . . . . . . . . . . . . . Vendor-Specific Configuration File Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attributes of the database Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attributes of the column Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
49 50 57 58 60 61 65 65 66 66 69 70 72 73 74 75 76 78 80 83 84 84 85 85 87 88 89 91
Chapter 4:
Database Auto-Synchronization
Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Instances of OpenDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing database.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Deployment Configuration File Templates and drop.cfg . . . . . . . . . . . . Editing iw.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring DAS in the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying DAS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
93
94 94 94 96 96 97 98 98 98
Contents
DAS Setup for Template Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 DAS Setup for Metadata Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Configuring DAS Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Running iwsyncdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 The Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Configuring the Event Subsystem with the Browser-Based User Interface . . . 105 Configuring the Event Subsystem Manually . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Logging Options for Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Generating DAS Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Using DAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Table Update Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Specifying How Tables are Updated. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Table Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Database Object Name Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 DAS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Configuring TeamSite Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Database Virtualization Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 DAS and Metadata Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Enabling DAS Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 DAS Out-of-Sync Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Multibyte Characters in DAS Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Increasing the Port Range on Linux to Accommodate Database Deployments . . . 123 Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Chapter 5:
DataDeploy Deployments
Standalone Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Deployment Configuration and Execution . . . . . . . . . . . . . . . . . . . . Specifying an Alternate TeamSite Mount Point . . . . . . . . . . . . . . . . . . . . . . . . Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Target-Side Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
125
126 126 127 128 128 129 130 131 132
Chapter 6:
Advanced Features
Deploying Data as Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Data as Database Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Data as Database Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . Filters and Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Replicants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replicant Order Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Comma Separated Lists of Values as Replicants. . . . . . . . . . . . . . . Deploying Multiple Replicants from Multiple Nesting Levels . . . . . . . . . . . . .
137
137 137 139 140 140 147 149 149 150 157
5
Contents
Performance Enhancement for Deploying Heavily Nested DCRs . . . . . . . . . . Enhancing Deployment Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Tuple Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying URL Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Miscellaneous Advanced Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Custom Data Content Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encoding/Encrypting Database Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . Real Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing a Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing Stored Procedures with Deployments . . . . . . . . . . . . . . . . . . . . . . . Executing Arbitrary Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
157 158 159 166 175 177 177 179 180 180 181 182
Chapter 7:
Troubleshooting
Failure in creating the necessary tables for Microsoft SQL Server databases . Failure of Database deployments to a Sybase database . . . . . . . . . . . . . . . . . . Error in creating the IWDELTRACKER table in a UTF-8 schema . . . . . . . . . Deployment Failure due to Invalid Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Failure When dbschema.cfg is Manually Modified. . . . . . . . . . . . . Renamed Files Fail to Deploy When UDS Table is Used for Metadata . . . . . .
185
185 186 186 186 187 187
Appendix A: Sample Configuration File

The Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Sections of the Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Include File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Filter Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Substitution Section (Global) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. Client Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. Deployment Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. Source Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. Source Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Location of Source Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. Substitution Section (In-Flow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10. Destinations Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Database Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Rows to Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13. Update Type and Related Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14. Columns to Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. SQL Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16. Server Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
189
189 193 193 193 194 194 194 195 195 195 195 195 196 196 198 198 198 198
Appendix B: Database Deployment Tutorials

Standalone Deployment Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Base Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Example: Custom XML to Database . . . . . . . . . . . . . . . . . . . . . . DAS Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
199
200 200 201 207 207
Contents
TeamSite Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Behavior On Other Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring for Oracle OCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Solaris. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Best Practices for Writing SQL Queries for Custom SQL Reports . . . . . . . . . . . . Conclusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
208 213 214 214 215 216 218
Appendix C: UDS vs. Wide Table Mapping

UDS vs. Wide Table Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Categories and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wide Table Mapping and Its Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDS and Normalization of the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation of a UDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Creating dbschema.cfg Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample dbschema.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating UDS-Based Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
219
219 219 220 221 222 223 223 225 228
Appendix D: Database Deployment Internal Tables

IWTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWDELTRACKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWOV_IDMAPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IWTMP_LOB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
231
231 231 232 233
Glossary Index
235 241
Contents
Tables
Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 Table 26 Table 27 Table 28 Table 29 Table 30 Table 31 Table 32 Table 33 Table 34 Table 35
Notation Conventions............................................................................................... Metadata Table (md)................................................................................................ Descriptor Table (desc)............................................................................................ Mapping XML-based Attributes to the DB Tables.................................................... Supported Use Cases for Data Deployments .......................................................... Migration Matrix ....................................................................................................... Data Sources ........................................................................................................... Tuple State Causes ................................................................................................. db Attributes............................................................................................................. vendor Attributes...................................................................................................... DAS Configuration Files........................................................................................... TeamSite Events in iw.cfg........................................................................................ Description of TeamSite Events............................................................................... Table Update Example .......................................................................................... Table Update Example (cont.) ............................................................................... Table Update Example (cont.) ............................................................................... Table Update Example (cont.) ............................................................................... Database Object Name Lengths............................................................................ DAS Triggers ......................................................................................................... Global Substitutions ............................................................................................... Non-Replicant Values ............................................................................................ Non-Replicant Values (cont.) ................................................................................. Non-Replicant Values (cont.) ................................................................................. Replicant Values .................................................................................................... SimpleDateFormat ................................................................................................. SimpleDateFormat Using the US Locale ............................................................... Database Tables.................................................................................................... Database Tables (deprecords) .............................................................................. Database Tables (employee)................................................................................. JDBC Date Conversion Functions ......................................................................... Table Headings in the Destination Database......................................................... Wide Table Mapping .............................................................................................. Wide Table Mapping (cont.)................................................................................... UDS ....................................................................................................................... UDS (cont.) ............................................................................................................
14 21 21 22 26 27 38 39 89 90 94 97 97 113 114 114 114 116 117 147 152 153 153 156 196 197 206 206 206 217 221 221 222 222 223
Tables
10
Figures
Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 Figure 14 Figure 15 Figure 16 Figure 17 Figure 18 Figure 19 Figure 20 Figure 21
62
Data Deployment Architecture .................................................................................... 25 Wide Tuple.................................................................................................................. 40 Wide Tuple with Similar Locale Keys .......................................................................... 40 Wide Tuple Default Base Table .................................................................................. 41 Narrow Tuples............................................................................................................. 42 Narrow Tuple Default Base Table............................................................................... 42 Generating an Initial Base Table ................................................................................. 43 Generating a Delta Table ............................................................................................ 44 Updating a Base Table ............................................................................................... 45 Sample Table Updates ............................................................................................... 46 Composite Table Views ............................................................................................. 48 Map DCT/DTD to Database Schema Window ............................................................ 51 Database Connection Window (for Oracle) ................................................................ 52 Map Data to a New Database Schema Window......................................................... 53 Mapping a Custom DTD and Specifying the Replicant Instances .............................. 54 Map Data Source to a New Database Schema Panel ................................................ 55 Display of the generated file ....................................................................................... 57 Map Data Source to an Existing Database Schema Panel......................................... 58 Configuration File: Specify Parameters for Data Source Window .............................. 61 Specify Parameters for Data Source Window (cont.) (TeamSite)............................... 62 Specify Parameters for Data Source Window (cont.) (OpenDeploy Server File System)
Figure 22 Create DataDeploy Configuration File: Specify Parameters for Data Source Window
(cont.) Part 262 Figure 23 Enter Destination Attributes Window .......................................................................... 63 Figure 24 Enter Database Connection Data Window (Oracle) ................................................... 63 Figure 25 Sample Generated DataDeploy Configuration File..................................................... 64 Figure 26 DAS............................................................................................................................. 93 Figure 27 DAS: Specify Parameters for DAS Setup Window ..................................................... 99 Figure 28 DAS Setup for Template Types Window .................................................................... 99 Figure 29 DAS Setup for Metadata Capture Window ............................................................... 100 Figure 30 Generation of Data Deployment Configuration Files ................................................ 102 Figure 31 Other DAS Setup Activities ....................................................................................... 103 Figure 32 How the Event Subsystem Works............................................................................. 105 Figure 33 Event Subsystem Configuration: Select Database Window ..................................... 106 Figure 34 Event Subsystem Configuration: Set Up Database Window .................................... 106 Figure 35 Warning Message ..................................................................................................... 107 Figure 36 Event Subsystem Configuration: Create Tables for Event Subsystem Repository WinDatabase Deployment for OpenDeploy Administration Guide
11
Figures
dow
Figure 37 Figure 38 Figure 39 Figure 40 Figure 41 Figure 42 Figure 43 Figure 44 Figure 45 Figure 46
107 Event Server Configuration: Start/Stop the Event Server Window ........................... 107 Using DAS ................................................................................................................ 112 Standalone Database Deployment ........................................................................... 126 Target-Side Database Deployment........................................................................... 129 Synchronized Database Deployment........................................................................ 130 Synchronized Database Fan-out Deployment .......................................................... 131 Sample Configuration File......................................................................................... 190 FormsPublisher Directory Structure .......................................................................... 220 Database Table Relationships Created by Sample dbschema.cfg File .................... 228 Using iwsyncdb to Create DataDeploy Configuration Files with Associated UDS .... 229
12
About This Book

This manual is a guide for configuring and running OpenDeploy to deploy structured content to a database within the OpenDeploy environment.
Intended Audience
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.
13
About This Book
Notation Conventions
This manual uses the following notation conventions: Table 1 Bold Notation Conventions
Definition and Usage
Convention
Text that appears in a GUI element such as, a menu item, button, or element of a dialog box, and command names are shown in bold. For example: Click Edit File in the Button Bar. Book titles appear in italics. Terms are italicized the first time they are introduced. Important information may be italicized for emphasis. Commands, command-line output, and file names are in monospace type. For example: The iwextattr command-line tool allows you to set and look up extended attributes on a file. Monospaced italics are used for command-line variables.For example:
iwckrole role user
Italic
Monospace
Monospaced italic
This means that you must replace role and user 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:
iwextattr -s project=proj1 //IWSERVER/default/main/dev/ WORKAREA/andre/products/index.html
Monospaced bold italic
Monospaced bold italic text is used to indicate a variable in user input. For example:
iwextattr -s project=projectname workareavpath
means that you must insert the values of projectname and workareavpath 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.
14
Notation Conventions
This guide also uses the following conventions: The term Windows indicates any supported version of the Microsoft Windows operating system, such as Windows NT or Windows 2000. Directory paths use UNIX conventions. These conventions mandate using forward slashes (/ ) in path names. (Windows systems use backward slashes.) The Windows convention is used when referring to a Windows-specific directory. For example:
UNIX: docroot/news/front.html Windows: docroot\news\front.html
15
About This Book
16
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.
NOTE
DataDeploy functionality is restricted by specific database imposed limitations. Please contact DB vendor for all such limitations.
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 DataDeploy Module Licensing section in the OpenDeploy Installation Guide for more information.
17
Chapter 1: Introduction
Required Database Privileges

OpenDeploy must have the following privileges when accessing a database: insert update delete create table create view query permissions
Invocation
DAS is invoked through TeamSite events using the Event Subsystem. See Chapter 4, Database Auto-Synchronization 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.
18
Usage
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. 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. FormsPublisher - 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. FormsPublisher 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.
19
Introductory Concepts
This section illustrates the relationship between XML and relational databases and how OpenDeploy bridges the two. An example is provided that introduces the following data deployment concepts: XML for defining structured content Database for storing structured content Mapping the XML representation to the database schema Deploying XML to the database
XML for Defining Structured Content

XML is a flexible text format for expressing content structure. The rules that govern the structure of a particular XML representation are typically defined in a DTD, which defines a hierarchy of elements. Each element may contain a list of attributes. For example, consider the use of metadata for describing a sales report. Metadata can help users easily find the report based on various search criteria. So, the first step is to define the structure of the metadata in a DTD, and to then capture the actual metadata for a particular report using XML. The DTD could be defined as follows:
<!ELEMENT metadata (descriptor+)> <!ATTLIST metadata title CDATA #REQUIRED> <!ELEMENT descriptor EMPTY> <!ATTLIST descriptor code CDATA #REQUIRED vocabulary CDATA #REQUIRED label CDATA #REQUIRED>
Essentially, our metadata element has a title attribute and contains one or more descriptor elements. Each descriptor element has a code, vocabulary and label attribute. The corresponding XML for our specific sales report might appear as follows:
<metadata title="Sales in Northern California"> <descriptor code="AG" vocabulary="Regions" label="Americas"/> <descriptor code="06" vocabulary="FIPS5-2" label="California"/> <descriptor code="A" vocabulary="Territory" label="West"/> </metadata>
20
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 2
Report
Metadata Table (md)

Symbol (primary key)
Sales in Northern California Sales in Northern California Sales in Northern California
AG 06 A
Table 3
Descriptor Table (desc)

Vocab Tag
Sym (foreign key)
AG 06 A
Regions FIPS5-2 Territory
Americas California West
The metadata table is the primary table and the descriptor table is its child table. The primary and foreign key columns are used for joining the two tables. For example, a search for all reports pertaining to Americas should return Sales in Northern California.
Mapping the XML Representation to the Database Schema

OpenDeploy deploys the deployment of XML-based content into relational databases. This requires a schema mapping that tells OpenDeploy how to write XML elements and attributes into the database tables.
21
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: Table 4 Mapping XML-based Attributes to the DB Tables md/report md/symbol (primary key) desc/sym (foreign key) desc/vocab desc/tag
This XML element/attribute maps to this table/column

metadata/title descriptor/code descriptor/code descriptor/vocabulary descriptor/label
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"
22
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> 23
<group name="metadata" table="md1" root-group="yes"> ... </group> <group name="descriptor" table="desc2" root-group="no"> ... </group> </dbschema> </database> </destinations> </deployment>
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.
24
Architectural Overview
Figure 1
Data Deployment Architecture
Source
A
TeamSite or LocalFile System
Invocation
CL TeamSi te Web Services Client
Destination
Data Deployment
B1
C1
XML XMLTuple Producer Tuple
Database
D1
Database Database Tuple Writer Tuple
XML XML Files Files
XML
Tup
JDB
RDBMS RDB
Tup Database
RDBMS RDB
B2
Deployment may go through an

D2
XM L T XML uple W riter
XML XML
JDB
Database Database Tuple Tuple Producer Producer
C2
XML-formatted Files
Tup
OpenDeploy Base
1. A data deployment is invoked (A) by a command line tool (CLT), a web services call, or though a TeamSite event. The actions that follow depend upon whether the source of the content is an XML-based file or a database table. 2. If the source of the content is an XML-based file in a TeamSite or local file system (B1), the XML Tuple Producer parses the XML file and generates a tuple based on this XML content. If the source of the content is a database table (B2), the Database Tuple Producer reads the table using the JDBC API and generates a tuple based on the tables contents. 3. Next, the tuple that was produced in step 2 is passed to one of the following: 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). XMLTupleWriter (C2) if the destination is an XML file. The tuple is then mapped into the XML format specified by OpenDeploy and is written into the destination XML file (D2).
25
Use Case Matrix

The following table illustrates the supported use cases for data deployments.A sample configuration for each source-destination combination is provided in Chapter 3, Configuration Files. Table 5
Source TeamSite Data Content Records (DCRs)
Supported Use Cases for Data Deployments

Destination Database Formatted XML*
TeamSite to Database (see page 66 for more information)
TeamSite to Formatted XML (see page 69 for more information) Metadata to Formatted XML (see page 72 for more information) Formatted XML to Formatted XML (see page 75 for more information)
Metadata to Database TeamSite Extended Attributes (Metadata) (see page 70 for more information)
Formatted XML*
Formatted XML to Database (see page 74 for more information)
XML
XML to Database (see page 74 XML to Formatted XML for more information) (see page 75 for more information) OpenDeploy and the DataDeploy module are not intended for database-to-database replication. Use the appropriate tool from your database vendor. Database to Formatted XML (see page 80 for more information)
Database
*Specific XML format defined by DataDeploy
26
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 Database Deployments section in the OpenDeploy Administration 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 DataDeploy Module Licensing section in the OpenDeploy Installation Guide for details about licensing the DataDeploy module. Table 6
Task
Migration Matrix
DataDeploy 5.6 OpenDeploy 6.0
Database DAS daemon is Auto-Synchroni configured for iwat zation (DAS). 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. See Chapter 4, Database Auto-Synchronization for more information. Use iwsyncdb -initial workareavpath [-nomdc] [dcrtype] command-line tool. Refer iwsyncdb section in the OpenDeploy Reference for more information. Use one of the following methods: Place legacy DataDeploy configuration in od-home/conf directory, and run it using OpenDeploy. Include reference to DataDeploy configuration file in OpenDeploy deployment configuration file using the dataDeploy element. See Standalone Database Deployments on page 126 for more information.
Initializing DAS Use iwsyncdb.ipl -initial tables.

workareavpath [-nomdc] [dcrtype]
command-line tool. Configuring standalone DataDeploy deployments. Configure DataDeploy deployment configuration file.
27
Table 6
Task
Migration Matrix
DataDeploy 5.6 OpenDeploy 6.0
Invoking standalone DataDeploy deployments.
Use iwdd.ipl or iwexecdascmd
Use iwodcmd start
-k iwdd=internal-deployment-name. See command-line tools. Invoking DataDeploy Deployments on page 28 for more information.
Three-tier mode Run a DataDeploy Run a base server or receiver on the target, deployments. daemon on the target with the databaseDeployment element host. enabled in the sending and receiving OpenDeploy server configuration files, and the dbLoader element included in the deployment configuration. Synchronized Deploy and Run OpenDeploy-Da (DNR)-based taDeploy solution. deployments. Deploying to wide tables. Supported. Synchronize deployments using the dbLoader element in the deployment configuration. See Synchronized Deployments on page 130 for more information. Wide table is supported, but it is recommended you migrate to UDS.
DataDeploy Administration User Interface

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

You can run your existing DataDeploy deployment configuration using one of the following methods: From the Start Deployment window in the browser-based user interface. You must include the following value:
iwdd=internal-deployment-name
in the Parameters text box, where internal-deployment-name refers to a named deployment element in the DataDeploy configuration file. Using the iwodcmd start command-line tool:
iwodcmd start OpenDeploy_configuration -k iwdd=internal-deployment-name
As a scheduled deployment configured either in the browser-based user interface, or from the command line using the iwodcmd schedadd command-line tool.
28
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 237 for more information.
Discontinued DataDeploy Commands and Scripts

The following DataDeploy command and scripts have been discontinued:
iwdd.ipl iwexecdascmd iwsyncdb.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 iwsyncdb.ipl has been discontinued, and has been replaced by the following scripts: Windows - iwsyncdb.bat UNIX - iwsyncdb.sh
29
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.
iwsyncdb.cfg
The following options have been deprecated from the iwsyndb.cfg configuration file:
ignoredcrtype ignorecategory vmoption
Running DataDeploy in Threadperbranch Mode

Refer to Determining the Runmode on page 239 in the OpenDeploy Administration 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. See Synchronized Deployments on page 130 for an overview of the new method.
30
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 237 in the OpenDeploy Administration Guide for more information. 2. Restart the OpenDeploy server. Refer to Starting OpenDeploy on page 47 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. 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 127 for more information.
31
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 158 for more information.
32
Chapter 2
Deployment Concepts
Appendix B, Database Deployment Tutorials contains a tutorial that will help you understand the basic concepts, configuration, and execution of database deployments. If you are new to database deployments using OpenDeploy, it is recommended to go through this tutorial. This chapter covers some basic deployment concepts that are useful to understand as you configure OpenDeploy for database deployments and execute deployments: Categories of deployments. Overview of database deployment process. Source/Destination configurations. Implementation of user-defined schemas. A sample deployment scenario that demonstrates update types, data sources, data organization and tuples, and the typical steps in a deployment sequence.
Categories of Deployments
There are three categories of deployments Database auto-synchronization (DAS) Standalone database deployments Synchronized deployments of files and data DAS deployments are deployments that are automatically synchronized with events in TeamSite. Tables representing TeamSite workareas and the staging area are created in the database. As files are created in the workarea or submitted to staging, events are generated to automatically invoke database deployments to read the files and deploy the contents into the database.
33
Chapter 2: Deployment Concepts
Standalone database deployments require installation of the licensed add-on module for DataDeploy. Standalone deployments allow you to deploy any files (not just TeamSite files). Standalone deployments are not triggered by any events. You invoke standalone deployments on-demand to deploy content. Synchronized deployment of files and data allow you to supplement OpenDeploy file deployments with database deployments. Specifically, after files are deployed from a source OpenDeploy server to a target OpenDeploy server, a database deployment can be invoked to further push content into a database.
Overview of Database Deployment Process

Database deployments are configured with XML-based files. The configuration file includes the data source, destination, and mapping of source to destination. Configuration files are described in detail in Chapter 3, Configuration Files. When OpenDeploy performs a database deployment, it reads and parses data from a source such as XML files and extended attributes, and deploys the content into the tables according to a mapping specified in the configuration file. When the data source is read, OpenDeploy translates the data source into tuples. A tuple is a set of key value pairs representing each data source (for example, a tuple is created for each XML file in the data source). OpenDeploy uses this tuple representation of the data to insert the data into the database. The key in the tuple is a representation of the location of a specific piece of data in the file and the value is the actual data. To illustrate this, if you have an XML file in your source as follows:
<emp> <name>John</name> <contact> <phone>555-11234</phone> </contact> </emp>
The tuple would contain an entry as follows to represent the data 'John' employee/0/name/ 0=John The configuration for the database deployment also specifies the destination, which is usually a database. A database destination is specified in the configuration file by specifying the target tables and columns. In addition, a mapping has to be specified to tell OpenDeploy how to map the data source to a table and column in the database. OpenDeploy uses the tuples and the database mapping to determine how and where to insert the data into the database. OpenDeploy also provides mechanisms such as filters, substitutions, and
34
Source/Destination Configurations
external manipulation techniques to make modifications on the data before it is deployed to the database.
Source/Destination Configurations
In the database deployment configuration file, you specify the source of the content to be deployed to the database. The source can be a database, XML file, and TeamSite extended attributes. The destination is usually a database. OpenDeploy has another option for source and destination referred to in this manual as Formatted XML. Formatted XML is a file that represents the tuple in an XML format. See Use Case Matrix on page 26 for more information on the various source/destination combinations.
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 49.
Overview
OpenDeploy has two deployment approaches for database deployments: wide table mapping and user-defined schemas (UDS). Wide table mapping is a legacy format used primarily when user-defined schema mapping was not available in OpenDeploy. It is highly recommend to use user-defined schemas. User-defined schemas refer to the process of creating a normalized table structure for deploying your content. Normalization is the process of logically breaking down a database's tables and schema into separate tables that are related through keys. Specifically, 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.
35
Advantages of normalization include: Relationships between tables are easier to understand. Tables are easier to query. Data integrity is better maintained through referential constraints. For users still using legacy wide table format, see Appendix C, UDS vs. Wide Table Mapping for more information. 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 FormsPublisher Developers Guide. Data can be deployed using user-defined database schemas manually or automatically using DAS. The example in the following section describes deployment using DAS. For more information on DAS, see Chapter 4, Database Auto-Synchronization.
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 189. 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 26 for all source-destination deployment combinations). Sample configuration files for these scenarios are provided and described briefly in Sample Configuration Files on page 66. 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.
36
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 tables associated base table should exist from a previous deployment). The relationship between the workarea data and the data in its parent area (a staging area or edition) is updated in the tracker table residing in the database. 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.
37
Data Sources
When you deploy data from TeamSite to a database, you can specify that it come from a TeamSite workarea, staging area, or edition. Of these three, workarea data is the only type that can be deployed using all of the three types of update (base, delta, or standalone). When deploying staging area or edition data, set update-type to base if you plan subsequent delta table generation, or set update-type to standalone if you do not need to track the tables relationship to other tables. The following table shows which data sources are supported for each type of update: Table 7 Data Sources
Update Type Base TeamSite Source Area Workarea Edition Delta Standalone
Supported Supported
Supported Not Supported Not Supported
Supported Supported Supported
Staging Area 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 databases organizational structure, or schema. OpenDeploy deploys data to databases using three different organizational structures: User-defined database schemas (which result in multiple tables when deployed to a database; any given data content record may be mapped to multiple tables). This is the preferred method. For more information about this option, see User-Defined Database Schemas on page 35. 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).
38
Tuple Metadata and State

All TeamSite tuples contain the following metadata: Exactly one path element, which is the area relative path name of the file associated with the tuples key-value pair(s). One or more key-value pairs. The key is the name of an attribute. For example, News-Section is the key of the extended attribute News-Section:Sports. The value is the data value for a tuples 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. In a delta table, the state is the tuples status as viewed in TeamSite area 1 (most often the staging area) relative to the tuple in TeamSite area 2 (most often a workarea). A delta table can have tuple states of Original, New, Modified, or NotPresent. The following table shows the scenarios that can cause these states: Table 8 Tuple State Causes
A delta table Was caused by: tuple state of:
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). Generating a new tuple through a delta update (such as when adding a new extended attribute to a file in a workarea). Updating a delta table through a delta update. Data existing in a base area but not in a workarea (such as when the data is deleted from the workarea, or when data is newly added to the base area from a different workarea).
New Modified NotPresent
NOTE
The tuples in standalone tables do not have a state.
39
Wide vs. Narrow Tuples

The following sections discuss wide tuples and narrow tuples and their role in the deployment process.
Wide Tuples
A wide tuple is an internal representation of all the data for the source element being deployed. By default, wide tuples deploy into wide tables when deployed to a database. Unlike narrow tuples, wide tuples can be deployed either manually or with DAS. Wide tuples contain exactly one path element and one state element, and any number of key-value pairs. Thus, a files extended attribute data can be represented in a single wide tuple even if the file has more than one extended attribute set. Figure 2 shows OpenDeploys internal representation of a wide tuple. Figure 2
Tuple 1 path = docroot/news/front.html News-Section = Sports Locale = SF state = Original
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 41. 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 3. Figure 3
Tuple 1
path = docroot/news/front.html News-Section = Sports Locale/0 = SF Locale/1 = Oakland state = Original
Wide Tuple with Similar Locale Keys
40
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 4) in which a single file record contains individual key value columns: Figure 4 Wide Tuple Default Base Table
News-Section=Sports, Locale/0=SF, Locale/1=Oakland
Key-Value List for

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

SF
State
docroot/news/front.html Sports
Oakland Original
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 5 shows OpenDeploys internal representation of two narrow tuples. Tuple 1 is for the News-Section:Sports extended attribute for the file docroot/news/front.html. Tuple 2 is for the Locale:SF extended attribute for the same file. Because a narrow tuple can contain only one key-value pair, DataDeploy must create multiple tuples (two in this case) if a files extended attributes consist of more than one key-value pair.
41
Figure 5
Tuple 1
Narrow Tuples
Tuple 2
path = docroot/news/front.html key = Locale value = SF state = Original
path = docroot/news/front.html key = News-Section value = Sports state = Original
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 6) in a database containing columns for Path, Key, Value, and State. Figure 6 Narrow Tuple Default Base Table
Key-Value List for
docroot/news/front.html: News-Section=Sports, Locale=SF
Tuple 1 (Narrow)
Tuple 2 (Narrow)
path = docroot/news/ front.html key = News-Section
path =docroot/news/ front.html key = Locale
Narrow Database Path Key Table: docroot/news/front.html News-Section

docroot/news/front.html Locale
Value
Sports SF
State
Original Original
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.
42
Deployment Sequence
The most common sequence of events when deploying in DAS mode from TeamSite to a database is as follows: 1. Generating an initial base table of a staging area or edition. 2. Generating a delta table for each workarea associated with the staging area or edition from step 1. 3. Configuring TeamSite to invoke OpenDeploy so that the base table from step 1 is automatically updated whenever changes have been submitted to its corresponding staging area or edition from a workarea. This section describes these steps, which are part of automated deployment through DAS.
Generating an Initial Base Table

Usually, the first action you instruct OpenDeploy to perform is the creation of an initial base table for a staging area or an edition. Figure 7 shows the creation of a base table BT1 from a staging area SA1 on a TeamSite branch such as /default/main/branch1. Figure 7
TeamSite
Generating an Initial Base Table

OpenDeploy Database
1
SA1 WA1 WA2 WA3
2
BT1 Tracker Table
Tracker Table
43
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. 2. Based on additional information in the configuration file, OpenDeploy creates base table BT1 in the destination database, populating it with the data from Step 1. 3. OpenDeploy creates the tracker table (or updates it if it already exists) to track relationships between base and delta tables
Generating a Delta Table

After creating the initial base table, you need to generate one or more delta tables based on the workareas associated with the base tables staging area. Figure 8 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 8 Generating a Delta Table
DataDeploy Database
TeamSite
SA1
1
WA1 WA2 WA3
3 2
BT1 DT1 DT2 DT3 Tracker 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.
44
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 9). 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 9 Updating a Base Table
Database BT1
5
TeamSite
DataDeploy
7
Workflo w or
SA1 WA
1 2
6
DT1 DT2 DT3

4
Tracker Table
WA WA
1a
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 9). If DAS is configured, OpenDeploy obtains the list of files to be submitted. 2. OpenDeploy compares the file list items in WA2 with the same items in SA1 to determine the tuple differences between the two areas. (These differences will be recorded in BT1 later in Step 5). 3. OpenDeploy checks the tracker table to determine the children of BT1. 4. Original rows from BT1 are propagated to DT1 and DT3 (but not to DT2). This ensures that the original rows in BT1 are not lost, but instead are stored as now-obsolete data in its child delta tables. 5. OpenDeploy updates BT1 with the data derived earlier in Step 2.
45
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 10. 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 10 Sample Table Updates
State 0 BT1 Path Key State 1 BT1 Path Key
P1 K1
Value State
Value State
V1 Orig
State 2 BT1 Path Key

P1 P2 K1 K2
Value State
V1 V2 Orig Orig
P1
K1
V1
Orig
DT1 Path Key
Value State
DT1 Path Key
Value State
DT1 Path Key

P2 K2
Value State
V2 NtPres
DT2 Path Key
Value State
DT2 Path Key P2 K2
Value State V2 New
DT2 Path Key
Value State
1. State 0: In their starting state, all tables are synchronized. Because there are no differences between SA1, WA1, and WA2, there is no delta data. Therefore, DT1 and DT2 are empty. 2. State 1: Workarea WA2 is changed locally with new data P2, K2, and V2, but the changes are not submitted to staging area SA1. Because the changes are not submitted, you must execute a delta update so that delta table DT2 reflects the new data in WA2. During this delta update, OpenDeploy identifies the differences between SA1 and WA2 and records these differences (the delta data) in DT2. In this scenario the delta tables already exist and therefore only need to be updated. 3. State 2: Workarea WA2 (complete with its changes from previous State 1) is submitted to staging area SA1. In the configuration file for this deployment, Path and Key were named as the basis-for-comparison columns. Therefore, OpenDeploy compares the State 1 values of these columns in BT1 and DT2, sees that they are different, and determines that the row
46
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. 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 45.
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 120 for more information. There are three ways that you can create table views: Through SQL commands that you execute manually to query the database after it is created. Through SQL commands named in the user-action attribute of the DataDeploy configuration files sql element. You run these commands by executing a SQL-specific deployment that you specify through the command line options iwdd-op=do-sql and user-op=anyname. By setting the table-view attribute in the DataDeploy configuration files database section. The following composite views (Figure 11) 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.
47
Figure 11 Composite Table Views

State 0 WA1 Path Key
P1 K1
Value State
V1 Orig

P1 K1
Value State
V1 Orig

P1 K1
Value State
V1 Orig
WA2 Path Key

P1 K1
Value State
V1 Orig
WA2 Path
P1 P2
Key
K1 K2
Value State
V1 V2 Orig New
WA2 Path
P1 P2
Key
K1 K2
Value State
V1 V2 Orig Orig
48
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. OpenDeploy contains many options for configuring database deployments, many of which are not described in this manual. Refer to Chapter 10, DataDeploy DTD in the OpenDeploy Reference for a full list of configurations and features.
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.
49
Chapter 3: Configuration Files
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.
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.
50
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 12). Figure 12 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)
51
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. 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 53. If you chose to edit an existing schema, the database connection screen is displayed. See Mapping to an Existing Database Schema on page 52.
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 51). Ensure that the Destination parameter is set to Existing Schema. 2. Click Create Map. The database connection screen (in this example, for Oracle) is displayed (Figure 13). Figure 13 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.
52
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 53.
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 51). Ensure that the Destination parameter is set to New Schema. 2. Click Create Map. The mapping screen is displayed (Figure 14). Figure 14 Map Data to a New Database Schema Window
C A B
53
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. 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 15) 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 15 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 16) contains the buttons and input boxes allowing you to specify how elements from the source file map to columns in the groups you create.
54
Figure 16 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 tables group and column names. To specify a group as the root table, select the Root Group of the Schema check box. 4. Create additional groups according to your needs: a. Enter a name for the group in the Group Name box, or copy an element from the data source to that box. b. Create columns by copying elements to the Item Name and Column Name fields as described in Process Flow on page 50 and specify the following: Column Name - The name of the column.
55
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. 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 17).
56
Figure 17 Display of the generated file
7. Save the dbschema.cfg file by clicking the Save button (located at the bottom of the main window). The Select File dialog is displayed. 8. Browse to the location where you want to save the file. Double click to browse directories. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt)
od-home/conf
directory (conf)
Single click to select files. 9. Click OK.
Updating an Existing Database Schema File

If you chose to work with existing tables, the Map Data Source to an Existing Schema window (Figure 18) 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:
57
Figure 18 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 121 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.
58
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. 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 section 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.
59
Validation of dbschema.cfg Files Using iwsyncdb -validate

You can perform validation of dbschema.cfg files for: A workareavpath or a particular data type under workareavpath. A file specified with a complete path name. Validating by Using workareavpath The syntax for performing validation of files in a workareavpath is as follows:
iwsyncdb -validate workareavpath [dcrtype]
This command validates the dbschema.cfg files for data types configured in iw-home/local/ config/templating.cfg under the specified workarea workareavpath. The optional dcrtype argument specifies that the iwsyncdb command will validate a single data types dbschema.cfg file (rather than all data types dbschema.cfg files under workareavpath). If a particular data type does not have a dbschema.cfg file, that type is skipped and no errors are generated. 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.
Creating the DataDeploy Configuration File

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 189. 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
60
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.
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 19). Figure 19 Configuration File: Specify Parameters for Data Source Window
2. Select the OpenDeploy server on which the DataDeploy configuration is being run from the Selected Server list. 3. Select TeamSite File System from the Area Type list if the data to be deployed resides in TeamSite. Otherwise, select the file system of the OpenDeploy server (the name of the each server appears in the list.) 4. Select Interwoven DCRs from the XML Data Type list if the deployment data conforms to the Interwoven DTD. Otherwise, select Custom Defined if the data conforms to a custom-defined DTD. 5. Click Next. A continuation of the previous window appears, depending on whether you selected a TeamSite file system (Figure 20) or an OpenDeploy server file system (Figure 21).
61
Figure 20 Specify Parameters for Data Source Window (cont.) (TeamSite)
Figure 21 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 localhost box. You can also click Browse and navigate to the location. The available locations for the vpath are the following: TeamSite mount point (Y: or /iwmnt)
od-home/conf
directory (conf)
7. Select whether the data to be deployed is located in a Directory, Filelist, or File from the Location list. 8. Click Next. A continuation of the previous window appears (Figure 22). Figure 22 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 Relative 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.
62
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. 12. The Enter Destination Attributes window appears (Figure 23). Figure 23 Enter Destination Attributes Window
13. Enter the dbschema.cfg file you want to use in the Dbschema file box, or click Browse and navigate to that location. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt)
od-home/conf
directory (conf)
If you saved a dbschema.cfg file during the current browser session through the Map Database section, the location of that file is displayed in the box. 14. Enter a name for the deployment in the Deployment name box. The default name is basearea. 15. Select the type of database from the Select database vendor list. 16. Click Next. The Enter Database Connection Data window (in this example, for Oracle) appears (Figure 24). Figure 24 Enter Database Connection Data Window (Oracle)
63
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 creating tables. 23. Click View Configuration File. The DataDeploy configuration file is displayed. Figure 25 is a sample file. Files generated from your input might look different: Figure 25 Sample Generated DataDeploy Configuration File
Modifications made to the file in this window cannot be saved. Modify the file through the previous steps, or through the TeamSite WebDesk interface. 24. Click Save to save the generated DataDeploy configuration file. 25. The Select File dialog box is displayed. Browse to the location where you want to save the file and click OK. The available locations for the path are the following: TeamSite mount point (Y: or /iwmnt)
od-home/conf
directory (conf)
After you have saved the DataDeploy configuration file you can click Deployment Setup to continue by executing a deployment.
64
Using the iwsyncdb -ddgen Command

TeamSite-to-database deployments that are deploying DCR files created in FormsPublisher can be configured with a DataDeploy configuration file autogenerated by the iwsyncdb -ddgen command. The syntax is as follows:
iwsyncdb -ddgen workareavpath dcrtype
where dcrtype provides data_category/data_type. This generates the following DataDeploy configuration file:
workareavpath/templatedata/data_category/data_type/data_type_dd.cfg.
Deploying Multiple XML-Formatted Files as a List of Filelists

In the DataDeploy configuration file you can specify multiple xml-formatted-files by using the filelist attribute in the xml-formatted-data element. In the following example:
<deployment name="basearea"> <source> <xml-formatted-data filelist="C:/temp/xmlfilelist.txt"/> </source> <destinations> ... </deployment> xmlfilelist.txt
is a text file containing a list of file paths where each path references a file containing xml formatted data.
xmlfilelist.txt: --------------c:/temp/xmldata1.dump.txt c:/temp/xmldata2.dump.txt xmldata1.dump.txt ----------------<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <xml-tuple-data version="2.0.0"> <data-tuple> <tuple-field name="Reviews/0"></tuple-field> <tuple-field name="Plot Summary">ps</tuple-field> <tuple-field name="ISBN">ABCDEF</tuple-field> <tuple-field name="Author">venkat</tuple-field> <tuple-field name="Cover Picture">pic4</tuple-field> 65
<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> <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>
Sample Configuration Files

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 189.
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> 66
</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"/> <column name="Cover_Picture" data-type="VARCHAR(255)" value-from-field="Cover Picture" allows-null="yes" is-url="no"/> <column name="Author" data-type="VARCHAR(40)" value-from-field="Author" allows-null="no" is-url="no"/> <column name="Publication_Date" data-type="DATETIME" value-from-field="Publication Date" data-format="yyyy-MM-dd" allows-null="no" is-url="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-from-field="ISBN" allows-null="no" is-url="no"/> <column name="Cover" data-type="CHAR(9)" value-from-field="Cover" allows-null="no" is-url="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no" is-url="no"/> <column name="Plot_Summary" data-type="VARCHAR(255)" value-from-field="Plot Summary" allows-null="yes" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> <key-column name="ISBN"/> </primary-key> </keys> </group> <group name="Reviewers" table="Reviewers" root-group="no"> 67
<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>
68
TeamSite to XML
The following file configures a typical deployment from a TeamSite DCR to an XML file. The xml-formatted-data tag has a single attribute, file, which specifies the absolute path and file name of the destination file. A destinations section can have any number of xml-formatted-data elements, or a combination of xml-formatted-data and database elements.
<data-deploy-configuration> <client> <deployment name="teamsite-to-xml"> <source> <teamsite-templating-records options="wide" area="/default/main/branch/WORKAREA/myworkarea"> <path name="templatedata/intranet/weather/data/w1"/> </teamsite-templating-records> </source> <destinations> <xml-formatted-data file="/tmp/ts2xml.out"> <fields> <field name="Announcement" element="Announcement"/> <field name="Day" element="Day"/> </fields> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
The XML file that results from invoking the above deployment:
<xml-tuple-data version="2.0.0"> <data-tuple> <tuple-field name="state">Original</tuple-field> <tuple-field name="path">templatedata\intranet\weather\data\a4 </tuple-field> <tuple-field name="Announcement">Its a hot and sunny day </tuple-field> <tuple-field name="Day">Monday</tuple-field> </data-tuple> </xml-tuple-data>
69
TeamSite Extended Attributes to Database

The following example illustrates a sample configuration file for deploying TeamSite extended attributes (metadata) to a database, using the user-defined database schema (UDS) feature. This example is applicable to the sample file for metadata capture, installed as:
IWHOME/local/config/datacapture.cfg.example <data-deploy-configuration> <data-deploy-elements filepath="/usr/local/od-home/etc/database.xml"/> <client> <deployment name="eauds"> <source>  <teamsite-extended-attributes options="wide" area="/default/main/branch1/WORKAREA/workarea1"> <path filelist="/tmp/fileswithea.lst"/> </teamsite-extended-attributes> </source> <destinations> <database use="sybase-sqlanywhere" update-type="standalone" state-field="state"> <dbschema> <group name="eauds_master" root-group="yes"> <attrmap> <column name="path" data-type="VARCHAR(255)" value-from-field="path" allows-null="no"/> <column name="state" data-type="VARCHAR(255)" value-from-field="state" allows-null="no"/> <column name="Title" data-type="VARCHAR(60)" value-from-field="TeamSite/Metadata/Title" allows-null="no"/> <column name="Description" data-type="VARCHAR(100)" value-from-field="TeamSite/Metadata/Description" allows-null="no"/> <column name="Type" data-type="VARCHAR(30)" value-from-field="TeamSite/Metadata/Type" allows-null="no"/> <column name="Category" data-type="VARCHAR(40)" value-from-field="TeamSite/Metadata/Category" allows-null="no"/> <column name="Languages" data-type="VARCHAR(60)" value-from-field="TeamSite/Metadata/Languages" allows-null="no"/> 70
<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"/> <column name="Keywords" data-type="VARCHAR(100)" value-from-field="TeamSite/Metadata/Keywords" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
NOTE
If you remove column elements that are mapped to path, you must set the delete-tracker attribute to yes in the database element.
For deletions to work correctly, one of the following conditions must be met: All group elements contain a column child element with its name attribute set to path and mapped to a path value. Only the root group contains a column element with a name attribute set to path and mapped to a path value. The delete-tracker attribute is set to yes in the database element. For example:
<database db="localhost:2638" user="DBA" password="SQL" vendor="sybase" update-type="standalone" delete-tracker="yes" state-field="state"> 71
TeamSite Extended Attributes to XML

The following file configures a typical deployment from TeamSite extended attributes (metadata) to an XML file. The xml-formatted-data tag has a single attribute, file, which specifies the absolute path and file name of the destination file. A destinations section can have any number of xml-formatted-data elements, or a combination of xml-formatted-data and database elements.
<data-deploy-configuration> <client> <deployment name="teamsite-to-xml"> <source>  <teamsite-extended-attributes options="full" area="/default/main/STAGING"> <path name="."/> </teamsite-extended-attributes> </source> <destinations> <xml-formatted-data file="/u/temp/someTable.xml"/> </destinations> </deployment> </client> </data-deploy-configuration>
The following sample file shows the default format of a typical XML destination file:
<xml-tuple-data version="2.0"> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">small</tuple-field> <tuple-field name="key">size</tuple-field> </data-tuple> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">blue</tuple-field> <tuple-field name="key">color</tuple-field> </data-tuple> </xml-tuple-data>
72
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)" 73
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> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
Formatted XML to Database

Formatted XML uses a specific XML format defined by DataDeploy. 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"/> 74
<field name="value" element="value"/> <field name="state" element="state"/> </fields> </xml-formatted-data> </source> <destinations> <database use="oracle8_db" table="TableFromXML"> <select> <column name="Path" value-from-field="path"/> <column name="KeyName" value-from-field="key"/> </select> <update> <column name="Value" value-from-field="value"/> <column name="State" value-from-field="state"/> </update> </database> </destinations> </deployment> </client> </data-deploy-configuration>
In this file, the field elements specify which attributes in the source XML file DataDeploy will use when building a tuple for each Path-Key-Value-State item in the file. The element attribute can name any valid element; it is not limited to naming just the path, key, value, or state elements shown here. Note that the xml-formatted-data element is used in this example and also in the 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 section in the OpenDeploy Reference guide.
Formatted XML to Formatted XML

Formatted XML uses a specific XML format defined by DataDeploy. 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.
<data-deploy-configuration> <client> <deployment name="xml-to-xml"> 75
<source>  <xml-formatted-data file="/u/iw/wcuan/billTable.xml" > <fields> <field name="path" element="path" /> <field name="key" element="key" /> <field name="value" element="value" /> <field name="state" element="state" /> </fields> </xml-formatted-data> </source> <substitution>         <field name="path" match="(.*)/WORKAREA/[^/]+/(.*)" replace="$1/STAGING/$2" /> <field name="path" match="EDITION/abcd" replace="/This/Special/Path"/> <field name="key" match="^BEFORE(.+)" replace="AFTER$1"/> </substitution> <destinations> <xml-formatted-data file="/u/temp/someTable.xml"/> </destinations> </deployment> </client> </data-deploy-configuration>
In this file, the field elements specify which attributes in the source XML file DataDeploy will use when building a tuple for each Path-Key-Value-State item in the file.
XML to Database
The following file configures a typical deployment from an XML file to a database:
<data-deploy-configuration> 76
<data-deploy-elements filepath="c:/Intewoven/OpenDeployNG/etc/database.xml/> <client> <deployment name="deployment1"> <source> <xml-source options="wide" area="E:/Interwoven/OpenDeployNG/conf/data" area-type="os-filesystem" xml-type="custom"> <path name="." visit-directory="deep"/> </xml-source> </source> <destinations> <database use="oracle-db" update-type="standalone" state-field="state" delete-tracker="yes" enforce-ri="no"> <dbschema> <group name="deptRecords" root-group="yes"> <attrmap> <column name="deptId" data-type="VARCHAR(250)" value-from-element="deptRecords/0/dept/0/deptId/0" allows-null="no" is-url="no"/> <column name="name" data-type="VARCHAR(250)" value-from-attribute="deptRecords/0/dept/0/ description/0/name" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="deptId"/> </primary-key> </keys> </group> <group name="employee" root-group="no"> <attrmap> <column name="name" data-type="VARCHAR(250)" 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(250)" value-from-attribute="deptRecords/0/employees/0/ employee/[0-5]/id" is-replicant="yes" allows-null="no" is-url="no"/>
77
<column name="deptId" data-type="VARCHAR(250)" 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> </database> </destinations> </deployment> </client> </data-deploy-configuration>
XML to Formatted XML

The following file configures a typical deployment from XML to a formatted XML
<data-deploy-configuration> <client> <deployment name="deployment1"> <source> <xml-source options="wide" area="E:/input" area-type="os-filesystem" xml-type="custom"> <path name="data" visit-directory="deep"/> </xml-source> </source> <destinations> <xml-formatted-data file="E:\files\data.out/> </destinations> </deployment> </client> </data-deploy-configuration>
78
In this example, the source and generated XML formatted output looks like the following: XML source:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE press-release SYSTEM "employee.dtd"> <deptRecords> <dept> <deptId>00101</deptId> <description name="Engineering"/> </dept> <employees> <employee name="Simson Garfinkel" id="345"/> <employee name="Art Vandalay" id="506"/> </employees> </deptRecords>
XML formatted output:

<xml-tuple-data version="2.0.0"> <data-tuple> <tuple-field name="state">Original</tuple-field> <tuple-field name="deptRecords/0/employees/0/ employee/1/name">Art Vandalay</tuple-field> <tuple-field name="deptRecords/0/employees/0/employee/0/ id">345</tuple-field> <tuple-field name="deptRecords/0/dept/0/ deptId/0">00101</tuple-field> <tuple-field name="deptRecords/0/dept/0/ description/0"></tuple-field> <tuple-field name="deptRecords/0/employees/0/ employee/1"></tuple-field> <tuple-field name="deptRecords/0/employees/0/ employee/0"></tuple-field> <tuple-field name="deptRecords/0/dept/0"></tuple-field> <tuple-field name="deptRecords/0/dept/0/description/0/ name">Engineering</tuple-field> <tuple-field name="deptRecords/0"></tuple-field> <tuple-field name="deptRecords/0/employees/0"> </tuple-field> <tuple-field name="deptRecords/0/employees/0/ employee/0/name">Simson Garfinkel</tuple-field> <tuple-field name="deptRecords/0/employees/0/ employee/1/id">506</tuple-field> <tuple-field name="path">.</tuple-field> </data-tuple> </xml-tuple-data>
79
Database to XML
This section describes extracting data tuples from single or multiple database tables and mapping to an XML file.
Extracting Data Tuples from a Single Table

The following file configures a deployment from a database to an XML file, including remapped field column tags:
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="tupleTable"> <fields> <field name="path" column="EPath"/> <field name="key" column="EKeyName"/> <field name="value" column="EValue"/> <field name="state" column="EState"/> </fields> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
The resulting XML output file is as follows:

<xml-tuple-data version="2.0"> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field> <tuple-field name="state">Original</tuple-field> <tuple-field name="value">small</tuple-field> <tuple-field name="key">size</tuple-field> </data-tuple> <data-tuple> <tuple-field name="path">mydir/f9</tuple-field>
80
<tuple-field name="state">Original</tuple-field> <tuple-field name="value">blue</tuple-field> <tuple-field name="key">color</tuple-field> </data-tuple> </xml-tuple-data>
Filtering
The previous implementation extracts all rows from the specified table and creates XML output for the required fields. The following implementation allows you to filter the rows to select from the specified table. Use the database elements where-clause attribute to filter table rows. To filter rows, set the where-clause attribute to a string value that specifies the row selection criteria.
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="tupleTable" vendor="oracle" where-clause="Epath='mypath.txt' AND Evalue like 'myvalue%'"> <fields> <field name="path"column="EPath"/> <field name="key"column="EKeyName"/> <field name="value"column="EValue"/> <field name="state"column="EState"/> </fields> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
In this example, DataDeploy executes the following query to extract data tuples:
SELECT * FROM TUPLETABLE WHERE Epath='mypath.txt' AND Evalue like 'myvalue%' 81
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.
Extracting Data Tuples from Multiple Tables

The previous examples show database-to-XML deployment implementations that only allow you to extract data tuples from a single table. The following implementation allows you to extract data tuples from multiple tables. This implementation uses the db-producer-query element as a subelement of database:
<data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <client> <deployment name="db-to-xml"> <source>   <database use="oracle8_db" table="not-used"> <db-producer-query> <![CDATA[ SELECT A.C1, A.C2, B.C3, B.C4 FROM TABLE1 A, TABLE2 B WHERE A.ID = B.ID AND A.ID = 10 ]]> </db-producer-query> </database> </source> <destinations> <xml-formatted-data file="/tmp/tupleTable.xml"> </xml-formatted-data> </destinations> </deployment> </client> </data-deploy-configuration>
82
Specifying Database Connection Properties
NOTES
To deploy tuples to an XML file, use the db-producer-query element to specify a complete SQL query statement that DataDeploy should use to extract data tuples. Ensure that the entire SQL select query is within a single CDATA node. If more than one CDATA node is specified under db-producer-query, DataDeploy will only use the first node. Use the where-clause attribute for the database element and the db-producer-query subelement inside the database element only if the database element is a subelement of the source element. If you specify the db-producer-query subelement, DataDeploy ignores the database elements table and where-clause attribute values. If you do not specify a where-clause attribute value and a db-producer-query subelement, DataDeploy will select all rows from the table specified in the database elements table attribute.
Specifying Database Connection Properties

Database connection parameters are specified in the database element of the deployment configuration file. In addition to the basic database connection parameters such as user and password, additional database connection parameters can be specified in a properties file. The path to the properties file is specified in the database elements properties-file attribute as shown in the following example:
<database name="oracle9i" db="host:1521:utf8db" user="username" password="password" properties-file="od-home/conf/additionalprops.txt" vendor="oracle"/>
The contents of the properties file is a set of name-value pairs, as shown in the following example:
prefetch=20 remarks=true batchvalue=25
If connection properties such as user and password are present in both the database element and the properties file, the values present in the properties file will be honored.
83
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".
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>
Invoking Deployment
After a DataDeploy deployment has been configured, it can be run in the following ways, similar to OpenDeploy deployments:
84
Deploying Metadata to UDS
"iwodcmd start" (or iwodstart) Admin UI ContentServices for OpenDeploy (web services call)
From the browser-based user interface. From the command line using the iwodcmd start command-line tool. Using ContentServices for OpenDeploy.
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

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. - used to track row deletions.
iwdeltracker
85
- 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:
iwov_idmaps
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. 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> 86
Tablespace Attribute Usage in CREATE TABLE Statements
</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>
Tablespace Attribute Usage in CREATE TABLE Statements

A tablespace attribute value will be used in CREATE TABLE statements only if that statement is generated by OpenDeploy. You can add a tablespace = option to the database element in a DataDeploy configuration file, however, if an overriding CREATE TABLE statement exists in the DataDeploy configuration file, specifying tablespace = in the database element has no effect. The default ddcfg.template and mdc_ddcfg.template files both have overriding CREATE TABLE statements, which means that adding the tablespace = option to the database element in those files will have no effect. Instead, edit the ddcfg.template and mdc_ddcfg.template files so that each overriding CREATE TABLE statement has IN tablespacename appended to it.
87
For example, by default one of the statements appears as follows:

CREATE TABLE \$mybasetable (Path VARCHAR(255) NOT NULL, iw_state VARCHAR(30),  $tabledef  CONSTRAINT \$mybasetable^_KEY PRIMARY KEY (Path) )
You should edit this file so that it appears as follows:

CREATE TABLE \$mybasetable (Path VARCHAR(255) NOT NULL, iw_state VARCHAR(30),  $tabledef  CONSTRAINT \$mybasetable^_KEY PRIMARY KEY (Path) IN mytablespace
Vendor-Specific Configuration File Settings

The following section details various attributes of the database and column elements that appear in your DataDeploy configuration file and any vendor-specific settings that apply to them.
88
Attributes of the database Element

The db Attribute
The syntax for the value of the database elements db attribute depends on the database vendor. Details are as follows. Syntax and example lines should all be on one line in the database configuration file. Table 9 Informix db Attributes
Syntax of db Attribute Example
Database/Driver
db="//host_name:port/ database_name:INFORMIXSERV ER= server_name"
db="// sys1.interwoven.c om:1357/ bank01:INFORMIXSE RVER= OL_sys1"
Oracle/JDBC thin
db="host_name:port:instanc db="host1:1357:db e_identifier" 1" db="bank01" (See Oracle documentation for details about configuring TNS names) db="(DESCRIPTION =(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = host1)(PORT = 1521)))(CONNECT_D ATA =(SERVICE_NAME = RAC.WORLD)))" db="sys1.interwov en. com:1357/bank01"
Oracle/JDBC OCI * db="database_tnsname"
Oracle/JDBC RAC db="(DESCRIPTION =(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port)))(CONNECT_DATA =(SERVICE_NAME = RAC Service Name)))"
Sybase ASE
db="host_name:port/ database_name"
Microsoft JDBC
db="host_name:port;databas db="localhost:143 e= 3; database_name" database=datadepl oy" db="host_name:port?databas db="localhost:143 e= 3? database_name" database=datadepl oy"
Microsoft SQL Server/ i-net UNA
89
Table 9
db Attributes (Continued)
Syntax of db Attribute Example
Database/Driver
IBM DB2 (UDB) MySQL
db="//host_name:port/ database_name" db="host_name:port/ database_name"
db="//host1:1357/ db1" db="myhostname:33 06/mydbname"
*Used by OpenDeploy if the use-oci attribute in the database section is set to "yes". Requires installation of the OCI client library on the system where the OpenDeploy base server is installed.
NOTE
For all database vendors, OpenDeploy supports deploying to case-insensitive databases only.
The vendor Attribute

The following settings are supported for the vendor attribute, which is required. Table 10 vendor Attributes
"microsoft-micros Specifies Microsoft SQL Server. Sets a default oft" max-id-length of 128. "microsoft-inetun Specifies Microsoft SQL Server using an i-net UNA a" driver. Sets a default max-id-length of 128. "oracle" Specifies an Oracle database. Sets a default
max-id-length of 30.
"ibm"
Specifies IBM DB2. Sets a default max-id-length of 18 for constraint names and 128 for table, column, and view names. Specifies Sybase ASE. Sets a default max-id-length of 30. Specifies an Informix database. Sets a default max-id-length of 18. Specifies MySQL. Sets a default max-id-length of 128.
"sybasease" "informix" "rdbms"
The table-view Attribute

Setting the table-view attribute to yes is incompatible with Sybase ASE and will result in an aborted deployment. The default value for this attribute is no, but setting it to yes with all other supported databases works correctly.
90
The use-oci Attribute

When the use-oci attribute is set to yes and the vendor attribute is set to oracle, OpenDeploy attempts to connect to the database server using the OCI driver. The following steps must be completed if you are using Oracle 9i: 1. Install Oracle client software (including OCI) 2. Set the ORACLE_HOME variable. 3. Set LD_LIBRARY_PATH (or the equivalent environment variable for your operating system) to $ORACLE_HOME/lib-the directory containing libocijdbc9.so and libocijdbc9_g.so (for Solaris) or ocijdbc9.dll (for Windows). 4. Back up the Oracle JDBC driver shipped with OpenDeploy, ojdbc14.jar, and replace it with the ojdbc14.jar file from your Oracle client installation. Set the attribute use-oci to "yes" and set the db attribute to a tnsname in the database element.
Attributes of the column Element

The data-format Attribute
On an Oracle database server, if the column elements data-type attribute is not DATE, DATETIME, or TIMESTAMP; the data-format attribute is ignored.
The db-datetime-format Attribute

This attribute specifies the format in which date and time stamp values are returned when executing a query. It is required only for Informix databases. If not set, the default is yyyy-MM-dd hh:mm:ss.S. For the following databases, set as specified: Informix: It should be set to the Informix equivalent of data-format attribute value. For example: if data-format is set to "MM-dd-yyyy" then db-datetime-format should be set to "%m-%d-%Y". Oracle: If specified, it should be the Oracle equivalent of the data-format attribute value. SQL Server: If specified, it should be the JDK equivalent of the default format in which SQL Server returns date values.
91
92
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 FormsPublisher UI. Creates, changes, or deletes a TeamSite branch, area, or file containing extended attributes through the TeamSite UI. Figure 26 shows the sequence of events associated with DAS. Figure 26 DAS TeamSite
DCR or EAs are modified TeamSite event server triggers OpenDeploy.
OpenDepl
OpenDeploy uses DAS synchronize TeamSite data with database.
database
TeamSite data is synchronized on the
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.
93
Chapter 4: Database Auto-Synchronization
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 FormsPublisher (if DCRs are to be deployed using DAS). If FormsPublisher 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 Running Multiple Instances of OpenDeploy section in the OpenDeploy Administration Guide for more information on this feature.
Configuration Files
The following table lists those file that control the operation of DAS. Note that in the od-home/ ddtemplate directory, there example files (containing the .example extension) for each of the configuration files listed in the following table. You can edit these files for your use, but you must remove the .example extension before use. Table 11 DAS Configuration Files
File
daemon.cfg
Location
od-home/etc
Description
Configuration file used by the OpenDeploy base server for start-up. You do not need to modify daemon.cfg before running DAS. However, you can optionally add allowed-hosts and bind tags to daemon.cfg to further control access to the database server. Specifies database connection parameters for different databases. See Editing database.xml on page 96.
database.xml
od-home/etc
or any user-defined location

94
Configuration Files
Table 11 DAS Configuration Files (Continued)

File Location Description
ddcfg.template od-home/ .example ddtemplate
Template for a database deployment configuration file used to deploy data to the wide table format. The .example file extension must be removed before using this file. 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 96 for more information. Template for a database deployment configuration file used to deploy data from custom DCRs to user-defined schemas. See Editing Deployment Configuration File Templates and drop.cfg on page 96 for more information. 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 96 before running DAS.
ddcfg_uds. template
od-home/ ddtemplate
ddcfg_uds. custom. template
od-home/ ddtemplate
drop.cfg
od-home/ ddsyncdb
iw.cfg
(installed with TeamSite)

mdc_ddcfg. template. example
(on UNIX)
Controls whether renaming, moving, or deleting files will trigger deployment. Also used to enable the Event Subsystem. See Editing iw.cfg on page 97 iw-home/etc for more information. (on Windows)
/etc od-home/ ddtemplate
Template for a database deployment configuration file use to deploy metadata to the wide table format. The .example file extension must be removed before using this file. Template for a database deployment configuration file use to deploy metadata to user-defined schemas.
databaseDeployment
mdc_ddcfg_uds. od-home/ template ddtemplate odbase.xml od-home/etc
element and its associated child elements and attributes. Controls name and port number for the OpenDeploy base server host, and the running mode. Refer Database Deployments section in the OpenDeploy Administration Guide for more information.
syntracker.cfg od-home/ ddsyncdb
Utility configuration file used by the OpenDeploy base server when dropping tables.
These files are installed automatically when you install OpenDeploy, with the exception of iw.cfg. These files must be edited as described in this section before you can configure DAS either through the browser-based user interface or manually with the iwsyncdb command. See the sections following the table for instructions about configuring these files and scripts with your site-specific information.
95
Editing database.xml
The database.xml file specifies database connection parameters for different databases. (See Database Configuration File on page 84 for more information). You must set the following attributes in each database element in database.xml:
name db user password vendor
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 (see Configuration Files on page 94 for a list of these) and the drop.cfg configuration file. If you use one of the template files located in the od-home/ddtemplate directory that includes the example extension, such as ddcfg.template.example or mdc_ddcfg.template.example, you must remove the .example extension from the file before use. 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.
96
Configuration Files
Editing iw.cfg
You must edit the iwserver section of /etc/iw.cfg as follows to support DAS recognition of TeamSite events. Table 12 TeamSite Events in iw.cfg
TeamSite Event
SyncDestroy SyncRevert RenameFSE SetEA DeleteEA
Setting in iw.cfg
log_syncdestroy=yes log_syncrevert=yes log_renamefse=yes log_setea=no log_deleteea=no
Once configured, DAS will support these events when they are initiated from the TeamSite user interface. Table 13 Description of TeamSite Events
TeamSite Event
CreateBranch CreateWorkarea DeleteEA
Description
A branch has been created. A workarea has been created. An extended attribute (EA) has been deleted from a file. A branch has been deleted. An edition has been deleted. A workarea has been deleted. A new edition has been published from the staging area A branch has been renamed. An FSE has been renamed. A workarea has been renamed An EA has been added to/modified on a file. A file or directory has been submitted. A file with EAs has been created. A file with EAs has been deleted. A file with EAs has been modified. A file with EAs has reverted to an earlier version. A file or directory has been updated.
97
DestroyBranch DestroyEdition DestroyWorkarea PublishStagingArea RenameBranch RenameFSE RenameWorkarea SetEA Submit SyncCreate SyncDestroy SyncModify SyncRevert
Update
Refer to your TeamSite documentation for more information on configuring iw.cfg.
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 156 in the OpenDeploy Administration 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 237 in the OpenDeploy Administration 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 27).
98
Configuring DAS in the User Interface
Figure 27 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. 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 FormsPublisher 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 28): Figure 28 DAS Setup for Template Types Window
99
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.
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 29): Figure 29 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:
100
Generates the dbschema.cfg file if DAS is set up. Generates configuration files for use by DAS. Submits the generated database deployment configuration files to the staging area and publishes an edition based on the updated staging area. Creates initial base and delta tables in the destination database for the updated TeamSite areas. The following subsections and diagrams explain these activities in detail.
Configuring DAS for a Workarea

To configure DAS for a specific workarea, run the following command:
od-home/bin/iwsyncdb -initial workarea_vpath
for deploying DCRs and EAs

od-home/bin/iwsyncdb -initial workarea_vpath teamsite/metadata
for deploying only EAs

od-home/bin/iwsyncdb -initial workarea_vpath category/dcrtype
for deploying only a specific DCR type. For workarea_vpath, specify the full vpath to the TeamSite workarea. For example, you would enter the following if the FormsPublisher 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 30 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.
101
Figure 30 Generation of Data Deployment Configuration Files

datacapture.cfg for data type X datacapture.cfg for data type Y datacapture.cfg for data type Z
2 1
deployment configuration file X_dd.cfg
Command Line iwsyncdb -initial
iwsyncdb command
deployment
deployment configuration file Y_dd.cfg deployment configuration file Z_dd.cfg
configuration files submitted Edition published
3
ddcfg_uds.template file
1. The iwsyncdb -initial command is executed from the command line. 2. The iwsyncdb script reads the datacapture.cfg file for each data type that exists in workarea_vpath specified in Step 1. For example, if the FormsPublisher directory in workarea_vpath contains the data types X, Y, and Z, iwsyncdb reads the datacapture.cfg file corresponding to each data type. Refer to the FormsPublisher Developers Guide for details about data types and the datacapture.cfg file. 3. The script uses ddcfg_uds.template as the base format of the deployment configuration files that it will generate for each data type. 4. Based on ddcfg_uds.template and the datacapture.cfg files for each data type, the script creates configuration files for each data type- X_dd.cfg, Y_dd.cfg, and Z_dd.cfg. These files configure a TeamSite-to-database deployment. The mdc_dd.cfg file is also created so that the OpenDeploy base server remains synchronized with other TeamSite features. 5. The newly generated database deployment configuration files are submitted to the staging area, and an edition based on the updated staging area is published.
NOTE
If iwsycndb succeeds in generating configuration files for the data types (data_type_dd.cfg), but fails to connect to your database, changes to database attributes in the ddcfg_uds.template file will not be propagated to the data_type_dd.cfg files. If this occurs, edit all data_type_dd.cfg files or use iwsyncdb -force to overwrite the data_type_dd.cfg files.
102
Other DAS Setup Activities

Figure 31 shows how the remaining DAS setup activities take place when the iwsyncdb command runs. Figure 31 Other DAS Setup Activities
TeamSite Event Subsystem TeamSite events registered as DataDeploy triggers daemon.cfg
OpenDeploy base
Command Line iwsyncdb -initial (continued) server startup information OpenDeploy Base Server
Reads daemon.cfg
for startup information Runs continuously Automatically deploys data when TeamSite trigger events occur
RDBM
1. The iwsyncdb command registers a default set of TeamSite events as triggers that will automatically initiate deployment. See DAS Triggers on page 117 for details about which events are registered as triggers. 2. The iwsyncdb command initiates DAS. 3. 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. 4. 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
103
branches, workareas, or files through the TeamSite UI, DAS automatically generates the necessary deployment configuration files and initial tables.
The Event Subsystem

NOTE
The OpenDeploy user interface cannot be used to configure the event server for TeamSite 6.5 or later. Please use the tools provided with TeamSite.
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. Figure 32 illustrates how the Event Subsystem works:
104
The Event Subsystem
Figure 32 How the Event Subsystem Works

Publishers TeamSite Server TeamSite Templating Message Service Interface Message Service Implementation Event Subsystem Subscribers
ProxyServlet
OpenDeploy (DAS)
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. To configure the Event Subsystem, follow these steps: 1. Select DAS > Event Server Configuration to display the Event Server Configuration: Select Database window (Figure 33).
105
Figure 33 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 34). Figure 34 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. 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 35):
106
The Event Subsystem
Figure 35 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 36). Figure 36 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. 6. Select DAS > Start/Stop Event Server to display the Event Server Configuration: Start/Stop the Event Server window (Figure 37). Figure 37 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 107
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 140).
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 2. Add the following line to the event_subsystem section, depending on the version of TeamSite you are using: Pre-TeamSite 6.5 - es_enable=true TeamSite 6.5 and later - ew_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. Uncomment the DatabaseConfiguration element.
108
The Event Subsystem
4. Configure the RdbmsDatabaseConfiguration element for use with your RDBMS. The RdbmsDatabaseConfiguration element contains the following attributes:
driver url
- class name of JDBC driver, used to access the database.
- JDBC URL. - RDBMS user name. - password associated with RDBMS user name.
user
password
- (optional) maximum number of active connections that can be allocated from the connection pool. Specify the value 0 for no limit. Default value is 10.
maxActive maxIdle - (optional) maximum number of connections that can sit idle in the connection pool, before connections are evicted. Default value is 10.
- (optional) minimum number of seconds that a connection may remain idle before it may be evicted. The default value of 0 disables eviction of idle connections. Must be used in conjunction with the evictionInterval attribute.
minIdleTime
- (optional) interval in seconds between checking idle connections for eviction. Idle connections are removed after the time specified by the minIdleTime attribute.
evictionInterval
The following sample shows the RdbmsDatabaseConfiguration element configured for use with an Oracle database:
<RdbmsDatabaseConfiguration driver="oracle.jdbc.driver.OracleDriver" url="jdbc:oracle:thin:@myhost:1521:dbsid" user="user1" password="abc123" maxActive="10" maxIdle="5" minIdleTime="1800" evictionInterval="3600"/>
5. Set the jdbc_classpath variable in the following file to the location of your database vendors JDBC driver:
iw-home/eventsubsystem/conf/eventsubsystem.properties
For example: Windows - jdbc_classpath=c:\\drivers\\oracle\\ojdbc14.jar or UNIX - jdbc_classpath=/var/drivers/oracle/lib/ojdbc14.jar 6. 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
109
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. 7. Start the Event Subsystem using one of the following methods, depending on your operating system: (Windows) Select Control Panel > Services > InterwovenEventSubsystem. (UNIX) Run the iw-home/private/bin/iweventsubd script. 8. 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 (depending on what release of TeamSite you are using) using your favorite text or XML editor: TeamSite 6.5 and earlier - iw-home/eventsubsystem/conf/jmsconfig.xml Post-TeamSite 6.5 - iw-home/eventsubsystem/conf/jmsconfignew.xml 2. Add a Datadeploy_History topic line in the AdministeredDestinations section:
<AdministeredTopic name="Datadeploy_History"/>
Your AdministeredDestinations section should look like the following:

<AdministeredDestinations> <AdministeredTopic name="TeamSite_User"/> <AdministeredTopic name="TeamSite_System"/> <AdministeredTopic name="TeamSite_Workflow"/> <AdministeredTopic name="Datadeploy_History"/> </AdministeredDestinations>
110
The Event Subsystem
NOTE
If you are using TeamSite 6.5 or earlier, the name attribute appears as topicName. 3. Stop and restart the Event Subsystem. 4. Stop and restart DAS.
Logging Options for Event Subsystem

You can change the logging level for the event subsystem by modifying the LoggerConfiguration elements logLevel attribute in the following configuration file (depending on which release of TeamSite you are using): TeamSite 6.5 and earlier - iw-home/eventsubsystem/conf/jmconfig.xml Post-TeamSite 6.5 - iw-home/eventsubsystem/conf/jmsconfignew.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 - designates error events that might still allow the application to continue running.
abort.
error 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. - (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.
debug
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
111
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 DAS Custom Reports section in the OpenDeploy Administration Guide for more information.
Using DAS
After DAS is configured, it is transparent to FormsPublisher 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 38 Using DAS
TeamSite
iwsyncdb
- End user activity results in TeamSite
- Receives and interprets data from TeamSite trigger event - Passes data to
2
OpenDeploy Determines which deployment configuration file to use Deploys data to database
RDBM
1. FormsPublisher end-user activity (that is, any activity shown in DAS Triggers on page 117) 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.
112
Using DAS
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. 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: Table 14 Table Update Example
Path State PressDate Headline Picture
. ..
113
When the initial delta table is created, it contains the same columns as the initial base table, in addition to values for each item: Table 15 Table Update Example (cont.)
Path State PressDate Headline Picture ...
mypath
New
4/17/03 New Candidate Enters Race
cand.gif ...
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: Table 16 Table Update Example (cont.)
mypath
New
4/17/03
New Candidate cand.gif ... Enters Race
Table 17 Table Update Example (cont.)

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
114
Using DAS
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.
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:
115
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.
Database Object Name Lengths

To overcome the maximum database object name length imposed by database servers, OpenDeploy builds a mapping table called IWOV_IDMAPS in the destination database. For each object name that exceeds the maximum length limit for the database, this mapping table establishes a relationship between the original object name and a generated name conforming to the databases object name length limits. The generated name is then used in place of the original object name in all database transactions. This implementation allows table names, column names, constraint names, and view names to contain any number of characters. Note that this table is also used for standalone deployments when object names exceed the maximum length. The IWOV_IDMAPS table contains the following three columns:
Type Longid Shortid
The Type column defines types as follows:

1: 2: 3: 4: Table name Column name View name Constraint name
The Longid column contains the entire character string for the object as it appears in the original source file. The Shortid column contains the generated name conforming to the databases object length limits. For example, a typical table might appear as follows: Table 18 Database Object Name Lengths
Type
2 1
Longid
Shortid
INFORMATION0_PRESENTATIONTITLE INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING
IWC_AA6A93A 7161 IWT_106342E 4D4C4
INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_ IWV_AEGF12D VIEW 4E
116
Using DAS
Table 18 Database Object Name Lengths

Type
4
Longid
Shortid
INTRANET_DEPTINFO__DATADPLYBRNCH_STAGING_ IWO_F023AF1 CONSTRAINT 290
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. 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. Table 19 DAS Triggers
TeamSite Event Delta Table Action Base Table Action
Create branch Create workarea Delete branch Delete workarea
None. Build delta tables. Delete delta tables. Delete delta tables.
Build empty base tables. None. Delete base tables. None. None. None. None.
Modify data content Update or insert a new row. record Add data content record Delete data content record Insert a new row. Insert or update the NOT-PRESENT row.
117
Table 19 DAS Triggers

Submit modified data 1. The Previous Staging row is Update the Staging content record propagated to all workareas except row. the submitting workarea. 2. Delete Previous Staging row from submitting workarea. 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. 1. The previous Staging row is propagated to all workareas except the submitting workarea. 2. Delete the previous Staging row from the submitting workarea. Rebuild the delta tables. 1. Delete old delta tables. 2. Regenerate new delta tables. None. Update the Staging row.
Submit deleted data content record
Update the Staging row.
Get latest (workarea) Rebuild the delta tables. Copy to (any area) Rename workarea Rename branch
None. None. None. 1. Delete old base tables. 2. Regenerate new base tables. None. None.
Rename directory Rename file
Regenerate delta tables. 1. Delete the row for the old file name. 2. Add a row for the new file name. 1. Delete the row for the old file name. 2. Add a row for the new file name.
Move file
None.
Delete file
If a row for the file exists in the base None. table, the row in the delta table is marked NOT-PRESENT. If no row existed in the base table, the row in the delta table is deleted. Insert or update the row. None.
Set metadata
118
Using DAS
Table 19 DAS Triggers

Revert
Use the data from the earlier version None. of the file (selected in the TeamSite graphical user interface) to update or insert a new row.
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 97. 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"
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.
119
Database Virtualization Views

DAS can create virtualization views for a workarea that are similar in behavior to TeamSite virtualization. When you query these views, if a file in a workarea is the same as the file in the staging area, the view retrieves the record corresponding to that file from the staging area or base tables. If a file in a workarea has been updated but not submitted to the staging area, then the database record for that particular file will be retrieved from the workarea or delta table. The virtualization view created by DAS is for a specific workarea. To enable the automatic creation of virtualization views by DAS, set the flag table-view attribute to yes in the deltagen deployment section of the database deployment configuration file for a specific data type type/type_dd.cfg. For example, internet/book/book_dd.cfg). The CREATE VIEW command in the following example is the default schema that executes when table-view is set to yes in the database deployment configuration files database element.
CREATE VIEW areaview AS SELECT * FROM stagingtable WHERE NOT EXISTS (SELECT * FROM WAtable WHERE WAtable.Path= stagingtable.Path ) UNION ALL SELECT * FROM WATable WHERE WATable.IW_State != 'NotPresent'
To query from the view:

SELECT path FROM areaview WHERE key = News-Section AND value = Sports
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
120
Using DAS
(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
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.
121
Enabling DAS Publishing

OpenDeploy and DataDeploy subscribe to a deprecated message topic called TeamSite_User. Publishing to this topic is disabled by default. To enable this, perform the following steps. Future releases of OpenDeploy use the new message topic Interwoven. If you are using DataDeploy, enable DAS by performing the following steps: 1. Stop the TeamSite services. 2. Make the following changes to the following file:
iw-home/httpd/webapps/eventsubsystem/WEB-INF/iw_bridge_cfg.xml
Add dasTopic="TeamSite_User" property to the iwovJMS tag. For example:

<iwovJMS classpath="_IW_HOME_/eventsubsystem/lib/ openjms-client-0.7.6.1.jar" initialContextFactory="org.exolab.jms.jndi. InitialContextFactory" url="tcp://localhost:3035/" factoryName="JmsTopicConnectionFactory" topic="Interwoven" dasTopic="TeamSite_User" expiryTimeInDays="4" waitTime="300000"> </iwovJMS>
Uncomment logFile tags with the name property value of "TeamSiteDASLog" and "TeamSiteClientDASLog". For example:
<logFile name="TeamSiteClientDASLog" baseLogName="_IW_LOG_DIR_/iwui/iwevents/TeamSiteClientEvents" stateFileName="_IW_HOME_/servletd/logs/iwclientDASproxy. properties" waitTime="30000" isDAS="true"/> <logFile name="TeamSiteDASLog" baseLogName="_IW_LOG_DIR_/iwevents/TeamsiteEvents" stateFileName="_IW_HOME_/servletd/logs/iwDASproxy.properties" waitTime="30000" isDAS="true"/>
3. Restart the TeamSite services. 4. The DAS enabling can be verified by looking into the messages_handles database table for the messages published for the DAS.
example: Pseudo Query:
122
DAS Out-of-Sync Conditions
Select * from message_handles where destinationId in (Select destinationId from destinations where name ='TeamSite_User')
DAS Out-of-Sync Conditions

The following scenarios are not supported by DAS and will cause out-of-sync conditions with the database: Scenario 1: Using the iwextattr command-line tool to add or delete extended attributes on a file if DAS is set up for extended attributes with wide tables. Scenario 2: Manipulating a data content record (for example, renaming, editing, moving, deleting, and so forth) from the command line or file system interface. Scenario 3: Shutting down the OpenDeploy and then performing any kind of extended attribute or file manipulation. In this situation, you must either restart OpenDeploy or perform a manual resynchronizing deployment, for example by running the following command at the prompt:
iwsyncdb -resyncwa iwsyncdb -resyncbr
or
Multibyte Characters in DAS Filters

When setting up DAS filters for TeamSite events, these filters cannot contain multibyte characters unless you have also installed TeamSite 5.5.2 Service Pack 2 or higher.
Increasing the Port Range on Linux to Accommodate Database Deployments

If you are planning to run database deployments or database auto-synchronization (DAS) on your Linux host, you should tune your hosts TCP/IP parameters first to increase the range of ports available to OpenDeploy. This tuning is required to accommodate the larger number of ports that are opened during these types of deployments.
123
To increase the port range: 1. Run following command at the prompt:

echo "8192 65535" > /proc/sys/net/ipv4/ip_local_port_range
2. Restart OpenDeploy, but do not reboot the host. If you reboot the host, the ip_local_port_range value will be set to default value and you will have to run the above command again in order to increase the number of ports available. 3. You can make these changes in port range permanent by modifying the sysctl.conf file, which resides in the /etc directory. Open this file using your favorite text editor and add the following line of code:
net.ipv4.ip_local_port_range = 8192 65535
4. Save and close this file, then reboot your host.
Tutorial
This manual includes a tutorial for configuring and using DAS. See Appendix B, Database Deployment Tutorials on page 199 for more information.
124
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 DataDeploy Module Licensing section 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 115). 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 before continuing with this chapter.
125
Chapter 5: DataDeploy Deployments
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 39 Standalone Database Deployment
structured content files Structured content files are deployed to relational database using JDBC
source
database
Figure 39 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 Database Deployments section in the OpenDeploy Administration Guide for more information.
126
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 60 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:
127
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.
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 directory.
/conf
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 Specifying an Alternate TeamSite Mount Point section in the OpenDeploy Administration Guide for more information.
Tutorial
This manual includes a tutorial for configuring and running standalone database deployments. See Appendix B, Database Deployment Tutorials for more information.
128
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 40 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 40 Target-Side Database Deployment
Structured content files are deployed to target
Structured content is deployed to database.
sourc
target
databas
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.
129
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 41 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 41 Synchronized Database Deployment
Code and content files are deployed to target. Structured content files are deployed to target source targe
XML content is deployed to
database
130
Synchronized deployments can deploy files to multiple OpenDeploy targets as a fan-out deployment (Figure 42). However, only one target can be specified for the receipt of data asset files that are to be written to a database. Figure 42 Synchronized Database Fan-out Deployment
Code and content files are deployed to targe Code and content files are deployed to Structure content files are deployed to target. source Code and content files are deployed to target target databas XML content is deployed to
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 licensed. Refer to DataDeploy Module Licensing section in the OpenDeploy Installation Guide for more information. The databaseDeployment element in the source base server configuration file (by default odbase.xml) must be enabled. Refer to Database Deployments section in the OpenDeploy Administration Guide for more information.
131
The deployment configuration must include the dbLoader element. This element references a database schema file, and also references the defined database element in the servers database configuration file (database.xml, see next section). See Deployment Configuration on page 132 for more information. The dnrProperties elements infoStreamFormat attribute value must be set to manifest. Refer to Specifying the Deployment Information Stream Format section in the OpenDeploy Administration Guide for more information.
Target Servers
The following tasks must be performed on each target OpenDeploy base server or receiver: The databaseDeployment element on the target OpenDeploy servers configuration file (by default odbase.xml or odrcvr.xml) must be enabled. Refer to Database Deployments section in the OpenDeploy Administration Guide for more information. The servers database configuration file (database.xml) must contain a defined database element corresponding to the database type being used. See Database Configuration File on page 84 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">
132
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: - the DCRs use the Interwoven style, as indicated by the dcr-type attribute having the value iwov in TeamSites templating.cfg file.
interwoven custom - the XML or DCR files are based on the user's custom-defined style, as indicated by the dcr-type attribute having the value xml in TeamSites templating.cfg file.
Refer to the TeamSite documentation for more information on configuring the templating.cfg file.
133
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> 134
</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> 135
</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
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.
136
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 section in the database configuration would look like:
<trigger> <fieldname prefix="Trig" /> 137
trigger
Chapter 6: Advanced Features
</trigger>
OpenDeploy examines each tuple for key-value pairs in which the key starts with the specified prefix value. If found, the value for that key is treated as a database trigger. OpenDeploy does not validate the value for a CREATE TRIGGER statements syntax and semantics. OpenDeploy looks for the trigger name and the table on which the trigger is being created. If a trigger exists with the same name on the same table, it is dropped and recreated. The following examples illustrate the configuration file for deploying a DCR field as a trigger, and the corresponding DCR file where the CREATE TRIGGER statement is specified:
<data-deploy-configuration> <data-deploy-elements filepath="od-home/etc/database.xml"/> <client> <deployment name="mydep2"> <exec-deployment use="basearea"/> </deployment> <deployment name="basearea"> <source> <teamsite-templating-records options="wide" area="/default/main/branch1/WORKAREA/wa"> <path name="templatedata/internet/book/data/book2" visit-directory="deep"/> </teamsite-templating-records> </source> <destinations>  <database use="oracledb" update-type="standalone"> <trigger> <fieldname prefix="Reviews/1/Review Reader E-Mail"/> </trigger> <dbschema> <group name="book" table="triggertest" root-group="yes"> <attrmap> <column name="IW_State" data-type="varchar(255)" value-from-field="state"/> <column name="MyPath" data-type="varchar(255)" value-from-field="path"/> <column name="Title" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Cover_Picture" data-type="VARCHAR(255)" value-from-field="Cover Picture" allows-null="yes" is-url="no"/> <column name="Author" data-type="VARCHAR(40)" value-from-field="Author" allows-null="no" 138
Deploying Data as Database Objects
is-url="no"/> ... </attrmap> <keys> <primary-key> <key-column name="Title"/> <key-column name="ISBN"/> </primary-key> </keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
DCR File:
<!DOCTYPE record SYSTEM "dcr4.5.dtd"> <record name="book2" type="content"><item name="Title"><value>patriot games</ value></item><item name="Cover Picture"><value>cvr.gif</value></item><item name="Author"><value>Tom Clancy</value></item><item name="Publication Date"><value>1999-01-01</value></item><item name="ISBN"><value>zcxcv1234</ value></item><item name="Cover"><value>Paperback</value></item><item name="Price"><value>44.99</value></item><item name="Plot Summary"><value>summary1</value></item><item name="Reviews"><value><item name="Review Reader"><value>John</value></item><item name="Review Reader E-Mail"><value>jj@aol.com</value></item><item name="Reader Comments"><value>comments</value></item></value><value><item name="Review Reader"><value>james</value></item><item name="Review Reader 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> 139
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.
Filters and Substitutions

This section details the setting up of both filters and substitutions. Note that you cannot use parameter substitutions in the match or replace attributes 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>
140
</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 one name/match attribute pair. When you deploy narrow tuples, name must be either key, value, path, or state. When you deploy wide tuples, name can be any be any field name that is valid in the source area. The match attribute names a targeted value for name. The following example shows the filtering of wide tuples for a TeamSite DCR:
Tuple:CITY=Boston STORE_NAME=CompanyA TeamSite/Templating/DCR/Type=databases/location state=Original, STORE/0/ID=9999 path=data/compa.txt
The following example shows a portion of a deployment configuration:

<data-deploy-configuration> <filter name="ClosedOffices"> <discard> <or> <field name="STORE/0/ID" match="9999"/> </or> </discard> </filter> <client> <deployment name="update"> ... </deployment> </client> ... </data-deploy-configuration>
141
A filter defined and located before the deployment section of the configuration file will be global. Global filters do not become active until they are called by the filter elements use attribute between the source and destinations sections of the configuration file. For a sample configuration file that displays the order of these sections, see Appendix A, Sample Configuration File on page 189. 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 100. The following is an example filter specified in daemon.cfg:
<filter name="DCRFilter"> <ignore> <type category-name="internet" name="yacht"/> <type category-name="internet" name="book"/> <category name="intranet"/> <category name="teamsite"/> </ignore> </filter>
The filter elements name attribute value is fixed as DCRFilter and should not be changed. A single instance of the ignore 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 ignore element. For example, the following type element entry results in the filtering of the DCR type internet/yacht:
<type category-name="internet" name="yacht"/>
142
Category Filters
You can filter an entire category by adding an instance of the category element. Specify the category as a value for the name attribute. For example, the following category element entry results in the filtering of the category intranet:
<category name="intranet"/>
As with DCR types, you can exclude multiple categories by adding an additional category element for each excluded category.
Using Regular Expressions for Filtering and Substitution

You can incorporate regular expressions in data filters and substitutions using the field elements name-pattern attribute. The name-pattern attribute value is a perl5 regular expression that can be matched against a group of tuples for filtering, or to replace character strings or entire fields for substitutions. Use this feature as an alternative to listing a separate name attribute for each item to want matched. The following example shows how the name-pattern attribute regular expression is used for filtering.
<filter name="regexfilter"> <discard> <or> <field name-pattern="Reviews/.*/Review Reader" match="b1r1"/> </or> </discard> </filter>
In this example, those tuples included in the regular expression Reviews/.*/Review Reader are matched to the value b1r1 and discarded. The following example shows how the name-pattern attribute regular expression is used for substitution.
<substitution name="GlobalSubstitution"> <field name-pattern="Reviews/.*/Review Reader" match="b1r1" replace="Reviwer0"/> </substitution>
Here, like with the filtering example, the name-pattern attribute regular expression retrieves a group of strings or fields. Those that match the value b1r1 are replaced by the value Reviwer0.
143
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.
144
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).
- 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.
<in> <notin> <notin>
- Used to create a list-based criterion for events that are to be excluded. Do not use 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 not use <notin> in a <discard> section; use <like> there instead.
are to be excluded. Do
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%')
145
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.
146
Setting Up Substitutions
Substitutions let you configure OpenDeploy to automatically replace character strings or entire fields in a table. A substitution can be set up to apply globally, to specific parts of a deployment (in-flow), or to a parameter string.
Global Substitutions
A substitution defined and located before the deployment section of the configuration file will be global. Global substitutions do not become active until they are called by the substitution elements use attribute between the source and destinations sections of the configuration file. For a sample configuration file that displays the order of these sections, see Appendix A, Sample Configuration File on page 189. 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 a tuple field. 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: Table 20 Global Substitutions
To do this: Include this line in the Substitution section:
<field name="value" replace="Newvalue"/> <field name="path" match="blue" replace="red"/> <field name="path" match="blue" replace="red" global="yes"/> <field name="key" match="Original" replace="NotPresent"/>
Replace all Value field values with the string Newvalue In the Path field, replace first occurrence of blue with red In the Path field, replace all occurrences of blue with red In the State field, replace the first occurrence of Original with NotPresent
The following is a sample substitution. It can be used by any deployment. It replaces the first occurrence of the string fun in the path field with bar, and completely replaces the value field with the string SpecialValue.
<substitution name="GlobalSubstitution"> <field name="path" match="fun" replace="bar"/> <field name="value" replace="SpecialValue"/> </substitution>
147
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>
148
Deploying Replicants
Parameter Substitutions
Any parameter string in a configuration file can be named using a parameter substitution. Syntax is as follows:
"varname=varvalue"
After a string is defined on the command line, all occurrences of $varname in the configuration file named on the command line are substituted with the string varvalue. Do not use the following terms for varname:
cfg deployment iwdd-op remote-host remote-port
Examples of parameter substitution within a configuration file are as follows:

prefix_string_$varname $varname^_suffix_string prefix_$varname^_suffix
(where ^ is a concatenator)
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.
149
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.
150
Non-Replicant Values
Assume that a DCR created from the following DCT is to be deployed. Note that a comma separated list of reviewers can be entered for the Reviewers item.
<data-capture-requirements type="content" name="book">  <ruleset name="Book Information"> <description> This allows for the entry of details relating to a book. </description> <item name="Title"> <database data-type="VARCHAR(100)"/> <text required="t" maxlength="100"/> </item> <item name="Author"> <database data-type="VARCHAR(40)"/> <text required="t" maxlength="40"/> </item> <item name="ISBN"> <database data-type="VARCHAR(20)"/> <text required="t" maxlength="20"/> </item> <item name="Price"> <description>dollars and cents</description> <database data-type="REAL"/> <text required="t" maxlength="7" validation-regex="^[0-9]+\.[0-9]{2}$"/>  </item> <item name="Reviewers"> <description>Reviewer names separated by comma</description> <database data-type="VARCHAR(255)"/> <text required="t" maxlength="255"/> </item> </ruleset> </data-capture-requirements>
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=" 151
Title" allows-null="no"/> <column name="Author" data-type="VARCHAR(40)" value-fromfield=" Author" allows-null="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-fromfield=" ISBN" allows-null="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no"/> <column name="Reviewers" data-type="VARCHAR(255)" valuefromfield="Reviewers" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> </dbschema>
DCRs created and deployed by using the preceding DCT and associated database schema would create a single table in the database as follows: Table 21 Non-Replicant Values
Title Author ISBN Price Reviewers
Interwoven
Author1
12345
100.00
R1,R2,R3,R4
To deploy the same data such that the comma separated list of reviewers is stored in a separate table as replicant values, modify the database schema as follows:
<dbschema> <group name="book" root-group="yes"> <attrmap> <column name="Title" data-type="VARCHAR(100)" value-fromfield=" Title" allows-null="no"/> <column name="Author" data-type="VARCHAR(40)" value-fromfield=" Author" allows-null="no"/> <column name="ISBN" data-type="VARCHAR(20)" value-fromfield=" ISBN" allows-null="no"/> <column name="Price" data-type="REAL" value-from-field="Price" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Title"/> </primary-key> </keys> </group> 152
<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: Table 22 Non-Replicant Values (cont.)
Title Author ISBN Price
Interwoven
Author1
12345
100.00
Table 23 Non-Replicant Values (cont.)

Title Reviewers
Interwoven Interwoven Interwoven Interwoven
R1 R2 R3 R4
153
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.
<data-capture-requirements type="content" name="book">  <ruleset name="Book Information"> <description> This allows for the entry of details relating to a book. </description> <item name="Title"> <database data-type="VARCHAR(100)"/> <text required="t" maxlength="100"/> </item> <item name="Author"> <database data-type="VARCHAR(40)"/> <text required="t" maxlength="40"/> </item> <item name="Publication Date"> <description>date format is YYYY-MM-DD</description> <database data-type="DATE" data-format="yyyy-MM-dd"/> <text required="t" maxlength="10" validation-regex="^[0-9][09][0-9][0-9]-[0-1][0-9]-[0-3][0-9]$" /> </item> <item name="ISBN"> <database data-type="VARCHAR(20)"/> <text required="t" maxlength="20"/> </item> <item name="Cover"> <database data-type="CHAR(9)"/> <radio required="t"> <option selected="t" value="Paperback" label="Paperback"/> <option value="Hardback" label="Hardback"/> </radio> </item> <item name="Price"> <description>dollars and cents</description> <database data-type="REAL"/> <text required="t" maxlength="7" validation-regex="^[0-9]+\.[0-9]{2}$"/> </item> <item name="Plot Summary"> 154
<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" /> 155
</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. 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: Table 24 Replicant Values
Title_in_review Reviewer Reviewer_Expertise
Java Message Service Java Message Service Java Message Service Java Message Service
Reviewer 1 Reviewer 1 Reviewer 2 Reviewer 2
Java Assembly C++ Java
Additionally, the following rules for mapping must be followed: 1. The virtual field specified for a column that maps list fields should have a similar node structure if the table contains columns mapped to replicants. For example:
<column name="Title_in_review" data-type="VARCHAR(100)" value-from-field="Title" allows-null="no" is-url="no"/> <column name="Reviewers" data-type="VARCHAR(255)" value-from-field="Reviews/[0-4]/Review Reader" allows-null="no" is-url="no" is-replicant="yes"/> <column name="Reviewer_Expertise" data-type="VARCHAR(255)" list-to-replicant="yes" value-from-field="Reviews/[0-4]/Selectlist/[0-5]/selectval" list-field="Reviews/[0-4]/Select_expertise" is-replicant="yes" allows-null="no" is-url="no"/>
The Reviewer_Expertise column maps the replicant Reviews/[0-4]/Select_expertise, which is a comma separated list. The column Reviewers maps a regular replicant item. The value-from-field attribute for the
156
Reviewer_Expertise column should have the same root node structure and with Reviewers/[0-4], which is the same as the mapping for Reviewers.
thus it starts
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
Deploying Multiple Replicants from Multiple Nesting Levels

OpenDeploy can deploy multiple replicants from multiple nesting levels which are mapped to the same table, without custom code having to be written. However, the following rules need to be followed: 1. When multiple replicants from any level are mapped to the same table, they must have the same maximum occurrence count.For example:
"Treatment List/[0-5]/Treatment", "Prognosis List/[0-5]/Prognosis"
where Treatment and Prognosis each have a maximum occurrence count of 0-5. 2. When multiple replicants from a level that is not the innermost level are mapped to the same table, multiple child replicants cannot be mapped to the same table unless its parent replicants are also mapped.
Performance Enhancement for Deploying Heavily Nested DCRs

DataDeploy builds and traverses data tree structures to compute the number of rows it needs to process for tables that map nested elements in DCRs. To speed this process, DataDeploy can be configured to serialize (cache in a file) the Java objects produced by such tree traversing, and to read in those objects during actual deployments. When this feature is enabled, DataDeploy builds the serialized Java objects in row maps (contained in a row map cache file) for those group elements in the dbschema definition that contain replicants from various nested levels which are mapped to table columns.
157
To use this feature, first generate the row-map-cache file using the iwsyncdb tool using the following syntax:
iwsyncdb -rowmapgen configfile deployment outfile
where the following variables apply:

configfile
- the name of the DataDeploy configuration file
deployment - the deployment within the DataDeploy configuration with the schema mapping to generate the row map for. outfile
- the user-specified output file where the row map should be written to.
For example:
iwsyncdb -rowmapgen c:\Interwoven\OpenDeploy\conf\dd.xml base c:\files\rowmap.txt
After creating this row map file, you need to reference it in your DataDeploy configuration through the row-map-cache-file attribute of the database element as follows:
<database name="mydb" row-map-cache-file="c:\files\rowmap.rxt"
When executing deployments that contain DCRs which have replicants from various levels of nesting, DataDeploy checks whether the row-map-cache-file attribute is specified. If it is, the serialized Java objects are read from the row map cache file. If an error occurs while reading the row map cache file, or if no file is specified in the row-map-cache-file attribute, DataDeploy builds the data structures. In DAS mode, DataDeploy stores the most recently used row map cache file in memory. The row map file contains serialized Java objects. To deserialize this file, execute the following:
iwsyncdb -row-map-text path-to-row-map-cache-file [path-to-row-map-text-file]
where path-to-row-map-cache-file is the row map cache file generated earlier. The optional argument path-to-row-map-text-file specifies the file where the output should be written to. If no file is given, the output will be written to standard out.
Enhancing Deployment Data

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.
158
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 section in 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
The Java interface definition for this callout is displayed here:

import java.util.Hashtable; /* IWExternalTupleProcessor
Java interface definition that user implements to augument/supplement/ instrument a data tuple object, before it gets deployed by DataDeploy. User must implement PreProcessTuple method. */
public interface IWExternalTupleProcessor { /* Property name to obtain the name of the deployment for which the tuple preprocessor method is being called by DataDeploy. This property exists in the cmdLineParams Properties object passed to the PreProcessTuple() method by DataDeploy, when the interface-version is set to 2.0 in the <external-tuple-processor> tag. */ public static final String kCurrentDeploymentName = "IWCurrentDeploymentName";
159
/* PreProcessTuple The only method in the interface. DataDeploy supplies the data tuple in the form of a Hashtable object (keys being the field names). User can modify the tuple (adding, modifying deleting key-value pairs) and then return the modified tuple object back to DataDeploy. area: Points to the "area" attribute value if the tuple was produced by either <teamsite-templating-records> or <teamsite-extendedattributes> source. null otherwise. basearea: Points to the "basearea" attribute value if the tuple was produced by either <teamsite-templating-records> or <teamsiteextended-attributes> source when a differential extraction type is specified. null otherwise. The following method is called by DataDeploy when the 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 interfaceversion 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 cmdLineParams.getProperty("mytable"). standalone deployment, call */ public Hashtable PreProcessTuple(Hashtable tuple, String area, String basearea, Properties cmdLineParams); }
160
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 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){
161
String deploymentName = cmdLineParams.getProperty( IWExternalTupleProcessor.kCurrentDeploymentName); System.out.println("PreProcessTuple() method called for " + "Deployment [" + deploymentName + "]."); } return ProcessTuple(input); }
private Hashtable ProcessTuple(Hashtable input) { // the input tuple contains path to the file, it's state value // and other user set extended attributes, in this example it would // be the book_id value // get the book_id value String book_id = (String) input.get("book_id"); // once we get the book_id, go to the database and retrieve the // related information. I am not typing the full code here for // retrieving the related information. // let's just assume that the related information we retrieved // has author, ISBN, price single-valued attributes. we add them // to the tuple here input.put("author","venkat"); input.put("ISBN", "12345"); input.put("price", "123.33"); // also assume that the related information has repeating-value // attributes reviewers and reviewer-email. let's assume we have // five reviewers and their email addresses to be added to the tuple // see the associated dd config file how these fields are mapped // to database table columns for (int i = 0; i < 5; i++){ input.put("Reviews/"+i+"/Name","reviewer"+i); input.put("Reviews/"+i+"/EMail","reviewer_email"+i); } return input; } }
This sample demonstrates how a user-written Java class can supplement data that would be deployed using DataDeploy. It assumes that you created a document in the TeamSite file system and set metadata on the file. The only Extended Attribute set on the document is called book_id.
162
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>
163
<destinations> <database db="localhost:1521:oracledb" user="user" password="password" vendor="oracle" update-type="standalone"> <dbschema> <group name="book_master" root-group="yes" table="book_master"> <attrmap> <column name="path" data-type="varchar(255)" value-from-field="path" allows-null="no"/> <column name="author" data-type="varchar(255)" value-from-field="author" allows-null="no"/> <column name="ISBN" data-type="varchar(255)" value-from-field="ISBN" allows-null="no"/> <column name="book_id" data-type="varchar(255)" value-from-field="book_id" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="book_id"/> </primary-key> </keys> </group> <group name="book_detail" root-group="no" table="book_detail"> <attrmap> <column name="book_id" data-type="varchar(255)" value-from-field="book_id" allows-null="no"/> <column name="Reviewer_name" data-type="varchar(255)" value-from-field="Reviews/[0-4]/Name" allows-null="no" is-replicant="yes"/> <column name="Reviewer_Email" data-type="varchar(255)" value-from-field="Reviews/[0-4]/EMail" allows-null="no" is-replicant="yes"/> </attrmap> <keys> <primary-key> <key-column name="book_id"/> <key-column name="Reviewer_name"/> </primary-key> <foreign-key parent-group="book_master"> <column-pair parent-column="book_id" child-column="book_id"/> </foreign-key> 164
</keys> </group> </dbschema> </database> </destinations> </deployment> </client> </data-deploy-configuration>
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. During this phase od-home/lib/ddcombo.jar must be included in the CLASSPATH of the compile line. 3. Package your Java class files into a .jar file, and place it in the following directory:
4. Create the DataDeploy configuration file. 5. Specify the external-tuple-processor element and the value of the class-name 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

<external-tuple-processor class-name="com.interwoven.datadeploy. myclassname" interface-version="2.0"/>
follows:
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 class-name="com.interwoven. datadeploy.myclassname" exec-sequence="before-stages"/> 165
If you want OpenDeploy to invoke the TuplePreProcessor class after substitutions and filters are executed, specify the exec-sequence attribute as:
<external-tuple-processor class-name="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.
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 section in 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. A column that is specified as a replicant (using the attribute setting is-replicant="yes"), cannot be used with this feature. 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;
166
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 source Parameters: conn - database connection. This is not the same connection that DataDeploy uses to perform the deployment. tableName - name of the table that has the column to contain externally generated value columnName - name of the column for which value is to be generated by the external source opCode - indicates type of operation that will be performed by DD on the table 1 - insert 2 - update 3 - delete 4 - query (SELECT) tuple - hashtable that contains the values for other columns. column name is the lookup key. isReplicant - true if the column for which value requested is mapped to a replicant field - false otherwise 167
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. */ }
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.
168
2. Compile the Java class and unit test it. During this phase od-home/lib/ddcombo.jar must be included in the CLASSPATH of the compile line. 3. Package your Java class files into a .jar file, and place it in the following directory:
4. Add a column element that defines the column for the dynamic (or external) value to one of the following files: The DataDeploy configuration file that will be used for deployments. The dbschema.cfg file if you want to use External Data Source with deployments that use UDS. Using the following example External Data Source interface, such a column element would look like this:
<column name="column1" data-type="VARCHAR(100)" value-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.
169
You must have od-home/lib/ddcombo.jar file in the CLASSPATH or it must be specified in the -classpath argument to javac.
package com.interwoven.datadeploy.sample;
//import the Interface definition for the Java Callout import com.interwoven.dd100.dd.IWExternalDataSource; //import other stuff needed import java.sql.*; import java.util.*;
public class IWDataDeploySample implements com.interwoven.dd100.dd.IWExternalDataSource { // we will use a random generator to generate unique values // for each DCR //that gets deployed private static Random fRandom = null; // we will use a hashtable to store the values with // 'tableName' value as the key // and TableData object as the value private static Hashtable fValues = null; //Constructor public IWDataDeploySample() { //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; } 170
/* 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){ 171
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); 172
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 = 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;
173
/* 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); } } }
174
Deploying URL Content

You can deploy content pointed to from a URL in the following scenarios: When DCRs and TeamSite metadata are deployed in standalone or DAS mode with user-defined schemas. When custom DCRs are deployed in standalone or DAS mode with user-defined schemas. When DCRs and TeamSite metadata are deployed in wide table format. The column element supports the use of these attributes to enable deployment of content that is pointed to by a URL:
is-urlvalid
values are yes and no. values are any DCR element or metadata.
value-from-fieldvalid valuevalid
values are URLs that contain a file: or http: prefix. value is encoding method, such as UTF-8.
url-content-encodingvalid
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.
175
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"/>
176
Miscellaneous Advanced Features

This section details various other advanced features that are supported by OpenDeploy.
Deploying Custom Data Content Records

You can deploy DCRs based on custom DTDs into user-defined database schemas. Custom DCRs cannot be deployed using the wide table format, however. The following attributes in the DataDeploy configuration file enable this feature: The custom attribute for the teamsite-templating-records element. To deploy custom DCRs, you must set the value of that attribute to "yes". The value-from-element and value-from-attribute attributes for the column element. These attributes allow you to specify whether a column maps to an element (node) or an attribute of the node. For example, assume that the following data from a custom DCR is to be deployed to a user-defined database schema:
<press-release> <head> <title>title1</title> <byline author="Chris" location="location1"/> </head> <body> <heading>heading1</heading> <paragraph>para1></paragraph> </body> </press-release>
To map an elements value to a column (for example, the value for title), the column element in the DataDeploy configuration file would look like this:
<column name="title" data-type="VARCHAR(100)" value-from-element="press-release/0/head/0/title/0"/>
To map the value of an elements named attribute to a column (for example, the value for the author attribute), the column element in the DataDeploy configuration file would look like this:
<column name="author" data-type="VARCHAR(100)" value-from-attribute="press-release/0/head/0/byline/0/author"/>
Note the /o/ succeeding each element name. Those are instance indicators that specify which instance of the nodes value or attribute is mapped. You must specify the maximum number of
177
instances (replicants) for a given node element. Arbitrarily large values can be specified when the maximum number of replicants allowed is unknown. 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 FormsPublisher would look like:
<dbschema> <group name="pr_master" table="pr_master" root-group="yes"> <attrmap> <column name="Path" data-type="varchar(255)" value-from-field="path"/> <column name="state" data-type="varchar(25)" value-from-field="state"/> <column name="title" data-type="varchar(100)" value-from-element="press-release/0/head/0/title/0"/> <column name="author" data-type="varchar(100)" value-from-attribute="press-release/0/head/0/byline/0/ author"/> <column name="location" data-type="varchar(15)" value-from-attribute="press-release/0/head/0/byline/0/ location"/> </attrmap> <keys> <primary-key> <key-column name="title"/> </primary-key> </keys> </group> <group name="pr_body" table="pr_body"> <attrmap> <column name="heading" data-type="varchar(40)" value-from-element="press-release/0/body/0/heading/[0-5]" is-replicant="yes"/> <column name="paragraph" data-type="varchar(100)" value-from-element="press-release/0/body/0/paragraph/[0-5]" 178
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/Encrypting Database Passwords

DataDeploy configuration files store database passwords as clear text, by default. However, the -encodepassword option in iwsyncdb can be used to encode database passwords specified in the database section of configuration files such as database.xml. This option sets a new attribute in the database element indicating that the file contains an encoded password, for example:
<database name="database-entry" db="database-url" user="username" password="passwd" password-encoded="yes" vendor="vendorname"/>
To encode a password attribute, run iwsyncdb with the encodepassword option. For example:
iwsyncdb -encodepassword <path-to-database-xml-file>
Decoding requests to the OpenDeploy server are treated as Decryption only when 'strictAuthentication' is set to 'yes' (see the Restricting Access to Users with OpenDeploy Roles (Strict Authentication) section in the OpenDeploy Administration Guide). All password decoding requests to the OpenDeploy server are treated as decryption. The passwords are encrypted using iwodpassencrypter CLT and then saved in the database configuration file, database.xml, which is decrypted by the OpenDeploy server. The iwodpassencrypter CLT is available in both the OpenDeploy base server and receiver, and resides in the following directory: od-home/bin
179
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 elements enforce-ri attribute must not be set to "yes" in the configuration file). If referential integrity is being enforced, OpenDeploy will only perform default (deletes followed by inserts) updates, because relational databases do not allow the modification of values or fields that are mapped to a primary/foreign key column due to constraint violation errors.
database
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 can not use UPDATE to change the value of columns designated as primary or foreign keys.
Executing a Stored Procedure

You can execute a database stored procedure by using the sql tag. A sample configuration file to execute a procedure called myproc, which takes two numeric arguments, is shown here:
<data-deploy-configuration> <data-deploy-elements filepath="/usr/od-home/etc/database.xml"/> <client> <deployment name="dep1"> <source> <teamsite-extended-attributes options="wide" area="/store2/main/branch1/WORKAREA/wa1"> <path name="file2.txt"/> </teamsite-extended-attributes> </source> <destinations> <database use="oracle" table="not-used"> <sql user-action="execute_my_procedure" type="exec-proc"> myproc(1,2) </sql> </database> </destinations> </deployment> </client> </data-deploy-configuration> 180
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 Stored Procedures with Deployments

There may be instances when you want to execute a stored procedure, and then execute a deployment. For example, there may be a schema update that is needed before you deploy DCRs to a table. To accomplish this, utilize the do-sql-and-exec parameter when invoking the deployment. For example, the following command:
iwodcmd start deployment -k iwdd=multi -k iwdd-op=do-sql-and-exec -k user-op=test
would invoke the following deployment configuration:

</data-deploy-configuration> ... </client> <deployment name="dep1"> <source> ... </source> <destinations> 181
<database use="dbconn"> <sql user-action="test" type="query"> <![CDATA[SELECT COUNT(*) "Count" FROM SYSIBM.SYSTABLES]]> </sql> <dbschema> ... </dbschema> </database> </destinations> </deployment> <deployment name="dep2"> <source> ... </source> <destinations> <database use="dbconn"> <sql user-action="test" type="query"> <![CDATA[SELECT COUNT(*) "Count2" FROM SYSIBM.SYSTABLES]]> </sql> <dbschema> ... </dbschema> </database> </destinations> </deployment> <deployment name="multi"> <exec-deployment use="dep1"/> <exec-deployment use="dep2"/> </deployment> </client> ... </data-deploy-configuration>
NOTE
The user-action attribute must be the same value for all deployments in the configuration.
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.
182
NOTE
You can also embed SQL commands in the DataDeploy configuration files sql element. These commands execute automatically during deployment and do not require you to manually query the database.
Querying Delta Tables

To query a delta table, you can first create a view consisting of a complex query and then apply a simple query on the view. For example:
CREATE VIEW areaview ( key, value, path ) AS SELECT key, value, path FROM sa WHERE NOT EXISTS ( SELECT * FROM wa_x WHERE wa_x.key = sa.key AND wa_x.path = sa.path ) UNION SELECT key, value, path FROM wa_x WHERE wa_x.state != NotPresent; SELECT path FROM areaview WHERE key = News-Section AND value = Sports
The CREATE VIEW command in this example is the default DataDeploy schema that executes when table-view is set to yes in the DataDeploy configuration files database element.
Querying Base and Standalone Tables

You can use simple SQL statements specifying key-value pair criteria when querying a base or standalone table. For example:
SELECT path FROM staging WHERE key = News-Section AND value = Sports;
183
184
Chapter 7
Troubleshooting
This chapter describes how to troubleshoot your OpenDeploy data deployment issues.
Failure in creating the necessary tables for Microsoft SQL Server databases
In some cases the iwoddbtool.bat fails to create the necessary tables for Microsoft SQL
Server databases. If you are using SQL Server, you must perform the following steps:
1. Open the server.xml file using your favorite text or XML editor. This file resides in
the following location:

admin-home/serletd/conf
2. Uncomment the following section:

 Include file 1 <data-deploy-configuration> <data-deploy-elements filepath="/local/iw-home/db.xml"/> <filter name="MyFilter">  <keep>    <or> <field name="path" match="dir2/subdir/index.html" /> <field name="path" match="dir1/*.html" /> <and>  <field name="key" match="guard" /> <field name="value" match="IGNORE" /> </and> </or> </keep> <discard>    <or> <field name="path" match="dir1/ignoreme.html" /> match="unneededKey" /> <field name="key"
Filter section (global) 2
Substitution section (global)
190
The Sample Configuration File
 <destinations host="DDServer.interwoven.com" port="1357">   
Start of Destinations section 10
Start of Database section and location of destination database

11
that -->
    <database name="myproductiondb" db="host1:1357:db1" table="table1" vendor="oracle" user="dba" password="ThisIsASecret" timeout="45"> <select>       <column name="filename"
191
  
SQL section 15
 <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 -->   <bind ip="204.247.118.99" port="1949" />  <allowed-hosts>
Server section
192
The Sections of the Sample Configuration File

The preceding sample configuration file contains 16 separate sections, each of which is labeled and numbered. Here, by number, each of these sections is explained and their usage is described:
1. Include File
You can use data-deploy-elements to name a file containing data to include by reference. The file named in data-deploy-elements can contain any number of database, filter, and substitution elements. It must use the same syntax for these elements that the main deployment configuration file uses. If mutually exclusive attributes are set in the include file and the main deployment configuration file, all are used in the deployment. If conflicting attributes are set in the two files, those set in the main deployment configuration file take precedence.
2. Filter Section (Global)

Filters let you explicitly state which tuples will be deployed. The keep section contains criteria for selecting which tuples will be deployed, and the discard section contains criteria for those which will not be deployed. Both sections use field tags. All field tags must contain at least one name/match attribute pair. When you deploy from TeamSite, name must be either key, value, path, or state. When you deploy from a source other than TeamSite, name can be any be any field name that is valid in the source area. The match attribute names a targeted value for name. A filter defined in the nesting level shown here and located before the Deployment section will be global. Global filters do not become active until they are called by the filter elements use attribute between the Source and Destinations sections using the syntax shown later in the sample file. Note that filters can also be defined in an include file and then be called by the use attribute. If a configuration file does not contain a filter section, all tuples are deployed (limited only by the type of update being performed). A configuration file can contain any number of global filter sections. A configuration file can also contain in-flow filters within a destinations section (see 10. Destinations Section on page 195). For more information about global filtering, see Setting Up Filters on page 140.
193
3. Substitution Section (Global)

Substitutions let you configure DataDeploy to automatically replace character strings or entire fields in a table. Substitutions use field tags that must contain at least one name/replace attribute pair. As with filters, name is either key, value, path, or state. The replace attribute is the new string that will overwrite the existing string or field. Two additional attributes, match and global, are optional. A substitution defined in the nesting level shown here and located before the Deployment section will be global. Global substitutions do not become active until they are called by the substitution elements use attribute between the Source and Destinations sections using the syntax shown later in the sample file. Note that substitutions can also be defined in an include file and then be called by the use attribute. A configuration file can contain any number of global substitution sections. For more information about global substitutions, see Global Substitutions on page 147.
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.
194
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 148.
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
195
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 section in the OpenDeploy Reference guide.
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 198). 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: Table 25 SimpleDateFormat
Symbol Meaning Presentation Example
G y M d h
196
era designator year month in year day in month hour in am/pm (1-12)
(Text) (Number) (Text & Number) (Number) (Number)
AD 1996 July & 07 10 12
Table 25 SimpleDateFormat (Continued)

Symbol Meaning Presentation Example
H m s S E D F w W a k K z
hour in day (0-23) minute in hour second in minute millisecond day in week day in year day in week in month week in year week in month am/pm marker hour in day (1-24) hour in am/pm (0-11) time zone escape for text single quote
(Number) (Number) (Number) (Number) (Text) (Number) (Number) (Number) (Number) (Text) (Number) (Number) (Text) (Delimiter) (Literal)
0 30 55 978 Tuesday 189 2 (2nd Wednesday in July) 27 2 PM 24 0 Pacific Standard Time
Examples using the US locale: Table 26 SimpleDateFormat Using the US Locale

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" "h:mm a" "hh 'o''clock' a, zzzz" "K:mm a, z" "yyyyy.MMMMM.dd GGG hh:mm aaa" Wed, July 10, '96 12:08 PM 12 o'clock PM, Pacific Daylight Time 0:00 PM, PST 1996.July.10 AD 12:08 PM
You can also obtain a description of the SimpleDateFormat Java class from the Sun Java API documentation Web site:
http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html
197
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.
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.
198
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). See Use Case Matrix on page 26 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 129. 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.
199
Before we get started, you must perform the following tasks: Install the OpenDeploy base server software. Refer to Chapter 2, Installation in the OpenDeploy Installation Guide for more information. For the standalone tutorial, ensure the DataDeploy module is properly licensed for use. Refer DataDeploy Module Licensing section in the OpenDeploy Installation Guide for more information. Obtain access to one of the databases supported by OpenDeploy. Refer Supported Databases for Data Deployments section 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 FormsPublisher). Refer Release Compatibility section in the OpenDeploy Release Notes for compatibility information. Refer to your TeamSite documentation for installation and usage information.
Standalone Deployment Tutorial

The following section describes configuring and performing standalone database deployments.
OpenDeploy Base Server Setup

This section assumes your OpenDeploy base server is not already set up for database deployments. If it is, you can skip to the next section. To activate database deployments, perform the following steps: 1. Open the following file:
od-home/etc/odbase.xml
using your favorite text editor, and uncomment out the databaseDeployment node. 2. Set the databaseDeployment elements daemon_port attribute value to 2345. 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
200
changes for the equivalent element for that database. Typically you will only need to change the following attributes:
db user password
The db attributes format is:

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

<database name="microsoft-db" db ="localhost:1433?database=mydb" user="user1" password="mypassword" vendor="microsoft-inetuna" max-id-length="128"/>
This example uses the una2000.jar driver that is included with OpenDeploy. 4. Restart the OpenDeploy base server.
Deployment Example: Custom XML to Database

In this example, we will start with a DTD for employee records and create some XML records based on this DTD. Our goal is to deploy these records to a set of database tables. Then we will create a configuration file for the deployment. Once we have this configuration file, we will invoke OpenDeploy and specify this file through the command line interface.
Create XML Records

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

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

201
/conf /data
- contains the DTD shown here and a deployment configuration file. - 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, and so forth) that will store our data. See User-Defined Database Schemas on page 35 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 205 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>
202
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 file system. (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.
203
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. Referential integrity ensures that these relationships are maintained such that if you delete a row of a parent table when there is a child table that refers to that same row, the corresponding child table rows will also be deleted. The dbschema element also falls under the database element. Recall that we created the dbschema earlier. So after you run the iwsyncdb dbschemagen command to generate the dbschema, you copy the contents of that dbschema into the deployment configuration file that we are creating here. Once this has been done, we no longer need the original dbschema file for standalone deployment, since the dbschema in included in the main configuration file.
<dbschema> <group name="deptRecords" root-group="yes"> <attrmap> <column name="deptId" data-type="VARCHAR(255)" value-from-element="deptRecords/0/dept/0/deptId/0" allows-null="no" is-url="no"/> <column name="name" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/dept/0/description/ 0/name" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key> <key-column name="deptId"/> </primary-key> </keys> </group> <group name="employee" root-group="no"> <attrmap> <column name="name" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/employees/0/employee/ [0-5]/name" is-replicant="yes" allows-null="no" is-url="no"/> <column name="id" data-type="VARCHAR(255)" value-from-attribute="deptRecords/0/employees/0/employee/ [0-5]/id" is-replicant="yes" allows-null="no" is-url="no"/> <column name="deptId" data-type="VARCHAR(255)" value-from-element="deptRecords/0/dept/0/deptId/0" allows-null="no" is-url="no"/> </attrmap> <keys> <primary-key>
204
<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:

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

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

od-home/conf/DDTutorial
This file must be located within the /conf directory and have the .xml extension. Be sure to make modifications to the file if any names or locations, such as the location of the XML data or database.xml file, are different than this sample file. We now have our database deployment configuration file. The SQL Server database is running, and our XML data is ready. We can now deploy the XML data to the SQL Server database using this configuration file.
Execute the Deployment

To execute the deployment, navigate to the od-home/bin directory and run the following command at the prompt:
iwodcmd start DDTutorial/ddconfig k iwdd=deployment1
where ddconfig is the name of our configuration file (do not specify the .xml extension). iwdd refers to the name of our deployment, which we are calling deployment1. You can also perform this same task using the OpenDeploy browser-based user interface by selecting the deployment and entering iwdd=deployment1 in the Parameters box contained in the Start Deployment window. You should see the deployment complete with no errors. If you see errors, check the logs residing in the following location:
205
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. Now we will look at the database to see if the tables were created and contain the data from the XML files. 1. Connect to SQL Server through the SQL Server Enterprise Manager. 2. View the tables. The following information should be displayed: Table 27 Database Tables
table_name
deptrecords employee iwdeltracker iwov_idmaps 3. View the details on the deptrecords table. The following information should be displayed: Table 28 Database Tables (deprecords)
DeptId name
00101 00102
Engineering Marketing
4. View the details on the employee table. The following information should be displayed: Table 29 Database Tables (employee)
Name id depId
Simon Garfunkel Art Vandalay Mark Jones Jane Smith
345 506 209 245
00101 00101 00102 00102
206
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.
207
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. 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 108 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.
208
DAS Tutorial
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. 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/ careers/datacapture.cfg templatedata/internet/
where TeamSite_mountpoint might be one of the following values: Windows - Y:\default UNIX - /iwmnt/default
209
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.
Set Up the Configuration File

To create the deployment configuration file, OpenDeploy will use one of the template files residing in the following location:
od-home/ddtemplate
There are several templates in this directory. For our example, to deploy DCRs to a set of tables that we have defined in our dbschema, we will use the ddcfg_uds.template. If this files name includes an additional extension, such as .new, remove it. Open the ddcfg_uds.template file using your favorite text editor. Change all instances of 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 elements use attribute. The data-deploy-elements elements filepath attribute value is the full path to the database.xml file. For example:
<data-deploy-elements filepath="od-home/etc/database.xml">
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.
210
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 deltagen
- Generates STAGING tables, deploys DCRs to the STAGING table.
- Generates workarea tables, deploys DCRs to the workarea tables. Since the workarea was submitted by DAS earlier, the workarea should have the same content as STAGING, and hence the workarea table will be empty. Recall, that the workarea tables only show differences between STAGING and the workarea. Now lets look at the log to see what occurred. Open the iwdd_default_main.log file residing in the od-home/logs directory. You will see the results of the basearea and deltagen deployments. We can query the database to check if the contents were deployed:
CONSUMERS DEPTRECORDS DESTINATIONS EMPLOYEE IWDELTRACKER IWOV_IDMAPS DEFAULT_INTERNET_CAREERS_CAREERS_MAIN_STAGING DEFAULT_INTERNET_CAREERS_CAREERS_MAIN_WORKAREA_JDOE IWTRACKER JNDI_CONTEXT MESSAGE_HANDLES MESSAGE_ID MESSAGES PERSONNELRECORDS SEEDS SYSTEM_DATA
Now, we can see our STAGING data.

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

select * from DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_WORKAREA_JDOE;
where JDOE is our workarea name for this test. Notice there is no data in this table. This is because DAS submitted the workarea before doing the basearea deployment. The workarea table only shows differences between STAGING. At this point, STAGING and the workarea are identical.
211
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 submitlist
- updates workarea table with any DCR changes made in your workarea.
- 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.
212
DAS Tutorial
7. Delete a DCR and observe the tables. At first, do not submit the change. You will see that the record is removed from the workarea table, but remains in the STAGING table. 8. Submit the deleted DCR. Now you will see that the record was removed from the STAGING table.
Behavior On Other Databases

If you are using this tutorial on a database other than Microsoft SQL, you will notice that there are no tables named careers as the dbschema suggests. Instead, we see some unconventional names like iwt_13a318ba73. Those names contained here are representative samples. You will probably see different names on your system. The iwt_* tables are actually the tables that contain our data. DAS has to create multiple tables for each table in our schema. Specifically, we need a separate table for STAGING and the workarea. OpenDeploy has a certain naming convention that it uses to create the table name. Instead of just careers, the STAGING careers table will be called the following:
DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING
This allows us to have a unique table name for each workarea and STAGING area. There may be many workareas that all have a careers table, so we can not simply have one careers table. We need unique tables for each area that we are working with. This naming convention of using the branch name, category, type, and area creates a problem however. Database table names are very limited in the maximum length. So we can not have a table name that is too large. Certainly, adding the branch info and templating type info to the table name will exceed the name limit. To overcome this, OpenDeploy creates a mapping table. It internally generates a unique short name for the table. OpenDeploy will create an entry in the iwov_idmaps table mapping the short name to the long name
select * from iwov_idmaps; Type Shortid Longid 1 IWT_FC3BD105F88 DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING 1 IWT_13A318BA73 DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_WORKAREA_JDOE
Here we see what short names correspond to our desired tables. So the STAGING data is in the table DEFAULT_INTERNET_CAREERS__CAREERS__MAIN_STAGING.
213
Configuring for Oracle OCI

The following sections describe configuration requirements for using Oracle OCI with OpenDeploy. Before performing these configuration tasks, back up the Oracle JDBC (ojdbc14.jar) driver included with OpenDeploy, and replace it with the ojdbc14.jar file from your Oracle client installation. Open the DataDeploy configuration file and make the following configuration to the database element: Set the attribute use-oci to yes. Set the db attribute to a tnsname Use one of the following methods, depending on whether the OpenDeploy base server configuration files standalone elements execProcess value is set to yes or no.
NOTE
The following steps use the Oracle_home variable. If your Oracle_home variable has not been set, enter the full path to the Oracle installation location.
Windows
If the execProcess attribute is set to no, follow these steps: 1. Check for the existence of environment variable %ORACLE_HOME%. If the variable is not present, add it and point to the Oracle installation home directory on your host. 2. Make the following entries in the PATH environment variable separated by semi-colons:
%ORACLE_HOME%\bin %ORACLE_HOME%\lib
This should be the directory containing ocijdbcX.dll where X is the version of Oracle client 3. Edit the registry and open the following entry:
\\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\iwodserver\ Parameters
4. Create the new string value JVM Option Number 11 and assign it the Data:
-Djava.library.path=oracle-home\bin;oracle-home\lib
where oracle-home is the actual value of the %ORACLE_HOME% variable. This should be the directory containing ocijdbcX.dll if the bin and lib directories do not have the required .dll file where X is the version of Oracle client in ocijdbcX.dll. 5. Change the string JVM Option Count strings value from b to c. 6. Restart OpenDeploy.
214
Configuring for Oracle OCI
7. Run the deployment. If the execProcess attribute is set to yes, follow these steps: 8. Check for the existence of environment variable %ORACLE_HOME%. If the variable is not present, add it and point to the Oracle installation home directory on your host. 9. Make the following entries in the PATH environment variable separated by semi-colons:
This should be the directory containing ocijdbcX.dll where X is the version of Oracle client. 10. Open the od-home\lib\iwddexec.bat file using your favorite text editor. 11. Locate the line containing the following string:
set JAVA_LIBRARY_PATH=%OD_LIB_DIR%;%JAVA_CLASSES%
and add the following entries each separated by semicolon:

This should be the directory containing ocijdbcX.dll if the bin and lib directories do not have the required .dll file where X is the version of Oracle client in ocijdbcX.dll. 12. Run the deployment.
Solaris
If the execProcess attribute is set to no, follow these steps: 1. Check for the existence of environment variable %ORACLE_HOME%. If the variable is not present, add it and point to the Oracle installation home directory on your host. 2. Make the following entry in the PATH environment variable:
$ORACLE_HOME/bin
This should be the directory containing libocijdbcX.so and libocijdbcX_g.so where X is the version of the Oracle client. 3. Add the entry $ORACLE_HOME/lib to LD_LIBRARY_PATH. 4. Open the od-home/processod file and search for the string JAVA_LIBRARY_PATH in the shell script. 5. Add the following entries each separated by colon to JAVA_LIBRARY_PATH both in the if and else cases i.e.
oracle-home/bin oracle-home/lib
where oracle-home is the actual value of the $ORACLE_HOME variable.

215
6. This should be the directory containing libocijdbcX.so and libocijdbcX_g.so where X is the version of the Oracle client. 7. Run the deployment. 8. If the execProcess attribute is set to yes, follow these steps: 9. Check for the existence of environment variable %ORACLE_HOME%. If the variable is not present, add it and point to the Oracle installation home directory on your host. 10. Make the following entry in the PATH environment variable:
$ORACLE_HOME/bin
This should be the directory containing libocijdbcX.so and libocijdbcX_g.so where X is the version of the Oracle client. 11. Open the od-home/lib/iwddexec file using your favorite text editor. 12. Search for the function set_LD_LIBRARY_PATH_TO_LIB() in the shell script. Add the following entries each separated by colon to LD_LIBRARY_PATH both in the if and else cases i.e.
${ORACLE_HOME}/bin ${ORACLE_HOME}/lib
This should be the directory containing libocijdbcX.so and libocijdbcX_g.so where X is the version of the Oracle client. 13. Run the deployment.
Best Practices for Writing SQL Queries for Custom SQL Reports
When writing SQL queries for custom SQL reports, it is recommended that you use JDBC functions instead of database specific functions whenever possible. The following list shows examples of using date JDBC date/time functions instead of DBMS-specific ones: Replace datepart(yyyy,D.start_time) with YEAR(D.start_time). Replace datepart(m,D.start_time) with MONTHNAME(D.start_time). Replace datepart(d,D.start_time) with DAYOFMONTH(D.start_time).
216
Best Practices for Writing SQL Queries for Custom SQL Reports
The following table shows the full set of JDBC date conversion functions: Table 30 JDBC Date Conversion Functions
Function Name CURDATE() CURTIME() DAYNAME(date) Function Returns
The current date as a date value. The current local time as a time value. A character string representing the day component of date; the name for the day is specific to the data source.
DAYOFMONTH(date An integer from 1 to 31 representing the day of the month in date. ) DAYOFWEEK(date)
An integer from 1 to 7 representing the day of the week in date; 1 represents Sunday. An integer from 0 to 23 representing the hour component of time. An integer from 0 to 59 representing the minute component of time. An integer from 1 to 12 representing the month component of date. A character string representing the month component of date; the name for the month is specific to the data source. A timestamp value representing the current date and time. An integer from 1 to 4 representing the quarter in date; 1 represents January 1 through March 31. An integer from 0 to 59 representing the second component of time. A timestamp calculated by adding count number of interval(s) to timestamp; interval may be one of the following: SQL_TSI_FRAC_SECOND SQL_TSI_SECOND SQL_TSI_MINUTE SQL_TSI_HOUR SQL_TSI_DAY SQL_TSI_WEEK SQL_TSI_MONTH SQL_TSI_QUARTER SQL_TSI_YEAR An integer from 1 to 53 representing the week of the year in date. An integer representing the year component of date.
217
DAYOFYEAR(date) An integer from 1 to 366 representing the day of the year in date. HOUR(time) MINUTE(time) MONTH(date) MONTHNAME(date) NOW() QUARTER(date) SECOND(time)
TIMESTAMPADD (interval, count, timestamp)
WEEK(date) YEAR(date)
The complete set of JDBC functions in documented in the JDBC 3.0 Specification available from the Sun Microsystems Web site:
http://java.sun.com/
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 140 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.
218
Appendix C
UDS vs. Wide Table Mapping

Wide table mapping is a legacy format used primarily when OpenDeploy did not support user-defined schemas (UDS). It is highly recommended to use the UDS format and migrate any of your wide-table based deployment configurations to UDS. OpenDeploy favors UDS over wide table mapping since UDS facilitates database normalization. See Chapter 2, Deployment Concepts for more information.

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 FormsPublisher.
Data Categories and Data Types

To understand the example, it is important to note that FormsPublisher uses a data storage hierarchy based on directories that contain data categories and types, as is shown in Figure 44. 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, refer to the FormsPublisher Developers Guide.
219
Figure 44 FormsPublisher Directory Structure Workarea templatedata

tutorials data_category_1 data_category_2
...
components
output
data_type_1
data_type_2
...
datacapture.cfg
data
content_record_1 content_record_2 ...
presentation
pres_template_1.tpl pres_template_2.tpl ...
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.
220
NOTE
Pat would need to perform additional configuration to set up FormsPublisher 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: Table 31 Table Headings in the Destination Database
Path Author ISBN Publisher Title Name0... E-Mail0... Comments0... State
The ellipses (...) in the column headings indicate that OpenDeploy creates additional column headings for each replicant field, up to the maximum number of fields indicated in the data capture template. In this example, Pat indicated a maximum of 10 fields for the Reviewers replicant by giving the max attribute a value of 10. Therefore, each Reviewers subelement would contain 10 headings:
Name0-Name9 E-Mail0-E-Mail9 Comments0-Comments9
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: Table 32 Wide Table Mapping
Path
mypath0
Author
ISBN Publisher Title Name0... E-Mail0.. Comments0. State . ..
William 1234- Software Usin Chris Faulkner 56 Inc. g Data
chris@ This book xyz.com describes...
origi nal
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,
221
OpenDeploy adds a new row in the table. OpenDeploy then inserts information from Dons data content record: Table 33 Wide Table Mapping (cont.)
Path
mypath0
Author
ISBN
Publishe E-Mail0.. Comments0.. Title Name0... State r . .
William 1234- Software Usin Chris Faulkner 56 Inc. g Data Harper Lee 1256- Software Usin 89 Inc. g Tupl es
chris@ This book xyz.com describes...
origi nal origi nal
mypath1
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: Table 34 UDS
Path
mypath0 mypath1
Author
ISBN
Publisher
Title
State
William Faulkner Harper Lee
1234-56 1256-89
Software Inc. Software Inc.
Using Data
original
Using Tuples original
222
Implementation of a UDS
Table 35 UDS (cont.)

Name0... E-Mail0... Comments0... ISBN
Chris
chris@xyz.com
This book describes...
1234-56
OpenDeploy deployments are driven by XML configurations files. This section discusses configuration files that you must create for using user-defined schemas. Generation of these files is described in more detail in Chapter 3, Configuration Files. 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.
223
If a column is designated as a primary key within a group, a column element for that key must exist within that groups attrmap element. If a column is designated as a foreign key: Its groups attrmap element must contain a column element whose name matches the name of the child column. Its parent group must exist. Its parent groups attrmap element must contain a column whose name matches the name of the parent-group attribute of the child groups foreign-key. A foreign key must have the same data-type attribute (for example, varchar) as its parent key. A column that is defined as a primary key cannot contain null values. Only use user-defined database schemas for database destinations, not database sources. In other words, only use the dbschema element inside a database element when the database element is inside a destinations element. Do not use narrow tuples. The options attribute for the teamsite-templating-records or teamsite-extended-attributes element inside the source element must be set to wide. 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> 224
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 FormsPublisher:
<dbschema> <group name="medical_master" root-group="yes"> <attrmap> <column name="Disease" data-type="varchar(100)" value-from-field="Disease" allows-null="no"/> <column name="LatinName" data-type="varchar(100)" value-from-field="Latin" allows-null="no"/> <column name="Type" data-type="varchar(15)" value-from-field="Type" allows-null="no"/> </attrmap> <keys> <primary-key> <key-column name="Disease"/> </primary-key> </keys> </group> <group name="vector_list" root-group="no"> <attrmap> <column name="Vector" data-type="varchar(40)" value-from-field="Vector List/[0-5]/Vector" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Vector"/> <key-column name="Disease"/> </primary-key> 225
<foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column="Disease"/> </foreign-key> </keys> </group> <group name="symptom_list" root-group="no"> <attrmap> <column name="Symptom" data-type="varchar(100)" value-from-field="Symptom List/[0-5]/Symptom" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Symptom"/> <key-column name="Disease"/> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column= "Disease" child-column="Disease"/> </foreign-key> </keys> </group> <group name="prognosis_list" root-group="no"> <attrmap> <column name="Prognosis" data-type="varchar(100)" value-from-field="Prognosis List/[0-3]/Prognosis" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <key-column name="Prognosis"/> <key-column name="Disease"/> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column= "Disease" /> </foreign-key> </keys> </group> <group name="Treatment_list" root-group="no"> <attrmap> <column name="Treatment" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Treatment" is-replicant="yes"/> 226
<column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> </attrmap> <keys> <primary-key> <column-key name="Treatment"/> <column-key name="Disease" /> </primary-key> <foreign-key parent-group="medical_master"> <column-pair parent-column="Disease" child-column= "Disease" /> </foreign-key> </keys> </group> <group name="drug_list" root-group="no"> <attrmap> <column name="Treatment" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Treatment" is-replicant="yes"/> <column name="Disease" data-type="varchar(100)" value-from-field="Disease"/> <column name="Drug" data-type="varchar(100)" value-from-field="Treatment List/[0-3]/Drug List/[0-4]/Drug" is-replicant="yes"/> </attrmap> <keys> <primary-key> <key-column name="Drug" /> <key-column name="Disease"/> <key-column name="Treatment"/> </primary-key> <foreign-key parent-group="Treatment_list" > <column-pair parent-column="Disease" child-column="Disease" /> <column-pair parent-column="Treatment" child-column="Treatment" /> </foreign-key> </keys> </group> </dbschema>
227
The preceding mapping would result in the database table relationships shown in Figure 45, 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 45 Database Table Relationships Created by Sample dbschema.cfg File
Prognosis List N N Symptom List 1 1 Medical Master 1 N Treatment List 1 N Drug List 1 N Vector List
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 46 shows an overview of this process. For more details, see Mapping a Database Schema with iwsyncdb on page 58.
228
templating.cfg
datacapture.cf g for data type dbschema.cfg for data type X
datacapture.cf g for data type dbschema.cfg for data type Y
2 1
Command Line: iwsyncdb iwsyncdb DataDeploy configuration file Y_dd.cfg
DataDeploy configuration file X_dd.cfg
3
ddcfg_uds.template file or ddcfg_uds_custom.templ
Figure 46 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.
229
230
Appendix D
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 BRANCH
- the time the particular row in the IWTRACKER table was updated.
- 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.
231
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 AREA
- the area relative path to the file. - the path to the area where the file is located. - the name of the primary key column of the actual table receiving the - the value of the primary key.
KEYCOLNAME
deployment.
KEYCOLVALUE
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 vendors limit for table name size. The IWOV_IDMAPS table is used to store an internally generated short name for the identifier when the length of the identifier exceeds the limits set by the database vendor. The table contains the following columns:
TYPE 1 2 3 232
- the type of identifier: - table - column - view
IWTMP_LOB
- constraint - the unique short ID that OpenDeploy generates.
SHORTID 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 version less than 9.0; that is, Oracle 8 or less.
233
234
Glossary
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 FormsPublisher. 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 FormsPublisher from a contributor or through other means. Data content records can be deployed to a database. Delete Tracker Table
235
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. 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 tables associated base table should exist from a previous deployment). The relationship between the workarea data and the data in its parent area (a staging area or edition) is updated in the tracker table residing in the database. 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
236
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 files extended attributes consist of more than one key-value pair. Also, you cannot deploy data content records using narrow tuples and you cannot automatically deploy narrow tuples with DAS. DAS only accepts wide tuples. 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 path name of the file associated with the tuples key-value pair(s). Replicant A repeatable data field in a FormsPublisher 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
237
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.
238
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.
239
240
Index
A
allowed-hosts element 198 architecture 24 attributes configFilePath 127 databaseXmlFile 132 db 89 row-map-cache-file 158 schemaMapFile (eaData) 133 schemaMapFile (xmlData) 133 useDatabaseRef 132 xmlData 133
db attribute 89 contents database schema 21
D
DAS 23, 93 configuration 100 configuration files 94 database.xml 96 DataDeploy configuration templates 96 drop.cfg 96 iw.cfg 97 metadata capture setup 100 multiple OpenDeploy instances 94 OpenDeploy server configuration 98 parameters, specifying 98 reports 112 requirements 94 template type setup 99 triggers 117 user interface 98 data categories 219 data category 142 data deployment configuration files generating 101 data organization 38 data sources 38 data type 56 data types 219 database drivers 89 database auto-synchronization composite tables 47 delta table 44 deployment sequence 43 initial base table 43 iwsyncdb.ipl 100 table updates 46 updating base tables 45 workareas 101
241
B
base table format 41 base tables 43 querying 183 updating 45, 113 base updates 37 bind element 198
C
client element 194 column element 196 composite tables 47 concepts DAS 23 database 21 DataDeploy 23 deployments 23 structured content 20 configFilePath attribute 127 configuration files
database connection properties 83 database deployments 17 architectural overview 24 architecture 24 categories 33 DataDeploy module 125 process 34 source/destination configurations 35 standalone 126 synchronized 130 target-side 129 database element 179, 196 database element attributes db 89 database privileges 18 database schema 21 database schemas data categories 219 data types 219 dbschema.cfg 223, 225 overview 35 rules 223 UDS 35 user-defined 35 wide table 35 database.xml DAS 96 databaseXmlFile attribute 132 DataDeploy 23 DataDeploy configuration files 127 running 128 DataDeploy configuration templates DAS 96 dataDeploy element 127 DataDeploy module 17, 125 DataDeploy wrapper file 127 data-deploy-elements element 193 db attribute 89 dbLoader element 132 dbschema element 60 dbschema.cfg creation rules 223 DCR deployments 19 delta tables 44
242
updating 113 delta updates 37 deployment element 194 deployments concepts 20 DAS 23 data organization 38 data sources 38 database 17 database schemas 35 DataDeploy 23 DCR 19 EA 19 invocation 18 scenarios 36 standalone 19 synchronized 19 table types 37 tuples 38 UDS 219 update types 37 usage 19 use cases 26 wide table 219 destinations element 195 discard element 193 dlLoaderCustom element 134 drop.cfg DAS 96
E
EA deployments 19 eaAndXmlData element 134 eaData element 133 elements dataDeploy 127 dbLoader 132 dlLoaderCustom 134 eaAndXmlData 134 eaData 133 xmlData 133 elements, DTD allowed-hosts 198
bind 198 client 194 column 196 database 179, 196 data-deploy-elements 193 dbschema 60 deployment 194 destinations 195 discard 193 exec-deployment 194 filter 193 for-deployment 198 host 198 keep 193 select 196 server 198 source 195 sql 198 substitution 194 update 198 xml-formatted-data 196 Event Subsystem configuration files eventsubsystem.properties 109 event subsystem 104 configuring 105, 108 events 104 logging 111 publishers 104 subscribers 104 eventsubsystem.properties 109 exec-deployment element 194 external data source 169
I
internal tables 231 IWDELTRACKER 231 IWOV_IDMAPS 232 IWOV_LOB 233 IWTRACKER 231 invocation 18 iw.cfg DAS 97 TeamSite mount point, alternate 98, 128 IWDELTRACKER internal table 231 IWOV_IDMAPS internal table 232 IWOV_LOB internal table 233 iwsyncdb.ipl 100 IWTRACKER internal table 231
K
keep element 193
L
logging event subsystem 111 TeamSite event 119
M
MetaTagger 19
N
narrow tuples 40, 41 base table format 42
F
filter element 193 for-deployment element 198 FormsPublisher 19
O
OpenDeploy DAS 93 DataDeploy module 17
H
host element 198
R
real updates 180 replicants 149
243
comma separated lists 150 deploying 149 deploying multiple 157 order columns 149 row-map-cache-file attribute 158 rowmapgen 157
S
schema mapping 21 schemaMapFile (eaData) attribute 133 schemaMapFile (xmlData) attribute 133 select element 196 server element 198 source element 195 sql element 198 standalone database deployments 126 alternate mount point 128 configuration 127 DataDeploy configuration file 127 execution 127 server configuration 126 standalone deployments 19 standalone tables querying 183 standalone updates 37 structured content storing 21 XML 20 substitution element 194 substitutions global 194 in-flow 195 synchronized deployments 19, 130
TeamSite 19 TeamSite event logging 119 To 98 tuples 38 metadata 39 narrow 40, 41, 42 defined 237 state 39 wide 40, 41
U
update element 198 update types 37 base updates 37 delta update 37 standalone updates 37 useDatabaseRef attribute 132 user defined schemas configuration files 228 implementation 223 normalization of data 222 user-defined schema 219 user-defined schemas normalization 35
W
wide table limitations 221 wide table schemas 35 wide tuples 40 base table format 41
X T
table types 37 table updates 46 tables, internal 231 target-side database deployments 129 deployment configuration 132 server configuration 131 synchronized 130
244
xmlData attribute 133 xmlData element 133 xml-formatted-data element 196

Od 71 Ddadmin v01 en

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Od 71 Ddadmin v01 en

Încărcat de

Drepturi de autor:

Formate disponibile

Database Deployment for OpenDeploy Administration Guide

Trademarks and Copyrights

Notice to Government End Users

About This Book

Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Appendix A: Sample Configuration File

Appendix B: Database Deployment Tutorials

Database Deployment for OpenDeploy Administration Guide

208 213 214 214 215 216 218

Appendix C: UDS vs. Wide Table Mapping

Appendix D: Database Deployment Internal Tables

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

About This Book

Database Deployment for OpenDeploy Administration Guide

About This Book

Monospaced bold italic

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

About This Book

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Required Database Privileges

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

XML for Defining Structured Content

Database Deployment for OpenDeploy Administration Guide

Database for Storing Structured Content

Metadata Table (md)

Sales in Northern California Sales in Northern California Sales in Northern California

Descriptor Table (desc)

Sym (foreign key)

Regions FIPS5-2 Territory

Americas California West

Mapping the XML Representation to the Database Schema

Database Deployment for OpenDeploy Administration Guide

This XML element/attribute maps to this table/column

Database Deployment for OpenDeploy Administration Guide

Deploying XML to the Database

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide

Data Deployment Architecture

XML XML Files Files

Deployment may go through an

Database Database Tuple Tuple Producer Producer

Database Deployment for OpenDeploy Administration Guide

Use Case Matrix

Supported Use Cases for Data Deployments

TeamSite to Database (see page 66 for more information)

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

*Specific XML format defined by DataDeploy

Database Deployment for OpenDeploy Administration Guide

Migration Notes for DataDeploy 5.6

Migration Notes for DataDeploy 5.6

Initializing DAS Use iwsyncdb.ipl -initial tables.

Database Deployment for OpenDeploy Administration Guide