You are on page 1of 98

PowerCenter Data Stencil Guide

Informatica PowerCenter
(Version 8.5.1)

Informatica PowerCenter Data Stencil Guide Version 8.5.1 December 2007 Copyright (c) 19982007 Informatica Corporation. All rights reserved. This software and documentation contain proprietary information of Informatica Corporation and are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright law. Reverse engineering of the software is prohibited. No part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise) without prior consent of Informatica Corporation. This Software is protected by U.S. and/or international Patents and other Patents Pending. Use, duplication, or disclosure of the Software by the U.S. Government is subject to the restrictions set forth in the applicable software license agreement and as provided in DFARS 227.7202-1(a) and 227.7702-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable. The information in this product or documentation is subject to change without notice. If you find any problems in this product or documentation, please report them to us in writing. Informatica, PowerCenter, PowerCenterRT, PowerCenter Connect, PowerCenter Data Analyzer, PowerExchange, PowerMart, Metadata Manager, Informatica Data Quality, Informatica Data Explorer, Informatica Complex Data Exchange and Informatica On Demand Data Replicator are trademarks or registered trademarks of Informatica Corporation in the United States and in jurisdictions throughout the world. All other company and product names may be trade names or trademarks of their respective owners. Portions of this software and/or documentation are subject to copyright held by third parties, including without limitation: Copyright DataDirect Technologies. All rights reserved. Copyright 2007 Adobe Systems Incorporated. All rights reserved. Copyright Sun Microsystems. All rights reserved. Copyright RSA Security Inc. All Rights Reserved. Copyright Ordinal Technology Corp. All rights reserved. Copyright Platon Data Technology GmbH. All rights reserved. Copyright Melissa Data Corporation. All rights reserved. Copyright Aandacht c.v. All rights reserved. Copyright 1996-2007 ComponentSource. All rights reserved. Copyright Genivia, Inc. All rights reserved. Copyright 2007 Isomorphic Software. All rights reserved. Copyright Meta Integration Technology, Inc. All rights reserved. Copyright MySQL AB. All rights reserved. Copyright Microsoft. All rights reserved. Copyright Oracle. All rights reserved. Copyright AKS-Labs. All rights reserved. Copyright Quovadx, Inc. All rights reserved. Copyright SAP All rights reserved. Copyright 2003, . 2007 Instantiations, Inc. All rights reserved. This product includes software developed by the Apache Software Foundation (http://www.apache.org/), software copyright 2004-2005 Open Symphony (all rights reserved) and other software which is licensed under the Apache License, Version 2.0 (the License). You may obtain a copy of the License at http:// www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. This product includes software which was developed by Mozilla (http://www.mozilla.org/), software copyright The JBoss Group, LLC, all rights reserved; software copyright, Red Hat Middleware, LLC, all rights reserved; software copyright 1999-2006 by Bruno Lowagie and Paulo Soares and other software which is licensed under the GNU Lesser General Public License Agreement, which may be found at http://www.gnu.org/licenses/lgpl.html. The materials are provided free of charge by Informatica, as-is, without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The product includes ACE(TM) and TAO(TM) software copyrighted by Douglas C. Schmidt and his research group at Washington University, University of California, Irvine, and Vanderbilt University, Copyright (c) 1993-2006, all rights reserved. This product includes software copyright (c) 2003-2007, Terence Parr. All rights reserved. Your right to use such materials is set forth in the license which may be found at http://www.antlr.org/license.html. The materials are provided free of charge by Informatica, as-is, without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (copyright The OpenSSL Project. All Rights Reserved) and redistribution of this software is subject to terms available at http://www.openssl.org. This product includes Curl software which is Copyright 1996-2007, Daniel Stenberg, <daniel@haxx.se>. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://curl.haxx.se/docs/copyright.html. Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. The product includes software copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://www.dom4j.org/license.html. The product includes software copyright (c) 2004-2007, The Dojo Foundation. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://svn.dojotoolkit.org/dojo/trunk/LICENSE. This product includes ICU software which is copyright (c) 1995-2003 International Business Machines Corporation and others. All rights reserved. Permissions and limitations regarding this software are subject to terms available at http://www-306.ibm.com/software/globalization/icu/license.jsp This product includes software copyright (C) 1996-2006 Per Bothner. All rights reserved. Your right to use such materials is set forth in the license which may be found at http://www.gnu.org/software/kawa/Software-License.html. This product includes OSSP UUID software which is Copyright (c) 2002 Ralf S. Engelschall, Copyright (c) 2002 The OSSP Project Copyright (c) 2002 Cable & Wireless Deutschland. Permissions and limitations regarding this software are subject to terms available at http://www.opensource.org/licenses/mitlicense.php.

This product includes software developed by Boost (http://www.boost.org/). Permissions and limitations regarding this software are subject to terms available at http://www.boost.org/LICENSE_1_0.txt. This product includes software copyright 1997-2007 University of Cambridge. Permissions and limitations regarding this software are subject to terms available at http://www.pcre.org/license.txt. This product includes software copyright (c) 2007 The Eclipse Foundation. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://www.eclipse.org/org/documents/epl-v10.php. The product includes the zlib library copyright (c) 1995-2005 Jean-loup Gailly and Mark Adler. This product includes software licensed under the terms at http://www.tcl.tk/software/tcltk/license.html. This product includes software licensed under the terms at http://www.bosrup.com/web/overlib/?License. This product includes software licensed under the terms at http://www.stlport.org/doc/license.html. This product includes software licensed under the Academic Free License (http://www.opensource.org/licenses/afl-3.0.php.) This product includes software developed by the Indiana University Extreme! Lab. For further information please visit http://www.extreme.indiana.edu/. This Software is protected by U.S. Patent Numbers 6,208,990; 6,044,374; 6,014,670; 6,032,158; 5,794,246; 6,339,775; 6,850,947; 6,895,471 and other U.S. Patents Pending. DISCLAIMER: Informatica Corporation provides this documentation as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of non-infringement, merchantability, or use for a particular purpose. Informatica Corporation does not warrant that this software or documentation is error free. The information provided in this software or documentation may include technical inaccuracies or typographical errors. The information in this software and documentation is subject to change at any time without notice.

Part Number: PC-DSG-85100-0001

Table of Contents
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Informatica Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Informatica Global Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Chapter 1: Understanding Data Stencil. . . . . . . . . . . . . . . . . . . . . . . . . 1


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Components of the Data Stencil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Using Data Stencil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Step 1. Create a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Step 2. Publish a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Step 3. Generate Mappings from Template Files . . . . . . . . . . . . . . . . . . . . 5 Data Stencil for Visio Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2: Working with Mapping Templates in Data Stencil . . . . . . . 9


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Starting Data Stencil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Macros in Data Stencil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Using the Data Integration Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Creating a Template from a Mapping XML File . . . . . . . . . . . . . . . . . . . 12 Validating a Mapping Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Publishing a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Arranging Objects in the Drawing Window . . . . . . . . . . . . . . . . . . . . . . 13 Declaring Parameters and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Showing All Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Using the Data Integration Stencil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Creating a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Table of Contents v

Create a Template from a New Drawing . . . . . . . . . . . . . . . . . . . . . . . . . 15 Create a Mapping Template from an Existing Mapping . . . . . . . . . . . . . . 16 Using Parameters in a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Configuring Mapping Objects in a Mapping Template . . . . . . . . . . . . . . . . . 19 Expressions in Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using the %ALL% Keyword in an Expression . . . . . . . . . . . . . . . . . . . . 20 Groups in Multi-Group Transformations . . . . . . . . . . . . . . . . . . . . . . . . 21 Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Using a Joiner Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Using a Lookup Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Using a Router Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Example Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Step 1. Creating a Mapping Template Drawing . . . . . . . . . . . . . . . . . . . 26 Step 2. Define Parameter and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Step 3. Publish the Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 3: Mapping Template Rules . . . . . . . . . . . . . . . . . . . . . . . . . . 31


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating and Configuring Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Rule Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Including or Excluding Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Multi-Group Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Creating Rules for a Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 All Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Foreign Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Named Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Primary Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 4: Using the Import Mapping Template Wizard . . . . . . . . . . . 49


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Export Source and Target Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Reference Source Definitions with Unique Names . . . . . . . . . . . . . . . . . 51

vi

Table of Contents

Step 1. Select the Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Step 2. Specify Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Step 3. Select Mappings to Generate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Step 4. Import Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Understanding Mapping Status Messages . . . . . . . . . . . . . . . . . . . . . . . . 58 Example Using Mapping Template Import Wizard . . . . . . . . . . . . . . . . . . . . 60 Step 1. Select the Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Step 2. Specify Parameters in the Mapping Template . . . . . . . . . . . . . . . 60 Step 3. Generate and Import Mappings . . . . . . . . . . . . . . . . . . . . . . . . . 61

Chapter 5: Using the mapgen Command Line Program . . . . . . . . . . . 63


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 mapgen File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Using Source and Target Files with mapgen . . . . . . . . . . . . . . . . . . . . . . . . . 65 Manually Updating Mapping Template Parameters . . . . . . . . . . . . . . . . . . . . 66 Parameter File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Modifying the Parameter File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Running the mapgen Command Line Program . . . . . . . . . . . . . . . . . . . . . . . 69 Example Using mapgen Command Line Program . . . . . . . . . . . . . . . . . . . . . 71 Step1. Export Source and Target Definitions . . . . . . . . . . . . . . . . . . . . . 71 Step 2. Edit the Parameter File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Step 3. Run the mapgen Command Line Program . . . . . . . . . . . . . . . . . 72 Step 4. Import the Mappings into the Repository . . . . . . . . . . . . . . . . . . 72

Appendix A: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Glossary of Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Table of Contents

vii

viii

Table of Contents

List of Figures
Figure Figure Figure Figure Figure Figure 1-1. 1-2. 1-3. 1-4. 1-5. 1-6. Creating a Mapping Template from a New Drawing . . . . . . . . . . . . . . . . . . . Creating a Mapping Template Drawing from a Mapping . . . . . . . . . . . . . . . . Publishing a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Importing Mappings with the Import Mapping Template Wizard Creating and Importing Mappings with mapgen and the Import Wizard . . . . . Data Stencil Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .... .... .... .... .... .... 4 5 5 6 6 7

List of Figures

ix

List of Figures

List of Tables
Table Table Table Table Table 3-1. 3-2. 3-3. 3-4. 5-1. Mapping Template Rules . . . . . . Example List of Ports . . . . . . . . . Named Port Rule . . . . . . . . . . . . Pattern Rule . . . . . . . . . . . . . . . mapgen Options and Arguments . . . . . . .. .. .. .. .. . . . . . .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. . . . . . .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. . . . . . .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. . . . . . .. .. .. .. .. . . . . . . . . . . 32 33 42 46 69

List of Tables

xi

xii

List of Tables

Preface

The Data Stencil Guide is written for developers and architects responsible for designing PowerCenter mappings. The Data Stencil Guide assumes that you have a solid understanding of PowerCenter and data integration concepts. This guide also assumes that you are familiar with Microsoft Office tools such as Visio.

xiii

Informatica Resources
Informatica Customer Portal
As an Informatica customer, you can access the Informatica Customer Portal site at http://my.informatica.com. The site contains product information, user group information, newsletters, access to the Informatica customer support case management system (ATLAS), the Informatica Knowledge Base, Informatica Documentation Center, and access to the Informatica user community.

Informatica Web Site


You can access the Informatica corporate web site at http://www.informatica.com. The site contains information about Informatica, its background, upcoming events, and sales offices. You will also find product and partner information. The services area of the site includes important information about technical support, training and education, and implementation services.

Informatica Knowledge Base


As an Informatica customer, you can access the Informatica Knowledge Base at http://my.informatica.com. Use the Knowledge Base to search for documented solutions to known technical issues about Informatica products. You can also find answers to frequently asked questions, technical white papers, and technical tips.

Informatica Global Customer Support


There are many ways to access Informatica Global Customer Support. You can contact a Customer Support Center through telephone, email, or the WebSupport Service. Use the following email addresses to contact Informatica Global Customer Support:

support@informatica.com for technical inquiries support_admin@informatica.com for general customer service requests

WebSupport requires a user name and password. You can request a user name and password at http://my.informatica.com.

xiv

Preface

Use the following telephone numbers to contact Informatica Global Customer Support:
North America / South America Informatica Corporation Headquarters 100 Cardinal Way Redwood City, California 94063 United States Europe / Middle East / Africa Informatica Software Ltd. 6 Waltham Park Waltham Road, White Waltham Maidenhead, Berkshire SL6 3TN United Kingdom Asia / Australia Informatica Business Solutions Pvt. Ltd. Diamond District Tower B, 3rd Floor 150 Airport Road Bangalore 560 008 India Toll Free Australia: 1 800 151 830 Singapore: 001 800 4632 4357 Standard Rate India: +91 80 4112 5738

Toll Free +1 877 463 2435

Toll Free 00 800 4632 4357

Standard Rate United States: +1 650 385 5800

Standard Rate Belgium: +32 15 281 702 France: +33 1 41 38 92 26 Germany: +49 1805 702 702 Netherlands: +31 306 022 797 United Kingdom: +44 1628 511 445

Preface

xv

xvi

Preface

Chapter 1

Understanding Data Stencil


This chapter includes the following topics:

Overview, 2 Components of the Data Stencil, 3 Using Data Stencil, 4 Data Stencil for Visio Interface, 7

Overview
You install Data Stencil when you install the PowerCenter client. With Data Stencil, you can create a mapping template using Microsoft Office Visio. A mapping template is a diagram that you can use to represent elements of a PowerCenter mapping. You can use rules and parameters in a mapping template to specify the extraction logic. If you have the mapping generation option, you can use the mapping template to create PowerCenter mappings. The mapping generation option provides tools to generate PowerCenter mappings from the mapping template. You can use Data Stencil mapping templates to provide consistency and improve productivity in the following cases:

Define consistent methodology and structure for data integration projects. Use mapping templates to standardize error handling or slowly changing dimension mappings. Distribute mapping templates to developers working on data integration projects to share best practices, standards, and special techniques. In addition, after an implementation is complete, developers can reuse templates for similar projects. Generate multiple mappings at one time. You can use one Data Stencil mapping template to generate multiple mappings that have similar structure. For example, create a mapping template that includes the basic design and uses rules and parameters to define the extraction logic. When you use the mapping template to create multiple mappings, you can specify different values for the parameters. You can use parameters to define data sources, transformation properties, port names, expressions, and other elements that comprise a mapping. Document data flow. You can use mapping template drawings to document methods to map or process data.

Chapter 1: Understanding Data Stencil

Components of the Data Stencil


Data Stencil has the following components:

Data Stencil for Visio. Use the Microsoft Office Visio software to create a mapping template that you can use to generate multiple PowerCenter mappings. Mapping template files. Files that you generate to create mappings from a mapping template:

Mapping template drawing file ([template name].vsd). A Visio drawing file that represents a PowerCenter mapping. After you create a mapping template drawing, you must save the file. You use this file to generate mappings. Mapping template XML file ([template name].xml). An XML representation of the mapping template. When you publish the mapping template, Data Stencil generates the mapping template XML file. You use this file to generate mappings. Mapping template parameter file ([template name]_param.xml). An XML file that you use to define and save parameter values. When you publish the mapping template, Data Stencil generates the mapping template parameter file. You use this file to generate mappings.

Import Mapping Template Wizard. A wizard that you can use in the PowerCenter Client to generate the mappings and import them into the repository. This component is part of the mapping generation option. mapgen command line program. A command line program that you can use to generate an XML representation of the mappings from mapping template files. After you generate XML representation of the mappings, you can import the XML file into PowerCenter to view the mappings. This component is part of the mapping generation option.

Components of the Data Stencil

Using Data Stencil


Data Stencil provides a Visio stencil with shapes that represent PowerCenter mapping objects. The mapping template is comprised of mapping objects available in the Data Integration Stencil. To create a mapping template and generate PowerCenter mappings, complete the following steps: 1. 2. 3. Create a mapping template. Use the Data Stencil for Visio to create a mapping template. Publish the mapping template. After you create the mapping template, publish the template to generate the mapping template files required to generate multiple mappings. Generate mappings from template files. Use one of the mapping generation options to create multiple PowerCenter mappings.

Step 1. Create a Mapping Template


Use one of the following methods to create a mapping template:

Create a mapping template from a new drawing. If you do not want to use an existing mapping to create a mapping template, use the mapping objects in the Data Integration Stencil in Visio to create a mapping template drawing. Create a mapping template from an existing mapping. If you have a mapping that you want to use as a basis for the mapping template, use the PowerCenter Export Wizard to export an existing mapping to an XML file, and then create a mapping template drawing from the exported XML file.

Creating a Mapping Template from a New Drawing


Use the mapping objects from the Data Integration Stencil to create a mapping template. Figure 1-1 shows how to create a mapping template drawing from a new drawing:
Figure 1-1. Creating a Mapping Template from a New Drawing
Data Stencil for Visio Create a New Drawing. Use Data Integration Stencil to draw a mapping template. Mapping Template Drawing

Creating a Mapping Template from a Mapping


To create a mapping template from a PowerCenter mapping, you must export the mapping from the PowerCenter Client to an XML file. Then create a mapping template from the XML file.

Chapter 1: Understanding Data Stencil

Figure 1-2 shows the method to create a mapping template drawing from an existing mapping:
Figure 1-2. Creating a Mapping Template Drawing from a Mapping
PowerCenter Client Mapping Export Mapping XML Data Stencil for Visio Create Template Mapping Template from XML Drawing

Step 2. Publish a Mapping Template


After you create a mapping template, save the mapping template drawing, and then publish the template. When you publish the template, Data Stencil generates files required to create multiple PowerCenter mappings. When you publish the mapping template drawing, Data Stencil creates the following files:

Mapping template XML file. Use this file to generate multiple mappings with the Import Mapping Template wizard. Mapping template parameter file. Use this file to generate multiple mappings with the mapgen command line program. You can also use this file to save the parameter values that you specify with the Import Mapping Template Wizard.

Figure 1-3 shows the method to create mapping template files:


Figure 1-3. Publishing a Mapping Template
Data Stencil for Visio

Mapping Template Drawing

Publish template.

Mapping Template XML File Mapping Template Parameter File

Step 3. Generate Mappings from Template Files


After you generate the mapping template files, you can generate and import mappings into PowerCenter Designer. You can generate and import the mappings into PowerCenter in one of the following ways:

Use the Import Mapping Template Wizard. A wizard in the PowerCenter Client that generates and imports mappings into the repository. Use the mapgen command line program. A program that generates an mapping XML file that you can import into the PowerCenter Client. The mapping XML file contains an XML representation of the generated mappings.

Using Data Stencil

Using Import Mapping Template Wizard


You can use the Import Mapping Template Wizard to specify parameters, generate mappings and import the mappings into the repository. Figure 1-4 shows the method to generate and import mappings with the Import Mappings Template Wizard:
Figure 1-4. Creating and Importing Mappings with the Import Mapping Template Wizard
PowerCenter Client Generate and import mapping. (Mapping Template Import Wizard)

Mapping Template XML File

Mappings

Using the mapgen Command Line Program


You can use mapgen to generate mappings from the mapping template. After you publish the template, specify the parameter values for the mappings you want to generate in the mapping template parameter file. After specifying parameter values, use the mapgen command line program to create a mapping file. The mapping file is an XML representation of the generated mappings. After you create the mapping file, use the PowerCenter Import Wizard to import the mapping file into the repository. Figure 1-5 shows the method to create and import mappings with the mapgen command line program:
Figure 1-5. Creating and Importing Mappings with mapgen and the Import Wizard
Mapping Template Drawing File Updated Mapping Template Parameter File Exported Source and Target Definitions Generate mapping file. (mapgen) Mapping File

PowerCenter Client Import Mappings

Chapter 1: Understanding Data Stencil

Data Stencil for Visio Interface


Data Stencil uses the Microsoft Office Visio interface. Typically, you do not need to use any tool other than those provided in the Data Integration toolbar and the Data Integration stencil. However, if you are an expert in the Visio software, you may find that you can use the Visio tools to help you complete the mapping template more easily and quickly. Figure 1-6 shows the Data Stencil for Visio window:
Figure 1-6. Data Stencil Window

Data Integration Toolbar

Drawing Window

Data Integration Stencil

When you work with a mapping template, you use the following main areas:

Data Integration stencil. Displays shapes that represent PowerCenter mapping objects. The Data Integration stencil contains the following mapping objects:

Source definitions Target definitions Link Transformations

Data Integration toolbar. Displays buttons for tasks you can perform on a mapping template. It also displays the online help button. You can perform the following tasks with the Data Integration toolbar:

Create a template from a mapping XML file. Validate a template. Publish a template. Arrange objects in the drawing window.

Data Stencil for Visio Interface

Declare mapping parameters and variables. Show all parameters.

Drawing window. Work area for the mapping template. Data Stencil for Visio initially displays an empty drawing window.

Chapter 1: Understanding Data Stencil

Chapter 2

Working with Mapping Templates in Data Stencil


This chapter includes the following topics:

Overview, 10 Starting Data Stencil, 11 Using the Data Integration Toolbar, 12 Using the Data Integration Stencil, 14 Creating a Mapping Template, 15 Using Parameters in a Mapping Template, 18 Configuring Mapping Objects in a Mapping Template, 19 Tips, 22 Example Mapping Template, 26

Overview
Data Stencil for Visio provides a Data Integration stencil and a Data Integration toolbar. The Data Integration stencil contains mapping object shapes that you can use to create a mapping template. The Data Integration toolbar contains button that help you complete the tasks to create a mapping template. You can create a mapping template drawing in Data Stencil in one of the following ways:

Create a mapping template drawing from scratch. Create a mapping template drawing from an existing mapping. Source definition. Represents the data source. Transformation. Represents PowerCenter transformation objects that perform different types of data transformation. Target definition. Represents the target. Links. Connects sources, targets, and transformations, and specifies the rules for data movement.

Use the following mapping objects in the mapping template drawing:


10

Chapter 2: Working with Mapping Templates in Data Stencil

Starting Data Stencil


To use Data Stencil, you must install the PowerCenter Client. The PowerCenter installer installs Data Stencil in the same folder as other PowerCenter Client tools. You can start Data Stencil in one of the following ways:

Launch Data Stencil from the Windows Start menu. Click Start > Programs > Informatica PowerCenter [version] > Client >PowerCenter Data Stencil. Run the MappingTemplate.vst file. Go to the Data Stencil folder and double-click the file MappingTemplate.vst file:
<PowerCenterInstallationDir>\client\MappingTemplate\MappingTemplate.vst

When you start Data Stencil, Visio displays an empty drawing window. After you save a Mapping Template drawing ([template name].vsd), you can double-click the drawing file to start Data Stencil. You can also open an existing drawing file after Data Stencil is open. Data Stencil displays the mapping template on the drawing window.
Warning: Do not start Microsoft Office Visio and then open the MappingTemplate.vst. If you

start Visio and then click File > Open > MappingTemplate.vst, you open the MappingTemplate.vst file for editing. If you try to create a mapping template after opening the MappingTemplate.vst file for editing, you might encounter unexpected behavior. If you save the mapping template to the MappingTemplate.vst file, you can cause inconsistencies in Data Stencil. Do not edit the MappingTemplate.vst file.

Macros in Data Stencil


Data Stencil contains unsigned macros. Set the security level in Visio to Medium so you can enable macros when you start Data Stencil. If the security level for Microsoft Office Visio is set to high or very high, you cannot run the Data Stencil macros. To set the security level for the Visio, select Tools > Macros > Security from the menu. On the Security Level tab, select Medium. When you start Data Stencil, Visio displays a security warning about viruses in macros. Click Enable Macros to enable the macros for Data Stencil.

Starting Data Stencil

11

Using the Data Integration Toolbar


You can use the buttons on the Data Integration toolbar to perform the following tasks:

Create a template from a mapping XML. Validate a template. Publish a template. Arrange objects in the drawing window. Declare mapping parameters and variables. Show all parameters.

Creating a Template from a Mapping XML File


If you have a PowerCenter mapping that you want to use as a basis for a mapping template, you can export the mapping to an XML file and create a mapping template from the XML file. Data Stencil for Visio creates a diagram with the mapping objects and links that are included in the mapping. You can modify the diagram and set up new rules and parameters in the drawing window. To create a template from a mapping XML file, click the Create Template from Mapping XML button on the Data Integration toolbar.

Validating a Mapping Template


Use Data Stencil to verify that the diagram meets all the requirements for a valid mapping template and displays a message about its validity. To validate a mapping template, click the Validate Mapping Template button on the Data Integration toolbar.

Publishing a Template
To use a mapping template to create multiple mappings, you must publish the template. When you publish a template, Data Stencil creates the following files:

Mapping template XML. The mapping template XML file contains details about the template. The Import Mapping Template Wizard uses the mapping template XML file to create multiple mappings. Do not edit the mapping template XML file. Mapping template parameter file. Use the mapping template parameter file to define parameter values. When you publish a mapping template, Data Stencil creates a mapping template parameter file ([template name]param.xml) based on the name of the mapping template.

To publish a template, click the Publish Template button on the Data Integration toolbar.

12

Chapter 2: Working with Mapping Templates in Data Stencil

Arranging Objects in the Drawing Window


You can manually arrange the mapping objects in the drawing window, or Data Stencil for Visio can arrange the objects for you. Data Stencil for Visio arranges the shapes on the drawing window in the best way to show the mapping objects and their links clearly and logically. To arrange the mapping objects in a Mapping Template drawing file, click the Arrange All button on the Data Integration toolbar.

Declaring Parameters and Variables


Mapping parameters and variables are used in PowerCenter sessions. If you declare mapping parameters and variables, you can reuse a mapping by changing the parameter and variable values of the mapping in the session. Mapping parameter and variable names start with two dollar signs ($$): $$ParameterName. You can declare mapping parameters and variables in a mapping template. Data Stencil for Visio includes all mapping parameters and variables when you generate mappings from the mapping template. To declare mapping parameters in a mapping template, click the Declare Mapping Parameters and Variables button on the Data Integration toolbar.
Note: The mapping template parameter ($ParameterName$) is not the same as the PowerCenter mapping parameter ($$ParameterName).

Showing All Parameters


You can view the list of all parameters used in the mapping template. The list includes all parameters used in transformation properties, link rules, expressions, or groups. The parameter names are enclosed by the dollar sign ($): $ParameterName$. To show the mapping template parameters in a template, click the Show Parameters button on the Data Integration toolbar.

Using the Data Integration Toolbar

13

Using the Data Integration Stencil


The shapes in the Data Integration stencil represent the PowerCenter mapping objects that you can use in a mapping template. The stencil includes shapes for the following mapping objects:

Source definition Target definition Link Transformations

Transformations
You can configure the following transformations in Data Stencil:

Aggregator Expression Filter Joiner Lookup Rank Router Sequence Generator Sorter Source Qualifier Transaction Control Union Update Strategy

The Data Integration stencil does not include shapes for all PowerCenter transformations. Data Stencil for Visio creates mapping templates based on the transformations that are included in the Data Integration stencil.

14

Chapter 2: Working with Mapping Templates in Data Stencil

Creating a Mapping Template


You can create a mapping template from a new drawing file or by using an existing PowerCenter mapping.

Create a Template from a New Drawing


The Data Integration Stencil contains mapping objects you can use to create a mapping template. To create a mapping template drawing, complete the following steps: 1. 2. 3. Start Data Stencil. Verify that the Data Integration Stencil and toolbar are available. Drag the Data Integration Shapes to the drawing window. Use the shape to create visual representation of the mapping. Create links from the source definition through the transformations to the target definition. Create links that connect each mapping object to another. The Lookup transformation is the only mapping object that can be unconnected. Create the rules for the links. Make sure that the rules you set are valid for all the mappings you plan to create from the template and the sources and targets you plan to use in the mappings. Use parameters to make the rules more flexible and the mapping template more generic. Configure the properties of the mapping objects. Add any group or expression required by the transformations in the mapping template. If you want to create multiple mappings, you must set a parameter for either the Source or Target Table property of the source or target definition. You can set parameters for both the Source and Target properties. Optionally, declare mapping parameters and variables to use when you run the mappings in PowerCenter. After you import the mappings created from the mapping template into PowerCenter, you can use the mapping parameters and variables in the session or workflow. Validate the mapping template. Validate the mapping template to identify errors in the mapping object configuration. Publish the mapping template. Save changes to the mapping template drawing file (.vsd) and then publish the mapping template. When you publish the template, Data Stencil generates a mapping template XML file (.xml) and a mapping template parameter file (param.xml). After you publish the mapping template, close Data Stencil. If you make any change to the mapping template drawing after publishing, you need to publish the mapping template again. Do not edit the mapping template XML file.

4.

5.

6.

7. 8.

Use one of the following mapping generation options to create mappings from a published mapping template:

Import Mapping Template Wizard. The wizard takes you through the process to define parameter values and import the mappings into the repository.
Creating a Mapping Template 15

mapgen Command Line Utility. The mapgen utility generates a mapping file from the mapping template drawing file and mapping template parameter file. You can import this mapping file into the repository.

Create a Mapping Template from an Existing Mapping


If you have a PowerCenter mapping that you want to use as a basis for a Visio drawing, you can export the mapping to a mapping XML file and then use the mapping XML file to create a mapping template. You cannot create a drawing from a mapping that contains unsupported transformations. The Lookup transformation is the only reusable transformation that you can use in a mapping template. When you create a mapping template from a PowerCenter mapping, verify that the mapping does not contain any reusable transformation other than the Lookup transformation. To create a drawing from a mapping file, complete the following steps: 1. 2. 3. In PowerCenter, export a mapping. In the PowerCenter Designer tool, select the mapping that you want to base the mapping template on and export it to an XML file. Start Data Stencil. Verify that the Data Integration Stencil and toolbar are available. Create a template from a mapping file. On the Data Integration toolbar, click Create Template from Mapping XML. Data Stencil determines the mapping objects and links included in the mapping and adds the appropriate objects to the drawing window. Save the drawing file. Save the drawing file as a .vsd file. Create or verify links from the source definition through the transformations to the target definition. Create or verify that links connect each mapping object to another. The Lookup transformation is the only mapping object that can be unconnected. Create the rules for the links. Make sure that the rules you set are valid for all the mappings you plan to create from the template and the sources and targets you plan to use in the mappings. Use parameters to make the rules more flexible and the mapping template more generic. Configure the properties of the mapping objects. Add any group or expression required by the transformations in the mapping template. If you want to create multiple mappings, you must set a parameter for either the Source or Target Table property of the source or target definition. You can set parameters for both the Source and Target properties. Optionally, declare mapping parameters and variables to use when you run the mappings in PowerCenter. After you import the mappings created from the mapping template into PowerCenter, you can use the mapping parameters and variables in the session or workflow.
Note: If the mapping you use to create the template contains mapping parameters and variables, it is possible that the mapping parameters and variables ($$ParameterName) may not work for all mappings you plan to create from the mapping template. Modify or

4. 5.

6.

7.

8.

16

Chapter 2: Working with Mapping Templates in Data Stencil

declare new mapping parameters and variables appropriate for running the new mappings created from the mapping template. 9. Validate the mapping template. Validate the mapping template to identify errors in the mapping object configuration.

10. Publish the mapping template. Save changes to the Visio drawing file (.vsd) and then publish the mapping template. When you publish the template, Data Stencil generates a mapping template XML file (.xml) and a mapping template parameter file (param.xml). After you publish the mapping template, close Data Stencil. If you make any changes to the mapping template drawing after publishing, you will need to publish the mapping template again. Do not edit the mapping template XML file. Use one of the following mapping generation options to create mappings from a published mapping template:

Import Mapping Template Wizard. The wizard takes you through the process to define parameter values and import the mappings into the repository. mapgen command line program. The mapgen program generates a mapping file from the mapping template drawing file and mapping template parameter file. You can import this mapping file into the repository.

Creating a Mapping Template

17

Using Parameters in a Mapping Template


You can create more than one mapping from a mapping template. You can use many different sources and targets with different port names in the mappings you create. Each mapping that you create from the template uses the same mapping objects, but you may need to configure each mapping object in a different way. Use parameters in the mapping template rules and configuration to set different values for each mapping. For example, you plan to create three mappings from the same mapping template. Each mapping uses a different source table. When you configure the source definition in the mapping template, you can set the value of the Source Table property to a parameter. Then, when you specify parameter values, define the three mappings and set the value of the parameter for the source table for each mapping to the specific source table name. When you define a mapping template parameter, enclose the name in dollar signs ($), such as $ParameterName$. Data Stencil recognizes any character string that starts with $ and ends with $ as a mapping template parameter name. The mapping template parameter name is case sensitive and can contain letters, numbers, or underscores (_). Provide a unique parameter name for each parameter. Data Stencil does not validate that parameter names are unique in the mapping template. To view a list of all the parameter values specified in a template, click the Show Parameters button on the Data Integration toolbar. Create parameters to represent the following mapping template components:

Mapping object properties. To configure a mapping object in a different way for each mapping, specify parameters instead of specific values when you set the properties.
Note: If you want to create multiple mappings, you must set a parameter for either the

Source or Target Table property of the source or target definition. You can set parameters for both the Source and Target properties.

Expressions. You can use a parameter as part of an expression or in place of an expression. Rules. You can use a parameter as part of any rule in a link. In a Parameter rule, you can include one or more rules in a parameter. Group names. To use different group names for different mappings, specify parameters instead of values when you set the group name.

Note: The mapping template parameter ($ParameterName$) is not the same as the PowerCenter mapping parameter ($$ParameterName).

18

Chapter 2: Working with Mapping Templates in Data Stencil

Configuring Mapping Objects in a Mapping Template


You can configure the properties of a transformation in a mapping template as you would configure the properties of a transformation in a mapping. Configure the transformations in a mapping template so that they work correctly for all the mappings that you plan to create from the mapping template. You must specify a name or use a parameter for the transformation name of each mapping object, except for source and target definitions. You may want to use parameters to handle different settings for transformations in multiple mappings. For example, you can use a parameter in the SQL query of a source qualifier. When you configure the source qualifier in the mapping template, set the value of the property to a parameter:
SQL Query=$SQL_QUERY$

In the mapping template parameter file, set the value of the parameter to the SQL statement appropriate for the mapping:
$SQL_QUERY$=SELECT * FROM EMPLOYEE

Or, you can include a parameter when you set the SQL query:
$SQL_QUERY$=SELECT * FROM $SRC_TABLE$

In the mapping template parameter file, set the value of the parameter to the source table name:
$SRC_TABLE$=EMPLOYEE

To configure the mapping object in the mapping template, double-click the object in the drawing window. The mapping object properties available for a transformation in Data Stencil are the same properties available for mapping objects in the PowerCenter Designer.

Expressions in Transformations
When you configure the following transformations, you must create expressions for the output ports:

Aggregator transformation Expression transformation Rank transformation

When you configure these transformations, you can enter an expression on the Configuration tab in the Transformation Details window. Data Stencil does not validate the expression. Make sure that you enter a valid expression. When you create an expression, use the following guidelines:

Do not use semicolons in an expression. The precision and scale values must be integers that do not exceed 10 digits.
Configuring Mapping Objects in a Mapping Template 19

The value of the precision must be greater than the scale.

By default, the ports for which you create the expressions are output ports. When you create the expression for a transformation port, you can change the port type to variable.

Using the %ALL% Keyword in an Expression


When you add an expression to a transformation, you can use the %ALL% keyword in the port name and in the expression. The %ALL% keyword acts as a placeholder for the names of all ports in the transformation. Use the %ALL% keyword if you have a number of ports for which you want to use the same expression. When you use the %ALL% keyword in the port name and expression, Data Stencil performs the following tasks:

Creates an output port with the same name for each input port in the transformation. To avoid duplicate ports in the transformation, use a prefix or suffix with the %ALL% keyword. Data Stencil creates output ports with the input port names plus the prefix or suffix. Sets up the same expression for all output ports. The datatype that the expression returns becomes the datatype of the output ports.

The following example shows an Aggregator transformation where the %ALL% keyword is used in the aggregate expression:

The input ports for the transformation have the following names:

PRICE COST QTY_ON_HAND

20

Chapter 2: Working with Mapping Templates in Data Stencil

The Aggregator transformation will have the following output ports:


Port Name AVG_PRICE_out AVG_COST_out AVG_QTY_ON_HAND_out Datatype Decimal Decimal Decimal Expression AVG(PRICE) AVG(COST) AVG(QTY_ON_HAND)

With the %ALL% keyword, you can also use a precision of 0 (zero). When you use a zero precision, the output ports will have the same precision as the input port from which it is created

Groups in Multi-Group Transformations


You must set up groups when you configure the following multi-group transformations:

Router transformation Union transformation

You can set up groups on the Configuration tab in the Transformation Details window. You must associate the groups you define in a multi-group transformation with the rules you create in links that connect to the transformation.

Configuring Mapping Objects in a Mapping Template

21

Tips
This section provides tips to help you avoid problems when you create mapping templates in Data Stencil.

Using a Joiner Transformation


The Joiner transformation joins data from two sources, one of which is designated as the master pipeline and the other as the detail pipeline. In Data Stencil, there must be two links that connect to a Joiner transformation. When you create the links to the Joiner transformation, you must ensure that the ending ports do not have duplicate names. For example, you have two sources with the same port names that you want to link to a Joiner transformation. If both the master and detail links use the All Ports rule, the ending ports will have duplicate names, as shown in the following situation:

The master link contains starting port names A, B, and C and the link uses the All Ports rule. Therefore, the starting ports link to ending port names A, B, and C. The detail link contains starting port names A, B, and E and the link uses the All Ports rule. Therefore, the starting ports link to ending port names A, B, and E.

The input ports in the Joiner transformation will have the port names A, B, C, A, B, E. Ports A and B are duplicate port names and are therefore invalid. If the master and detail links contain the same starting ports, use the Named Port, Pattern, or Dictionary rules to ensure that ending ports will contain unique port names. Avoid using All Ports, Primary Key, Foreign Key, and Datatype rules which link starting ports to ending ports with the same name. To ensure that there are no duplicate port names in the Joiner transformation, you can use a Pattern rule similar to the following pattern:
Link Master Link Pattern Starting port pattern: [A-Za-z_][A-Za-z_0-9]* Ending port pattern: $0_1 Starting port pattern: [A-Za-z_][A-Za-z_0-9]* Ending port pattern: $0_2 Port Names Starting ports A links to ending port A1. Starting ports B links to ending port B1. Starting ports C links to ending port C1. Starting ports A links to ending port A2. Starting ports B links to ending port B2. Starting ports C links to ending port C2.

Detail Link

Using a Lookup Transformation


When you configure the Lookup transformation, you must set the Lookup condition property. The lookup condition must have the following syntax:
<LookupTableColumnName> <operator> <TransformationPort>

You can use one of the following operators or combination of operators:


=, <, <=, >, >=, != 22 Chapter 2: Working with Mapping Templates in Data Stencil

Do not use any other combination of operators. The following operators are invalid and will generate errors when you create mappings from the template:
=>, =<, <>

Data Stencil does not validate the Lookup condition. You must ensure that you use the correct syntax for the condition. You can include a connected or unconnected Lookup transformation in a mapping template. For an unconnected Lookup transformation, you must set the following required properties:

Input ports. Enter a list of input ports separated by commas. Return port. Enter the return port for the transformation.

Default values appear for many of the properties.

Using a Router Transformation


A Router transformation evaluates data based on one or more conditions and routes the rows of data that meet each condition into a separate output group. Optionally, you can route rows of data that do not meet any of the conditions to a default output group. When you configure a Router transformation, you may define one or more router groups. These groups have the same ports.When you generate mappings from the mapping template, unique numeric suffixes are assigned to the names of the output ports in each group.

Tips

23

The suffix follows the order in which the groups are listed in the Router configuration window. For example, you define the following router groups for a Router transformation in the mapping template:

When you generate mappings from a mapping template, PowerCenter assigns the following suffixes to the groups:
Group DEFAULT Suffix 1 Examples OutputPortA1 OutputPortB1 OutputPortC1 OutputPortA2 OutputPortB2 OutputPortC2 OutputPortA3 OutputPortB3 OutputPortC3

LONDON_GROUP

SEATTLE_GROUP

24

Chapter 2: Working with Mapping Templates in Data Stencil

When you create the rules for the links that start from a Router transformation, you must identify the group associated with the link. The rules must refer to port names with the suffix for the associated group. If you set up rules that refer to port names with the suffix for another group, you cannot generate mappings from the mapping template.

Tips

25

Example Mapping Template


In this example, you use parameters and rules to turn an existing mapping into a mapping template. Complete the following steps: 1. 2. 3. Create a mapping template drawing from a mapping XML file. Define parameters and rules. Publish the mapping template.

Step 1. Creating a Mapping Template Drawing


After you export the mappings from the PowerCenter repository, you can create a mapping template drawing of the mapping by using the Create Template from Mapping XML function in Data Stencil. The mapping template appears in the Visio drawing window. The following example shows a mappings in the drawing window:

The drawing above uses the mapping objects provided by the Data Integration stencil. The source is a flat file containing the following employee data: Employee Number, First Name, Last Name, Gender, and Ethnic Group. The mapping loads the employee numbers into the target.

26

Chapter 2: Working with Mapping Templates in Data Stencil

You want to create a mapping template because you need to create multiple mappings that use the same mapping objects, but have different sources, targets, or data extraction logic.

Step 2. Define Parameter and Rules


Use parameters and rules in the template to define different logic for each mapping. To define parameters, complete the following steps: 1. 2. Set parameters for the source and target definitions. Use a parameter in a Link rule to specify which data to load into the target.

To set parameters for the source and target definitions, double-click on each mapping object and then specify a parameter for the Source Table and Target Table. The following example shows the source table definition properties:

Next, set a parameter for the link rule to specify which source data moves on to the target. To update the rule, double-click on the link between the source qualifier and the target. The following example shows a list of the defined Link rules between the source qualifier and the target:

Example Mapping Template

27

The Link rules that appear are based on the original mapping. Since all the mappings that you plan to generate do not load the same source data into the target, you can use parameters. To create a parameter that specifies the data loaded into the target, complete the following steps: 1. 2. Delete existing Link Rule(s) that exist between the source qualifier and the target. Create a new rule with a parameter.

28

Chapter 2: Working with Mapping Templates in Data Stencil

The following example shows a link rule with parameters for the named port:

The new Named Port link rule should contain two parameters, one for the source port ($start$) and one for the target port ($end$). When you define the $start$ and $end$ parameter values, you can enter the source and target port names for each mapping that Data Stencil generates.

Step 3. Publish the Mapping Template


After you complete the mapping template, click Validate Template to check if the template is valid. When you are ready to create mappings from the mapping template, click Publish Template. When you click Publish Template, Data Stencil creates the mapping template XML file and the mapping template parameter files that you can use to import mappings into repository.

Example Mapping Template

29

30

Chapter 2: Working with Mapping Templates in Data Stencil

Chapter 3

Mapping Template Rules

This chapter includes the following topics:


Overview, 32 Creating and Configuring Rules, 33 All Ports, 38 Datatype, 39 Dictionary, 40 Foreign Key, 41 Named Port, 42 Parameter, 44 Pattern, 46 Primary Key, 47

31

Overview
When you create a link between mapping objects, you must also create a set of rules to indicate the movement of data from one mapping object to the next. Every link in a mapping template must have an associated rule set. A rule set can have one or more rules. Table 3-1 describes the rules that you can create in the mapping template:
Table 3-1. Mapping Template Rules
Rule Name All Ports Datatype Dictionary Foreign Key Named Port Parameter Pattern Primary Key Description Links all the ports in a mapping object to all the ports in another mapping object. Links all the ports of the selected datatype in a mapping object to all ports of the same datatype in another mapping object. Links specified starting and ending ports based on the contents of a referenced text file. Links all foreign key ports in a mapping object to foreign key ports with the same names in another mapping object. Links all ports with the specified names in a mapping object to ports with the specified name in another mapping object. Replaces the rules on a link with the rules included in the parameter you specify. Links all ports in a mapping object with names that match the specified starting port pattern to all ports in another mapping object with names that match the specified ending port pattern. Links the primary key port in a mapping object to the primary key port with the same name in another mapping object.

32

Chapter 3: Mapping Template Rules

Creating and Configuring Rules


Rules determine how mapping objects are linked for each mapping that is generated from the mapping template.

Rule Order
You can set the order in which Data Stencil evaluates the rules in a rule set. The order of the rules affects the list of ports for which Data Stencil creates links. After you create the rules for a rule set, you can change the order in which you want Data Stencil to evaluate them. Data Stencil evaluates the rules from top to bottom and creates one link for each port. Two rules can affect the same port. For example, a Named Port or a Foreign Key rule at the bottom of the rule set may override a Named Port rule at the top of the list. Table 3-2 shows an example list of starting ports for a link:
Table 3-2. Example List of Ports
Port Name ITEM_ID ITEM_NAME ITEM_DESC PRICE DISCONTINUED_FLAG MANUFACTURER_ID DISTRIBUTOR_ID Foreign key Foreign key Port Type Primary key String String Decimal Boolean Datatype

Creating and Configuring Rules

33

The following table shows how Data Stencil evaluates the rules in a rule set. Based on the example ports in Table 3-2 on page 33, Data Stencil creates links for the example rule sets:
This rule set... All Ports Named:ITEM_DESC (TO) DESCRIPTION Named:PRICE (TO) ITEM_PRICE DataType:decimal Creates these links... ITEM_ID links to ITEM_ID ITEM_NAME links to ITEM_NAME ITEM_DESC links to DESCRIPTION PRICE links to PRICE DISCONTINUED_FLAG links to DISCONTINUED_FLAG MANUFACTURER_ID links to MANUFACTURER_ID DISTRIBUTOR_ID links to DISTRIBUTOR_ID Note: The Named Port rules for ITEM_DESCRIPTION and PRICE override the All Ports rule. However, the Datatype rule overrides the Named Port rule for PRICE. Named:ITEM_DESC (TO) DESCRIPTION Named:PRICE (TO) ITEM_PRICE Pattern:[A-Za-z_][A-Za-z_0-9]*_ID$ (TO) NEW_$0 All Ports ITEM_ID links to ITEM_ID ITEM_NAME links to ITEM_NAME ITEM_DESC links to ITEM_DESC PRICE links to PRICE DISCONTINUED_FLAG links to DISCONTINUED_FLAG MANUFACTURER_ID links to MANUFACTURER_ID DISTRIBUTOR_ID links to DISTRIBUTOR_ID Note: The All Ports rule overrides all previous rules. Pattern:^ITEM.*_.*$ (TO) $0_IN Primary Key Foreign Key ITEM_ID links to ITEM_ID ITEM_NAME links to ITEM_NAME_IN ITEM_DESC links to ITEM_DESC_IN MANUFACTURER_ID links to MANUFACTURER_ID DISTRIBUTOR_ID links to DISTRIBUTOR_ID Note: The Primary Key rule overrides the Pattern rule for ITEM_ID.

Including or Excluding Rules


When you create a rule, you can include or exclude ports that conform to a rule. If you select the Include option, Data Stencil sets up a link for all the starting ports that conform to the rule. If you set up more than one rule in a rule set, Data Stencil sets up links for the list of starting ports that conform to rules, based on the order of the rules. After you set up rules to create the list of ports to link, you can set up a rule with the Exclude option that removes ports from the list. The order in which an exclusion rule appears in a rule set is important. An exclusion rule can exclude ports only from the list of included ports. Therefore, an exclusion rule is valid only when it follows one or more rules that create links for ports. You cannot set up a rule set that contains only an exclusion rule. You cannot set up a rule set where the first rule is an exclusion rule. When you create a rule set that contains rules with the Include or Exclude options, Data Stencil evaluates the rules in the order they are listed.
34 Chapter 3: Mapping Template Rules

The following table shows how Data Stencil evaluates the rules in rule sets that contain exclusion rules. Based on the example ports in Table 3-2 on page 33, Data Stencil creates links for the example rule sets:
This rule set... All Ports Named:ITEM_DESC (TO) DESCRIPTION Named:PRICE (TO) ITEM_PRICE DataType:decimal EXCLUDE Foreign Key Creates these links... ITEM_ID links to ITEM_ID ITEM_NAME links to ITEM_NAME ITEM_DESC links to DESCRIPTION PRICE links to PRICE DISCONTINUED_FLAG links to DISCONTINUED_FLAG Note: The All Ports rule creates links for all ports. The Named Port rules for ITEM_DESC and PRICE override the All Ports rule. The Datatype rule overrides the Named Port rule for PRICE. The Exclude Foreign Key rule removes the links for the foreign key ports. Named:ITEM_DESC (TO) DESCRIPTION Named:PRICE (TO) ITEM_PRICE EXCLUDE Pattern:^ITEM.*$ (TO) $0 PRICE links to ITEM_PRICE Note: The Named Port rules create links for ITEM_DESC and PRICE. However, the Exclude Pattern rule removes the link for ports that start with the string ITEM. ITEM_NAME links to ITEM_NAME_IN ITEM_DESC links to ITEM_DESC_IN MANUFACTURER_ID links to MANUFACTURER_ID DISTRIBUTOR_ID links to DISTRIBUTOR_ID Note: The Pattern rule creates links for ITEM_ID, ITEM_NAME, and ITEM_DESC. However, the Exclude Primary Key rule removes the link for ITEM_ID. The Foreign Key rule creates links for MANUFACTURER_ID and DISTRIBUTOR_ID.

Pattern:^ITEM.*_.*$ (TO) $0_IN EXCLUDE Primary Key Foreign Key

Multi-Group Transformations
Many transformations have one group of input ports and one group of output ports. You do not have to specify the group with which to associate a rule. Some transformations can have multiple input or output groups. You can use the following multi-group transformations in Data Stencil:

Router transformation Union transformation

When you set up a rule on a link for a multi-group transformation, you must specify the group to which you want to associate the rule. For example, a Router transformation has one input group but can have more than one output group. You create a link from a Source Qualifier transformation to a Router transformation and a link from the Router transformation to a target definition. When you create a rule on the link from the Router transformation to the target definition, you must specify the Router group to associate with the rule.

Creating and Configuring Rules

35

When you set up groups for a transformation, Data Stencil adds the group name enclosed in curly brackets ( {} ) to any rule associated with a group. For example, if you set up an All Ports rule in a link that connects from a Router transformation, Data Stencil adds the router group name in front of the rule:
{SEATTLE_GROUP}All Ports

Creating Rules for a Link


You must create a rule for each link in the mapping template.
To create link rules: 1.

On the drawing window, double-click a link. The Link Rules window appears.

2.

Enter a name for the rule set. You cannot include spaces in the Rule Set Name.

3.

Click New Rule.

36

Chapter 3: Mapping Template Rules

The Define Link Rule dialog box appears.

Appears for links connected to multi-group transformations, such as a Router transformation.

4. 5.

If you want to exclude starting ports that conform to the rule, select the Exclude option. Select the rule you want to add to the rule set:

For a Named Port rule, enter the starting and ending port names. For a Datatype rule, select the datatype. For a Pattern rule, enter the starting and ending port patterns. For a Dictionary rule, select the dictionary text file. For a Parameter rule, you can select any defined parameter except source and target parameters.

6. 7. 8. 9.

If the link connects to a Router or Union transformation, enter the group name. Click OK to save the rule. To add another rule, click New Rule on the Link Rules window. After you create all the rules you require for the link, click OK on the Link Rules window to save the rule set.

Creating and Configuring Rules

37

All Ports
The All Ports rule links all ports in a mapping object to all ports in another mapping object. For example, if you set up an All Ports rule on the link between a source definition to a source qualifier, Data Stencil creates ports in the source qualifier with the same names and properties as those in the source definition. Data Stencil also creates links between ports of the same name.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
All Ports

38

Chapter 3: Mapping Template Rules

Datatype
The Datatype rule links all ports of the selected datatype in a mapping object to all ports of the same datatype in another mapping object. You can select the following datatypes:

binary date/time decimal double integer nstring ntext real small integer string text

For example, if you create a Datatype rule on a link from a source definition to a source qualifier and select the integer datatype, then the source qualifier will include all datatype integer ports of the source definition. The ports on the source qualifier will have the same names and properties as the source definition and links are established between ports of the same name.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
DataType:<Datatype>

Datatype

39

Dictionary
The Dictionary rule links starting ports with specified names to ending ports with the specified names. The Dictionary rule looks for the list of port names in a text file. When you create a Dictionary rule, you must provide the name of the text file. Use the Dictionary rule when you want to use the Named Port rule for a large number of ports. Unlike the Named Port rule, you cannot use parameters or a combination of parameter and character string to specify the name of a port in the text file for the Dictionary rule.

Format for the Dictionary Text File


Use the following syntax to specify the starting ports and ending ports in the text file for the Dictionary rule:
<StartingPortName> = <EndingPortName>

For example, the following list is valid content for a Dictionary rule text file:
ITEM_NAME = ITEM_NAME ITEM_PRICE = ITEM_PRICE_OUT

The following list is invalid:


$PORT_NAME$ = $PORT_NAME$_OUT $START_PORT$ = $END_PORT$

The name of the text file can be any valid Windows file name. Data Stencil does not validate the text file. Verify that the dictionary text file contains rules with valid syntax.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
Dictionary:<PathName>\<TextFileName>

40

Chapter 3: Mapping Template Rules

Foreign Key
The Foreign Key rule links all foreign key ports in a mapping object to foreign key ports with the same names in another mapping object. For example, if you set up a Foreign Key rule on the link from a Filter transformation to a target definition, Data Stencil creates all foreign key ports in the target definition with the same names and properties as the Filter Transformation. Data Stencil also creates links between foreign key ports of the same name.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
Foreign Key

Foreign Key

41

Named Port
The Named Port rule links all ports with the specified names in a mapping object to ports with the specified name in another mapping object. You can use parameters instead of character strings to specify the name. You can also combine a parameter and a character string to specify the name. If you use parameters, you must provide the parameter value in the parameter file you generate for the mapping template. You cannot include spaces in port names.
Note: If the ending port name is blank, the starting port links to an ending port with the same name.

Table 3-3 describes how you can specify port names in a Named Port rule:
Table 3-3. Named Port Rule
Parameter or String Starting Port: ITEM_NAME Ending Port: <blank> Starting Port: ITEM_NAME Ending Port: PRODUCT_NAME Starting Port: ITEM,CODE Ending Port: <blank> Starting Port: ITEM,CODE Ending Port: ITEM_DESC,ITEM_ID Starting Port: $PORT_NAME$ Ending Port: <blank> Description Starting port named ITEM_NAME links to an ending port ITEM_NAME. Starting port named ITEM_NAME links to an ending port PRODUCT_NAME. Starting port named ITEM links to an ending port named ITEM. Starting port named CODE links to an ending port named CODE. Starting port named ITEM links to an ending port named ITEM_DESC. Starting port named CODE links to an ending port named ITEM_ID. Starting port with a name that matches the value of the $PORT_NAME$ parameter links to the ending port with the same name. You must provide the parameter value in the mapping template parameter file. The parameter value can include a comma-separated list of port names. Examples of parameter values:
<PARAM NAME="$START_PORT$" VALUE="PORT1" /> <PARAM NAME="$END_PORT$" VALUE="" />

Starting port named PORT1 links to an ending port named PORT1.


<PARAM NAME="$START_PORT$" VALUE="PORT1,PORT2" /> <PARAM NAME="$END_PORT$" VALUE="" />

Starting port named PORT1 links to an ending port named PORT1. Starting port named PORT2 links to an ending port named PORT2. Starting Port: $PORT_NAME$ Ending Port: $PORT_NAME$ Starting port with a name that matches the value of the $PORT_NAME$ parameter links to the ending port with the same name. You must provide the parameter value in the mapping template parameter file.

42

Chapter 3: Mapping Template Rules

Table 3-3. Named Port Rule


Parameter or String Starting Port: $PORT_NAME$ Ending Port: IN_$PORT_NAME$ Description Starting port with a name that matches the value of the $PORT_NAME$ parameter links to the ending port with the same name prefixed by IN_. You must provide the parameter value in the mapping template parameter file. For example, you set the parameter value in the parameter:
<PARAM NAME="$PORT_NAME$" VALUE="ITEM_NAME" />

Starting port named ITEM_NAME links to an ending port named IN_ITEM_NAME. Starting Port: $START_PORT$ Ending Port: $END_PORT$ Starting port with a name that matches the value of the $START_PORT$ parameter links to the ending port with a name that matches the value of the $END_PORT$ parameter. You must provide the parameter value in the mapping template parameter file. The parameter value can include a comma-separated list of port names. Examples of parameter values:
<PARAM NAME="$START_PORT$" VALUE="ITEM_NAME" /> <PARAM NAME="$END_PORT$" VALUE="PRODUCT_NAME" />

Starting port named ITEM_NAME links to an ending port named PRODUCT_NAME.


<PARAM NAME="$START_PORT$" VALUE="PORT1,PORT2" /> <PARAM NAME="$END_PORT$" VALUE="PORTA,PORTB" />

Starting port named port1 links to an ending PORT1 named PORTA. The starting port named PORT2 links to an ending port named PORTB.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
Named:<StartingPortName|ParameterName> (TO) <EndingPortName|ParameterName>

Named Port

43

Parameter
The Parameter rule replaces the rules on a link with the rules included in the parameter you specify. When you set up a Parameter rule, select the name of a parameter from the list of mapping template parameters. The value of the parameter must be a set of rules that you want to use for the link. You must configure rules with the same syntax that is displayed on the Link Rules window:

Use this syntax to list the rules in a Parameter rule.

The rules must be separated by semicolons (;). Use a Parameter rule when the rules for a link between two transformation objects change from mapping to mapping. For example, you can set up a parameter named $REPLICATION_RULES$ and provide the following value in the parameter file:
<PARAM NAME="$REPLICATION_RULES$" VALUE="Primary Key;Named:$COL1$ (TO) $COL2$;DataType:date/time" />

Data Stencil expands the Parameter rule to separate rules and evaluates the rules in the order they are listed. You can provide different parameter values for the $REPLICATION_RULES$ for each mapping you create from the mapping template.

Limitations
You cannot include the following types of rules in a Parameter rule:

Parameter rule. You cannot include a Parameter rule within a Parameter rule. Rules with associated groups. You cannot include rules for links that connect to multigroup transformations such as a Router transformation. For example, you cannot include the following rule in a Parameter rule:
{GROUPA}Named:ITEM_DESC (TO) DESCRIPTION

44

Chapter 3: Mapping Template Rules

Exclusion rule. You cannot include a rule with the Exclude option enabled. For example, you cannot include the following rule in a Parameter rule:
EXLUDE Foreign Key

Parameter

45

Pattern
The Pattern rule links all ports in a mapping object with names that match the specified starting port pattern to all ports in another mapping object with names that match the specified ending port pattern. Do not include spaces in port pattern names. To set up a Pattern rule, you must use a regular expression (regex) pattern. A regular expression is a specialized formula for matching text strings that follow a pattern. Set up a Pattern rule only if you are familiar with the regex syntax. Table 3-4 shows examples of regex patterns and the port names that match the patterns:
Table 3-4. Pattern Rule
Regex Pattern Starting Port Pattern: _IN$ Ending Port Pattern: <blank> Starting Port Pattern: ^EMP.*_.*$ Ending Port Pattern: $0 Starting Port Pattern: ^EMP.*_.*$ Ending Port Pattern: $0_IN Starting Port Pattern: [\d]$ Ending Port Pattern: $0 Starting Port Pattern: [A-Za-z_][A-Za-z_0-9]* Ending Port Pattern: x_$0 Example Port Names that Match or Do Not Match the Pattern GENDER_IN links to GENDER ETHNIC_GROUP_IN links to ETHNIC_GROUP EMPLOYEE_ID and EMPLOYEE_NAME do not match the starting port pattern. EMPLOYEE_ID links to EMPLOYEE_ID EMPLOYEE_NAME links to EMPLOYEE_NAME GENDER and ETHNIC_GROUP do not match the starting port pattern. EMPLOYEE_ID links to EMPLOYEE_ID_IN EMPLOYEE_NAME links to EMPLOYEE_NAME_IN GENDER and ETHNIC_GROUP do not match the starting port pattern. EMPLOYEE_NAME1 links to EMPLOYEE_NAME1 GENDER1 links to GENDER1 EMPLOYEE_ID and ETHNIC_GROUP do not match the starting port pattern. EMPLOYEE_ID links to x_EMPLOYEE_ID EMPLOYEE_NAME links to x_EMPLOYEE_NAME GENDER links to x_GENDER ETHNIC_GROUP links to x_ETHNIC_GROUP

Syntax
Use the following syntax when you include this rule in a Parameter rule:
Pattern:<StartingPortPatternString> (TO) <EndingPortPatternString>

46

Chapter 3: Mapping Template Rules

Primary Key
The Primary Key rule links the primary key port in a mapping object to the primary key port with the same name in another mapping object. For example, if you set up a Primary Key rule on the link from a source definition to a source qualifier, Data Stencil creates the primary key port in the source qualifier with the same name and properties as the source definition. Data Stencil also creates links between ports of the same name.

Syntax
Use the following syntax when you include this rule in a Parameter rule:
Primary Key

Primary Key

47

48

Chapter 3: Mapping Template Rules

Chapter 4

Using the Import Mapping Template Wizard


This chapter includes the following topics:

Overview, 50 Before You Begin, 51 Step 1. Select the Mapping Template, 53 Step 2. Specify Parameter Values, 54 Step 3. Select Mappings to Generate, 56 Step 4. Import Mappings, 58 Example Using Mapping Template Import Wizard, 60

49

Overview
If you have the mapping generation option, you can create one or more mappings based on published mapping templates created using Data Stencil for Visio. The Mapping Template Import Wizard uses the mapping template XML file to generate mappings. You can use the Import Mapping Template Wizard to perform the following tasks:

Select the published mapping template. Specify parameter values. Select mappings to generate. Import mappings into the repository.

50

Chapter 4: Using the Import Mapping Template Wizard

Before You Begin


To use the Import Mappings Template Wizard, verify that the source and target definitions that you want to use in the mappings meet the following requirements:

Source and Target definitions exist in the repository. The Import Mapping Template Wizard uses an XML version of the source and target to create mappings from the mapping template. If the Import Mapping Template Wizard cannot access the source and target definitions, the wizard does not generate the mappings. Source definitions in the active repository folder have unique names. The Import Mapping Template Wizard looks in the active folder to provide a list of valid source objects. If there are multiple source definitions with the same name, duplicate source names appear, and mapping generation may fail.

Export Source and Target Definitions


The Import Mapping Template Wizard looks for the source and target definitions in the following location: <PowerCenterInstallationDir>\client\MappingTemplate\tabledefs You can export source and target definitions to this folder in the following ways:

Use the PowerCenter Export Wizard to manually export the source and target definitions. Use the Import Mapping Template Wizard to automatically export source and target definitions based on parameter values.

The Import Mapping Template Wizard prompts you to export source or target definitions that are specified in parameters to the default location. If you plan to use the Import Mapping Template Wizard, and the Source Table property does not use a parameter to set its value, you must manually export the source definition. If a source or target definition already exists in the table definition location and you do not want to overwrite the current exported version, you can choose not to export the source or target definition. If you export the table definitions manually, ensure that you save the definitions in the correct location.
Note: If you use a Lookup transformation in a mapping template, you must manually export the lookup source. The Import Mapping Template Wizard does not export the source that the Lookup transformation references.

Reference Source Definitions with Unique Names


When you define the parameter values for the Source Table property of the source definition, the Import Mapping Template Wizard looks in the active folder to provide a list of valid source objects. Each source in the active folder must have a unique name. The Import Mapping Template Wizard treats source definitions with the same name as duplicates when they appear under different database types of the same active repository folder.

Before You Begin

51

If you have two source definitions with the same name, create the source objects in different folders. If you select a source definition that is duplicated in the list of source objects that the Import Mapping Template Wizard displays, the mapping generation may fail.

52

Chapter 4: Using the Import Mapping Template Wizard

Step 1. Select the Mapping Template


In the first step of the Mapping Template Wizard, select the mapping template that you want to use.
To start the Import Mapping Template Wizard: 1. 2. 3.

Open the Designer and connect to the repository. Open the folder that contains the source and target objects required for your mappings. Select Tools > Import Mapping Template. The Import Mapping Template Wizard appears.

4. 5. 6.

Click Browse. Navigate to the location where the mapping template was saved. Click Next.

Step 1. Select the Mapping Template

53

Step 2. Specify Parameter Values


This step displays all parameters for the selected mapping template. You must specify all parameter values for each mapping you want to generate.
To configure parameter values for each mapping: 1.

If you want to use an existing mapping template parameter file, click Use Existing. Then navigate to the location where the parameter file is stored. If the selected parameter file does not include the same parameters as the parameters configured in the mapping template, the following error appears:
<filename> is not valid for current mapping template.

The Import Mapping Template Wizard displays the list of parameters set up in the mapping template.
2. 3.

Click the Add Mapping button to define a mapping and specify the values for the parameters. Specify a mapping name and description, and enter values for all parameters used in the mapping template. Source and target parameters display the list of available sources and targets in the active folder. Select the source and target you want to use for the mapping.

54

Chapter 4: Using the Import Mapping Template Wizard

4.

Repeat steps 1 and 2 for each mapping you want to create. -orUse the Copy mapping button and Paste mapping button to replicate existing mapping configurations. Add and edit the parameter values for each new mapping you want to define.

5.

Click Next.

Note: You must define at least one mapping before you can proceed to the next step.

Step 2. Specify Parameter Values

55

Step 3. Select Mappings to Generate


This step displays the list of mappings you configured. You can select the mappings that you want to generate. If you select the Save parameter values for the selected mapping option, you can reuse the mapping template parameter file to create more mappings. The wizard saves the parameter values for each mapping you selected in the mapping template parameter file.
Note: Always save the parameter values to a mapping template parameter file. If you do not save the parameter file and an error occurs when generating the mappings, you cannot retrieve the parameter value settings for each mapping you configured.
To select the mappings you want to generate: 1. 2.

Select the mappings you want to generate. If you want to save the parameter values for the selected mappings, select Save parameter values for the selected mappings and then click Browse to navigate to the folder where you want to save the parameter file. By default, the Publish Template function creates a mapping template parameter file in the same location as the mapping template file. You can choose to overwrite the existing file or create a new mapping template parameter file.

56

Chapter 4: Using the Import Mapping Template Wizard

3.

Click Next. The wizard prompts you to export table definitions.

4.

Click Yes. The Export Object dialog box appears and the table definitions are exported to the default location.

5.

Click Close on the Export Objects dialog box.

Step 3. Select Mappings to Generate

57

Step 4. Import Mappings


This step displays the number of mappings that the wizard generated and the status of each mapping.
To import the mappings: 1.

Review the list to verify that the wizard generated the correct number of mappings.

2.

Click Import. If there is any conflict while importing the mappings, the Conflict Resolution Wizard appears. The generated mappings appear in the mappings folder of the selected repository folder.

Understanding Mapping Status Messages


On step 4, a status message appears for each mapping configuration selected for mapping generation. This section describes common mapping status messages. TableDefinitionNotFoundException Error: <Table Name> Cause: Source or Target definitions are not available in the tabledefs folde r.

58

Chapter 4: Using the Import Mapping Template Wizard

Action:

Export the source or target definition to the tabledefs folder. Then, use the Import Mapping Template Wizard to create the mappings.

RuleNot SupportedException: Unknown Rule <Rule Name> Cause: Action: The parameter values specified for the rules are invalid. Review and fix the parameter values settings. Then, use the Import Mapping Template Wizard to create the mappings.

If no message appears and no mapping is generated, then one possible cause is source or target values were set incorrectly when you defined parameter values. You should review and fix the parameter values settings. Then, use the Import Mapping Template Wizard to create the mappings.

Step 4. Import Mappings

59

Example Using Mapping Template Import Wizard


In this example, you use the mapping template XML file to create two PowerCenter mappings. To create multiple mappings from a mappings template, complete the following steps: 1. 2. 3. Select the mapping template. Specify parameter values. Select mappings to generate, and import the mappings.

Step 1. Select the Mapping Template


In the PowerCenter Designer, connect to the repository, and select the folder that contains the source and target definitions required for the mappings you want to generate. Then click Tools > Import Mapping Template. After the Import Mappings Template Wizard appears, select the mapping template XML file that you want to use.

Step 2. Specify Parameters in the Mapping Template


After you select the mapping template, use parameters to create two mappings. The parameters that you defined in the mapping template appear in the wizard. You configured the following parameters in the mapping template:

$end$. This parameter defines the target port. $start$. This parameter defines the source port that contains the data required in the target $Source$. This parameter defines the source table.

Create two mappings with different values for the $end$ and $start$ fields. Enter the same value for the $source$ field.

60

Chapter 4: Using the Import Mapping Template Wizard

The following example shows the settings for the two mappings you want to create:

These settings create two mappings that use the same source table, but extract different data and load the data to different ports of the same target table.

Step 3. Generate and Import Mappings


The wizard displays all the mappings you configured. To generate both mappings, leave both mappings selected.

Example Using Mapping Template Import Wizard

61

The following example shows two mappings selected:

Before you import the mappings, the wizard asks you to export the table definitions. Since you did not manually export the source or target definitions to the tabledefs folder, you must export the definitions when prompted. After you import the mappings, the mappings appear in the mapping folder of the selected repository folder.

62

Chapter 4: Using the Import Mapping Template Wizard

Chapter 5

Using the mapgen Command Line Program


This chapter includes the following topics:

Overview, 64 Using Source and Target Files with mapgen, 65 Manually Updating Mapping Template Parameters, 66 Running the mapgen Command Line Program, 69 Example Using mapgen Command Line Program, 71

63

Overview
If you have the mapping generation option, you can create one or more mappings based on published mapping templates you created using Data Stencil for Visio. Before you run mapgen, verify that you have created a Visio drawing file for the mappings you want to generate. To create mappings from a mapping template, complete the following steps: 1. Export the source and target definitions. In the PowerCenter Designer or Repository Manager, export the source and target definitions that you plan to use in the mapping template. Edit the parameter file for the mapping template. The Publish Template function in Data Stencil for Visio creates a mapping template parameter file. The parameter file must provide the values for all parameters used in the mapping template. Each mapping you want to create must be defined in the parameter file. Create mapping file. mapgen creates a mapping file (.xml) that you can import into the PowerCenter repository. The mapping file contains an XML representation of the mappings defined in the mapping template and parameter file. Import the mapping file into the PowerCenter repository. After mapgen creates the mapping file, go to the PowerCenter Repository Manager or Designer to import the mapping file into the PowerCenter repository.

2.

3.

4.

mapgen File Requirements


mapgen requires the following files:

Mapping template drawing file. After you create the mapping template drawing file in Data Stencil for Visio, you must save it as a Visio drawing file with a .vsd extension. mapgen reads the Visio drawing file to determine the transformations and link rules for the mappings it creates based on the mapping template. Mapping template parameter file. When you publish the mapping template, Data Stencil creates a mapping template parameter file. Edit the parameter file to provide the values for the mapping parameters. mapgen reads the mapping template parameter file to determine the values of the parameters used in the mapping template. Source and target definition files. The mapping template does not include the definitions for sources and targets. You must export the source and target definitions from PowerCenter. mapgen reads the source and target definition files to determine the source and target table properties and columns to use in the mappings it creates based on the mapping template.

64

Chapter 5: Using the mapgen Command Line Program

Using Source and Target Files with mapgen


When mapgen evaluates the rules in the mapping template, it requires the names and properties of the columns available in the source and target tables. mapgen uses the column names and properties to determine the ports in the mapping transformations that conform to the rules. Therefore, you must make the source and target table definitions available to mapgen. When you export the source and target definitions, use the following guidelines:

mapgen looks for all the source and target table definition files in one folder. By default, it looks for the files in the Data Stencil table definition folder:
\<PowerCenterInstallationDir>\Client\MappingTemplate\tabledefs

If you export the source and target table definition files into a different folder, you must supply the folder path name when you run mapgen.

mapgen requires all XML files in the folder to be valid PowerCenter XML files that comply with the powrmart.dtd. mapgen reads all XML files in the directory. To ensure that mapgen can read all XML files in the folder, keep only valid PowerCenter XML files in the table definition folder. Since mapgen reads all files in the table definition folder, you can export multiple source definitions to one XML file. For example, the folder can contain one XML file that describes five sources or five XML files that each describe one source definition. mapgen uses the first definition it finds in the table definition folder. For example, if you have ASources.xml that has a source definition for EMPLOYEE and BSources.xml that also has a source definition for EMPLOYEE, mapgen uses the first EMPLOYEE source definition it finds. Even if the source definitions are from different folders or databases and they have different columns and properties, mapgen may use the wrong table definition for the mapping. Create separate folders for table definitions with the same names but different properties to ensure that mapgen uses the correct table definition for the mapping. Then supply the appropriate folder name when you run mapgen.

Note: If you use a Lookup transformation in the mapping template, you must export the lookup source.

Using Source and Target Files with mapgen

65

Manually Updating Mapping Template Parameters


When you publish a mapping template, Data Stencil creates a mapping template XML file and a mapping template parameter file. The mapping template parameter file contains the parameters set up in the mapping template and is located in the same folder as the mapping template file. You must modify the mapping template parameter file to provide the values for the mapping template parameters. If you want to create more than one mapping from the mapping template, modify the parameter file so that it contains as many mapping definitions as you require. Then provide the parameters values for each mapping. The mapping template parameter file has an associated Document Type Definition (DTD) file called parameters.dtd. When you create the mappings based on the mapping template, the parameter file is validated against parameter.dtd. When you modify the parameter file, make sure that the XML file conforms to the structure of parameter.dtd.

Parameter File Requirements


The following XML file is an example mapping template parameter file:

Parameter Properties Mapping Properties Parameter Values for the Mapping

The mapping template parameter file requires the following information:


Parameter properties. Contains the repository name. It is required for each parameter file. Mapping properties. Contains the name, description, and location of the mapping to be created. This property is required for each mapping in the parameter file. Parameter values. Values required for each mapping in the parameter file.

Parameter Properties
The parameter file requires the name of the repository where you plan to import the mappings defined in the parameter file. You set the REPOSITORY_NAME property once

66

Chapter 5: Using the mapgen Command Line Program

for each parameter file. All mappings defined in the parameter file will have the same repository name.

Mapping Properties
You must set the following properties for each mapping in the parameter file:

NAME. Name of the mapping. FOLDER_NAME. Name of the repository folder where you plan to import the mapping. DESCRIPTION. Description of the mapping.

All mapping properties are required.

Parameter Values
Use mapping template parameters to set different values for properties, expressions, port names, and other mapping elements that may vary for each mapping. You must set the value for each mapping template parameter that you define. Each PARAM element defines a parameter name-value pair. You set the parameter name in the mapping template. You then set the value for the parameter in the parameter file.

Modifying the Parameter File


The mapping template parameter file is an XML file. Modify it in the same way you modify HTML and other text files. When you install PowerCenter, the installer installs the DTD for the mapping template parameter file. To view the DTD for the parameter file, go to the following directory and locate the file named parameter.dtd:
<PowerCenterInstallationDir>\client\MappingTemplate\dtd

The number of MAPPING elements in the parameter file equals the number of mappings you want to create from the mapping template.
To modify the parameter file: 1. 2. 3.

Locate the mapping template parameter file for the mapping template you want to use. Open the mapping template parameter file with a text editor. Search for the following string in the file:
<PARAMETERS REPOSITORY_NAME=

4. 5.

Set the REPOSITORY_NAME property to the name of the repository where you plan to import the mappings. Search for the following string in the file:
<MAPPING NAME=

6.

Set the following required mapping properties:

Name of the mapping


Manually Updating Mapping Template Parameters 67

7.

Folder name in the repository where you plan to import the mappings Description of the mapping

Search for the following string in the file:


<PARAM NAME=

8. 9.

Set the mapping template parameters to values appropriate for the mapping. If you want to create more than one mapping from the same mapping template, add as many copies of the MAPPING element to the parameter file as you require and set the parameters to the values appropriate for each mapping. Save the parameter file and close it.

10.

68

Chapter 5: Using the mapgen Command Line Program

Running the mapgen Command Line Program


Use the mapgen command line program to create the mappings from a mapping template. mapgen uses the following syntax:
mapgen <-t> VisioDrawingFile <-p> ParameterFile <-o> MappingFile [-d] TableDefinitionDir

Table 5-1 describes the mapgen options and arguments:


Table 5-1. mapgen Options and Arguments
Option -t Argument VisioDrawingFile Required/ Optional Required Description Name of the Visio drawing file for the mapping template. The file has a .vsd extension. To create the file, save the mapping template in Data Stencil as a Visio drawing file. If the file is not in the current working folder, add a path name in front of the file name. Name of the mapping template parameter file. Data Stencil automatically creates the parameter file when you publish the mapping template. The filename is <mapping template name>_param.xml. If the file is not in the current working folder, add a path name in front of the file name. Name of the PowerCenter mapping file used to create mappings from the mapping template. The file has a .xml extension. If you do not want to create the file in the current working folder, add a path name in front of the file name. Name of the folder where the source and target definition files are located. Required if the files are not located in the default folder. The default folder for the source and target definition files is
\<PowerCenterInstallationDir>\Client \MappingTemplate\tabledefs

-p

ParameterFile

Required

-o

MappingFile

Required

-d

TableDefinitionDir

Conditional

Before you run mapgen, verify that you have all the files required by the program.
To run the mapgen program: 1.

Close the referenced Visio drawing file before running the mapgen program. If the .vsd file is open when you run mapgen, mapgen generates a warning that the file is open for modification. In the PowerCenter Repository Manager or Designer, export the source and target definitions for the sources and targets you want to use in the mappings to be created by the mapgen program. By default, mapgen looks for the source and target definition files in the following folder:
<PowerCenterInstallationDir>\client\MappingTemplate\tabledefs Running the mapgen Command Line Program 69

2.

If you export the files to another folder, you must provide the folder name when you run the mapgen program.
3. 4.

On the machine where Data Stencil is installed, open a command line window. Go to the Data Stencil folder. The default folder for Data Stencil is
<PowerCenterInstallationDir>\client\MappingTemplate\

5.

Run mapgen.exe. After you generate the mapping file, import the file into the repository to view all the generated mappings.

70

Chapter 5: Using the mapgen Command Line Program

Example Using mapgen Command Line Program


In this example, you use mapgen to generate a two mapping from a mapping template. Perform the following steps to generate PowerCenter mappings and import them into the repository. 1. 2. 3. 4. Export source and target definitions to the tabledefs folder. Edit the parameter file. Run the mapgen command line program. Import the mapping file into the PowerCenter repository.

Step1. Export Source and Target Definitions


Open the PowerCenter Designer or Repository Manager and export the source and target definitions that you plan to use in the mapping template. In this example, you export s_Employees and t_Employees to the following default location:
\<PowerCenterInstallationDir >\Client\MappingTemplate\tabledefs

Step 2. Edit the Parameter File


When you publish the mapping template, Data Stencil creates a parameter file in the same location as the Mapping Template XML file. Locate the parameter file and then edit the file to include the parameter values required for the mappings you want to generate. In the mapping template you specified the following parameters:

$end$. This parameter defines the target port. $start$. This parameter defines the source port that contains the data required in the target. $Source$. This parameter defines the source table.

Now you update the parameter file to create two mapping. Both mappings use the same source, however they extract data different source ports and load data to different ports of the same target. The following code appears in the completed parameter file:
<?xml version='1.0'?> <!DOCTYPE PARAMETERS SYSTEM "parameters.dtd"> <PARAMETERS REPOSITORY_NAME="HR"> <MAPPING NAME="M_EmployeeID" FOLDER_NAME="CRM" DESCRIPTION="M_EmployeeID"> <PARAM NAME="$end$" VALUE="EMPLOYEE_ID" /> <PARAM NAME="$start$" VALUE="EMPLOYEE_NUMBER" /> <PARAM NAME="$Source$" VALUE="s_Employees" /> </MAPPING>

Example Using mapgen Command Line Program

71

<MAPPING NAME="M_EmployeeName" FOLDER_NAME="CRM" DESCRIPTION="M_EmployeeName"> <PARAM NAME="$end$" VALUE="FIRST_NAME" /> <PARAM NAME="$start$" VALUE="EMPL_FIRST_NAME" /> <PARAM NAME="$Source$" VALUE="s_Employees" /> </MAPPING> </PARAMETERS>

Step 3. Run the mapgen Command Line Program


Before you run mapgen, close and save both the mapping template parameter and drawing files. You have the following mapping template files in the folder
<PowerCenterInstallationDir>\client\MappingTemplate\

mt_employee.vsd mt_employee.param.xml Change the directory to the following location: < PowerCenterInstallationDir> \client\MappingTemplate\ Enter the following command:
mapgen -t mt_employees.vsd -p mt_employees_param.xml -o output_employees.xml

Go to the command line and perform the following steps:


mapgen creates the mapping file named output_employees.xml. You use this file to import the new mappings into the repository.

Step 4. Import the Mappings into the Repository


Go to the PowerCenter Designer or Repository Manager and connect to the repository. Then select Repository > Import Objects.

72

Chapter 5: Using the mapgen Command Line Program

The Import Wizard appears.

To import the mappings, select the mapping file output_employees.xml that mapgen created. After you complete the steps in the Import Wizard, the mappings appear in the PowerCenter repository.

Example Using mapgen Command Line Program

73

74

Chapter 5: Using the mapgen Command Line Program

Appendix A

Glossary

This appendix includes the following topic:

Glossary of Terms, 76

75

Glossary of Terms
Data Integration stencil

A template that includes shapes that represent PowerCenter mapping objects such as source definitions, target definitions, link, and transformations.
Data Integration toolbar

A toolbar that displays buttons for tasks you can perform on a mapping template, such as create a template from a mapping XML file, validate a template, publish a template, and declare mapping parameters and variables.
drawing window

Work area for the mapping template. Data Stencil for Visio initially displays an empty drawing window.
Import Mapping Template Wizard

A wizard in the PowerCenter Client that generates mappings from mapping template files and imports them into the repository.
mapgen command line program

A command line program that generates an XML file from mapping template files. Import the XML file into PowerCenter to create the mappings.
mapping template

A diagram in Visio that represents a PowerCenter mapping. Use rules and parameters in a mapping template to specify the transformation logic.
mapping template files

Files that Data Stencil generates when you save or publish a mapping template. Mapping template files include mapping template drawing files, mapping template XML files, and mapping template parameter files.
mapping template drawing file ([template name].vsd)

File that Data Stencil generates when you save a mapping template.
mapping template XML file ([template name].xml)

File that Data Stencil generates when you publish a mapping template, or a mapping template drawing file. Data Stencil also generates mapping template parameter file.

76

Appendix A: Glossary

mapping template parameter file ([template name]_param.xml)

File that Data Stencil generates when you publish a mapping template. Data Stencil also generates mapping template XML file. Use the mapping template parameter file to define and save parameter values.
rule set

Set of rules that indicates how data is moved from one mapping object to the next. Every link in a mapping template must have an associated rule set. A rule set can have one or more rules.

Glossary of Terms

77

78

Appendix A: Glossary

Index

A
All Ports rule description 38 %ALL% keyword using in expressions 20 using with zero precision 21

C
components Data Stencil 3 configuring mapping objects 19

D
Data Integration stencil Data Stencil interface 7, 14 definition 76 mapping objects 14 supported transformations 14 Data Integration toolbar Data Stencil interface 7, 12 definition 76 Data Stencil components 3 description 2

interface 7 starting 11 supported transformations 14 Datatype rule description 39 syntax 39 datatypes available for Datatype rule 39 Dictionary rule description 40 syntax for rule 40 syntax for text file 40 drawing mapping template 15 drawing window arranging objects 13 Data Stencil interface 7 definition 76

E
evaluating include and exclude rules 35 exclude rules 34 expressions in transformations 19 using %ALL% keyword 20 using parameters 18
79

F
Foreign Key rule description 41 syntax 41

G
group names using parameters 18 groups in multi-group transformations 21, 35

I
import mapping template status message 58 Import Mapping Template Wizard definition 76 description 50 include rules 34 interface Data Stencil 7

J
Joiner transformation avoiding duplicate names 22 using in mapping template 22

L
limitations Parameter rule 44 link creating rules 36 Lookup transformation source files 51 using in mapping template 22 valid operators 22

running the program 69 mapgen command line program definition 76 mapping objects arranging 13 configuring 19 Data Integration stencil 14 required in mapping template 10 using parameters 19 mapping parameters See also PowerCenter Designer Guide declaring 13 mapping properties in Data Stencil parameter file 67 mapping template creating mappings 64 definition 76 drawing 15 from a mapping file 12 Import Mapping Template Wizard 50 required mapping objects 10 tips in creating 22 using the wizard 50 validating 12 mapping template drawing file definition 76 mapping template files definition 76 mapping template parameter file definition 77 mapping template parameters showing all 13 using 18 mapping template rules See rules mapping template XML file definition 76 mapping XML creating from mapping template 64 multi-group transformations requiring groups 35 Router transformation 35 supported 21 Union transformation 35

M
mapgen creating mappings from mapping template 64 description 64 guidelines for source and target files 65 requirements 64
80 Index

N
Named Port rule description 42 syntax 43

O
order in evaluating rules 33

P
parameter files mapping properties for Data Stencil 67 mapping template for Data Stencil 66 mapping template requirements for Data Stencil 66 modifying for Data Stencil 67 parameter properties for Data Stencil 66 parameter values for Data Stencil 67 parameter properties in Data Stencil parameter file 66 Parameter rule description 44 limitations 44 parameter values in Data Stencil parameter file 67 $$ParameterName mapping parameters 13 $ParameterName$ mapping template 18 parameters See mapping parameters See mapping template parameters Pattern rule description 46 syntax 46 precision using zero precision with %ALL% keyword 21 Primary Key rule description 47 syntax 47

Datatype rule 39 description 32 Dictionary rule 40 evaluating include and exclude rules 35 Foreign Key rule 41 including or excluding ports 34 Named Port rule 42 order of evaluation 33 Parameter rule 44 Pattern rule 46 Primary Key rule 47 using parameters 18

S
source files exporting 65 Lookup transformation 51 using with mapgen 65 starting Data Stencil 11 suffixes for Router transformation groups 23 syntax Datatype rule 39 Dictionary rule 40 Dictionary rule text file 40 Foreign Key rule 41 Named Port rule 43 Pattern rule 46 Primary Key rule 47

T
tabledefs folder for source and target files 65 target files exporting 65 using with mapgen 65 tips creating a mapping template 22 Joiner transformation in Data Stencil 22 Lookup transformation in Data Stencil 22 Router transformation in Data Stencil 23 transformation properties using parameters 18 transformations See also PowerCenter Transformation Guide multi-group 21, 35 requiring expression 19

R
Router transformation avoiding duplicate names 23 requiring groups 35 using in mapping template 23 rule sets definition for Data Stencil 77 evaluating include and exclude rules 35 rules All Ports rule 38 available in Data Stencil 32 creating 36

Index

81

requiring groups 21 supported in Data Stencil 14

U
Union transformation requiring groups 35

V
validating mapping template 12 Visio drawing 15

W
wizards Import Mapping Template 50

Z
zero precision using with %ALL% keyword 21

82

Index