IBM Directory Integrator 4.7: Reference Guide

IBM Directory Integrator 4.7: Reference Guide

IBM Directory Integrator 4.7: Reference Guide

Note Before using this information and the product it supports, read the general information under Appendix C, Notices on page 189. First Edition (August 2002) This edition applies to ersion 4, release 7, of The IBM Directory Integrator and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2002. All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Preface.............. ii Chapter 1. Introduction........ 1 General concepts............. 1 Program components and interface....... 1 Admin tool.............. 1 IBM Directory Integrator serer....... 1 IBM Directory Integrator components...... 1 IBM Directory Integrator API......... 2 Script objects.............. 2 Chapter 2. Getting Started Guide.... 3 Chapter 3. Supported platforms and known issues............ 5 Chapter 4. IBM Directory Integrator concepts.............. 7 The AssemblyLine............ 7 Starting an AssemblyLine......... 8 Starting from the Admin tool........ 8 Accessing connectors inside the AssemblyLine.. 9 Connectors............... 9 How do Connectors share data?....... 9 Iterator mode............. 10 Multiple Iterators in an AssemblyLine.... 10 Using the Iterator mode......... 10 Lookup mode............ 11 AddOnly mode............ 12 Update mode............. 12 Delete mode............. 13 Passie mode............. 13 Link criteria............. 14 EentHandler............. 15 Starting the EentHandler........ 15 The Eent object............ 16 Configuration and data flow........ 16 Prolog............... 16 Actions............... 16 Attribute/property names........ 17 Epilog............... 17 Scripting............... 17 When is scripting needed?........ 17 Integrating scripting into the AssemblyLine?.. 17 How will scripting affect execution?..... 18 Control points for scripting........ 19 Comparing JaaScript strings....... 20 Accessing your own Jaa classes...... 21 Scripting in JaaScript.......... 22 Scripting in languages without new jaa.*... 22 Using binary alues in scripting...... 22 Using date alues in scripting....... 22 Using floating point alues in scripting.... 23 Hooks................ 23 Enabling/disabling Hooks........ 24 Oerride Hooks............ 24 Failure Hooks............ 24 Hooks called on other eents....... 24 List of Hooks............. 25 Deltas and compute changes........ 28 Deltas............... 28 Inheritance.............. 30 Attribute Mapping............ 30 Null Value Behaior.......... 31 Conn object............. 31 Tasks................ 32 How to control the number of threads.... 33 The configuration file........... 33 Externalizing fields like username and password 33 Export, import and include........ 34 IBM Directory Integrator Secure Sockets Layer Support............... 35 Securing the connection between IBM Directory Integrator and serers with SSL (IBM Directory Integrator as a client).......... 35 Securing the connection between client and IBM Directory Integrator with SSL (IBM Directory Integrator as a serer).......... 36 Replacing security from IBM JCE and JSSE to another ender............ 36 Chapter 5. IBM Directory Integrator installation instructions....... 39 Installing on Windows platforms....... 39 Installing on Unix platforms......... 39 Uninstalling on Windows platforms...... 40 Uninstalling on Unix platforms........ 40 Chapter 6. Connectors........ 41 Connector aailability and reference...... 41 Raw Connectors............ 41 Script-based Connectors......... 43 Configurations............ 43 ADSI Connector............. 43 Preconditions............. 43 Btree Connector............. 46 Configuration............ 46 Btree object............. 46 Downloads............. 47 Command line Connector......... 47 Configuration............ 47 Downloads............. 47 Direct TCP /URL scripting......... 47 TCP................ 47 URL................ 48 EMI/UCP Connector........... 48 Configuration............ 48 Downloads............. 48 See also............... 48 Copyright IBM Corp. 2002 iii

File system Connector........... 48 Configuration............ 48 See also............... 49 FTP Connector............. 49 Configuration............ 49 Note................ 49 See also............... 49 GSM Phone Connector.......... 50 Configuration............ 50 Downloads............. 50 HTTP Client Connector.......... 50 Modes............... 50 Special attributes........... 50 Configuration............ 51 Samples.............. 52 Lookup Mode............ 52 Downloads............. 52 See also............... 52 HTTP Client Connector Version 2....... 52 Changes from earlier ersions....... 52 Modes............... 53 Special attributes........... 53 Configuration............ 54 Samples.............. 54 Lookup Mode............ 54 See also............... 55 HTTP Serer Connector.......... 55 Configuration............ 55 Downloads............. 56 See also............... 56 HTTP Serer Connector Version 2....... 56 Configuration............ 56 See also............... 57 JDBC Connector............. 57 Configuration............ 57 Other............... 58 Notes............... 58 See also............... 59 ODBC specifying database paths directly.... 59 JMS Connector............. 60 Configuration............ 60 Specific topics............ 61 JNDI Connector............. 61 Configuration............ 61 Downloads............. 62 See also............... 62 LDAP Connector............ 62 Configuration............ 62 Notes............... 64 Handling memory problems in the LDAP Connector.............. 64 Duplicating a whole directory from a serer to another............... 65 IBM Directory Changelog Connector..... 65 Lotus Notes Connector.......... 66 Configuration............ 67 Downloads............. 67 Ports............... 67 Security.............. 67 Mailbox Connector............ 68 Configuration............ 68 Predefined Properties/Attributes...... 68 See also............... 69 Memory Stream Connector......... 69 Configuration............ 69 NT4 Connector............. 70 Preconditions............. 70 Character sets............ 73 NT4 Connector functional specifications and software requirements........... 73 Functionality............. 73 Business Objects............ 74 Use cases.............. 78 Hardware and software configuration.... 84 Oracle8 JDBC Drier........... 85 Configuration............ 85 Note................ 85 See also............... 86 (runtime proided) Connector........ 86 Configuration............ 86 Downloads............. 86 See also............... 86 Script Connector............. 86 Predefined script objects......... 87 Functions.............. 87 Configuration............ 88 Note................ 88 See also............... 88 SMPP Connector............ 88 Configuration............ 88 Downloads............. 89 See also............... 89 SNMP Connector............ 89 Configuration............ 89 Notes............... 90 TCP Connector............. 90 Iterator Mode............. 90 AddOnly Mode............ 91 Configuration............ 91 See also............... 91 URL Connector............. 91 Configuration............ 91 Downloads............. 91 See also............... 91 Chapter 7. EentHandlers....... 93 EentHandler types........... 93 When are they started?.......... 93 What do they do?............ 93 EentHandlers............. 94 Listeners: simple EentHandlers....... 94 Connector EentHandler.......... 94 Configuration............ 94 Objects/properties/attributes....... 95 Downloads............. 95 See also............... 95 HTTP EentHandler........... 95 Example.............. 95 Configuration............ 96 See also............... 96 IBM SecureWay LDAPEentHandler...... 96 Configuration............ 97 i IBM Directory Integrator 4.7: Reference Guide

See also............... 98 LDAP EentHandler........... 98 Object Added (objadded)........ 99 Object Rename (objrenamed)....... 99 Object Modified (objmodified)....... 99 Object Remoed (objremoed)....... 99 Configuration............ 100 Notes............... 100 See also.............. 100 Mailbox EentHandler.......... 100 Configuration............ 100 Objects/properties/attributes....... 101 Downloads............. 101 See also.............. 101 TCPEentHandler............ 101 Configuration............ 101 Objects/properties/attributes....... 101 See also.............. 102 Port listener.............. 102 AdminPort (simple EentHandler)..... 102 Generic thread (simple EentHandler).... 103 LDAP listener............ 103 MailboxListener (simple EentHandler)... 104 TCPListener (simple EentHandler)..... 105 Timer EentHandler.......... 105 Chapter 8. Script languages..... 107 BeanShell............... 107 Perl................ 107 Perl example............. 108 Script languages............ 108 BSF-based script languages........ 109 WSH-based script languages....... 109 Chapter 9. Parsers......... 111 Parser aailability and reference....... 111 Base parsers............. 111 Character set conersion.......... 111 Aailability............. 111 CSV parser.............. 112 Configuration............ 112 Notes............... 112 DSML parser............. 113 Configuration............ 113 Example.............. 113 References............. 114 See also.............. 114 CDS-EDB file parser........... 114 Configuration............ 114 Notes............... 114 Fixed parser.............. 114 Configuration............ 114 HTTP parser.............. 114 Configuration............ 114 Attributes/properties.......... 115 See also.............. 116 LDIF parser.............. 116 See also.............. 117 LineReader.............. 117 Configuration............ 117 Regular Expression parser......... 117 Functional specification......... 117 Source code............. 118 Regular Expression parser source code..... 119 Script parser.............. 121 Objects.............. 121 Functions.............. 122 Configuration............ 122 Note............... 122 See also.............. 122 Simple parser............. 122 Configuration............ 123 SOAP parser............. 123 Sample Entry............ 123 Sample SOAP............ 123 Configuration............ 123 Parser-specific calls.......... 124 XML parser.............. 124 Configuration............ 125 Examples.............. 125 Notes............... 127 References............. 127 See also.............. 127 Chapter 10. Objects......... 129 The AssemblyLine Connector object...... 129 The Attribute object........... 130 Methods.............. 130 Examples.............. 131 See also.............. 131 The Raw Connector object......... 131 Methods.............. 132 The Entry object............ 132 Methods.............. 132 Global Entry instances aailable in scripting.. 133 See also.............. 134 The FTP object............. 134 Methods.............. 134 Example.............. 134 Main object.............. 135 The Search criteria object......... 135 Methods.............. 135 Operands.............. 135 Example.............. 136 The shellcommand object......... 136 Methods.............. 136 The status object............ 136 Methods.............. 137 The system object............ 137 Methods.............. 137 The task object............. 141 task AssemblyLine.......... 142 task EentHandler.......... 142 Chapter 11. Program interfaces.... 143 AssemblyLine setting tab......... 143 IBM Directory Integrator command line options 144 IBM Directory Integrator Admin tool.... 144 IBM Directory Integrator serer...... 144 Discoer schemas and browsing data..... 145 Contents

Distribution components......... 145 Other files on install directory....... 145 Jar-files (jars/subdirectory)........ 146 Jaa Naming and Directory Interface (JNDI).. 146 JaaMail API............ 146 XML............... 146 Libraries (Windows) libs/ subdirectory.... 146 Other............... 146 global.properties file.......... 147 JDBC Client.............. 147 Parameter labels on the Connector/parser tabs... 148 LDAP Client............. 148 Preferences/system properties........ 149 System/Jaa properties.......... 149 Using external properties......... 151 Chapter 12. Samples........ 153 VBScript Connector and MSOutlook connector.. 153 Sample code............. 153 See also.............. 155 JaaScript Connector........... 155 Sample code............. 155 See also.............. 155 JaaScript parser............ 156 Sample code............. 156 See also.............. 156 Writing a new Raw Connector........ 156 Script-based Connector......... 156 Jaa-based Connector.......... 156 Building and installing a Jaa-based Connector 157 system.parsedate (string alue, string format).. 159 Example.............. 159 Other examples............ 159 Chapter 13. Logging and debugging 161 AssemblyLine Debugger.......... 161 Logging and debugging.......... 161 Dumping the content of an Entry object... 162 Dumping the content of an Attribute.... 162 Dumping the state of a Connector..... 162 Dumping arbitrary log messages...... 163 Chapter 14. Optional tasks in IBM Directory Integrator 4.7....... 165 Copying directories with the LDAP Connector.. 165 Chapter 15. Optimizing IBM Directory Integrator 4.7........... 167 Chapter 16. IBM Directory Integrator 4.7 Downloads and related material 169 Installation notes............ 169 IBM Directory Integrator 4.7........ 169 Download instructions......... 169 Download 4.7............ 169 New features 4.6........... 169 GUI improements 4.6......... 169 Bugs fixed since 4.6 beta2........ 170 Fixed issues 4.6............. 170 Script libraries not aailable to Listeners... 170 JMS 1.13 can lose queue elements when Iterating.............. 170 JMS MQ Series does not support topics... 170 NT/ADSI Connector can clear passwords during update............ 171 Connectors: Oerride Add hook defect in Update and AddOnly modes....... 171 HTTP EentHandler using Auth Connector.. 171 XML parser limitations......... 171 Memory leak............ 171 Running out of file handles........ 172 If you use https:/ as part of the URL, the AssemblyLine will fail......... 172 In certain situations, the Lotus Domino Connector (and possibly some others) do not run from the Admin Tool........ 172 4.6 Installer fails for some systems..... 172 Backward compatibility......... 172 Known issues 4.6............ 173 Delta on iterator........... 173 Memory leak............ 174 Chapter 17. Release Notes...... 175 Appendix A. FAQ IBM Directory Integrator 4.7........... 177 Questions.............. 177 Installation and licensing........ 177 Writing AssemblyLines......... 177 Security.............. 177 Error messages............ 177 Limitations............. 178 Third party software.......... 178 Answers............... 178 Installation and licensing........ 178 Writing AssemblyLines......... 179 Security.............. 181 Error messages............ 182 Limitations............. 182 Third party software.......... 183 Appendix B. Dictionary of terms... 185 LDAP terms.............. 185 IBM Directory Integrator terms....... 185 Appendix C. Notices........ 189 Trademarks.............. 190 i IBM Directory Integrator 4.7: Reference Guide

Preface In order to work with examples complementing this manual, you must refer back to the installation package to download the necessary files. To access these example files, go to the %IBMDI_ROOT%/sample directory in the installation directories. Copyright IBM Corp. 2002 ii

iii IBM Directory Integrator 4.7: Reference Guide

Chapter 1. Introduction General concepts The following are some of the general concepts that can be found in the IBM Directory Integrator documentation: The AssemblyLine on page 7 Connectors on page 9 Scripting on page 17 Hooks on page 23 Chapter 9, Parsers on page 111 EentHandler on page 15 Deltas and compute changes on page 28 Inheritance on page 30 Attribute Mapping on page 30 Tasks on page 32 The configuration file on page 33 Accessing your own Jaa classes on page 21 Chapter 13, Logging and debugging on page 161 Appendix B, Dictionary of terms on page 185 Program components and interface Admin tool Distribution components on page 145 IBM Directory Integrator command line options on page 144 Preferences/system properties on page 149 System/Jaa properties on page 149 AssemblyLine setting tab on page 143 Discoer schemas and browsing data on page 145 Parameter labels on the Connector/parser tabs. on page 148 JDBC Client on page 147 LDAP Client on page 148 IBM Directory Integrator serer IBM Directory Integrator command line options on page 144 IBM Directory Integrator components Chapter 7, EentHandlers on page 93 Connector aailability and reference on page 41 Parser aailability and reference on page 111 Copyright IBM Corp. 2002 1

IBM Directory Integrator API Script objects Full technical JaaDoc of all aailable internal jaa objects is found in the installation package. Script objects are aailable eerywhere inside the AssemblyLines (proided their context is alid). Some of the major objects are described below: The Attribute object on page 130 The AssemblyLine Connector object on page 129 The Raw Connector object on page 131 The Entry object on page 132 The FTP object on page 134 Main object on page 135 The shellcommand object on page 136 The status object on page 136 The system object on page 137 The task object on page 141 AssemblyLine Debugger on page 161 2 IBM Directory Integrator 4.7: Reference Guide

Chapter 2. Getting Started Guide IBM Directory Integrator 4.7: Getting Started Guide is a brief tutorial and introduction to IBM Directory Integrator 4.7. You need Acrobat Reader to read the IBM Directory Integrator 4.7: Getting Started Guide as it is in PDF format. Copyright IBM Corp. 2002 3

4 IBM Directory Integrator 4.7: Reference Guide

Chapter 3. Supported platforms and known issues IBM Directory Integrator 4.7 ships with IBM JRE 1.3.1. The following are the platforms supported for IBM Directory Integrator 4.7. A minimum of 128 MB RAM is required for each platform (256 MB is strongly recommended): Windows NT 4.0, Windows 2000 AIX 4.3.3, or later Solaris 7, or later HP-UX 11, or later Linux Intel RedHat 7.1 or later SuSE 7.2 or later Linux s/390 RedHat 7.1 or later SuSE 7.0 or later, kernel 2.2.16 Copyright IBM Corp. 2002 5

6 IBM Directory Integrator 4.7: Reference Guide

Chapter 4. IBM Directory Integrator concepts The AssemblyLine The general philosophy of an AssemblyLine, is that it processes data (for example, entries, records, items, objects) from one data source, transform and aggregate it with data from others sources and finally output it to one or seeral targets. It is important to keep in mind that the AssemblyLine is designed and optimized for working with one item at a time. Howeer, if you would like to do multiple updates or multiple deletes (i.e. processing more than a single item at the time) then you must write AssemblyLine scripts to handle this same thing if you want to sort data. This kind of processing can be implemented using your choice of scripts, Jaa libraries and standard IBM Directory Integrator functionality (like pooling the data to a sorted datastore, for example, ODBC Connector) and then reading it back and processing it with a second AssemblyLine. The AssemblyLine consists of a number of Connectors that operate in specific modes. It is the AssemblyLine that does the work (it is in a way your program). For an oeriew of the AssemblyLine please read the Getting Started guide. In short the AssemblyLine consists of: EentHandler. (Optional) An EentHandler that decides when the AssemblyLine runs (could be when a file shows up on a directory or when a mail arries). Connectors. Two or more Connectors that are plugged into your data-source (file system, ldap, database, com-port etc.) At least one Connector proides input to the AssemblyLine, and at least one proides output. A rich Connector library is one of the strength of the IBM Directory Integrator, but you can of course write your own Connectors. The Connectors can be run in different modes like Iterator, Update, Delete etc. AssemblyLines can in fact hae fewer Connectors (this is for the adanced user). Parser. (sometimes) If the Connector deliers a bytestream (such as a url-connector or a file Connector), the Connector has a Parser associated with it. As for Connectors, you can write your own but a set of standard Parsers are aailable. A business body where data from the Connectors are subject to your business logic such as transformation, erification etc. If you leae the body (Prolog, Dataflow and Epilog in the IBM Directory Integrator Admin tool) empty, you hae probably implemented a filter translating from one format to another. This body is not physical, since the code is located in the Connectors. The exception being the Component, that just contains code. The workobject contains attributes that can be shared between Connectors. Mapping between the data source and the work Entry is described in detail under Attribute Mapping on page 30. The AssemblyLine is usually started by some external eent or by the user from the IBM Directory Integrator Admin tool. The AssemblyLine is defined by a file. This file defines a serer that is independent of the Admin Tool Graphical User Interface to run. Copyright IBM Corp. 2002 7

Starting an AssemblyLine The AssemblyLine flow starts with the execution of code placed in the Before Connectors Actiated subtab of the Prolog tab. This could be a good place to create a file one of the Connectors expects (typically the result of a preprocessed input file). You could also place code here which change connector specific parameters, such as filenames. Then Connectors are initialized. Each Connector s initialize function is called in this step. If the Connector operates in Iterator mode, then the Connector s selectentries function is also called. Then, when all Connectors are ready for action, the AssemblyLine s Prolog s After Connectors Actiated code is executed. The Connectors are then called in the sequence in which they appear in the configuration. Think of this as haing each of your data entries flowing down the AssemblyLine. If you hae more than one Connector in Iterator mode, these Connectors are stacked in the order in which they appear in the configuration. If you hae two iterators, a and b, then a is called until it returns no more entries before the AssemblyLine switches to b. If you hae no Connectors in Iterator mode, you must make sure there exists an Entry proided by a calling Handler or set in the Prolog. If no Working Entry exist, no Connectors are called. Controlling an AssemblyLine Hooks can be used to add extra code and logic within a Connector. If you want to skip or re-execute parts of the AssemblyLine entirely, you typically do this from within a Hook in a Connector: (system.ignoreentry) - Ignore the current Connector and continue processing your existing data entry with the next Connector. (system.skipentry) - Skip (drop) the entry completely and get the next entry (from the current iterator). (system.restartentry) - Re-execute the AssemblyLine without getting fresh entry data from the current Iterator. system.skipto(string name) - Skip to the named Connector. system.abortassemblyline(string reason) - Abort the entire AssemblyLine. Note that if you put any of these command in an Error Hook, the AssemblyLine continues regardless of how you got to the Error Hook. This means that een syntax errors in your script are ignored. Check the object if you want to know what caused the error. Also note that the methods aboe are implemented as exceptions: This means that no code following these calls are called. Starting from the Admin tool When you start an AssemblyLine from the admin tool you must hae at least one Connector operating in Iterator mode. If you don t hae an iterator the AssemblyLine has no data feeding it. You can hae multiple Connectors as iterators: The AssemblyLine starts with the first iterator and continue with the next after draining each iterator in the AssemblyLine. 8 IBM Directory Integrator 4.7: Reference Guide

Connectors Starting from an EentHandler or script When an AssemblyLine is started through startal by an EentHandler or from a script, the AssemblyLine may be passed parameters feeding it, e.g. an initial working entry (work). Passing an initial working entry causes the AssemblyLine to run through the list of Connectors once before terminating. You can inestigate the result (which is the working entry when the AssemblyLine terminates) by using the (getresult()) function. See also (runtime proided) Connector on page 86 Example: ar entry = system.newentry(); entry.setattribute ("cn", "My Name"); // Here we start the AssemblyLine itself ar al = main.startal ( "AssemblyLine", entry ); // wait for al to finish al.join(); ar result = al.getresult(); // assume al sets the mail attribute in its working entry task.logmsg ("Returned email = " + result.getstring("mail")); Accessing connectors inside the AssemblyLine You may hae noticed that you can dynamically load Connectors in your scripts using the system.getconnector function. The Connector object you get from that is what we call the raw Connector object. Inside the assembly howeer, each Connector is embedded in a wrapper that proides additional functionality to the Connector. Each Connector is aailable in the AssemblyLine scripts as the name you chose for the Connector when it was added to the AssemblyLine. For example, the Sample1 AssemblyLine in the default configuration has two Connectors named input and output. Connectors are used to access and update information sources in a ariety of formats and protocols. There are basically two types of connectors. The first is where both transport and content is known to the connector using a well known API (like ODBC, LDAP). The second type is where the transport mechanism is known but not the content. The latter requires a Parser to interpret or generate the content in order to function properly. A list of all Connectors included with the IBM Directory Integrator is included (see Connector aailability and reference on page 41). But you can also write your own Connector (see Writing a new Raw Connector on page 156). Connectors operate in the following modes: Iterator, Lookup, AddOnly, Update, Delete and Passie. Each Connector mode determines a specific Connector s behaior. Note howeer, that it is not necessary that eery Connector support all of the modes aailable. When you use a Connector you should first consult its manual for the modes supported. How do Connectors share data? Connectors not in Iterator mode hae their data passed through the work object. If no work object exist because you hae no Iterator, the non-iterator Connectors are not called. You can create your own Working Entry in the Prolog by: Chapter 4. IBM Directory Integrator concepts 9

init_work = system.newentry(); // Create a new Entry object init_work.setattribute("uid", "cchateauieux"); // populate it task.setwork(init_work); // make it known as work to the Connectors Note that an initial work Entry in the Prolog can be regarded as fed from an inisible one pass Iterator. See Multiple Iterators in an AssemblyLine below for side effect this causes. Iterator mode Connectors in Iterator mode are used to scan a data source and extract its data. The Iterator Connector actually iterates through the data source entries, reads their attributes alues and deliers each Entry to the AssemblyLine and its non-iterator connectors. Note that it does not matter exactly what the data source is (database, LDAP directory, XML document, etc.) and how its data is actually stored. Each Connector presents an abstract layer oer the particular data source and you access and process data through instances of the Entry and Attribute classes. In fact, each AssemblyLine (except those called with an initial Entry, see How do Connectors share data? on page 9) should contain at least one Connector in Iterator mode. Iterators (if we call the Connectors in Iterator mode this way) supply the AssemblyLine with data. If an AssemblyLine has no Iterator it is useless because its Connectors are passed nothing to process. Iterators are always regarded as being first in the AssemblyLine. They are executed before other non-iterator Connectors, regardless of their place in the AssemblyLine. Multiple Iterators in an AssemblyLine If you hae more than one Connector in Iterator mode, these Connectors are stacked in the order in which they appear in the configuration and processed one at the time. An initial work Entry is treated as coming from an inisible Iterator processed before any other Iterators. Assume you hae an AssemblyLine with two Iterators, a preceding b. a is first used (the AssemblyLine ignoring b) until it returns no more entries. Then the AssemblyLine switches to b (ignoring a). An initial work Entry is treated like it came from an inisible Iterator before a and b: It would be processed (the AssemblyLine ignoring both a and b), before the AssemblyLine starts calling a. If you do not want an initial work Entry to be used in the AssemblyLine because it contains the wrong Attributes, and has been used for instance in the Prolog, you could call task.setwork(null) in the Prolog to remoe the initial work Entry, thus causing the first Iterator to be used to get the first work Entry. Using the Iterator mode The most common pattern for using a Connector in Iterator mode should be: 1. Add a Connector in Iterator mode to your AssemblyLine. 2. Choose the configure... link from IBM Directory Integrator Admin user interface. 3. Set alues for the Connector s parameters (usually specifying the data source to be used). 4. Go to the Attributes section (tab) of the Configure Connector dialog. 5. Click Connect to connect to the data source. 10 IBM Directory Integrator 4.7: Reference Guide

6. Click Query Schema (or Next if Query Schema is not supported) to retriee an Entry s Attributes. 7. In the Attribute Map Connector s section push the Select button and mark all Attributes you need in your integration process. These Attributes are retrieed from the data source and passed to the non-iterator Connectors in your AssemblyLine. Lookup mode Connectors in Lookup mode are used to retriee particular Entry s attributes from a data source by other most often key Entry s attributes (already retrieed from another data source or set by the Administrator). Lookup Connectors gie the possibility to join data from different data sources using the relations among the entities from these data sources. The main action in setting up and using a Lookup Connector is the configuration of its Link Criteria. It is always configured through the IBM Directory Integrator Admin user interface - each Lookup Connector has an associated Link Criteria tab. The tab defines the rule for finding releant entries. The Link Criteria rule itself is either a conjunction of simple conditions required for certain Entry s attributes or a more general Connector specific mini script. Note that the Link Criteria may identify more than one Entry (these Entries are called Duplicates).Lookup Connectors hae an option that allows/disallows Duplicates. You can control this option from the Allow Duplicates check-box. If Allow Duplicates is turned off (default state) and Duplicates appear then: if the Multiple Entries Found Hook is not enabled, the work Entry being processed is skipped (i.e. not passed to the other Connectors in the AssemblyLine) if the On Error Hook is not enabled. If the On Error Hook is enabled it should handle the situation. if the Multiple Entries Found Hook is enabled, the custom script placed there should handle the situation. If Allow Duplicates is turned on and Duplicates appear then automatically the first of the Duplicates is used. If no additional processing is performed in any of the Hooks aailable, the rest of the Duplicate Entries are ignored. Howeer they can be handled according to user-defined logic by scripting in the Lookup OK Hook. See On Success, page 27 for code example on this. Using the Lookup mode The most common pattern for using a Connector in Lookup mode should be: 1. Add a Connector in Lookup mode to your AssemblyLine. 2. Choose the configure... link from IBM Directory Integrator Admin user interface. 3. Set alues for Connector s parameters (usually specifying the data source to look up in). 4. Go to the Attributes section (tab) of the Configure Connector dialog. 5. Push the Connect button to connect to the data source. 6. Push the Query Schema button (or the Next button if Query Schema is not supported) to retriee Entry s Attribute. 7. In the Attribute Map Connector s section (tab) push the Select button and mark all Attributes you need in your integration process (these include the Attributes used for looking up). 8. In the (Link Criteria) tab of the Connector, add all criteria for looking up. Chapter 4. IBM Directory Integrator concepts 11

9. All new Attributes added from the Lookup Connector along with the Attributes added from preious Iterator and Lookup Connectors are aailable for the other Connectors in the AssemblyLine. AddOnly mode Connectors in AddOnly mode are used for adding new data in a data source. This Connector mode requires almost no configuration - just point out the attributes of the Entry and the data source parameters. The AddOnly Connector receies Entries (most often from an Iterator) and writes them in its data source. Using the AddOnly mode The most common and simple pattern for using a Connector in AddOnly mode should be: 1. Add a Connector in AddOnly mode to your AssemblyLine. 2. Choose the configure... link from IBM Directory Integrator Admin user interface. 3. Set alues for Connector s parameters (usually specifying the output data source to be used). 4. In the Connector s Attribute Map section, click Select and mark all working Attributes you need in your integration process. You can also create your own Attributes and calculate their alues through scripting. Entries with the Attributes you hae selected are added in the data source during AssemblyLine s execution. Update mode Connectors in Update mode are used for adding and modifying data in a data source. For each Entry passed from the AssemblyLine, the Update Connector tries to locate an Entry from the data source to modify with the Entry s attributes alues receied. The rule for finding the Entry for modification is configured in the Link Criteria section in the same format as in the Lookup mode. If no such Entry is found, a new Entry is added to the data source. If one such Entry is found, it is modified. If more than one entry matches the Link Criteria, the Multiple Entries Found Hook is called. Furthermore, each attribute can be tuned whether to be modified or added, when respectiely Modify or Add operation is performed. When doing a Modify operation, only those attributes that are marked as Modify, are changed in the data source. If the Entry passed from the AssemblyLine does not hae a alue for one attribute, the Null Value Behaior for that attribute becomes significant. If it is set to Delete, the attribute does not exist in the modifying entry, thus the attribute cannot be changed in the data source. If it is set to NULL, the attribute exists in the modifying entry, but with a null alue, which means that the attribute is deleted in the data source. An important feature that Update Connectors offer is the Compute Changes option. When turned on, the Connector first checks the new alues against the old ones and updates only if and where needed. Thus you can skip unnecessary updates which can be really aluable if the update operation is a heay one for the particular data source you are updating. Using the Update mode The most common and simple pattern for using a Connector in Update mode should be: 1. Add a Connector in Update mode to your AssemblyLine. 12 IBM Directory Integrator 4.7: Reference Guide

2. Choose the configure... link from IBM Directory Integrator Admin user interface. 3. Set alues for Connector s parameters (usually specifying the output data source to be used). 4. Go to the Attributes section (tab) of the Configure Connector dialog. 5. Push the Connect button to connect to the data source. 6. Push the Query Schema button (or the Next button if Query Schema is not supported) to retriee Entry s Attributes. 7. In the Attribute Map Connector s section push the Select button and mark all Attributes you need to update in your integration process. Through the Add and Modify check-boxes you can specify for each Attribute whether it should be modified or added when respectiely Modify or Add operation is performed. 8. In the Link Criteria tab of the Connector, add all criteria for fixing the Entry to be updated (or finding out that it is missing and has to be added). Entries Attributes you hae selected are updated in the data source during AssemblyLine s execution. Delete mode Connectors in Delete mode are used for deleting data from a data source. For each Entry passed from the AssemblyLine, the Delete Connector tries to locate an Entry from the data source. If one Entry is found, it is deleted, otherwise nothing happens. The rules for finding the Entry for deletion is configured in the Link Criteria section in the same format as in the Lookup mode. Using the Delete mode The most common and simple pattern for using a Connector in Delete mode should be: 1. Add a Connector in Delete mode to your AssemblyLine. 2. Choose the configure... link from IBM Directory Integrator Admin user interface. 3. Set alues for Connector s parameters (usually specifying the output data source to be used). 4. In the Link Criteria tab of the Connector, add all criteria for locating the Entry to be deleted. If exactly one Entry matches the Link Criteria, it is deleted. 5. The Attribute Map section is ignored for a Connector in Delete mode. Passie mode Connectors in Passie mode are not passed Entries during the AssemblyLine execution. They are configured by the Administrator and initialized by the AssemblyLine, but neer used in the standard AssemblyLine s execution process. They can be inoked by script code from any of the control points for scripting proided by IBM Directory Integrator (see Scripting on page 17). Using the Passie mode The most common and simple pattern for using a Connector in Passie mode should be: 1. Add a Connector in Passie mode anywhere in your AssemblyLine. 2. Set alues for the Connector s parameters (usually specifying the output data source to be used). The name of the Connector is used to refer to it from other Connectors. Chapter 4. IBM Directory Integrator concepts 13

3. Add scripting code to use the Connector, usually in Hooks in other Connectors (it could be in a Script Component or prolog/epilog as well). If you hae named the Passie Connector MyPassie and want it to add an entry with an error message, the code may look like this: ar err = system.newentry(); err.merge(work); err.setattribute ( "ERROR", "Failed to do something" ); MyPassie.connector.putEntry ( err ) ; 4. The methods aailable to the connector attribute of the Passie Connector, are documented in The Raw Connector object on page 131. The instructions aboe assume that you only want to use the Raw Connector and Parser components of the Passie mode Connector. If you also want to use the Attribute Mapping and Hooks that the Connector proides, you can do the following instead: 1. Add the Connector in the mode that matches the way you are going to use it. 2. Specify the Attribute Mapping and the Hooks you want. 3. Change the mode of the Connector to Passie. The attribute mapping is remembered. 4. You may now use the calls aailable to the Connector, e.g. MyPassie.lookup(myEntry). The parameter specified is treated as the work entry by the Passie Connector. 5. Note that the local work entry reference is set to myentry when you use the code just aboe, and you need to sae a reference to the original local work entry if you want to continue using it in your Hook or Script Component. The AssemblyLine work entry reference is not changed, only the reference in the current Hook or Script Component. Of course, if myentry really is the AssemblyLine work entry, it s content is changed as well. Link criteria The Link Criteria is used to let Update, Lookup and Delete Connectors know what record to access in the external data-source. The Link Criteria is accessible in the admin tool through a tab that you find in Update, Lookup and Delete Connectors. There are to ariants of Link Criteria: Simple and Adanced. Note that usually the Connector goes to the On Error Hook if more than one record match the link criteria. Simple link criteria In the simplest case it links a alue from the AssemblyLine with a alue from the Data-source. To be more precise it links the alue of an attribute in the work entry to a alue of an attribute in the raw Connector. As an example, imagine we hae a work entry with an attribute called Name. We want from a database the row of table Student where column ID is equal to work.name. Using Simple Link Criteria (default), the syntax would be: ID equal ($Name) As you will see from the Link Criteria tab, drop-downs for these three columns are proided. For the Connector Attribute column you must hae preiously done a Connect/Query Schema in the Configure/Attribute window in order to get drop-down alues. 14 IBM Directory Integrator 4.7: Reference Guide

A Connector can hae many link criteria. They are added by using the Add button. If you hae seeral link criteria, there is an implicit AND operator between them. Note that in the example aboe, the Value was set to $Name. The possible formats for Value are A text string - mapped to a constant with that alue $Name - corresponds to work.getstring( Name ), that is the first alue of the attribute Name. @Name - meaning one of the alues of the multi-alued attribute Name Adanced link criteria Sometime, the Simple Link Criteria is not enough, because multiple link criteria are always ANDed. If you select the Adanced Link Mode check box, you are able to script your link criteria. You will hae to populate a text string called ret.filter that will proide the Link Criteria or filter. Howeer, you will hae to know the syntax used by the underlying Raw Connector: An LDAP and an SQL Connector will hae different syntax. A simple JaaScript example for a SQL Connector would be ret.filter = ID LIKE + work.getstring( Name ) + ; The example assumes an example where the Raw Connector has an attribute called ID (typically a column name) and that we want to match it with work.name. Notes: 1. The first part of the SQL expression, Select * from Table Where, is proided by the IBM Directory Integrator. 2. Single quotes hae been added since work.getstring() returns a string, while SQL Syntax asks for single quotes around strings constants. 3. The special syntax with $ and @ is not used here. EentHandler EentHandlers are meant to simplify the task of eent enabling the IBM Directory Integrator serer. With the EentHandlers you can configure actions to be taken using a point & click metaphor. you can script eenthandlers if you want, but IBM Directory Integrator proides some predefined functions to make life easier. Starting the EentHandler In the admin-tool, under the Configuration tab, there is an EentHandler tab. If an EentHandler has the auto-start check-box set, it starts up wheneer the Serer is started with that configuration file. You can disable it by the -D switch as seen under Line Options. While working with the Admin-tool, you typically start the serer (and thus all your auto-started EentHandlers) simply by selecting File Start Serer. If you want to start just one EentHandler, press the EentHandler Object tab, select the EentHandler you want to run, and press the Run Button. Some new EentHandlers een hae their own Run button you can press while configuring the EentHandler. Chapter 4. IBM Directory Integrator concepts 15

The Eent object The key object in the EentHandlers is the eent object. This object is an instance of the familiar entry object you find in AssemblyLines. Configuration and data flow Each EentHandler consists of a configuration section and a data flow section. The configuration section contains the parameters that goern each specific EentHandler. The data flow consists of a prolog, action map and an epilog. The prolog and epilog are executed before and after the action map. The action map contains a number of actions and dependencies for the actions. This enables you to perform simple tests and start AssemblyLines without typing a single line of script code. Prolog In this section you can execute script code before the action map is executed. You hae access to the eent object and global functions (e.g. system, main etc.) as usual. Eent Handler action map In this section you add action items. Each action item has an associated list of Conditions and actions. If the list of conditions is true, the actions under the On Success tab is executed, otherwise the On Fail actions are executed. If the Consumeeent option is set, and actions are executed, the rest of the action map is skipped. It is also possible to temporarily Disable an action item. Conditions If Match any condition is set, the list of conditions ealuates to true when at least one condition is true, otherwise all conditions must be true for the list to ealuate to true. An empty list of conditions is true. Each condition can be a small script, or a test based on properties or attributes of the eent object. See Attribute/property names on page 17 Actions Each action in the action list could be any one of these: Apply Parser - In Read Mode you set the Parser Input, and the result is put into the eent object. In Write Mode you set the Parser Output, and the eent object is written, unless you hae specified another Entry object as the Parser Input, in which case that object is written. Run AssemblyLine - Runs a named AssemblyLine. You may send the eent object to the AssemblyLine as the initial work entry, by setting Proide eent object. You may een specify a connector to send to the AssemblyLine, see (runtime proided) Connector on page 86. If you set the Wait for completion flag, the action list waits for the AssemblyLine to finish, and sets the properties AssemblyLine.result, AssemblyLine.error and AssemblyLine.stats. Some of the properties may not be set, depending on what happens in the AssemblyLine. Custom Script - The script may refer to the eent and task objects. Dump Eent Object - writes the eent object to the Eent Handler s log file. Set Property/Attribute - See Attribute/property names on page 17 Remoe Property/Attribute - See Attribute/property names on page 17 Terminate Handler - terminates the Eent Handler with a specified message. 16 IBM Directory Integrator 4.7: Reference Guide

Scripting Attribute/property names If the name begins with entry., it is assumed to be an attribute of the eent object, otherwise it is a property of the eent object. The same rule applies to alues in a condition or Set Property/Attribute, but strings surrounded by quotes ( ) are constants. Epilog This section is executed after the action map has been completed. IBM Directory Integrator proides its users with a highly-flexible engine that can be tuned both from the user interface controls of IBM Directory Integrator Admin as well as through script input from the user. While the user interface controls proide a means of controlling the data flow on a higher leel, scripting proides users with the ability to control almost any aspect of the data flow at any leel (including oerriding standard IBM Directory Integrator processing). Special function exists within the System object to reiterate on an AssemblyLine, skip a Connector and so forth, for example, skipentry, ignoreentry, and restartentry. IBM Directory Integrator proides support for a number of scripting languages. You can set the Script Language for the entire AssemblyLine in the Settings tab. If you change the language, remember that this affects the code used in the Prolog, Epilog, Hooks and Attribute Maps. It does not affect a Connector or Parser written in a script language. When is scripting needed? Scripting is necessary when you need to add custom processing to your AssemblyLine. Examples of where scripting would be helpful include: The alue of an attribute in your output Connector is calculated based on one or more of the input Connector s attributes. You want to process only entries that match a particular set of criteria. You want to oerride the update operation of the Connector you are using. You want to run some initializing procedures before your AssemblyLine starts. Each of these cases mentioned (and many others not mentioned) require scripting. Integrating scripting into the AssemblyLine? As we already explained, you must utilize scripting when the need for custom processing arises in the integration process. The need for custom data processing will ineitably come in some identifiable point in the flow of data (e.g., before any processing begins, before processing a particular entry, after a failure, etc.). IBM Directory Integrator proides you with a number of control points throughout the data flow where you may proide direction through scripting (e.g., the AssemblyLines Prolog and Epilog sections, Connectors Hooks sections, etc.). These control points are easily accessed within the IBM Directory Integrator Admin tool. Implementing custom processing is simply a matter of identifying the correct control point and adding your script in the appropriate edit window. It is important to both correctly identify the appropriate control point where you will input your script as well as limit the scope of your script to coer just that single goal associated with the control point. Chapter 4. IBM Directory Integrator concepts 17