ibm directory integrator 5.1.1: reference...

IBM Directory Integrator 5.1.1:Reference Guide

��

NoteBefore using this information and the product it supports, read the general information under Appendix F, “Notices” onpage 257.

First Edition (November 2002)

This edition applies to version 5, release 1, of The IBM® Directory Integrator and to all subsequent releases andmodifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . ixGetting Started Guide . . . . . . . . . . . ix

Chapter 1. Introduction . . . . . . . . 1General concepts . . . . . . . . . . . . . 1Program components and interface . . . . . . . 1

Admin tool . . . . . . . . . . . . . . 1IBM Directory Integrator Server . . . . . . . 1

IBM components . . . . . . . . . . . . . 1IBM API . . . . . . . . . . . . . . . . 1Script objects . . . . . . . . . . . . . . 2

Chapter 2. New for IBM DirectoryIntegrator 5.1.1 . . . . . . . . . . . . 3User Interface . . . . . . . . . . . . . . 3Configuration Files . . . . . . . . . . . . 3

Includes . . . . . . . . . . . . . . . 3Starting the programs . . . . . . . . . . . 3User preferences . . . . . . . . . . . . . 3Management Framework . . . . . . . . . . 3Library functions . . . . . . . . . . . . . 3Various Renaming . . . . . . . . . . . . 4Mode changes . . . . . . . . . . . . . . 8EventHandlers. . . . . . . . . . . . . . 8Hooks and Flow . . . . . . . . . . . . . 8

Hook changes for 5.1.1 . . . . . . . . . . 8Connectors . . . . . . . . . . . . . . 12Schema . . . . . . . . . . . . . . . . 12Deltas . . . . . . . . . . . . . . . . 12Parsers . . . . . . . . . . . . . . . . 12Scripting/Debugging . . . . . . . . . . . 13Inheritance . . . . . . . . . . . . . . 13Deleted components . . . . . . . . . . . 13Documentation . . . . . . . . . . . . . 14

Chapter 3. Supported platforms . . . . 15

Chapter 4. IBM Directory Integratorconcepts . . . . . . . . . . . . . . 17The AssemblyLine . . . . . . . . . . . . 17

Starting an AssemblyLine. . . . . . . . . 18Starting from the Admin tool . . . . . . . 19Starting from an EventHandler or script . . . . 19Accessing connectors inside the AssemblyLine. . 19When creating XML files from an LDAPdirectory or LDIF file, the AssemblyLine fails. . . 19AssemblyLine parameter passing . . . . . . 19

Connectors . . . . . . . . . . . . . . 21Connector Schema . . . . . . . . . . . 22How do Connectors share data? . . . . . . 22Connector modes . . . . . . . . . . . 22Connector states . . . . . . . . . . . . 25

Link criteria . . . . . . . . . . . . . . 26Simple link criteria . . . . . . . . . . . 26

Advanced link criteria . . . . . . . . . . 27EventHandler . . . . . . . . . . . . . 28

Starting the EventHandler . . . . . . . . 28The Event object . . . . . . . . . . . . 28Configuration and data flow. . . . . . . . 28Prolog . . . . . . . . . . . . . . . 28Event Handler action map . . . . . . . . 28Conditions. . . . . . . . . . . . . . 29Actions . . . . . . . . . . . . . . . 29Attribute/property names . . . . . . . . 29Epilog . . . . . . . . . . . . . . . 29

Scripting . . . . . . . . . . . . . . . 29When is scripting needed? . . . . . . . . 30Integrating scripting into the AssemblyLine? . . 30How does scripting affect execution? . . . . . 30Control points for scripting . . . . . . . . 31Comparing JavaScript strings . . . . . . . 32Accessing your own Java classes . . . . . . 34Scripting in JavaScript . . . . . . . . . . 35JavaScript string methods. . . . . . . . . 35Scripting in languages without new java.* . . . 35Using binary values in scripting . . . . . . 35Using date values in scripting . . . . . . . 36Using floating point values in scripting . . . . 36Examples . . . . . . . . . . . . . . 37

Hooks . . . . . . . . . . . . . . . . 37Enabling/disabling Hooks . . . . . . . . 37Override Hooks . . . . . . . . . . . . 38Failure Hooks . . . . . . . . . . . . 38List of Hooks . . . . . . . . . . . . . 38

Deltas and compute changes . . . . . . . . 41Deltas . . . . . . . . . . . . . . . 41

Inheritance . . . . . . . . . . . . . . 43Attribute Mapping . . . . . . . . . . . . 44

Null Value Behavior . . . . . . . . . . 44Conn object . . . . . . . . . . . . . 45

Tasks . . . . . . . . . . . . . . . . 46How to control the number of threads . . . . 46

The configuration file . . . . . . . . . . . 47Externalizing fields like username and password 47Include/Namespaces . . . . . . . . . . 47

IBM Directory Integrator Secure Sockets LayerSupport . . . . . . . . . . . . . . . 48

Securing the connection between IBM DirectoryIntegrator 5.1.1 and servers with SSL (IBMDirectory Integrator as a client) . . . . . . . 48Securing the connection between client and IBMDirectory Integrator 5.1.1 with SSL (IBMDirectory Integrator as a server) . . . . . . 49

Chapter 5. IBM Directory Integratorinstallation instructions . . . . . . . 51Installing on Windows platforms . . . . . . . 51Installing on Unix platforms . . . . . . . . . 51Silent install (command line) . . . . . . . . 52

© Copyright IBM Corp. 2002 iii

Uninstalling on Windows platforms . . . . . . 52Uninstalling on Unix platforms . . . . . . . . 52Silent uninstall (command line) . . . . . . . . 52Distribution components . . . . . . . . . . 53

Other files on install directory . . . . . . . 53Jar-files (jars/subdirectory) . . . . . . . . 54Java Naming and Directory Interface (JNDI) . . 54JavaMail API . . . . . . . . . . . . . 54XML. . . . . . . . . . . . . . . . 54Libraries (Windows) libs/ subdirectory . . . . 54Management . . . . . . . . . . . . . 54Logging . . . . . . . . . . . . . . 54Other . . . . . . . . . . . . . . . 55global.properties file . . . . . . . . . . 55

Troubleshooting . . . . . . . . . . . . . 55

Chapter 6. Migrating from IBMDirectory Integrator 4.7 to IBMDirectory Integrator 5.1.1 . . . . . . . 57Hook flow. . . . . . . . . . . . . . . 57User preferences . . . . . . . . . . . . . 57Custom made Connectors . . . . . . . . . 57Xalan and Xerces libraries . . . . . . . . . 57Include . . . . . . . . . . . . . . . . 58Classes and methods that have been renamed . . . 58BTree databases . . . . . . . . . . . . . 58Connector Library . . . . . . . . . . . . 58

Chapter 7. Connectors . . . . . . . . 59Connector availability and reference . . . . . . 59

Raw Connectors . . . . . . . . . . . . 59Script-based Connectors . . . . . . . . . 60Configurations . . . . . . . . . . . . 61

Btree Object DB Connector . . . . . . . . . 61Configuration . . . . . . . . . . . . 61Btree object . . . . . . . . . . . . . 62

Command line Connector . . . . . . . . . 62Configuration . . . . . . . . . . . . 62Examples . . . . . . . . . . . . . . 62

Direct TCP /URL scripting . . . . . . . . . 62TCP . . . . . . . . . . . . . . . . 63URL . . . . . . . . . . . . . . . . 63

Domino Users Connector . . . . . . . . . . 63Deployment and connection to Domino server . 63Configuration . . . . . . . . . . . . 64Security . . . . . . . . . . . . . . 65Using the Domino Connector . . . . . . . 65List of Domino user Attributes (or Persondocument items). . . . . . . . . . . . 73Examples . . . . . . . . . . . . . . 75See also. . . . . . . . . . . . . . . 75

File system Connector . . . . . . . . . . . 75Configuration . . . . . . . . . . . . 76See also. . . . . . . . . . . . . . . 76

FTP Client Connector . . . . . . . . . . . 76Configuration . . . . . . . . . . . . 76Note. . . . . . . . . . . . . . . . 77See also. . . . . . . . . . . . . . . 77

Old HTTP Client Connector . . . . . . . . . 77Modes . . . . . . . . . . . . . . . 77

Special attributes . . . . . . . . . . . 78Configuration . . . . . . . . . . . . 78Examples . . . . . . . . . . . . . . 79Lookup Mode . . . . . . . . . . . . 79See also. . . . . . . . . . . . . . . 79

HTTP Client Connector . . . . . . . . . . 79Changes from earlier versions . . . . . . . 80Modes . . . . . . . . . . . . . . . 80Special attributes . . . . . . . . . . . 80Configuration . . . . . . . . . . . . 81Examples . . . . . . . . . . . . . . 81Lookup Mode . . . . . . . . . . . . 82See also. . . . . . . . . . . . . . . 82

Old HTTP Server Connector . . . . . . . . . 82Configuration . . . . . . . . . . . . 83See also. . . . . . . . . . . . . . . 83

HTTP Server Connector . . . . . . . . . . 83Configuration . . . . . . . . . . . . 84See also. . . . . . . . . . . . . . . 84

JDBC Connector . . . . . . . . . . . . . 84Configuration . . . . . . . . . . . . 84Link Criteria . . . . . . . . . . . . . 85Other . . . . . . . . . . . . . . . 85Notes . . . . . . . . . . . . . . . 86

ODBC–specifying database paths directly . . . . 87JMS Connector . . . . . . . . . . . . . 87

JMS messages . . . . . . . . . . . . 88JMS message types . . . . . . . . . . . 88Iterator mode. . . . . . . . . . . . . 89CallReply mode . . . . . . . . . . . . 89Lookup mode . . . . . . . . . . . . 89JMS headers and properties . . . . . . . . 90Configuration . . . . . . . . . . . . 92Examples . . . . . . . . . . . . . . 93Specific topics . . . . . . . . . . . . 93

JNDI Connector . . . . . . . . . . . . . 94Configuration . . . . . . . . . . . . 94See also. . . . . . . . . . . . . . . 94

LDAP Connector . . . . . . . . . . . . 95Configuration . . . . . . . . . . . . 95Notes . . . . . . . . . . . . . . . 97Handling memory problems in the LDAPConnector . . . . . . . . . . . . . . 98See also. . . . . . . . . . . . . . . 99IBM Directory Changelog Connector . . . . . 99Netscape/iPlanet Changelog Connector . . . 100Active Directory Changelog Connector . . . . 100Exchange Changelog Connector . . . . . . 103

Lotus Notes Connector . . . . . . . . . . 107Known limitations. . . . . . . . . . . 107Session types . . . . . . . . . . . . 108Connecting . . . . . . . . . . . . . 108Configuration . . . . . . . . . . . . 109Security . . . . . . . . . . . . . . 109

MailboxConnector Connector . . . . . . . . 110Configuration . . . . . . . . . . . . 110Predefined Properties/Attributes . . . . . . 111See also . . . . . . . . . . . . . . 111

Memory Stream Connector . . . . . . . . . 111Configuration . . . . . . . . . . . . 112

NT4 Connector . . . . . . . . . . . . . 112

iv IBM Directory Integrator 5.1.1: Reference Guide

Preconditions . . . . . . . . . . . . 112Character sets . . . . . . . . . . . . 115Examples . . . . . . . . . . . . . . 115NT4 Connector functional specifications andsoftware requirements . . . . . . . . . 115

(runtime provided) Connector . . . . . . . . 127Configuration . . . . . . . . . . . . 128See also . . . . . . . . . . . . . . 128

Script Connector . . . . . . . . . . . . 128Predefined script objects. . . . . . . . . 128Functions. . . . . . . . . . . . . . 129Configuration . . . . . . . . . . . . 129Note . . . . . . . . . . . . . . . 130Examples . . . . . . . . . . . . . . 130See also . . . . . . . . . . . . . . 130

SNMP Connector . . . . . . . . . . . . 130Configuration . . . . . . . . . . . . 130Examples . . . . . . . . . . . . . . 131Notes . . . . . . . . . . . . . . . 131

TCP Connector . . . . . . . . . . . . . 131Iterator Mode . . . . . . . . . . . . 131AddOnly Mode . . . . . . . . . . . 132Configuration . . . . . . . . . . . . 132See also . . . . . . . . . . . . . . 132

URL Connector . . . . . . . . . . . . . 132Configuration . . . . . . . . . . . . 132Supported URL protocol. . . . . . . . . 132See also . . . . . . . . . . . . . . 133

Web Service Connector . . . . . . . . . . 133Using the Connector . . . . . . . . . . 133Configuration . . . . . . . . . . . . 134The ″on error″ hook . . . . . . . . . . 135Schema/namespaces types support . . . . . 135

Chapter 8. EventHandlers . . . . . . 137EventHandler types . . . . . . . . . . . 137When are they started? . . . . . . . . . . 137What do they do? . . . . . . . . . . . . 137Data flow . . . . . . . . . . . . . . 137Passing input/output file names to anAssemblyLine . . . . . . . . . . . . . 138EventHandler availability . . . . . . . . . 138Connector EventHandler . . . . . . . . . 139

Configuration . . . . . . . . . . . . 139Objects/properties/attributes . . . . . . . 139See also . . . . . . . . . . . . . . 139

FTP Poller . . . . . . . . . . . . . . 139Examples . . . . . . . . . . . . . . 139

HTTP EventHandler . . . . . . . . . . . 140Example . . . . . . . . . . . . . . 140Configuration . . . . . . . . . . . . 140See also . . . . . . . . . . . . . . 141

IBM Directory Server EventHandler . . . . . . 141Configuration . . . . . . . . . . . . 142See also . . . . . . . . . . . . . . 143

JMX EventHandler . . . . . . . . . . . 143Behavior description . . . . . . . . . . 143Using the EventHandler . . . . . . . . . 144IBM Directory Integrator notification types . . 144JMX system notification types . . . . . . . 145Configuration . . . . . . . . . . . . 145

Dynamic addition/removal of notification types 146LDAP EventHandler . . . . . . . . . . . 147

Object Added (_objAdded) . . . . . . . . 147Object Rename (_objRenamed) . . . . . . 147Object Modified (_objModified) . . . . . . 147Object Removed (_objRemoved) . . . . . . 148Error Encountered (_handleError) . . . . . 148Configuration . . . . . . . . . . . . 148Notes . . . . . . . . . . . . . . . 148See also . . . . . . . . . . . . . . 149

MailboxConnector EventHandler . . . . . . . 149Configuration . . . . . . . . . . . . 149Objects/properties/attributes . . . . . . . 149Examples . . . . . . . . . . . . . . 150See also . . . . . . . . . . . . . . 150

TCP Port EventHandler . . . . . . . . . . 150Configuration . . . . . . . . . . . . 150Objects/properties/attributes . . . . . . . 150Examples . . . . . . . . . . . . . . 151See also . . . . . . . . . . . . . . 151

Generic thread (simple EventHandler) . . . . . 151Configuration . . . . . . . . . . . . 151See also . . . . . . . . . . . . . . 151

Timer EventHandler . . . . . . . . . . . 151Configuration . . . . . . . . . . . . 151Examples . . . . . . . . . . . . . . 152

Outlook MailboxConnector . . . . . . . . . 152Web Service EventHandler . . . . . . . . . 153

AssemblyLines–WSDL mapping . . . . . . 153Using the EventHandler . . . . . . . . . 155WS EventHandler Processing Sequence. . . . 155Configuration . . . . . . . . . . . . 157Hosting WSDL . . . . . . . . . . . . 157Automatic WSDL Generation . . . . . . . 158

Chapter 9. Parsers . . . . . . . . . 161Parser availability and reference . . . . . . . 161

Base parsers . . . . . . . . . . . . . 161Character Encoding conversion . . . . . . . 161

Availability . . . . . . . . . . . . . 161CSV parser . . . . . . . . . . . . . . 161

Configuration . . . . . . . . . . . . 161Notes . . . . . . . . . . . . . . . 162

DSML parser . . . . . . . . . . . . . 162Configuration . . . . . . . . . . . . 162Example . . . . . . . . . . . . . . 163See also . . . . . . . . . . . . . . 163

Fixed parser . . . . . . . . . . . . . . 163Configuration . . . . . . . . . . . . 163

HTTP parser . . . . . . . . . . . . . 164Configuration . . . . . . . . . . . . 164Attributes/properties . . . . . . . . . . 164See also . . . . . . . . . . . . . . 166

LDIF parser . . . . . . . . . . . . . . 166See also . . . . . . . . . . . . . . 167

LineReader . . . . . . . . . . . . . . 167Configuration . . . . . . . . . . . . 167

Regular Expression parser . . . . . . . . . 167Functional specification . . . . . . . . . 167Source code . . . . . . . . . . . . . 168Examples . . . . . . . . . . . . . . 169

Contents v

Script parser. . . . . . . . . . . . . . 169Objects . . . . . . . . . . . . . . 169Functions. . . . . . . . . . . . . . 170Configuration . . . . . . . . . . . . 170Note . . . . . . . . . . . . . . . 170Examples . . . . . . . . . . . . . . 171See also . . . . . . . . . . . . . . 171

Simple parser . . . . . . . . . . . . . 171Configuration . . . . . . . . . . . . 171

SOAP parser . . . . . . . . . . . . . 171Example Entry . . . . . . . . . . . . 171Example SOAP document . . . . . . . . 172Configuration . . . . . . . . . . . . 172Parser-specific calls . . . . . . . . . . 172Examples . . . . . . . . . . . . . . 173

XML parser . . . . . . . . . . . . . . 173Configuration . . . . . . . . . . . . 173Examples . . . . . . . . . . . . . . 174Notes . . . . . . . . . . . . . . . 175Examples . . . . . . . . . . . . . . 176See also . . . . . . . . . . . . . . 176

Chapter 10. Script languages . . . . 177BSF-based script languages . . . . . . . . . 177WSH-based script languages . . . . . . . . 177BeanShell. . . . . . . . . . . . . . . 177PerlScript. . . . . . . . . . . . . . . 178

PerlScript example . . . . . . . . . . 179VB Script . . . . . . . . . . . . . . . 179JavaScript . . . . . . . . . . . . . . 179Java and JavaScript . . . . . . . . . . . 179

Chapter 11. Objects. . . . . . . . . 181The AssemblyLine Connector object . . . . . . 181The Attribute object . . . . . . . . . . . 181

Examples . . . . . . . . . . . . . . 181See also . . . . . . . . . . . . . . 182

The Raw Connector object . . . . . . . . . 182Methods . . . . . . . . . . . . . . 182

The Entry object . . . . . . . . . . . . 183Global Entry instances available in scripting . . 183See also . . . . . . . . . . . . . . 183

The FTP object . . . . . . . . . . . . . 183Example . . . . . . . . . . . . . . 183

Main object . . . . . . . . . . . . . . 184The Search (criteria) object . . . . . . . . . 184

Operands. . . . . . . . . . . . . . 184Example . . . . . . . . . . . . . . 184

The shellCommand object . . . . . . . . . 185The status object . . . . . . . . . . . . 185The system object . . . . . . . . . . . . 185The task object . . . . . . . . . . . . . 185

Chapter 12. Program interfaces. . . . 187AssemblyLine setting tab . . . . . . . . . 187IBM Directory Integrator command line options 188

IBM Directory Integrator Admin tool . . . . 188IBM Directory Integrator server . . . . . . 188

Discover schemas and browsing data . . . . . 190Parameter labels on the Connector/parser tabs. . . 191

Preferences (Java properties) . . . . . . . . 191Java properties . . . . . . . . . . . . . 192External Properties . . . . . . . . . . . 192

Setting Up External Properties. . . . . . . 193Managing External Properties . . . . . . . 193Using External Properties . . . . . . . . 193

Chapter 13. Examples . . . . . . . . 195VBScript Connector and Microsoft OutlookContacts Connector . . . . . . . . . . . 195

Example code . . . . . . . . . . . . 195See also . . . . . . . . . . . . . . 197

JavaScript Connector . . . . . . . . . . . 197Example code . . . . . . . . . . . . 197See also . . . . . . . . . . . . . . 197

JavaScript parser . . . . . . . . . . . . 198Example code . . . . . . . . . . . . 198See also . . . . . . . . . . . . . . 198

Writing a new Raw Connector. . . . . . . . 198Script-based Connector . . . . . . . . . 198Java-based Connector. . . . . . . . . . 198Building and installing a Java-based Connector 199

Copying directories with the LDAP Connector . . 200

Chapter 14. Logging and debugging 203AssemblyLine Debugger. . . . . . . . . . 203

Examples . . . . . . . . . . . . . . 203Logging and debugging . . . . . . . . . . 203

Logging . . . . . . . . . . . . . . 204Dumping the content of an Entry object . . . 204Dumping the content of an Attribute . . . . 204Dumping the state of a Connector . . . . . 205Dumping arbitrary log messages . . . . . . 205Debugging a Script Connector (or other object)where the task object is unavailable . . . . . 205

log4j default parameters . . . . . . . . . . 205Log Levels . . . . . . . . . . . . . 206Creating your own log strategies . . . . . . 206

Appendix A. FAQ IBM DirectoryIntegrator . . . . . . . . . . . . . 209Questions . . . . . . . . . . . . . . 209

Writing AssemblyLines . . . . . . . . . 209Limitations . . . . . . . . . . . . . 209

Answers . . . . . . . . . . . . . . . 209Writing AssemblyLines . . . . . . . . . 209Limitations . . . . . . . . . . . . . 209

Appendix B. Dictionary of terms . . . 211LDAP terms . . . . . . . . . . . . . . 211IBM Directory Integrator terms . . . . . . . 211

Appendix C. Administration andMonitor Console . . . . . . . . . . 215Administration and Monitor Console user reference 215

Considerations . . . . . . . . . . . . 215Some AMC functions . . . . . . . . . . 216

AMC setup . . . . . . . . . . . . . . 218AMC properties . . . . . . . . . . . 218

vi IBM Directory Integrator 5.1.1: Reference Guide

Accounts configuration file . . . . . . . . 219SSL configuration . . . . . . . . . . . 219Example AMC configuration in global.properties 219

Appendix D. Plug-ins . . . . . . . . 221IBM Directory Integrator password synchronizerplug-in . . . . . . . . . . . . . . . 221

Synchronizing . . . . . . . . . . . . 221Included Files . . . . . . . . . . . . 222Installing IBM Directory Integrator passwordsynchronizer plug-in . . . . . . . . . . 222

Appendix E. Connector modesflowcharts . . . . . . . . . . . . . 227AddOnly mode. . . . . . . . . . . . . 230Call/Reply mode . . . . . . . . . . . . 233

Delete mode. . . . . . . . . . . . . . 236On Multiple Entries . . . . . . . . . . 236

Iterator mode . . . . . . . . . . . . . 239Lookup mode . . . . . . . . . . . . . 242

On Multiple Entries . . . . . . . . . . 242Update mode . . . . . . . . . . . . . 246

On Multiple Entries . . . . . . . . . . 246End-of-flow for all modes . . . . . . . . . 253

End-of-flow . . . . . . . . . . . . . 254Error Handling . . . . . . . . . . . . 254

Appendix F. Notices . . . . . . . . 257Third-party component statements . . . . . . 258

Apache statement . . . . . . . . . . . 258Rhino statement . . . . . . . . . . . 259

Trademarks . . . . . . . . . . . . . . 259

Contents vii

viii IBM Directory Integrator 5.1.1: Reference Guide

Preface

In order to work with examples complementing this manual, you must refer backto the installation package to download the necessary files.

To access these example files, go to the root_directory/examples directory in theinstallation directories.

Getting Started GuideIBM Directory Integrator 5.1.1: Getting Started Guide is a brief tutorial andintroduction to IBM Directory Integrator. You need Acrobat Reader to read the IBMDirectory Integrator 5.1.1: Getting Started Guide as it is in PDF format.

© Copyright IBM Corp. 2002 ix

x IBM Directory Integrator 5.1.1: Reference Guide

Chapter 1. Introduction

General conceptsThe following are some of the general concepts that can be found in the IBMDirectory Integrator documentation:v “The AssemblyLine” on page 17v “Connectors” on page 21v “Scripting” on page 29v “Hooks” on page 37v “Parser availability and reference” on page 161v “EventHandler” on page 28v “Deltas and compute changes” on page 41v “Inheritance” on page 43v “Attribute Mapping” on page 44v “Tasks” on page 46v “The configuration file” on page 47v “Accessing your own Java classes” on page 34v “Logging and debugging” on page 203v Appendix B, “Dictionary of terms” on page 211

Program components and interfacev “Distribution components” on page 53

Admin toolv “IBM Directory Integrator command line options” on page 188v “Preferences (Java properties)” on page 191v “Java properties” on page 192v “AssemblyLine setting tab” on page 187v “Discover schemas and browsing data” on page 190v “Parameter labels on the Connector/parser tabs.” on page 191

IBM Directory Integrator Serverv “IBM Directory Integrator command line options” on page 188

IBM componentsv “EventHandler types” on page 137v “Connector availability and reference” on page 59v “Parser availability and reference” on page 161

IBM APIFull technical JavaDoc of all available internal java objects is found in theinstallation package.

© Copyright IBM Corp. 2002 1

Script objectsScript objects are available everywhere inside the AssemblyLines (provided theircontext is valid). Some of the major objects are described below:v “The Attribute object” on page 181v “The AssemblyLine Connector object” on page 181v “The Raw Connector object” on page 182v “The Entry object” on page 183v “The FTP object” on page 183v “Main object” on page 184v “The shellCommand object” on page 185v “The status object” on page 185v “The system object” on page 185v “The task object” on page 185v “AssemblyLine Debugger” on page 203

2 IBM Directory Integrator 5.1.1: Reference Guide

Chapter 2. New for IBM Directory Integrator 5.1.1

The following are new for IBM Directory Integrator version 5.1.1:

User InterfaceThe GUI for IBM Directory Integrator version 5.1.1 has been completelyredesigned.

An Administration and Management Console is added. See Appendix C,“Administration and Monitor Console” on page 215.

Configuration FilesPrevious versions of IBM Directory Integrator used a proprietory format (.cfg files).The format has been changed to .xml files. Old files can be read, but not writtien.

IncludesThe way inclusion of configuration files is done is greatly simplified. All includesare now loaded in separate name places. See “Include/Namespaces” on page 47.

Starting the programsv The Admin tool can now take several filenames as parameter (since it can visit

several files at once). The syntax is changed, see “IBM Directory Integratorcommand line options” on page 188 as -c is not used anymore.

v -e (error log) is not used anymore as logging is now described in alog-configuration file.

v -l (look and feel) is not used anymore as it is now part of your preferences.

User preferencesMany preference parameters are moved out of the configuration file and into the.ibmdi file in your home directory. Some other are found in the global.propertiesfile and then finally some are placed in your configuration file. See “Preferences(Java properties)” on page 191 for more on this.

Note: For IBM Directory Integrator version 5.1.1, configuration files are now storedin an XML format (previously, configuration files were stored in .cfg format).

Management FrameworkLogging has changed dramatically (become very flexible). For example, IBMDirectory Integrator now can log to syslog (Unix) or eventlog (Windows®). See“Logging and debugging” on page 203 for more information.

Library functionsv system.deleteFile added.v system.arrayToString added.


v main.dumpEntry() added (Now there is symmetry for dump-syntax betweenmain and task).

v main/task.dumpEntry() are changed. (The change is minor, but read on if youwant to know the details) Now the name printed is the name used by the Entryto reference the Attribute (it used to be name contained in the Attribute). If thename contained in the Attribute is different, it is printed inside square brackets.

v New AssemblyLine Connector method: getFirstDuplicateEntry()v External properties can now be accessed through scripts. You can use

main.getMetamergeConfig().getExternalProperties() to obtain the externalproperties object (or null if it does not exist).

v Improved snmpTrap function: You can send more parameters.v Xalan and Xerces libraries updated for this release.

Various Renamingv User properties are now always referred to as External Properties both in Admin

tool and documentation.v Attribute map is now called Input Map and Output Map in the GUI.v Certain hooks have their name slightly changed in the GUI: Generic terms like

On Error is now called ’XXX Error’ where XXX typically is the mode. Theinternal names of the hook are unchanged, and this only affects GUI anddocumentation. A translation map is not enclosed as the changes are quiteobvious.

v Renamed Items in IBM Directory Integrator 5.1.1 (see the following table):

Note: If you in your JavaScript or in Javalibraries have used the classnameslisted, you must translate those. For example, if you load Connectorsexplicitly, this is necessary. If you are only referring to generic objects asmain, system, connector and so forth you don’t need to worry about this.

4.7 Name 5.1.1 Name Removed?

metamerge.inf idi.inf

com.architech.config remove

com.architech.btree com.ibm.di.btree

com.architech.jmx com.ibm.di.jmx

com.architech.connector com.ibm.di.connector

HTTPConnector2 HTTPClientConnector

HTTPConnector OldHTTPCLient

HTTPServer HTTPServerConnector

Mailbox MailboxConnector

connector.SNMP connector.SNMPConnector

rscCOMPort COMPortConnector

rscCommandLine CommandLineConnector

rscConnectorInterface ConnectorInterface

rscConnector Connector

rscConsumerProducerConnectorConsumerProducer

rscEmiUcpConnector EmiUcpConnector

rscFTPClient FTPClientConnector


rscFileConnector FileConnector

rscHashtable HashtableConnector

rscHttpServer OldHTTPServer

rscJMSConnector JMSConnector

rscJNDI JNDIConnector

rscJdbc JDBCConnector

rscLdap LDAPConnector

rscLotusDomino DominoConnector

rscMailStream MailStreamConnector

rscNTAccountManager remove

rscNetscapeChangelog LDAPChangelogConnector

rscNotes remove

rscOdbc ODBCConnector

rscPPInterface PPInterface

rscProxyConnector remove

rscRemoteConnect RemoteConnect

rscRemoteProtocol RemoteProtocol

rscRemote Remote

rscRfc822Message RFC822Message

rscSMPPConnector remove

rscScriptConnector ScriptConnector

rscSmtp SMTPConnector

rscSoap SOAPConnector

rscStreamConnector StreamConnector

rscTest remove

rscURLConnector URLConnector

DominoUsers DominoUsersConnector

rscVBD remove

rscADChangelog ADChangelogConnector

rscExchangeChangelog ExchangeChangelogConnector

com.architech.entry com.ibm.di.entry

com.architech.event com.ibm.di.event

com.architech.exceptions com.ibm.di.exceptions

LicenseExpiredException remove

LicenseWarningException remove

rseAbortAL AbortALException

rseReturn ReturnException

rseEntryIgnore IgnoreEntryException

rseEntrySkipped SkipEntryException

rseExceptionHandlerInterface ExceptionHandlerInterface

rseNonFatalException NonFatalException

rseSkipTo SkipToException

Chapter 2. New for IBM Directory Integrator 5.1.1 5

rseRestartEntry RestartEntryException

rseRetryException remove

rseUnsupportedOperation UnsupportedOperation

rseUpdateNoChanges UpdateNoChangesException

com.architech.function com.ibm.di.function

eventFunctions EventFunctions

executeCommand ExecuteCommand

httpFunctions HTTPFunctions

mailMessage MailMessage

nho_functions remove

systemFunctions SystemFunctions

userFunctions2 UserFunctions

com.architech.parser com.ibm.di.parser

rspCSVParser CSVParser

rspDSML DSMLParser

rspEDBFile EDBFileParser

rspFixed FixedRecordParser

rspHttpParser HTTPParser

rspLdif LDIFParser

rspOnmail remove

rspParserInterface ParserInterface

rspParser ParserImpl

rspRigal70 Rigal70Parser

rspScriptParser ScriptParser

rspSimpleParser SimpleParser

rspSoapParser SOAPParser

rspXml2 remove

rspXmlSax XMLSaxParser

rspXml XMLParser

com.architech.protocols com.ibm.di.protocols

com.architech.script.ASPerl remove

com.architech.script com.ibm.di.script

scriptEngine ScriptEngine

scriptExitCode ScriptExitCode

com.architech.security com.ibm.di.security

rssEncryptedReader EncryptedReader

rssEncryptedWriter EncryptedWriter

rssKey SecurityKey

rssCrypto SecurityCrypto

com.architech.switchboard com.ibm.di.eventhandler

com.architech.trigger com.ibm.di.trigger

rstAdminPort remove


rstBaseClass Trigger

rstGenericThread GenericTrigger

rstLDAPListener remove

rstMailbox remove

rstProxyServer remove

rstSnmpTrap remove

rstSonicMQ remove

rstTimer TimerTrigger

rstTriggerInterface TriggerInterface

rstTrigger remove

rstMBean remove

com.architech.util com.ibm.di.util

rsuHttpUtil HTTPUtils

rsuString StringUtils

xmlUtils XMLUtils

com.architech.webService com.ibm.di.webService

com.architech com.ibm.di.server

dsCompare Compare

dsEntry remove

jobStatus JobStatus

rsConstants ServerConstants

rsLog Log

rsMonitor Monitor

rsStats TaskStatistics

rscDeltaTaskComponent DeltaTaskComponent

rscScriptComponent ScriptComponent

rscSearchCriteria SearchCriteria

rscTaskComponent AssemblyLineComponent

rscTask AssemblyLine

rscVersion Version

adminServer remove

fileConfig FileConfig

com.metamerge.management com.ibm.di.management

com.metamergeloader com.ibm.di.loader

miloader IDILoader

com.metamerge.miadmin com.ibm.di.admin

com.metamerge.config.base com.ibm.di.config.base

com.metamerge.config.xml com.ibm.di.config.xml

com.metamerge.config.convert remove

com.metamerge.config com.ibm.di.config.interfaces


Mode changesv Delete mode now has attribute map and returns the deleted object.v Passive mode has disappeared. It is replaced by setting the new ’state’ variable

to Passive for the Connector. This has the advantage that you now will be ableto see the attribute map of your ’passive’ connectors. Old configuration files willhave their passive connectors changed to passive AddOnly Connectors, youmight want to change the mode to something else. Note that passive Connectorsis initialized, this might be a problem for you if you had Passive File Connectorsconfigured as Iterators. In addition to the Passive state, a Disabled state alsoexists.

v Query Reply mode added.

EventHandlersThe concept of Listeners is removed from the documentation, we now only talk ofEventHandlers. Listeners are now just an EventHandler with a slightly differentGUI.

Obsolete former Listeners are removed. Existing ones still work.

There are new EventHandlers for this release:v “JMX EventHandler” on page 143v “Web Service EventHandler” on page 153

Hooks and Flowv See Appendix E, “Connector modes flowcharts” on page 227 for changes in the

hook flow.v Prolog and Epilog are now called AssemlyLine hooks. Shutdown Request is a

new AssemblyLine hook. See more under Scripting.v A new hook exists in Lookup: On No Match. This lets you handle the situation

where the hook returns no match. In IBM Directory Integrator 4.7 you wouldend up in the error-hook.

v Global Entry object current is now available in Delete mode (shows what isdeleted).

v Global Entry object error more available than it was.v In all Hooks (and usually in the epilog), an object called thisConnector will

always be available. This facilitates use of generic scripts, because you don’tneed to know the name of the connector. In the epilog thisConnector is the lastconnector executed.

v The Allow Duplicates checkbox is removed from IBM Directory Integrator 5.1.1.See “Lookup Mode” on page 9, following.

v Default behavior for No Match in Lookup is now to abort the AssemblyLineunless there is code in the relevant error hooks or in the new On No Matchhook. This behavior should be taken care of for you unless you have put logic inyour error-hook: That logic will have to be changed according to the newhook-flow.

Hook changes for 5.1.1In all Hooks (and usually in the epilog ), an object called thisConnector will alwaysbe available, pointing at the current Connector. This facilitates use of generic


scripts, because you don’t need to know the name of the connector. In the epilogthisConnector will be the last connector executed (normally the iterator)

Most of the following items are done when IBM Directory Integrator converts oldconfiguration files (.cfg) to new ones (.xml). This section is here to help you if youhave hook-logic in your AssemblyLine: Some things might have to be changedmanually.

IBM Directory Integrator will try to convert the old files on the fly (you will thenhave to save them as .xml files), but some items can not be converted automaticaly.Look for the !!! below to see what you might have to do. The rest of the sectionserves as a documentation of what has been changed and what is done by theconverter when you load an old file.

Note that you should have the new Appendix E, “Connector modes flowcharts” onpage 227 available if you read the section. The section below should not benecessary to read in detail unless you have code in your Multiple Entries Foundhooks. Also note that for new AssemblyLines you are writing, you should refer toAppendix E, “Connector modes flowcharts” on page 227.

Lookup Mode

Note: The Allow Duplicates checkbox is removed from IBM Directory Integrator5.1.1.

No entries found: There is a new Hook, No Match Found. It is invoked when thelink criteria returns no match. This Hook does not exist in old configuration files.v If failure hook (On error) is enabled:

Old behaviorCall failure hook. Continue with On Success.

New behaviorCall specific hook if enabled, otherwise call failure hook.

v If failure hook disabled:

Old behaviorThrow SkipEntryException exception (continue with Iterator).

New behaviorCall specific hook if enabled, otherwise abort AssemblyLine.

If On Error was disabled in your 4.7 configuration file, the converter adds a NoMatch Found Hook with the contentsystem.skipEntry("No Entries Found");

to maintain pre-5.1.1 behavior.

Multiple entries found: If Allow Duplicates was set, old and new behavior is thesame as the converter will add a On Multiple Entries Hook with the contentthisConnector.setCurrent(thisConnector.getFirstDuplicateEntry())

If Allow Duplicates not set:v If On Multiple Entries Hook enabled:

Old behaviorCalled On Multiple Entries Hook. If setCurrent was called, used that


entry, otherwise used getNextDuplicateEntry. If this resulted in no entryset, continued as if no Entries were found.

New behaviorCall On Multiple Entries Hook. If setCurrent is called, uses that entry,otherwise continues with On Success.

v If On Multiple Entries Hook disabled:

Old behavior

– If failure hook (On error) was enabled: Called failure hook. Continuedwith On Success.

– If failure hook was disabled: logged a messages and threwSkipEntryException exception (continuing with Iterator).

New behavior

– If failure hook (On error) enabled: Calls failure hook.– If failure hook disabled: Aborts AssemblyLine.

To maintain pre-5.1.1 behavior:v If Allow Duplicates is set, the behavior is the same.v If Allow Duplicates is not set, the state of On Multiple Entries becomes relevant:

– !!!If On Multiple Entries is enabled, you need to check the script in yourhook, and if it does not contain a setCurrent(), you might want to select oneof the entries usingthisConnector.setCurrent(thisConnector.getNextDuplicateEntry());

– If On Multiple Entries is not enabled, and neither is On error, the converteradds a On Multiple Entries hook with the contentsystem.skipEntry("Multiple Entries Found");

Update Mode

Multiple entries found: Note that this stituation was and is difficult: If your linkcriteria returns multiple entries, it is not obvious which of the entries should bechanged. Certain drivers might not even let you do multiple updates and the IBMDirectory Integrator philosophy is to treat one entry at a time, never to do multipleupdates. This means that different Connectors could and can behave differently.v If On Multiple Entries Hook enabled:

Old behaviorCalled On Multiple Entries Hook. If setCurrent was called, tried to usethat entry (submitting the update to the datasource using the linkcriteria that found multiple entries), otherwise usedgetNextDuplicateEntry. If this resulted in no entry set, added anotherentry. (Multiple entries could be changed, but in general the behaviorwas undefined).

New behaviorCalls On Multiple Entries Hook. If setCurrent is called, try to use thatentry (submitting the update to the datasource using the link criteriathat found multiple entries), otherwise continue with On Success (seeAppendix E, “Connector modes flowcharts” on page 227).


Old behaviorLogged a messages and threw SkipEntryException exception (continuingwith Iterator).


New behavior

– If failure hook (On error) enabled: Call failure hook.– If failure hook disabled: Abort AssemblyLine

!!! If you had code in your On Multiple Entries Hook, check that it still does whatyou intend it to do.

If On Update Error is not enabled, the converter will add an On Multiple EntriesHook with the contentsystem.skipEntry("Multiple Entries Found");


Delete Mode

No entries found: There is a new Hook, No Match Found, it will not exist in oldfiles. It is called when the link criteria return no matches.

Old behaviorCall failure hook if it exists. Continue with On Success.

New behaviorCalls No Match Found hook if enabled. If failure hook exists, calls thatHook, otherwise aborts AssemblyLine.

If On Error is disabled, the converter will add a No Match Found Hook with thecontentsystem.ignoreEntry("No Entries Found");


Multiple entries found:

v If On Multiple Entries Hook enabled:

Old behaviorCalled hook. If setCurrent was called, used that entry. If this resulted inno entry set, continued as if no Entries were found.

New behaviorCall hook. If setCurrent was called, used that entry. If this resulted in noentry set, continue with On Success flow.


Old behavior

– If failure hook (On error) enabled: Call failure hook.– If failure hook disabled: abort AssemblyLine.

New behavior

– If failure hook (On error) enabled: Call failure hook.– If failure hook disabled: Abort AssemblyLine

No changes needed to maintain pre-5.1.1 behavior.

CallReply modeCallReply mode is used to make requests to data source services (like Webservices) which require you to send input parameters and then return theinformation you request. Unlike the other modes, CallReply give access to bothInput and Output AttributeMaps.


Notesv The mode specific On success Hook is called even after mode specific override

Hook is called.v The default Error Hook is called after the mode specific error Hook, even if that

error hook is enabled, unless the mode specific error hook changes the flow.

ConnectorsFile Connector

Mode is removed (Input/Output/Append). It is simplified by a checkboxfor Append. The Connector will understand whether it is supposed to doinput or output dependent on the mode. ’Connect’ in the GUI can alwaysbe performed safely. It used to be that if the Connector was in Outputmode, Connecting would reset the file. File Connector can now read fromstandard input/output.

JDBC Connector

The JDBC Connector now tries to keep both date and timestamp if they arepresent. It used to heed only the date part of an Oracle SQL Date (OracleDate can contain a time as well, contrary to other SQL dialects).

JDBC Connector now supports a Schema parameter. The schema parameteris added for the users to specify the schema name of the table belongs to.If the schema is not specified, the user name is used as schema name. Thetable list field in the configuration panel displays the table names in theschema.

Add Only ConnectorsIn previous releases, Add Only Connectors without attribute map couldmap out entries. Add Only Connectors cannot function this way in IBMDirectory Integrator 5.1.1.

ActiveDirectory ChangeLog ConnectorActiveDirectory ChangeLog Connector has increased performance whenlooking up DN in this release.

There are new Connectors for release 5.1.1:v “Web Service Connector” on page 133v “Domino Users Connector” on page 63

SchemaConnecting to a datasource and exploring it, is now replaced by the Schema tab forConnectors. See “Discover schemas and browsing data” on page 190.

DeltasA ″Return Unchanged″ flag now exists in the delta connector. There are also newpossible values for the getOp() and getOperation() methods for the Entry object, ’u’and ″unchanged″.

Parsersv LDIF parser now can suppress the LDIF version number by using the

ldifVersion parameter. This creates compatibility with old versions were theLDIF standard was followed more laxly.


Scripting/Debuggingv Highly improved parameter passing to/from AssemblyLines: The Task Call

Block. Also sports the Accumulator that lets you accumulate result from anAssemblyLine and return it in one chunk.

v Line numbers are supplied when script errors are found (during parsing notexecution).

v Name of the hook where the error is located will often show up when errors arecaught during execution.

v try/catch construction available within JavaScript™.v Inherited static methods now work. For example, task.sleep() is now available.

With earlier versions of IBM Directory Integrator, you had to writejava.lang.Thread.sleep() to get access to task.sleep().

v Debug Interface changed and improved.v While debugging, visual trace of where you are in the AssemblyLine flow.

InheritanceConnectors can now inherit connection parameters, parser, schema, attribute maps,link criteria, hooks, delta settings and schema from other Connectors.

Deleted componentsThe following components have been removed from the IBM Directory Integratorinstallation.v LDAP Browserv JDBC Browserv AssemblyLine report (report can now easily be generated from the

xml-configuration files)v ADSI Connectorv EMI/UCP Connectorv GSM Phone Connectorv Microsoft® Outlook Contacts Connectorv SMPP Connectorv Oracle 8 JDBC Driver Connector (including the following):

– JDBC-based Connectors– Oracle Thin JDBC driver Connector– mySQL JDBC driver Connector

These components still work with the JDBC Connector. As before, you mustinstall the native driver.

v CDS-EDB Parserv Support for Fiorano MQ and SoniqMQ currently removed.v AdminPort Event Handler (replaced by AMC functionality)v CronJob Event Handler (replaced by Timer Event Handler)v ComPort Connectorv LDAP Listenerv Mailbox Listenerv TCP Listenerv SNMP Event Handler


Documentationv Most of the methods are removed from this manual and only documented in the

JavaDocs (root_directory\docs\api).v IBM Directory Integrator 5.1.1: Reference Guide updated to reflect new and

changed functionality for release 5.1.1.v IBM Directory Integrator 5.1.1: Getting Started Guide updated to reflect new and

changed functionality for release 5.1.1.v IBM Directory Integrator 5.1.1: Administrator Interface added to the documentation

library for release 5.1.1.


Chapter 3. Supported platforms

IBM Directory Integrator ships with IBM JRE 1.3.1.

The following are the platforms supported for IBM Directory Integrator. Aminimum of 128 MB RAM is required for each platform (256 MB is stronglyrecommended):v Windows NT® 4.0, Windows 2000v AIX® 4.3.3, or laterv Solaris 7, or laterv HP-UX 11, or laterv Linux Intel

– RedHat 7.2, 7.3– SuSE 7.2,7.3,8.0– United Linux– RedHat Advanced Server 2.1

v Linux s/390– RedHat/SuSE/TurboLinux with kernel level of 2.4.x


Chapter 4. IBM Directory Integrator concepts

The AssemblyLineThe general philosophy of an AssemblyLine, is that it processes data (for example,entries, records, items, objects) from one data source, transform and aggregate itwith data from others sources and finally output it to one or several targets.

It is important to keep in mind that the AssemblyLine is designed and optimizedfor working with one item at a time. However, if you would like to do multipleupdates 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 wantto sort data. This kind of processing can be implemented using your choice ofscripts, Java™ libraries and standard IBM Directory Integrator functionality (likepooling the data to a sorted datastore, for example, JDBC Connector) and thenreading it back and processing it with a second AssemblyLine.

The AssemblyLine consists of a number of Connectors that operate in specificmodes. It is the AssemblyLine that does the work (it is in a way your program).For an overview of the AssemblyLine please read the Getting Started guide.

When naming an AssemblyLine, use alpha-numeric characters only. Do not usespecial national characters (for example, å, ä), separators, and so forth. These mustbe avoided as they can cause incompatibility problems.

In short the AssemblyLine consists of:v EventHandler. (Optional) An EventHandler that decides when the AssemblyLine

runs (could be when a file shows up on a directory or when a mail arrives). TheEventHandler is a part of a configuration file and decides when theAssemblyLine runs from outside itself (without being a part of AssemblyLine).

v Connectors. Two or more Connectors that are plugged into your datasource (filesystem, ldap, database, and so forth) Usually, one Connector provides input tothe AssemblyLine, and at least one provides output. A rich Connector library isone of the strength of the IBM Directory Integrator, but you can of course writeyour own Connectors. The Connectors can be run in different modes likeIterator, Update, Delete etc. AssemblyLines can in fact have fewer Connectors(this is for the advanced user).

v Parser. (sometimes) If the Connector delivers a bytestream (such as a urlConnector or a file Connector), the Connector has a Parser associated with it. Asfor Connectors, you can write your own but a set of standard Parsers areavailable.

v A business body where data from the Connectors are subject to your businesslogic such as transformation, verification etc. If you leave the body (Prolog,Dataflow and Epilog in the IBM Directory Integrator Admin tool) empty, youhave probably implemented a filter translating from one format to another. Thisbody is not physical, since the code is located in the Connectors. The exceptionbeing the script Component, that just contains code.

v The work object contains attributes that can be shared between Connectors.Mapping between the data source and the work Entry is described in detailunder “Attribute Mapping” on page 44.

v Script Connector. The Script Connector enables you to write your ownConnector using a script you are familiar with.


The AssemblyLine is usually started by some external event or by the user fromthe IBM Directory Integrator Admin tool. The AssemblyLine is defined by a file.This file defines a server that is independent of the Admin tool Graphical UserInterface to run.

Starting an AssemblyLineThe AssemblyLine flow starts with the execution of code placed in the ″BeforeConnectors Initialized″ subtab of the Prolog tab. This could be a good place tocreate a file one of the Connectors expects (typically the result of a preprocessedinput file). You could also place code here which change connector specificparameters, such as filenames.

Then Connectors are initialized. Each Connector’s initialize function is called in thisstep. If the Connector operates in Iterator mode, then the Connector’s selectEntriesfunction is also called.

Then, when all Connectors are ready for action, the AssemblyLine’s Prolog’s″AfterConnectors Initialized″ code is executed.

The Connectors are then called in the sequence in which they appear in theconfiguration. Think of this as having each of your data entries flowing down theAssemblyLine.v If you have more than one Connector in Iterator mode, these Connectors are

stacked in the order in which they appear in the configuration. If you have twoIterators, a and b, then a is called until it returns no more entries before theAssemblyLine switches to b.

v If you have no Connectors in Iterator mode, there are no Entry provided by acalling Handler, and no Entry set in the Prolog, the AssemblyLine still performsa single pass.

Controlling an AssemblyLineHooks 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 typicallydo this from within a Hook in a Connector:v (system.ignoreEntry) - Ignore the current Connector and continue processing

your existing data entry with the next Connector.v (system.skipEntry) - Skip (drop) the entry completely and get the next entry (from

the current iterator).v (system.restartEntry) - Re-execute the AssemblyLine without getting fresh entry

data from the current Iterator.v system.skipTo(String name) - Skip to the named Connector.v system.abortAssemblyLine(String reason) - Abort the entire AssemblyLine.

Note that if you put any of these command in an Error Hook, the AssemblyLinecontinues regardless of how you got to the Error Hook. This means that evensyntax errors in your script are ignored. Check the object if you want to knowwhat caused the error.

Also note that the methods above are implemented as exceptions: This means thatno code following these calls are called.


Starting from the Admin toolWhen you start an AssemblyLine from the Admin tool you usually have at leastone Connector operating in Iterator mode, unless you provide the AssemblyLinewith an initial entry. If you don’t have an iterator the AssemblyLine has no datafeeding it. You can have multiple Connectors as iterators: The AssemblyLine startswith the first iterator and continue with the next after draining each iterator in theAssemblyLine.

Starting from an EventHandler or scriptRefer to “AssemblyLine parameter passing” for more information.

Accessing connectors inside the AssemblyLineYou may have noticed that you can dynamically load Connectors in your scriptsusing the system.getConnector function. The Connector object you get from that iswhat we call the raw Connector object. Inside the AssemblyLine however, eachConnector is embedded in a wrapper that provides additional functionality to theConnector. Each Connector is available in the AssemblyLine scripts as the nameyou chose for the Connector when it was added to the AssemblyLine.

When creating XML files from an LDAP directory or LDIF file,the AssemblyLine fails.

When reading from an LDAP directory or an LDIF file, the distinguished namewill typically be in an attribute named $dn. If you map this attribute withoutchanging the name into an XML file, it will fail because $dn is not a legal tag in anXML document. If you do explicit mapping, you should change ″$dn″ to ″dn″ (orsomething without a special character) in your output connector. If you do implicitmapping (e.g. * or ″Automatically map all attributes″ checked inAssemblyLine/Settings) you could configure the XML parser to translate thedistinguished name (i.e. $dn) to a different name. For example, you could addsomething like this in the Before Add Hook:conn.setAttribute("dn", work.getAttribute("$dn"));conn.removeAttribute("$dn");

AssemblyLine parameter passingThere are three ways for data to get into an AssemblyLine:v Generating your own initial entry inside the AssemblyLinev Being fed from one or more Iteratorsv Starting the AssemblyLine with parameters from another AssemblyLine or

EventHandler

This section addresses the final point. There are two ways to start theAssemblyLine with parameters:v Using the Task Call Block (preferred way)v Providing an initial work entry (provided for backwards compatibility)

TaskCallBlock

Basic Use: The TaskCallBlock (TCB) is used by a caller to set a number ofparameters for an AssemblyLine. The TCB can provide the user with a list ofinput/output parameters specified by an AssemblyLine and also all the connectorsand their parameters the user can set. You can use this feature to discover

Chapter 4. IBM Directory Integrator concepts 19

dynamically what an AssemblyLine is expecting as its initial work entry and alsowhat it returns in its result entry. The TCB consists of the following logicalsections:v The Initial Work Entry passed to the AssemblyLine (tcb.setInitalWorkEntry)v The connector parameters (tcb.setConnectorParameter)v The input/output mapping rules for the AssemblyLine (set in Admin tool under

Call/Return)v An optional user provided accumulator object that receives all work entries from

the AssemblyLine (tcb.setAccumulator)

Calling an AssemblyLine with an initial work entry ( iwe ) and setting theMyInput connector’s filePath parameter to ’d:/myinput.txt’ is accomplished withthe following code:var tcb = system.newTCB();tcb.setInitialWorkEntry ( iwe );tcb.setConnectorParameter ( "MyInput", "filePath", "d:/myinput.txt" );var al = main.startAL ( "MyAssemblyLine", tcb );

Using the accumulator: The TCB is also called by the AssemblyLine for eachwork entry in the AssemblyLine. This work entry can be accumulated by the TCBinto an object called the accumulator. The accumulator can be one of the following:v java.util.Collection - All work entries are cloned and added to the collection (e.g.

ArrayList, Vector ..)v com.ibm.di.server.ConnectorInterface - The putEntry() method is calledv com.ibm.di.server.ParserInterface - The writeEntry() method is calledv com.ibm.di.server.AssemblyLineComponent - The add() method is called

If the accumulator is not of the above classes/interfaces an exception is thrown.

To accumulate all work entries of an AssemblyLine into an XML file you could dothis:var parser = system.getParser ( "example_name.XML" );parser.setOutputStream ( new java.io.FileOutputStream ( "d:/accum.xml" ));parser.initParser();tcb.setAccumulator ( parser );

var al = main.startAL ( "MyAssemblyLine", tcb );al.join();

parser.closeParser();

Of course, you could configure a connector instead of programming the parsermanually as in:var connector = system.getConnector("MypreconfiguredOutputConnectorWithXMLParser");tcb.setAccumulator ( connector );....connector.terminate();

The TCB is typically initialized by the user and then used by the AssemblyLine. Ifthe AssemblyLine has a call/return specification the TCB remaps input attributes(initial work entry) into what the AssemblyLine expects internally and likewise forsetting the result object. This is done so that the external call interface to anAssemblyLine can remain the same even though the internal work entry nameschange in the AssemblyLine itself. Once the TCB is passed to an AssemblyLine youshould not expect anything more from the TCB. Use the AssemblyLine’sgetResult() and getStats() to retrieve the result object and statistics.


The TCB result mapping is performed before the Epilog so you can still access thefinal result before the caller of the AssemblyLine gets to it.

Providing an initial work entryThis is an alternative way of passing parameters. It used to be the only way topass parameters, but is still supported for backward compatibility reasons.

When an AssemblyLine is started (through startAL) by an EventHandler or from ascript, the AssemblyLine may be passed parameters feeding it, e.g. an initialworking entry (work). The work entry is sent through the AssemblyLines thatterminate after one iteration. You can investigate the result (which is the workingentry when the AssemblyLine terminates) by using the getResult() function. Seealso “(runtime provided) Connector” on page 127.For example:var entry = system.newEntry();entry.setAttribute ("cn", "My Name");

// Here we start the AssemblyLine itselfvar al = main.startAL ( "AssemblyLine", entry );

// wait for al to finishal.join();

var result = al.getResult();

// assume al sets the mail attribute in its working entrytask.logmsg ("Returned email = " + result.getString("mail"));

ConnectorsConnectors are used to access and update information sources in a variety offormats and protocols. There are basically two types of connectors. The first iswhere both transport and content is known to the connector using a well knownAPI (like JDBC, LDAP). The second type is where the transport mechanism isknown but not the content. The latter requires a Parser to interpret or generate thecontent in order to function properly.

When you select a Connector for your AssemblyLine, a dialogue box is displayed,enabling you to choose the type of Connector you want to inherit from:

system:/Connectors/ibmdiThese Connectors are the standard out-of-the-box Connectors.

/Connectors/These are Connectors that you have preconfigured in the currentconfiguration file (located in your Connector Library).

myInclude:/Connectors/These are Connectors that you can include from another configuration file(see “Include/Namespaces” on page 47).

@myConnectorThis is a very special case where, instead of inheriting a Connector, youcan reuse the configuration of a Connector already in your AssemblyLine(myConnector is used as an example, it can be any Connector name).

A list of all Connectors included with the IBM Directory Integrator is included (see“Connector availability and reference” on page 59). But you can also write yourown Connector (see “Writing a new Raw Connector” on page 198).


Connectors operate in the following modes: Iterator, Lookup, AddOnly, Update, Deleteand CallReply. Each Connector mode determines a specific Connector’s behavior.Note however, that it is not necessary that every Connector support all of themodes available. When you use a Connector you should first consult its manualfor the modes supported.

Connector SchemaAs you probably know, Connectors can read and write data. The ConnectorSchema describes what to expect. If an input field is required, the AssemblyLinewill fail if it does not show up in the raw Connector.

The schema can be seen in the Schema tab of the Connector and certain behaviorcan be customized there. See “Discover schemas and browsing data” on page 190.

How do Connectors share data?Connectors not in Iterator mode have their data passed through the work object.You can create your own Working Entry in the Prolog by:init_work = system.newEntry(); // Create a new Entry objectinit_work.setAttribute("uid", "cchateauvieux"); // populate ittask.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 aninvisible one pass Iterator. See “Multiple Iterators in an AssemblyLine” below forside effect this causes.

Work entry can be populated by a Lookup mode connector also.

Connector modesFor more information on Connector Modes, see Appendix E, “Connector modesflowcharts” on page 227.

Iterator modeConnectors 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 theirattributes’ values and delivers each Entry to the AssemblyLine and its non-Iteratorconnectors. 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. EachConnector presents an abstract layer over the particular data source and you accessand process data through instances of the Entry and Attribute classes.

In fact, each AssemblyLine (except those called with an initial Entry, see“AssemblyLine parameter passing” on page 19) should contain at least oneConnector in Iterator mode. Iterators (Connectors in Iterator mode) supply theAssemblyLine with data. If an AssemblyLine has no Iterator it is often uselessunless it gets data from another source (see “AssemblyLine parameter passing” onpage 19).

Iterators are always regarded as being first in the AssemblyLine. They are executedbefore other non-iterator Connectors, regardless of their place in the AssemblyLine.

Multiple Iterators in an AssemblyLine: If you have more than one Connector inIterator mode, these Connectors are stacked in the order in which they appear inthe configuration and processed one at the time. An initial work Entry is treated ascoming from an invisible Iterator processed before any other Iterators.


Assume you have an AssemblyLine with two Iterators, a preceding b. a is firstused (the AssemblyLine ignoring b) until it returns no more entries. Then theAssemblyLine switches to b (ignoring a). An initial work Entry is treated like itcame from an invisible Iterator before a and b: It would be processed (theAssemblyLine 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 itcontains the wrong Attributes, and has been used for instance in the Prolog, youcould call task.setWork(null) in the Prolog to remove the initial work Entry, thuscausing the first Iterator to be used to get the first work Entry.

Using the Iterator mode: The most common pattern for using a Connector inIterator mode should be:1. Add a Connector in Iterator mode to your AssemblyLine.2. Choose the config... link from IBM Directory Integrator Admin tool user

interface.3. Set values for the Connector’s parameters (usually specifying the data source to

be used).4. Go to the Schema section (tab) of the Configure Connector dialog.5. Click Connect to connect to the data source.6. Click Query Schema (or Next if Query Schema is not supported) to retrieve an

Entry’s Attributes.7. In the Input Map Connector’s section click Select and mark all Attributes you

need in your integration process.

These Attributes are retrieved from the data source and passed to the non-IteratorConnectors in your AssemblyLine.

Lookup modeLookup Connectors give the possibility to join data from different data sourcesusing the relations among the entities from these data sources.

The main action in setting up and using a Lookup Connector is the configuration ofits Link Criteria. It is always configured through the IBM Directory IntegratorAdmin tool user interface - each Lookup Connector has an associated Link Criteriatab. The tab defines the rule for finding relevant entries. The Link Criteria rule itselfis either a conjunction of simple conditions required for certain Entry’s attributesor a more general Connector specific mini script.

For more information about new Hooks in IBM Directory Integrator, see “Hookchanges for 5.1.1” on page 8.

Using the Lookup mode: The most common pattern for using a Connector inLookup mode should be:1. Add a Connector in Lookup mode to your AssemblyLine.2. Choose the ″configure...″ link from IBM Directory Integrator Admin tool user

interface.3. Set values for Connector’s parameters (usually specifying the data source to

look up in).4. Go to the Schema 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 retrieve Entry’s Attribute.


7. In the ″Input Map″ Connector’s section (tab), drag and drop the Attributes youneed in your integration process (these include the Attributes used for lookingup) from the left window to the right window.

8. In the (Link Criteria) tab of the Connector, add all criteria for looking up.

All new Attributes added from the Lookup Connector along with the Attributesadded from previous Iterator and Lookup Connectors are available for the otherConnectors in the AssemblyLine.

AddOnly modeConnectors in AddOnly mode are used for adding new data in a data source. ThisConnector mode requires almost no configuration - just point out the attributes ofthe Entry and the data source parameters. The AddOnly Connector receives 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 aConnector 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 tool user

interface.3. Set values for Connector’s parameters (usually specifying the output data

source to be used).4. In the Connector’s ″Output Map″ section, drag and drop all working Attributes

you need from the work entry window to the Connector attribute window. Youcan also create your own Attributes and calculate their values throughscripting.

Entries with the Attributes you have selected are added in the data source duringAssemblyLine’s execution.

Update modeConnectors in Update mode are used for adding and modifying data in a datasource. For each Entry passed from the AssemblyLine, the Update Connector triesto locate an Entry from the data source to modify with the Entry’s attributes valuesreceived.

The rule for finding the Entry for modification is configured in the Link Criteriasection in the same format as in the Lookup mode. If no such Entry is found, a newEntry is added to the data source. If one such Entry is found, it is modified. Ifmore than one entry matches the Link Criteria, the ″Multiple Entries Found″ Hookis called. Furthermore, each attribute can be tuned whether to be modified oradded, when respectively Modify or Add operation is performed.

When doing a Modify operation, only those attributes that are marked as Modify(Mod) in the Output Map, are changed in the data source. If the Entry passed fromthe AssemblyLine does not have a value for one attribute, the Null Value Behaviorfor that attribute becomes significant. If it is set to ″Delete″, the attribute does notexist in the modifying entry, thus the attribute cannot be changed in the datasource. If it is set to ″NULL″, the attribute exists in the modifying entry, but with anull value, 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 values against the oldones and updates only if and where needed. Thus you can skip unnecessaryupdates which can be really valuable if the update operation is a heavy one for theparticular data source you are updating.


Using the Update mode: The most common and simple pattern for using aConnector in Update mode should be:1. Add a Connector in Update mode to your AssemblyLine.2. Choose the ″configure...″ link from IBM Directory Integrator Admin tool user


source to be used).4. Go to the ″Schema″ tab of the Connector.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 retrieve Entry’s Attributes.7. In the Connector’s ″Output Map″ section, drag and drop all working Attributes

you need from the work entry window to the Connector attribute window. Youcan also create your own Attributes and calculate their values throughscripting. Through the ″Add″ and ″Modify″ check-boxes you can specify foreach Attribute whether it should be modified or added when respectivelyModify or Add operation is performed.

8. In the Link Criteria tab of the Connector, add all criteria for fixing the Entry tobe updated (or finding out that it is missing and has to be added).

Entries’ Attributes you have selected are updated in the data source duringAssemblyLine’s execution.

Delete modeConnectors in Delete mode are used for deleting data from a data source. For eachEntry passed from the AssemblyLine, the Delete Connector tries to locate an Entryfrom the data source. If one Entry is found, it is deleted, otherwise nothinghappens. The rules for finding the Entry for deletion is configured in the LinkCriteria section in the same format as in the Lookup mode.

Using the Delete mode: The most common and simple pattern for using aConnector 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 tool user


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.

CallReplyCallReply mode is used to make requests to data source services (like Webservices) which require you to send input parameters and then return theinformation you request. Unlike the other modes, CallReply give access to bothInput and Output AttributeMaps.

Connector states

EnabledEnabled is the normal Connector state and the one described previous. Data flowsthrough the enabled state.


PassiveConnectors in Passive state are not passed Entries during the AssemblyLineexecution. They are initialized by the AssemblyLine, but never used in thestandard AssemblyLine’s execution process. Because it is initialized, a Connector inpassive state has to contain legal parameters.

Connectors in passive state can be invoked by script code from any of the controlpoints for scripting provided by IBM Directory Integrator.

Using the Passive state: The most common and simple pattern for using aConnector in Passive state should be:1. Add a Connector in Passive mode anywhere in your AssemblyLine.2. Set values 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 otherConnectors.

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 havenamed the Passive Connector MyPassive and want it to add an entry with anerror message , the code may look like this:var err = system.newEntry();err.merge(work);err.setAttribute ( "ERROR", "Failed to do something" );MyPassive.connector.putEntry ( err ) ;

4. The methods available to the connector attribute of the Passive Connector, aredocumented in “The Raw Connector object” on page 182.

DisabledThe Connector is neither initialized, nor operated during normal AssemblyLineexecution. If you want to use it in your scripts, then you have to initialize ityourself.

This state is often used during troubleshooting in order to simplify the solutionwhile debugging, helping to localize any problems.

Link criteriaThe Link Criteria is used to let Update, Lookup and Delete Connectors know whatrecord to access in the external datasource. The Link Criteria is accessible in theAdmin tool through a tab that you find in Update, Lookup and Delete Connectors.

There are two variants of Link Criteria: Simple and Advanced.

Simple link criteriaIn a simple case it links a value from the AssemblyLine with a value from thedatasource. To be more precise it links the value of an attribute in the work entry toa value of an attribute in the raw Connector.

As an example, imagine we have a work entry with an attribute called Name. Wewant from a database the row of table Student where column ID is equal towork.Name.

Using Simple Link Criteria (default), the syntax would be:

ID equal ($Name)


As you see from the Link Criteria tab, drop-downs for these three columns areprovided. For the Connector Attribute column you must have previously done aConnect/Query Schema in the Configure/Attribute window in order to getdrop-down values.

A Connector can have many link criteria. They are added by using the Add button.If you have several link criteria, there is an implicit AND operator between them.

Note that in the example above, the Value was set to $Name. The possible formatsfor Value arev A text string - mapped to a constant with that valuev $Name - corresponds to work.getString(″Name″), that is the first value of the

attribute Name.

v @Name - meaning ’one of the values of the multi-valued attribute Name

Advanced link criteriaSometimes, the Simple Link Criteria is not enough, because multiple link criteriaare always ANDed. OR can always be simulated. Define several connectors tolookup each part of the search criteria, then use whatever entry is first returnedfirst by each of these lookups in the rest of the AssemblyLine. Each of these lookupconnectors must have the same attribute map, but once an entry has been found,all following lookup connectors are ignored (for example, by using alookupSucceeded flag that you use in the before execute lookup hooks to ignoreconnectors, and that you set to true in each success hook.

If you select the Build Criteria with Custom Script check box, you are able toscript your link criteria. Not all Connectors support the Advanced Link Criteria,the Connector documentation states if Advanced Link Criteria is not supported

You must populate a text string called ret.filter that provides the Link Criteria orfilter. However, you must know the syntax used by the underlying Raw Connector:An LDAP and an SQL Connector has different syntax.

A simple JavaScript 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 calledID (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 provided by theIBM Directory Integrator.

2. Single quotes have been added since work.getString() returns a string, whileSQL Syntax asks for single quotes around strings constants.

3. The special syntax with $ and @ is not used here.

ERROR> AssemblyLine x failed because No criteria can be builtfrom input (no link criteria specified)This happens when you have a link criteria like:uid equals $w_uid

but the w_uid working attribute is not present in the work entry. This could bebecause it has not been read from the input sources, or was not present in theinput sources. In other words, work.getAttribute(″w_uid″) would return null.


One way to avoid this is to write, in the before_execute hook of the Lookup orUpdate Connector™ that fails, some code to skip the Connector when the linkcriteria cannot be resolved. For example:if (work.getAttribute("w_uid") == null)

system.ignoreEntry();

Your business logic may require other processing, like a skipEntry() call instead ofan ignoreEntry(). skipEntry() will switch to the next entry returned by the currentiterator.

EventHandlerEventHandlers are meant to simplify the task of event enabling the IBM DirectoryIntegrator Server. With the EventHandlers you can configure actions to be takenusing a point & click metaphor. You can script EventHandlers if you want, butIBM Directory Integrator provides some predefined functions to make life easier.

Starting the EventHandlerIn the Admin tool, notice EventHandler in the console tree in the left hand panel.Event Handlers will be listed here. On the config panel of each EventHandler thereis a checkbox for ″auto-start″. When this box is checked, the given Event Handlerwill automatically start when the server is started. This behavior can be disabledby using the -D switch as seen in the command line options help.

If you want to start an EventHandler, open the event handler in question and pressthe run button.

The Event objectThe key object in the EventHandlers is the event object. This object is an instance ofthe familiar entry object you find in AssemblyLines.

Configuration and data flowEach EventHandler consists of a configuration section and a data flow section.

The configuration section contains the parameters that govern each specificEventHandler.

The data flow consists of a prolog, action map and an epilog. The prolog and epilogare executed before and after the action map. The action map contains a number ofactions and dependencies for the actions. This enables you to perform simple testsand start AssemblyLines without typing a single line of script code.

PrologIn this section you can execute script code before the action map is executed. Youhave access to the event object and global functions (e.g. system, main etc.) as usual.

Event Handler action mapIn this section you add action items. Each action item has an associated list of“Conditions” on page 29 and actions. If the list of conditions is true, the actionsunder the Condition True tab is executed, otherwise the Condition False actions areexecuted. If the Consume option is set, and actions are executed, the rest of theaction map is skipped. It is also possible to temporarily Disable an action item.


ConditionsIf Match Any is set, the list of conditions evaluates to true when at least onecondition is true, otherwise all conditions must be true for the list to evaluate totrue. An empty list of conditions is true. Each condition can be a small script, or atest based on properties or attributes of the event object. See“Attribute/propertynames”

ActionsEach action in the action list could be any one of these:v Apply Parser - In Read Mode you set the Parser Input, and the result is put into

the event object. In Write Mode you set the Parser Output, and the event object iswritten, unless you have specified another Entry object as the Parser Input, inwhich case that object is written.

v Run AssemblyLine - Runs a named AssemblyLine. You may send the eventobject to the AssemblyLine as the initial work entry, by setting ″Provide eventobject″. You may even specify a connector to send to the AssemblyLine, see“(runtime provided) Connector” on page 127. If you set the ″Wait forcompletion″ flag, the action list waits for the AssemblyLine to finish, and setsthe properties AssemblyLine.result, AssemblyLine.error and AssemblyLine.stats. Someof the properties may not be set, depending on what happens in theAssemblyLine.

v Custom Script - The script may refer to the event and task objects.v Dump Event Object - writes the event object to the Event Handler’s log file.v Set Property/Attribute - See “Attribute/property names”v Remove Property/Attribute - See “Attribute/property names”v Terminate Handler - terminates the Event Handler with a specified message.

Attribute/property namesIf the name begins with ’entry.’, it is assumed to be an attribute of the event object,otherwise it is a property of the event object. The same rule applies to values in acondition or ″Set Property/Attribute″, but strings surrounded by quotes (″) areconstants.

EpilogThis section is executed after the action map has been completed.

ScriptingIBM Directory Integrator provides its users with a highly-flexible engine that canbe tuned both from the user interface controls of IBM Directory Integrator Admintool as well as through script input from the user. While the user interface controlsprovide a means of controlling the data flow on a higher level, scripting providesusers with the ability to control almost any aspect of the data flow at any level(including overriding standard IBM Directory Integrator processing). Specialfunction exists within the System object to reiterate on an AssemblyLine, skip aConnector and so forth, for example, skipEntry, ignoreEntry, and restartEntry.

IBM Directory Integrator provides support for a number of scripting languages.You can set the Script Language for the entire AssemblyLine in the Settings tab. Ifyou 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 writtenin a script language.


When is scripting needed?Scripting is necessary when you need to add custom processing to yourAssemblyLine. Examples of where scripting would be helpful include:v The value of an attribute in your output Connector is calculated based on one or

more of the input Connector’s attributes.v You want to process only entries that match a particular set of criteria.v You want to override the update operation of the Connector you are using.v 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 customprocessing arises in the integration process. The need for custom data processinginevitably comes in some identifiable point in the flow of data (e.g., before anyprocessing begins, before processing a particular entry, after a failure, etc.). IBMDirectory Integrator provides you with a number of control points throughout thedata flow where you may provide direction through scripting (e.g., theAssemblyLines ″Prolog″ and ″Epilog″ sections, Connectors ″Hooks″ sections, etc.).These control points are easily accessed within the IBM Directory Integrator Admintool. Implementing custom processing is simply a matter of identifying the correctcontrol point and adding your script in the appropriate edit window.

It is important to both correctly identify the appropriate control point where youinput your script as well as limit the scope of your script to cover just that singlegoal associated with the control point.

How does scripting affect execution?The IBM Directory Integrator Engine exposes a number of classes and instancesthat may be accessed, read and modified from user-created scripts in theAssemblyLine. These objects represent the state of the AssemblyLines and thewhole IBM Directory Integrator environment at any moment. By modifying any ofthese objects, you modify the IBM Directory Integrator environment itself and thusaffect the execution of the integration process.

For more information about the global objects, see the Javadocs material includedas part of the IBM Directory Integrator product (go toroot_directory\docs\api\com\ibm\di)

A description of all classes and instances available can be found in the installationpackage.

By understanding the classes and interfaces exposed, you can better understandthe elements of the IBM Directory Integrator engine as well as the language itspeaks.

Using variablesIt is very important to distinguish the holder of the data processed (the Entryobject) from other generic variables and data types provided to you by yourchosen scripting language. Your creativity and the capabilities of the scriptinglanguages are your only restrictions in terms of what may be placed in thescripting windows. However, when you manipulate data in the context of dataflow, you should be aware of and utilize the structure of the Entry object.


As Attribute objects serve as the primary containers for data within the context ofan AssemblyLine, it is just these objects that are accessed and modified during theintegration process. Note that each attribute value is in fact an object and belongsto some class (for example, a date could be either a java.lang.String orjava.util.Date depending of what was inserted in the Attribute by the Connector oruser).

The classes to which the Connector’s attributes belong can be guessed/seen in the″Syntax″ column in the ″Configure Connector″ dialog, ″Schema″ tab.

Knowing the attribute value’s class, one can successfully access and interpret thisvalue. For example, if a java.lang.String attribute contains a floating point valuethat you want to use as a floating point, you must first manually transform thisvalue (by the means of the scripting language) to some numeric data type.

When creating variables or processes not directly related to the data flowing in theintegration process and the global objects available, the following principle applies:You can declare and use any variables (objects) allowed by the scripting languageyou choose. The purpose of these variables should be to help you achieve thespecific goal associated with the control point in which you script. They shouldserve only as temporary buffers and not attempt to affect the state of the IBMDirectory Integrator environment itself.

Control points for scripting

Scripting in an AssemblyLine

AssemblyLine hooks: These are found in the Hooks tabs of the AssemblyLine.They are all executed only once per AssemblyLine run, but if you happen to startyour AssemblyLine multiple times (for example by using an EventHandler), thenyou will of course execute the hooks multiple times as well.v Prolog before Initialization.v Prolog after Initializationv Various hooks found in Dataflow, see Appendix E, “Connector modes

flowcharts” on page 227 and “Script Connector” on page 128.v Epilog

Prolog before Initialization: Here is the place to put code that would modify theparameters of the Connectors. If you at runtime knew the filename to use in a FileConnector, you would saymyConnector.connector.setParam("filePath",fileNameVariable);

Prolog after Initialization: The code here is executed before control is passed tothe Connectors. This is the best place to declare global variables you need throughthe execution of the AssemblyLine (e.g., for counters, average values, etc.).

Epilog: The code is executed once for each run of the AssemblyLine after allConnectors have finished their tasks. A common pattern is to release here allresources allocated in the ″Prolog″ section and save

Shutdown Request: This hook lets you enter script to be executed when theAssemblyLine has been instructed to terminate (e.g. from the AMC Console, orfrom another server). This script allows you to add clean-up code for terminatingthe AssemblyLine cleanly.


Note: if the AssemblyLine gets a shutdown request and this script is empty, thenthis results in an error (that can be handled in the Epilog).

Script ComponentYou may add Script Components to your AssemblyLine in addition to Connectors,by using the Insert new Object button under the Data Flow tab in theAssemblyLine. The Script Components is executed once for each entry processedby the Assembly Line, just like a Connector and can be placed anywhere in theAssemblyLine (but after the Iterators you might have

Scripting in a ConnectorInput/Output Map (separate tab in the Connector)

Custom attribute mapping is performed here. Refer to the GUI manual formore information. When the attribute is selected, you have to choose the″Advanced Mapping″ checkbox, and input your script in the edit window.Remember that after you’ve done all processing necessary, you have toassign the result value achieved to ″ ret.value,″ i.e. ″ ret.value =resultValue; ″

Connector HooksHooks give you the means to respond to certain events that occur, andoverride Connectors’ basic functionality. In the Hooks scope you haveaccess to the global IBM Directory Integrator objects, so you have fullcontrol over the IBM Directory Integrator environment, the AssemblyLine,the Connector itself, entries and attributes. Hooks give you a diversity ofcontrol points for customizing the process flow. See “Hooks” on page 37.

Setting internal parameters by scriptingIt is possible to set Internal Parameters for a Connector by scripting, like this:conn.setParam ( "filePath", "examples/scripting/sample.csv" );

This is typically something you would do in the prolog, but it can be very usefulwhile the AssemblyLine is being executed as well (provided that you terminateand reinitialize the Connector).

Scripting in an EventHandlerReference about scripting in an EventHandler is included in “EventHandler types”on page 137.

Scripting in a parserScripting in a parser actually refers to implementing your own parser by scripting.A description of this process is included in “Script parser” on page 169.

Comparing JavaScript stringsIf you use JavaScript within your AssemblyLines, you might experience somestrange behavior when comparing strings. This is due to some not-always-intuitivebehavior of JavaScript.

To make a long story short, you might want to append the empty string ″″whenever comparing strings in JavaScript. If you want to know why, read on.

The following table shows the behavior when comparing different variables. Allconstants, string literals and JavaScript string objects below contains the characters″test″: If the value is False, you might want to understand why.


var a = ″test″;

a== ″test″

True

var a = ″test″;

var b = ″test″

a== b

True

var c = new String(″test″);

c == ″test″

True (because the object c is cast to a string)

var c = new String(″test″);

var d = new String(″test″);

c == d

False (two string objects are created, but theobjects are not the same. They merelycontain strings that happens to have thesame value. Comparison is done byreferences.)

This is important to understand because the Entry objects all have agetString()method that returns an Object, not a string. Think of it as correspondingto doing a new String(). So assumingvar w = system.newEntry();w.setAttribute("x","test");w.setAttribute("y","test");x = w.getString("y"); // really same as x = new String("test")y = w.getString("y"); // really same as y = new String("test")

gives you

x == y False (because these are two differentobjects, as above)

x == ″test″ True (because x is cast to a string)

var a = ″test″

x == a

True (as above)

(x + ″″) == (y + ″″) True (because appending ″″ to a generalObject containing a string, converts it to aJavaScript string object.)

So unless you understand the type of the string objects you use, you might want toalways play it safe by adding a ″″ before comparing.


Attention:

The statementsn = null;n = n + "";

in JavaScript make the variable n contain the string ″null″. So if you have two nullvariables, n1 and n2

n1 == n2True

n1 + ″″ == n2False (because you compare ″null″ and null)

n1 + ″″ == n2 + ″″True (because you compare ″null″ and ″null″)

So when forcing a ’cast’ by adding ″″, do so on both side of the compare operand.

Accessing your own Java classesYou can access your own Java classes from inside the IBM Directory Integratorframework, as long as it contains public classes and methods. These libraries mustbe packaged into a .jar or .zip file and should be placed in your own subdirectoryof the IBM Directory Integrator jars directory: IBM Directory Integrator finds themthere. You can also use the the CLASSPATH environment variable or the Javaruntime environment extension folder, but both these methods are discouraged.These methods let you call IBM Directory Integrator classes from within your ownclasses only if the loader happened to have loaded the IBM Directory Integratorclasses before your own.

If you are running the Server from the Admin tool, you have to restart the Admintool before it knows about new classes in the jars directory and subdirectories.

After putting the jar-files in the jars/ subdirectory, you can create an instance aninstance of the class to refer to within the IBM Directory Integrator.

Instantiating the classes using the IBM Directory IntegratorAdmin toolUse theJava Library treeview from the left hand panel (it is configurationfile-specific) to declare your classes. This works only if your class has a defaultconstructor (a constructor that does not take arguments). When adding a classobject, you must specify two parameters: the script object name (the name of thescripting object which is an instance of your java class) and the java class name.

For example, you could have a Script Object Name being ″mycls″ while the JavaClass would be my.java.classname. The mycls object would be available whereverthe system object is available, as the system object is really an instance of thecom.ibm.di.function.UserFunctions java class.

Runtime instantiation of the classesIn case you do not want to use the Java Class Objects tab because you want toinstantiate your class at a specific point of execution or your class does not have adefault constructor, or for the classes without default constructors, you need toinstantiate the class during runtime.


Scripting in JavaScript

Using a standard class (for example, which name starts with″java″)Assuming you want to use the standard java.io.FileReader:var javafile = new java.io.FileReader ( "myfile" );

Using non-standard classes (for example, a user class)The ’Packages’ root must be used for the framework to understand that the class isnon-standard. For example, instantiating a class called my.Filereader is done bytyping:var myfile = new Packages.my.FileReader ("myfile");

JavaScript string methodsJavaScript has lot of built-in objects (Strings is one of them), which has severalbuilt-in methods (for example, string.replace). For example, Object stringstring=foo.getString("attribute Name");

returns a datatype string, whereasstring.replace

returns an Object called String.

Your favorite JavaScript documentation describes the available functions, but itcannot tell you that specific strings you encounter within IBM Directory Integratorare Java Strings!

For example, assuming foo is an Entry,string = foo.getString("attributeName")

returns a JavaString, and not a JavaScript string.

So string.replace calls the Java String replace method that wants another set ofparameters and behaves differently.

You can convert a Java String to a JavaScript String by adding an empty string toit, so the following code works (note the extra ″″ added to string).string = foo.getString("attributeName") + "";// This line removes all blanks in stringstring = string.replace(/\s+/g, "");

Scripting in languages without new java.*When you script with a language that does not support the new java.* instruction,you can use the newObject (className) method found in the IBM DirectoryIntegrator (system object):

var f = system.newObject (″java.io.File″);

Note that in this case you cannot call the class constructor with parameters.

Using binary values in scriptingBinary attributes are returned as byte arrays within the scripting code you create.Here is a JavaScript example:


var x = conn.getObject("objectGUID");for ( i = 0; i < x.length; i++ ) {task.logmsg ("GUID[" + i + "]: " + x[i]);}

This would write some numbers varying between -128 and 127 into the logfile. Youmight want to do something else with your data. If you have read a passwordfrom a connector which stored it as a ByteArray, you could convert it to a stringwith this code:password = system.arrayToString(conn.getObject("userpassword"));

Using date values in scriptingWhen we talk about using dates, we are referring to instances of java.util.Date .Armed with any of the available scripting languages you can of course implementyour own mechanism for handling dates. This will not, however, be a commonpractice.

The IBM Directory Integrator scripting engine provides you with a mechanism forparsing dates. The system object has a parseDate(date, format) method accessible atany time. Note that once you get an instance of java.util.Date, you can use thestandard java libraries and classes to extend your processing.

Here is a simple JavaScript example that handles dates. This code can be placedand executed from any scripting control point:var string_date1 = "07.09.1978";var date1 = system.parseDate(string_date1, "dd.MM.yyyy");

var string_date2 = "1977.02.01";var date2 = system.parseDate(string_date2, "yyyy.dd.MM");

task.logmsg(date1 + " is before " + date2 + ": " +date1.before(date2));

The script code first parses two date values (in different formats) into java.util.Date. It then uses the standard java.util.Date method ″before java.util.Date″ todetermine whether the first date instance comes before the second one. The outputof this script is then printed to the log file.

Using floating point values in scriptingThe following examples demonstrate how floating point values can be used withinthe scripting code you create. All of the following examples are implemented inJavaScript. While the same examples may be repeated using several other scriptinglanguages, the syntax may be different. The simple script below assigns floatingpoint values to two variables in order to find their average. This code may beexecuted from any scripting control point. The log file output will always read ″ r= 3.85 ″.var a = 5.5;var b = 2.2;var r = (a + b) / 2;task.logmsg("r = " + r);

The next example extends the simple script presented above. Consider you have inyour input Connector a multiple values attribute called ″Marks″ containing stringvalues (java.lang.String) representing floating point values (a common situation inreality). This attribute is mapped to an attribute in your output Connector called″AverageMark″, which holds the average value of the ″Marks″ attribute’s values.Below is the code used to correctly map these attributes:


01. var values = work.getAttribute("Marks").getValues();02. var sum = 0;04. var count = 0;05. for (i=0; i<values.length; i++)06. {07. sum = sum + new Number(java.lang.Double(values[i]));08. count++;09. }10. var average = (count > 0) ? (sum / count) : 0;

11. avr_attr = system.newAttribute("AverageMark");12. avr_attr.addValue(average);13. ret.value = avr_attr;

In this example, the core of the floating point processing takes place at line 7 . Itfirst parses the attributes’s string value [ java.lang.Double(values[i]) ] and thencreates a numeric value to use in scripting [ newNumber(java.lang.Double(values[i])) ]. Line 10 calculates the average value andassigns it to a variable. Lines 11-13 assign the calculated value as the outputattribute value, thereby completing the mapping operation.

ExamplesIn order to work with the examples complementing this manual, you must referback to the installation package.

To access the example mentioned here, go to the root_directory/examples/scriptingdirectory of your IBM Directory Integrator installation.

HooksThe AssemblyLine objects (“EventHandler” on page 28, Chapter 7, “Connectors” onpage 59) have a mechanism called Hooks allowing you to:1. Override the basic fetch/put functions for Connectors (see “Override Hooks”

on page 38).2. Respond to events signaled by the AssemblyLine: For example, an Iterator

Connector has a Get_fail hook that can be programmed to log or send mailabout input errors.

3. Modify the flow of an AssemblyLine (like skipping a Connector).

Hooks are usually called in the AssemblyLine execution as part of the flow control.If for some good reason you actually want to call a hook yourself, that can beachieved by the JavaScript line myConnector.trigger(″hookName″);where myConnectoris the name you gave your Connector and hookName is the internal name of theHook. The internal name of the hook is documented following and is not to beconfused with the name of the hook as seen in the Admin tool.

In all Hooks (and usually in the epilog ), an object called thisConnector will alwaysbe available. This facilitates use of generic scripts, because you don’t need to knowthe name of the connector. In the epilog thisConnector will be the last connectorexecuted (normally the iterator).

Enabling/disabling HooksBy default, all Hooks are disabled. As soon as you add some code to a particularHook, the Admin tool marks that Hook as enabled. If you do not want a Hook tobe used, you can uncheck the Enabled flag for that Hook. This allows you to keepthe code in your Hook in case you later want to use the code again.


A Hook is enabled if it is marked as enabled, even if it contains no code. This canbe important in error hooks, where IBM Directory Integrator can treat the error ashandled based on the mere presence of an enabled hook.

Override HooksFor every Connector mode there is a mode-specific Override Hook. If this Hook isenabled, first the Before Execute Hook is called (if it is enabled), and then theOverride Hook, before the flow control continues with the next Connector in theAssemblyLine. No other Hooks are called, except Failure Hooks, if necessary.

For a Connector in Update mode, there are also ″Override Add and OverrideModify Hooks. After the Connector has decided that it wants to perform a Modifyor Add operation (based on whether there already exists a matching Entry in thedata source), the appropriate Hook is called if it is enabled. After the Hook hasfinished, the flow control continues with the ″After Update″ and ″Update OK″Hooks.

Failure HooksFailure Hooks allow you to respond to events signalled by the Connector. Forexample, an Iterator Connector has an ″Iterator Error″ hook that can beprogrammed to log or send mail about input errors, or you can modify the flow ofthe AssemblyLine (like skipping the rest of the AssemblyLine). RefertoAppendix E, “Connector modes flowcharts” on page 227 to see when error hooksare called.

When a failure occurs in a Connector, this is what happens:1. The error counter is increased by one.2. The Connector’s mode specific ″On Error″ Hook is called3. If that Hook is not enabled, the Connector’s default (″Top Level″) ″On Error″

Hook is called.4. If no Hook is enabled to catch the error, the AssemblyLine either ignores this

Connector (if this is a Connector in Delete mode), skips the rest of theAssemblyLine (if this is a Connector in Lookup mode), or aborts the entire task.

5. After the Hook, the AssemblyLine continues with the next Connector. If youwant another behavior, you should program it in the Hook with one of themethods described in “The AssemblyLine” on page 17.

List of HooksThe format is:

Admin tool NameInternal Name (Description)

These Hooks are common for all Connectors. See Appendix E, “Connector modesflowcharts” on page 227 to see the flow. These tables are mainly here to let youknow the internal name of hooks (if you want to use the trigger() method).

Before Initializebefore_initialize (called before initialize of the Connector is attempted)

After Initializeafter_initialize (called after the Connector has been initialized)

On Error (In Prolog)initialize_fail (called when the Connector initialization fails. If no Hook is


enabled to catch the error, the AssemblyLine aborts. If a Hook is enabled, itshould take the proper action, which could possibly be to abort theAssemblyLine.)

Before Executebefore_execute (called before every execution of the Connector)

On Success (Dataflow, After ConnectorMode)default_ok (called when a Connector operation has succeeded, after allother OK hooks.)

On Error (Dataflow, After ConnectorMode)default_fail (called when an error occurs during a Connector operation,unless the mode specific fail Hook is enabled. (GetNext fail, AddOnly fail,etc.))

Before Closebefore_close (called before the Connector is closed. The work object is thelast entry processed by the AssemblyLine)

After Closeafter_close (called after the Connector was closed. The work object is thelast entry processed by the AssemblyLine)

On Error (After Epilog)close_fail (called when the Connector fails to close after the AssemblyLinehas finished. If no Hook is enabled to catch this error, it is ignored. ThisHook is only available from version 4.6.6.)

These Hooks are available for Connectors in Iterator mode

Before Selectionbefore_selectEntries (called before the Connector selects entries as part ofthe initialization)

After Selectionafter_selectEntries (called after the Connector has selected entries (in theinitialization))

Before GetNextbefore_getnext (called before the Connector attempts to get the next item)

After GetNextafter_getnext (called after a getnext is successfully performed on theConnector, before mapping is done. An object named conn is available forinspecting or changing the attributes retrieved from the Connector)

On Successget_ok (called after a successful get operation)

On Errorget_fail (called when the getnext operation fails)

These Hooks are available for Connectors in AddOnly mode

Before Addbefore_add (called before an add operation is attempted)

After Addafter_add (called after an entry was successfully added)

On Successaddonly_ok (called after a successful add operation)


On Erroraddonly_fail (called when the add operation fails)

These Hooks are available for Connectors in Delete mode

On Multiple Entriesdelete_multiple (when more than one entry matches the Link Criteria, theConnector calls this Hook if it is enabled, otherwise delete fail is called.)

Before Deletebefore_delete (called before delete is attempted)

After Deleteafter_delete (called after an entry was deleted)

On Successdelete_ok (called after a successful delete operation)

On Errordelete_fail (called when the delete operation fails)

These Hooks are available for Connectors in Lookup mode

Before Lookupbefore_lookup (called before lookup is attempted)

On Multiple Entrieslookup_multiple (when the result yields more than one matching entry, theConnector calls this Hook. See Appendix E, “Connector modes flowcharts”on page 227 for a description on how to select a particular entry).

After Lookupafter_lookup (called after an entry was found, before mapping is done. Anobject named conn is available for inspecting or changing the attributesretrieved from the Connector)

On Successlookup_ok (called after a successful lookup operation. See Appendix E,“Connector modes flowcharts” on page 227 for more information).

On Errorlookup_fail (called when the lookup operation fails (no entries found, ormultiple entries found and the corresponding Hook not enabled))

These Hooks are available for Connectors in Update mode

Before Updatebefore_update (called before an update is attempted (add or modify))

Multiple Entries Foundupdate_multiple (called when there are more than one matching entry. Ifthe Hook is not enabled and there are multiple entries, the update is notperformed.)

Before Modifybefore_modify (called before a modify operation is attempted)

Modify NoChangesmodify_nochange (called when an Update Connector with the ComputeChanges flag set, reports no changes to update)

Before Applying Changesmodify_apply (called immediately before a modification is performed. This


Hook is called only when the Compute Changes flag is set. If no changesapply, the Modify No Changes Hook is called instead)

After Modifyafter_modify (called after an entry was modified)

Before Addbefore_add (called before an add operation is attempted)

After Addafter_add (called after an entry was successfully added)

After Updateafter_update (called after successful update (add/modify))

On Successupdate_ok (called after a successful update operation (add/modify))

On Errorupdate_fail (called when the update operation fails (add/modify))

These Hooks are available for Connectors in CallReply mode

Before CallReplybefore_call (called before the call)

After CallReplyafter_reply (after the call returns)

CallReply Succesfullcallreply_ok (called if CallReply was successful)

CallReply Errorcallreply_fail (called if CallReply operation failed)

Deltas and compute changes

DeltasAttention: The Delta mechanism should be avoided if you can. Not because itdoes not work as it should, but because it introduces a new local repository inorder to manage the synchronization process. The data source which is beingscanned for changes becomes the master in a master-slave relationship, and it isthen vital that all changes made to the slave be done such that the Deltamechanism is informed of them. Otherwise, the temporary Delta database whichthe IBM Directory Integrator maintains becomes inconsistent, and the Deltafunction fails.

However, there are some situations where you want to integrate as non-intrusivelyas possible, or be forced to, for example, with a legacy application that cannot beinterfaced directly. In cases like this you may be forced to read a change loggenerated by the target system, or even a periodic dump of all registered entries.Here is where the Delta feature can be used so that IBM Directory Integrator candetermine which Entries are new, modified or deleted.

Whenever possible, use the Compute Changes functionality of the Updateconnector mode instead of the Delta feature.

Deltas are used to synchronize a slave data source with a master. The Deltamechanism knows whether Entries or Attributes have been added, changed or


deleted in the master and replicate the changes to the slave. However, if the slaveis changed by anyone but the Delta mechanism, the Delta mechanism neverdiscovers it.

You can set Delta settings on Iterator Connectors only. The effect of this is that thefirst time the Connector iterates through the data, it records each Entry in a localhigh-speed B-tree database. Then, on successive runs, the Connector looks up eachEntry read, and sees if it has been changed (requiring a modify), is new (resultingin an add), or has gone missing from the input data source (signalling a delete).

Note that this functionality could be implemented by hand by creating a separateLookup Connector for any database of choice, and using it to check whether add,modify or delete was necessary. The IBM Directory Integrator Delta feature simplywraps all this into a check box. If the repository you are creating in the B-tree getsbig, you should consider using a more scalable data storage such as an SQLdatabase.

Process workflowThe Delta functionality uses a local B-tree database for storing all Entries handledby the Iterator Connector during its runs. During a run of the AssemblyLine eachEntry is compared to its record in the local B-tree database if it exists. Thus eachEntry is tracked for existence and changes in its Attributes’ values.

After the Entry’s Attributes have been mapped into the work entry, these Attributesare stored in the local B-tree database. One of the Attributes is selected as theunique key Attribute–this is configured in IBM Directory Integrator Admin tool,Iterator’s Delta tab. Note that the key Attribute must be unique for each Entry. ThisAttribute is used to retrieve the copy stored in the local database, and determinethis Entry’s state–unchanged, new, modified or deleted. This state is set in the workEntry, and the Entry is delivered to the other Connectors in the AssemblyLine. Youcan get an Entry’s state from within your scripts through the ″getOperation()″ Entrymethod (in an Output Connector you may actually have to filter Entries accordingto their state and this means you have to examine the value of″work.getOperation()″).

Below is the sequence of actions performed by IBM Directory Integrator todetermine the state of each Entry obtained from the data source:1. The Iterator retrieves the Entry from the data source and does the Attribute

Mapping.2. A search is performed in the local B-tree database for the Entry, based on the

specified key Attribute.3. If no Entry is found in the B-tree database, the Entry processed is marked as

new and the ″getOperation()″ method returns the value of ″add″.4. If an Entry with the same key Attribute value is found then:5. If any of the Attributes’ values have changed then the Entry processed is

marked as modified, and the ″getOperation()″ method returns the value of″modify″. (conn.getProperty() used in after getnext hook supplies you with anentry called delta.old which was the entry as it was before it was modified).

6. If none of the Attributes’ values have changed, the Entry is skipped, i.e. notpassed to the other Connectors in the AssemblyLine. You can override thisfunctionality by checking the ″Return Unchanged″ flag: It might be that youstill want to process the entry for some reason.

If you want the Delta mechanism to process the Entries that have been deletedthen you have to turn on the ″Read Deleted″ option in the Iterator’s ″Delta″ tab.


With this option turned on, the following processing occurs after the IteratorConnector has read all Entries from the data source:1. The local B-tree database is scanned.2. Each Entry present in the B-tree database and not retrieved by the Iterator

Connector is marked for deletion. This means the ″getOperation()″ methodreturns the value of ″delete″ for these Entries.

Another important Delta option concerning the processing of the deleted Entries is″Remove Deleted″. When this option is turned on the deleted Entries, oncedetermined, are removed from the local B-tree database. When the option is turnedoff, these Entries stay in the B-tree database and are processed for deletion infurther executions of the AssemblyLine. If you delete Entries in the target system,you typically want to check ″Remove Deleted″ so the Entries disappear from theB-tree as well.

How it worksIn the B-tree every Entry gets a counter as it is iterated through. This is aninternally generated number, which is incremental for each run of theAssemblyLine. For the sake of this explanation, we’ll say that it has a value of n.Next time the Iterator connects to the source and starts to iterate through the dataagain, one of the following three operations takes place:1. If the Entry already exists in the B-tree database, then we can check whether its

Attributes have changed or been added/deleted. The generation number of theEntry in the B-tree store is incremental to n+1.

2. If the Entry did not exist, then it is added to the B-tree database withgeneration number n+1

3. If, after Connector iteration is over, there still exist Entries in the B-treedatabase with generation number n or less, those Entries have disappearedfrom the original source. These Entries are returned one at time by the Iteratorif the ″Read Deleted″ check box was ticked.

Computed ChangesComputed Changes option is a switch on Update Connectors. It is used to makesure an existing record has changed before the Connector tries to update it.Description of how is this option used can be found in “Connectors” on page 21, inUpdate mode.


To access the example mentioned here, go to the root_directory/examples/deltasdirectory of your IBM Directory Integrator installation.

InheritanceAll Connectors can inherit configuration from other Connector located in your ownConnector Library (or system Connectors). The inheritance is recursive (e.g.myldap could inherit from corpldap in your Connector library that again couldinherit from com.ibm.di.connector.LDAPConnector).

You can inherit connection parameters, parser, schema, attribute maps, link criteria,hooks, delta settings and schema from other Connectors: Inside the IBM DirectoryIntegrator Admin tool, select a Connector and use the Inheritance button.


Inheriting from a Connector in the Connector library causes inheritance of everypart of the Connector. The sole exception is the Delta setting.

Attribute MappingAn AssemblyLine Connector is divided into two parts: a generic part that fits intoan AssemblyLine and can be set to a particular mode (Iterator, Lookup, Delete,etc.), and a second ″behind the scenes″ part that understands the technical detailsof the data source being connected to. When we speak of a Connector, we aregenerally referring to the AssemblyLine Connector, while the data source specificbit is called the Raw Connector.

Whenever information is read from or written to a data source, the actual read orwrite or delete is carried out by the Raw Connector. In order to move databetween the generic part of the Connector in an AssemblyLine (where scriptedprocessing takes place) and the Raw Connector, attributes must be moved betweenthe Raw Connector’s data store and the work Entry. This is called AttributeMapping.

Data in an AssemblyLine is stored as attributes in the work Entry, while theinformation stored locally in the Raw Connector is an Entry object called conn. Thisis a temporary object which only exists during Attribute Mapping, and is thereforeof limited availability in scripting. So when a Connector reads in and parses data,this information is stored in conn, and must be transferred to the work Entry.Otherwise data read is gone when the Connector Attribute Mapping is done.Conversely, you have to transfer attribute data from the work object to conn inorder for an output Connector to be able to update the data source. The conn objectis only available for scripting in Attribute Mapping code, and in the Hooksmentioned below, which in turn are dependent on the mode of the Connector.

Depending on the mode the Connector is in, the attribute mapping is done in theInput Map tab or the Output Map tab of the Connector.

Attribute Mapping from an input Connector can been perceived as a form ofstandardizing of the data to a java object. You would start out with the data sourcespecific format of the Raw Connector and then rename, aggregate or format theminto standardized attributes of the work Entry. The rest of the AssemblyLine seesonly the standardized attributes. For example, the Raw Connector could deliver theattributes frstnm (first name) and lstnm (last name), while the attribute mappingwould map them over to the single standardized FullName attribute that would beknown to other Connectors within the AssemblyLine. The Schema tab gives youcontrol over the datatypes involved in the mapping.

On the AssemblyLine specification, there is an option to automatically map allattributes. To automatically map all attributes means that if you have not specifiedan attribute map on the connectors, every attribute is mapped, keeping the originalattribute name. Specifically, if this is an input connector (iterator, lookup, callreply,delete), all attributes are copied from the conn object to the work object. If this isan output connector (addonly, update, callreply) all attributes are copied from thework object to the conn object.

Null Value BehaviorSometimes, the Raw Connector cannot deliver data due to missing values. It couldbe that an optional telephone number is not present. Different data sources treatmissing values in different ways (NULL value, empty string) and the IBM


Directory Integrator provides a way of mapping missing values as well: It is calledNull Value Behavior. Null Value Behavior works both when mapping to and fromthe Raw Connector.

Note: Null Value Behavior only kicks in when no attribute is returned by the rawConnector: If the Attribute is returned (exists) but has the value NULL, NullValue Behavior does not kick in.

The “JDBC Connector” on page 84 has the jdbcExposeNullValues letting you mapNULL values to missing Attributes.

Empty StringNULL values mapped to ″″

Value NULL values mapped to the given Value

Null No value delivered on output, attribute created on input with no value.

Delete No value delivered on output, no attribute created on input.

Default BehaviorOn Attribute mapping level, default is AssemblyLine Settings. ForAssemblyLine Settings this is Settings.

These options are usually set in the configuration file’s Java Properties section: See“Preferences (Java properties)” on page 191 for their name and value.

Conn objectThis depends on the mode of the Connector. Below is a list of the Hooks that areexecuted around Attribute Mapping, and which therefore have access to the connobject.

Mode When conn is available.

IteratorAfter the Connector has read and parsed the data into the conn object,Attribute Mapping is done. The After GetNext Hook is called just beforeAttribute Mapping is done, and the GetNext OK Hook is calledimmediately afterwards.

LookupAfter the Connector has located the data and put it into the conn object,Attribute Mapping is done. The After Lookup Hook is called beforeAttribute Mapping is done, and the Lookup OK Hook is called afterwards.

UpdateThe first thing the Connector does is try to locate the Entry to be updatedin order to determine whether an Add or Modify operation is needed:v If no Entry is found, Attribute Mapping is done. Then empty Attributes

are removed, and so are Attributes not marked as Add in the AttributeMap. Then the Hook Before Add is called, and the Entry is added to thesource. On completion, the Hook After Add is called.

v If more than one matching Entry is found, the Hook ″Multiple EntriesFound″ is called. If this Hook does not exist, the update fails. The connobject is not available in this Hook, but the work object is. After this, theupdate continues as if one matching Entry were found (the first), unlessyou script other behavior.

v If one matching Entry is found, Attribute Mapping is done. The currentobject refers to the object found, which is to be updated, and conn refers


to the object containing the new values. The work object is also available.Then the Before Modify Hook is called, and attributes not marked as″Mod″ in the Attribute Map are removed. If ″Compute Changes″ is set,and there are changes, the Before Applying Changes Hook is called.Then the data source is updated with the conn Entry, and the AfterModify Hook is called, or the Modify No Changes Hook is called. Thecurrent object is available in all these Hooks.

AddOnlyAfter the Attribute Mapping, empty Attributes are removed. Then theHook Before Add is called, and the Entry is added to the source.Afterwards the Hook After Add is called.

Delete No Attribute Mapping takes place, and therefore no conn object isavailable.

TasksBy convention all threads (AssemblyLines, EventHandlers etc ...) are referred to asthe task object. See “The task object” on page 185.

The task object is the thread that executes the AssemblyLine. For each Connector inthe AssemblyLine, there is a com.ibm.di.server.AssemblyLineComponent classencapsulating each Connector. Each Connector is automatically declared by theirnames (as given in the AssemblyLine configuration). Hence, name the Connectorsuch that they are valid names in the selected scripting language.

See also the “Main object” on page 184 being the top level thread. This object hasmethods for manipulating AssemblyLines and querying status information.

How to control the number of threadsThis section is for advanced users.

As stated above AssemblyLines and EventHandlers both are threads. CertainEventHandlers (such as TCP and HTTP) might even start a new thread for everynew event they get. Forking out lots of threads by letting AssemblyLines start lotsof other AssemblyLines can cause you to run out of memory.

Using global system propertiesThe global system property com.ibm.di.server.maxThreadsRunning can be used toreduce the maximum of threads started by the server: it does so by only permittingnew threads to start if it has not started any for a long time (this is to try to avoiddeadlocks where an AssemblyLine cannot finish before it has started and waitedfor another one).

Using scriptingIf you want to completely avoid starting too many threads, an easy way is to waitfor AssemblyLines to finish before you start a new one using the join() call. Thecode:// Here we start the AssemblyLine itselfvar al = main.startAL ( "AssemblyLine", entry );// wait for al to finishal.join();var result = al.getResult();

will do just that: If you omit the al.join() call, the master AssemblyLine willcontinue without waiting (and might create new AssemblyLines).


Another way of limiting the number of threads you have is to use the functionjava.lang.Thread.activeCount() (and possibly java.lang.Thread.sleep() ).

activeCount() can be used to know the total number of threads in use by the threadgroup task belongs to.

For example, if the EventHandler checks how many threads are existing, it cansleep before starting new ones. Here is the Java code for the EventHandler to sleep1000 milliseconds if you have started more than 20 threads which are still running.Note that the Admin-tool and Server eat up some threads, so your activeCountstarts around 4.while (java.lang.Thread.activeCount() > 20)java.lang.Thread.sleep(1000);main.startAL ( "AssemblyLine", entry );

If you wanted to start asynchronous AssemblyLines unless your thread count washigh, you could say something likevar al = main.startAL ("xxx");main.logmsg ("Number of threads: " + java.lang.Thread.activeCount() );if (java.lang.Thread.activeCount() > 20 )al.join();

The configuration fileThe configuration file defines a server, and is an XML file. Your AssemblyLines,Connector Libraries, preferences etc. are saved in this file.

In a simple case, you have everything in one configuration file. However, there aremany situations where you would want to isolate parts of it:v Usernames and passwords in configured Connectorsv Shared Components you want to reuse in several configuration files

Externalizing fields like username and passwordExternal properties are configured via the external properties entry from the treeview in the left hand panel

Note that External Properties have a key, but can have multi-line values.

Also note that the external properties are intended for externalizing certainconfiguration parameters as username, password, filename etc. If you want to savemore general parameters and make them available for your AssemblyLine, seeSave task parameters to, page 187.

Include/NamespacesA configuration file can include items from other configuration files. If you do so,the included components will below to another namespace.

To create a new namespace, select Oject–>New Include and choose a name (forexample, myInclude) for your namespace (system is reserved). Link the name youchoose to a file in the table, and you can then later refer tomyInclude:/Connectors/myConnector to use a myConnector from the Connectorlibrary of your include.


IBM Directory Integrator Secure Sockets Layer SupportThe IBM Directory Integrator Server has the ability to have secure communicationwith those directories supporting Secure Sockets Layer (SSL) security protocol.

The following Connectors and EventHandlers support SSL with the properlyconfigured IBM Directory Integrator Servers:v Connectors

– HTTP Client– LDAP– Netscape ChangeLog– IBM Directory ChangeLog

v EventHandlers– HTTP EventHandler– LDAP EventHandler– IBM Directory Server EventHandler

Notes:

1. keytool is provided as part of JRE. keytool is Key and Certificate managementtool. For more details, seehttp://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/keytool.html

Securing the connection between IBM Directory Integrator5.1.1 and servers with SSL (IBM Directory Integrator as aclient)

The following steps are required to enable SSL support for IBM DirectoryIntegrator as a client:1. Configure a server (such as IBM Directory Server) to enable SSL.2. If the certificate in the server is a self-signed certificate, export the certificate.3. If you don’t have a java (jks) keystore file already, create a keystore file using

keytool (root_directory/_jvm/bin) for IBM Directory Integrator.4. If the server certificate is self-signed certificate, import the server certificate to

the IBM Directory Integrator keystore file as a root authority certificate usingkeytool.

5. Edit root_directory/global.properties file for the keystore file location, keystorefile password and keystore file type. In the current release, we support jks-typeonly.# Keystore file information for the server authentication.# It is used to verify the server’s public key.# examplejavax.net.ssl.trustStore=d:\test\KeyRings\ibmdi.jksjavax.net.ssl.trustStorePassword=secretjavax.net.ssl.trustStoreType=jks

# Keystore file information for the client authentication.# It is used to provide the public key of the IBM Directory Integratorto the server if the server requests the client authentication.# examplejavax.net.ssl.keyStore=d:\test\KeyRings\ibmdi.jksjavax.net.ssl.keyStorePassword=secretjavax.net.ssl.keyStoreType=jks

6. Edit root_directory/_jvm/lib/security/java.security for the security provider list.


security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.crypto.provider.IBMJCA

7. Enable SSL for the connectors.8. Restart IBM Directory Integrator.

Securing the connection between client and IBM DirectoryIntegrator 5.1.1 with SSL (IBM Directory Integrator as a server)

The following steps are required to enable SSL support for IBM DirectoryIntegrator as a server:1. If you don’t have a java (jks) keystore file already in IBM Directory Integrator,

create a keystore file using keytool (root_directory/_jvm/bin). If you don’t havepersonal key to be used in IBM Directory Integrator, get one from a CertificateAuthority or create a self-signed key.

2. If the certificate in the IBM Directory Integrator is a self-signed certificate,export the certificate.

3. If the IBM Directory Integrator certificate is a self-signed certificate, using a keytool, import the exported IBM Directory Integrator certificate to the keystorefile in the client as a root authority certificate.

4. Edit root_directory/global.properties file for the keystore file location, keystorefile password and keystore file type. In the current release, we support jks-typeonly.# Keystore file information for the server

(IBM Directory Integrator) authentication.# It is used to provide the public key of the IBM Directory Integratorto the SSL enabled client.javax.net.ssl.keyStore=D:\test\clientStore.jksjavax.net.ssl.keyStorePassword=secretjavax.net.ssl.keyStoreType=jks

5. Edit root_directory/_jvm/lib/security/java.security for the security provider list.security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.crypto.provider.IBMJCA

## SSLServerSocketFactory Provider#ssl.ServerSocketFactory.provider=com.ibm.jsse.JSSEServerSocketFactory

6. Enable SSL for the clients (for example, using https in the Web browser).7. Restart IBM Directory Integrator.


Chapter 5. IBM Directory Integrator installation instructions

Note: PATH system variable is not set during installation. Set the path socommands such as ibmditk, ibmdisrv, ibmditk.bat and ibmdisrv.bat canwork in a directory other than IBM Directory Integrator root directory.

Installing on Windows platforms1. Locate the setupwin32.exe file.2. Double-click on setupwin32.exe, or type setupwin32.exe at a command

prompt. The program loads Installshield and begins installing.3. The first panel gives you information about the product.4. Click Next to continue.5. The next panel is the license agreement. Read this carefully.6. Click Next to continue.7. The next panel displays a default working directory where the product is

installed. You can change this location by clicking Browse and selectinganother location.

8. Click Next to continue.9. The next panel gives you information about where the product is installed

and the disk space the product requires.10. Click Next to continue.11. The product finishes installing and continues to the final panel. This is another

information panel telling you that the install completed successfully.12. Click Finish.

Installing on Unix platforms1. Locate the setupNameofunixOS.bin file. You might need to change your

permissions:chmod +x setupNameofunixOS.bin

2. Run setupNameofunixOS.bin:./setupNameofunixOS.bin

The program loads Installshield and begins installing.3. The first panel gives you information about the product.4. Click Next to continue.5. The second panel is the license agreement. Please read this over carefully.6. Click Next to continue.7. The next panel displays a default working directory where the product is

installed. You can change this location by clicking Browse and selectinganother location.

8. Click Next to continue.9. The next panel gives you information about where the product is installed

and the disk space the product requires.10. Click Next to continue.11. The product finishes installing and continues to the final panel. This is another

information panel telling you that the install completed successfully.


12. Click Finish.

Silent install (command line)Do the following to perform a silent install of IBM Directory Integrator:

Windows platformssetupwin32.exe -is:silent -silent

AIX setupAIX.bin -is:silent -silent

Linux s/390setupLinux390.bin -is:silent -silent

HPUX setupHPUX.bin -is:silent -silent

Linux IntelsetupLinux.bin -is:silent -silent

SolarissetupSolaris.bin -is:silent -silent

Uninstalling on Windows platforms1. Go to Control Panel—>Add/Remove Programs.2. Locate IBM Directory Integrator 5.1.1, and click Remove. This initiates the

Uninstall Wizard.3. Click Next on the first panel. The product is now being uninstalled.4. An informational panel is displayed. Read this carefully. IBM Directory

Integrator leaves files it creates such as configuration files. They must bemanually deleted, if required.

5. Click Next. A panel is displayed that says IBM Directory Integrator successfullyuninstalled.

6. Click Finish. Uninstall is complete.

Uninstalling on Unix platforms1. Go to the install directory of IBM Directory Integrator. This is the directory

where IBM Directory Integrator was installed.2. Change your directory to the uninstall directory:

cd _uninst

3. Execute the uninstaller:./uninstaller

This initiates the Uninstall Wizard.4. Click Next on the first panel. The product is now being uninstalled.5. An informational panel is displayed. Read this carefully. IBM Directory

Integrator leaves files it creates such as configuration files. They must bemanually deleted, if required.

6. Click Next. Uninstall is complete.

Silent uninstall (command line)Do the following to perform a silent uninstall of IBM Directory Integrator:

All platformsuninstall.exe -is:silent -silent


Distribution componentsHere is the list of all components (.jar and .dll files) installed on your computerwith IBM Directory Integrator.

.jar files are found in the jars/ subdirectory. Connectors, EventHandlers andparsers are found in separate subdirectories and not described here.

Other files on install directorylog4j.properties

File where the log strategy is described.

IDILoader.jarMakes sure jar-files in jars/ subdirectory are loaded by ibmditk andibmdisrv.

global.propertiesStores configuration information. See “global.properties file” on page 55.

log.txt Install log file.

ibmditkExecutable file for Admin tool (non-Windows platforms only).

Note: PATH system variable is not set during installation. Set the path socommands such as ibmditk can work in a directory other than IBMDirectory Integrator root directory.

ibmditk.batExecutable file for Admin tool (Windows platforms only).

Note: PATH system variable is not set during installation. Set the path socommands such as ibmditk.bat can work in a directory other thanIBM Directory Integrator root directory.

ibmdisrvExecutable file for server (non-Windows platforms only).

Note: PATH system variable is not set during installation. Set the path socommands such as ibmdisrv can work in a directory other than IBMDirectory Integrator root directory.

ibmdisrv.batExecutable file for server (Windows platforms only).

Note: PATH system variable is not set during installation. Set the path socommands such as ibmdisrv.bat can work in a directory other thanIBM Directory Integrator root directory.

executetask.propertiesThis configures the logging strategy for AssemblyLines run within theAdmin tool, as opposed to log4j.properties that configures the standaloneserver (ibmdisrv).

Chapter 5. IBM Directory Integrator installation instructions 53

Jar-files (jars/subdirectory)

IBM Directory Integrator jar-filesmiadmin.jar, miserver.jar - Admin tool and IBM Directory Integrator Server.

The rest are 3rd party libraries used by the product:

Scripting Frameworkv bsf.jar - The IBM open source wrapper for a variety of script engines -

http://oss.software.ibm.com/developerworks/projects/bsf. It provides a unifiedinterface to the various script engines available (BSF). Note that this frameworkdoes not provide any script engines at all. The script engines must bedownloaded from other Web sites. See also “Libraries (Windows) libs/subdirectory”

v js.jar - The Mozilla implementation of JavaScript engine (Rhino) -www.mozilla.org/rhino. It is 100% java.

Java Naming and Directory Interface (JNDI)v jndi.jar–Java Naming and Directory Interfacev ldap.jar, ldap12.jar, ldapbp.jar, providerutil.jar–JNDI provider for LDAP and

LDAP controls. Used by jndi.jar.

JavaMail APIv smtp.jar, imap.jar, pop3.jar, mail.jar, mailapi.jar, activation.jar - JavaMail libraries for

SMTP, IMAP, POP3 - http://java.sun.com/products

XMLv xalan.jarv xerces.jar

The Apache XML project that provides XML parsing (xerces.jar) and XPath/XSL(xalan.jar) (http://xml.apache.org).

Libraries (Windows) libs/ subdirectoryv bsfactivescriptengines.dll (part of BSF) - This is the wrapper used by BSF to

access the Windows Scripting Host engine. The WSH engine in turn can accessthe installed windows scripting engines like JScript, VBScript and PerlScript.

v NtMetaData.dll (component of NT4 Connector) - Wraps calls of WinAPIfunctions that interact with NT/AD database.

Managementv mx4j.jarv mx4j-tools.jarv mx4j-jmx.jarv JMX java management interface

Loggingv log4j-1.2.jar

A General purpose java logging function, supporting logging to various target logsincluding the Windows event log and the Unix syslog.


Otherv snmp.jar - Used by SNMPConnector. Code from Tivoli/IBMv ncso.jar - Lotus® Domino™ Client Library.

global.properties filecom.metamerge.securityTransformation=DES/ECB/NoPadding

Encryption Algorithms

com.metamerge.sslProvider=com.ibm.jsse.IBMJSSEProviderJSSE provider

com.metamerge.securityProvider=com.ibm.crypto.provider.IBMJCEJCE Provider

com.metamerge.handlerPkgs=com.ibm.net.ssl.internal.www.protocolHandler packages

com.metamerge.trustStore=Trust key store file path. If it is not specified, it will use the default value.

com.metamerge.trustStorePassword=Trust key store file password.

com.metamerge.trustStoreType=Trust key store file type. If it is not specified, it will use the default value(jks).

com.metamerge.keyStore=Personal key store file path. If it is not specified, it will use the defaultvalue.

com.metamerge.keyStorePassword=Personal key store file password.

com.metamerge.keyStoreType=Personal key store file type. If it is not specified, it will use the defaultvalue (jks).

#javax.net.debug=truedebug flag

For more information about the global.properties file as it relates to theAdministration and Management Console, see Appendix C, “Administration andMonitor Console” on page 215.

TroubleshootingIf you are experiencing difficulties with the installer, you might want to generatethe install log. Specify -is:log <logfile> on the command line of the installer. Forexample, on AIX you issue the following command:setupAIX.bin -is:log mylogfile.txt

If you do not have much space in your system temp directory, you can overridethe temp directory used by the installer during install. Specify -is:tmpdir <tmpdirectory> on the command line of the installer. For example, on AIX you issuethe following command:setupAIX.bin -is:tmpdir /home/bigfilesys

Chapter 5. IBM Directory Integrator installation instructions 55

Chapter 6. Migrating from IBM Directory Integrator 4.7 to IBMDirectory Integrator 5.1.1

1. Save any configuration files created by IBM Directory Integrator.2. Uninstall IBM Directory Integrator 4.7.3. Install IBM Directory Integrator 5.1.1.4. Copy your config files and any other custom files from your old installation

directory to the new installation directory.5. You can now safely remove the old installation directory.6. Test your solution with the new version.

When you visit old configuration files (.cfg) with the Admin tool (ibmditk) andthen save them, these files are converted to the new configuration file format(xml). During loading of the old configuration file (either by ibmditk or byibmdisrv), problems encountered during loading or conversion are logged to thestandard log (ibmdi.log). Check the logs periodically.

Hook flowWhen you visit old configuration files (.cfg) with the Admin tool and then savethem, they will be converted to the new format (xml). Some of the hook-flowconversion is done for you (see “Hook changes for 5.1.1” on page 8). However, ifyou have put logic in your error hooks, you will want to check that the new hookflow (see Appendix E, “Connector modes flowcharts” on page 227) still yields theresults you are expecting. Pay special attention to Lookup mode (no match is nowdefault considered an error), Multiple entries found logic and Allow Duplicatesflag not set. Check “Hook changes for 5.1.1” on page 8 to see what you might haveto change.

User preferencesIBM Directory Integrator 4.7 had many preference parameters stored in theconfiguration file. IBM Directory Integrator 5.1.1 has a more distinct divisionbetween GUI properties (in .ibmdi), config-file properties (such as Null ValueBehavior) and installation specific properties (global.properties). If you havemodified Java Properties (both the Java Engine and IBM Directory Integratorparameters), you should review “Preferences (Java properties)” on page 191 andmake sure your properties are set accordingly in 5.1.1.

Custom made ConnectorsAlso, if you have written your own connectors or used the IBM DirectoryIntegrator API directly, you will want to review the list of renamedclasses/methods.

Xalan and Xerces librariesThe Xalan and Xerces libraries have been updated to version 2.4 and 2.2. XMLparsing that you have coded yourself using the xmldom object can thereforebehave differently.


IncludeIf you have used Include in your old configuration files, you must ensure that theInclude logic is still correct.

Classes and methods that have been renamedSee “Various Renaming” on page 4 for more information.

If in your JavaScript or Javalibraries you have used the classnames listed, youmust translate those. Also all connectors have been renamed (usually just frommetamerge.* to ibmdi.*), and if you have used the old names in your JavaScriptsyou must translate them. For example, if you load Connectors explicitly, this isnecessary. If you are only referring to generic objects as main, system, connector,and so forth, you don’t need to worry about this.

For some components the renaming is special:v metamerge.HTTPClient -> ibmdi.OldHTTPClientv metamerge.HTTPClient2 -> ibmdi.HTTPClientv metamerge.HTTPServer -> ibmdi.OldHTTPServerv metamerge.HTTPServer2 -> ibmdi.HTTPServerv metamerge.SecureWayEventHandler -> ibmdi.IBMDirectoryServerEventHandlerv metamerge.SecureWayChangelog -> ibmdi.IBMDirectoryServerChangelog

BTree databasesYour BTree databases (used directly thought the BTree or indirectly though theDelta functionality) must be converted from 4.7 to 5.1.1 format.

Note: In cases where you don’t need your old BTree data, you can simply deletethe old database and create a new one.

The program used to migrate the BTree database is called migrate. You call it usingeither the bat file for Windows (migrate.bat) or the script file for Unix (migrate).There is a README file (readme.txt) which informs you what to do exactly. It islocated in install directory\tools\migration\47to51.

The program converts a 4.7 Btree database to a 5.1.1 Btree database. So, to use aBTree database created in IBM Directory Integrator 4.7 on an IBM DirectoryIntegrator 5.1.1 you must convert it using this utility.

Connector LibraryIf your 4.7 configuration file has a Connector in the Connector Library with no setmode, then the converted version gets AddOnly mode.

Furthermore, your 4.7 configured attribute map is copied both into the Input(attribute) Map and Output (attibute) Map. One of these attribute maps isinaccurate, but no harm is done.


Chapter 7. Connectors

Connector availability and referenceBelow follows a list of all Raw Connectors (and hence AssemblyLine Connectors)included with the IBM Directory Integrator.

You can also make your own Raw Connectors if needed (the AssemblyLine willwrap them so they are available as AssemblyLine Connectors).

All AssemblyLine Connectors below have access to the methods described in thecom.ibm.di.server.AssemblyLineComponent in addition to the methods/propertiesof the Raw Connector.

Raw ConnectorsFor a list of Supported Modes, see “Legend for the Supported Mode columns” onpage 60.

For each Raw Connector listed, see the documentation outlined in this chapter.

Btree Object DB ConnectorI A D L U

Command Line ConnectorI A

Domino Users ConnectorI A D L U

File SystemI A

FTP Client ConnectorI A

Old HTTP Client ConnectorI A

HTTP Client ConnectorI L A C

Old HTTP Server ConnectorI A

HTTP Server ConnectorI A

IBM MQ Series (JMS)I A +

IBM Directory Changelog ConnectorI

JDBC I A D L U

JMS ConnectorI A C

JNDI I A D L U


LDAP I A D L U

Lotus Notes™

I A D L U

MailboxConnector ConnectorI A D

Memory Stream ConnectorI A

Netscape/iPlanet Changelog ConnectorI

NT4 I A D L U

Script Connector? ? ? ? ?

You write the script connector yourself, and it will provide the modes youwrite into it. See “Script Connector” on page 128.

SNMP ConnectorI A L

TCP Connector (Generic)I A

URL Connector (Generic)I A

(runtime provided) Connector? ? ? ? ?

A runtime provided Connector is a connector sent to the AssemblyLine asa parameter when the AssemblyLine is started. We cannot say what modesthat connector supports. See “(runtime provided) Connector” on page 127.

Web Service ConnectorC

Legend for the Supported Mode columnsv I–Iteratorv A–Addv D–Deletev L–Lookupv U–Updatev C–CallReplyv ?–Conditionally supported, see documentationv +–Newer version supporting exists

Script-based ConnectorsAnother source of problems could show up if you use the same libraries as IBMDirectory Integrator. A new version of IBM Directory Integrator might haveupdated it’s libraries, or you might have upgraded your libraries since last timeyou compiled your Connector.

For a list of Supported Modes, see “Legend for the Supported Mode columns”.

Generic Connector? ? ? ? ?


You write the script connector yourself, and it will provide the modes youwrite into it. See “JavaScript Connector” on page 197.

ConfigurationsFor a list of Supported Modes, see “Legend for the Supported Mode columns” onpage 60.

Btree Object DB ConnectorThe Btree Connector is a simple database capable of storing Java objects. Eachobject is uniquely identified by a value called the key. The Connector uses anunderlying Btree implementation to store AssemblyLine Entry objects. This willenable the user to store the conn and work entries using a unique key. ThisConnector is also used by the AssemblyLine’s Delta feature.

If you want to use the Btree implementation directly to store other Java object thanAssemblyLine entries you must first get the Btree object and then use its methodsdirectly.

Note: The Btree Connector creates a new Btree database if one does not exist.However, if you iterate on a non-existing database, it is created and theiterator returns no values.

ConfigurationThe Connector needs the following:

connectorTypecom.ibm.di.connector.Btree

filePathThe file path where the Btree data is stored

keyAttributeThe attribute name giving the unique value for the entry

selectionMode

Specify All, Existing or Deleted. In order to use the Existing and Deletedkeywords the Connector (database) must have been used by anAssemblyLine with the delta enabled. When delta is enabled on an iterator,the AssemblyLine stores a sequence property in the database and also adda sequence number to each entry read from the source. See “Deltas andcompute changes” on page 41.

The Delta feature is associated with a Connector operating in Iterator mode. Butthis Connector is typically part of an AssemblyLine. You specify ″All″ as theselectionMode. If the database (the file stored in the file system) used by thisConnector has already been used as the ″!DB File Path″ of a Connector in Iteratormode with delta enabled, the database might contain some entries, each containinga sequence number, and the database also contains a sequence number, whichtypically tells you how many times the AssemblyLine containing the Connector inIterator mode with delta enabled, has been run (see “Deltas and compute changes”on page 41). If you specify ’Existing’ as the selectionMode, you get all entries with

a sequence number greater than or equal to the sequence number stored in thedatabase. If you specify selectionMode ’Deleted’, you get all entries with asequence number less than the sequence number stored in the database.

Chapter 7. Connectors 61

Btree objectThe getDatabase() method returns the underlying Btree object. This object can beused to store other Java objects than AssemblyLine entries. The following snippetshows how you can insert, search and replace objects in the database:var bt = system.getConnector("btreedb");bt.initialze (null);

var db = bt.getDatabase();db.insert ("my key", new java.lang.String("my value"));var value = db.search ("my key");value = value + " - modified";db.replace ("my key", value);

Note: The BTree Connector does not support the Advanced Link Criteria (see“Advanced link criteria” on page 27).

Command line ConnectorThe command line Connector enables you to read the output from a command lineor pipe data to a command line’s standard input. Every command argument isseparated by a space character, and quotes are ignored.

Note: You do not get a separate shell, so redirection characters ( | > etc.) will notwork. In order to use redirection, make a shell-script (Unix) or batchcommand (DOS) with a suitable set of parameters. For example, onwindows typecmd /c dir

to list the contents of a directory.

ConfigurationThe Connector needs the following parameters:

connectorTypecom.ibm.di.connector.CommandLineConnector

commandLineThe command line to execute

parser The Parser responsible for interpreting/generating entries


To access the example mentioned here, go to theroot_directory/examples/commandLine_connector directory of your IBM DirectoryIntegrator installation.

Direct TCP /URL scriptingSometime, you may want to access URL objects or TCP ports directly, not using theConnectors. Here is some example code that typically could be put in your Prolog:


TCP// This example creates a TCP connection to www.example_page_only.com

and asks for a bad page

var tcp = new java.net.Socket ( "www.example_page_only.com", 80 );var inp = new java.io.BufferedReader ( new java.io.InputStreamReader

( tcp.getInputStream() ) );var out = new java.io.BufferedWriter ( new java.io.OutputStreamWriter

( tcp.getOutputStream() ) );

task.logmsg ("Connected to server");

// Ask for a bad pageout.write ("GET /smucky\r\n");out.write ("\r\n");

// When using buffered writers always call flush to make sure datais sent on connection

out.flush ();

task.logmsg ("Wait for response");var response = inp.readLine ();

task.logmsg ( "Server said: " + response );

URL// This example uses the java.net.URL object instead of the raw

TCP socket object

var url = new java.net.URL("http://www.example_page_only.com");var obj = url.getContent();

var inp = new java.io.BufferedReader ( new java.io.InputStreamReader( obj ) );

while ( ( str = inp.readLine() ) != null ) {task.logmsg ( str );}

Domino Users ConnectorThe Domino Users Connector provides access to Lotus Domino user accounts andmeans for managing them. It operates in Iterator, Lookup, AddOnly, Update andDelete modes and enables the following operations to be performed:v Iterator: Iterate over all (or a filtered subset of) Person documents from the

Name and Address Book.v Lookup: Search for and retrieve Person documents that match some criteriav AddOnly: Register new users in Domino Server and create their Person

documents.v Update: Modify users’ Person documents; Enable/disable users; Register existing

(internet) users.v Delete: Post requests for user deletion in the Domino Server Administration

Requests Database.

Note: Domino Users Connector Connector requires Lotus Notes to be release 5.0.8or higher.

Deployment and connection to Domino serverThe Domino Users Connector must be used with Lotus Domino Server version5.0.8 or above.


IBM Directory Integrator must be installed and run from the machine where theDomino Server is installed in order for the DominoUsersConnector to function.Add the pathname of Notes.jar to the myclasspath variable in both theibmdisrv.bat and ibmditk.bat files (or the MYCLASSPATH variable in both theibmdisrv and ibmditk files if you are not operating on a Windows platform). Itprovides interfaces to native calls that access the Domino Server. This library isprovided by Lotus and can be found in the folder where the Domino Server isinstalled (for example, C:\Lotus\Domino).

The file ncso.jar must be removed from the root_directory/jars folder. Also, removethe string jars/ncso.jar; from the myclasspath variable in both ibmdisrv.bat andibmditk.bat files (or the MYCLASSPATH variable in both the ibmdisrv and ibmditkfiles if you are not operating on a Windows platform).

Finally, add the path to the local Domino binaries (for example, C:\Lotus\Domino)to the PATH environment variable inside ibmditk and ibmdisrv.

Solaris specfic settingsEdit the ibmditk and ibmdisrv files and add the following line to the javacommand line:-Djava.library.path=$PATH

This enables the JVM (and therefore the DominoUsersConnector) to find therequired Domino libraries. The following is an example of the java command line:/opt/IBM/IBMDirectoryIntegrator/_jvm/bin/java-cp $MYCLASSPATH -Djava.library.path=$PATH-Dcom.ibm.di.installdir=/opt/IBM/IBMDirectoryIntegratorcom.ibm.di.loader.IDILoader com.ibm.di.admin.miadmin "$@"

On certain versions of Domino (at least 5.0.8), an additional change to the javacommand line is required. The Domino library is expecting the Java propertyos.name to be SOLARIS, when in fact Java 1.3.1 returns SunOS as the value. Toremedy the situation, edit ibmditk and ibmdisrv and add the following line to thejava command:-Dos.name=SOLARIS

Here’s an example line with all of the previous information:/opt/IBM/IBMDirectoryIntegrator/_jvm/bin/java-cp $MYCLASSPATH -Djava.library.path=$PATH-Dos.name=SOLARIS -Dcom.ibm.di.installdir=/opt/IBM/IBMDirectoryIntegratorcom.ibm.di.loader.IDILoader com.ibm.di.admin.miadmin "$@"

Linux specific settingsWhen running on Linux, you must make the java.library.path changes asmentioned previously. The following is an example of the Linux startup script:/opt/IBM/IBMDirectoryIntegrator/_jvm/bin/java-Xquickstart -Xms16m -cp $MYCLASSPATH -Djava.library.path=$PATH-Dcom.ibm.di.installdir=/opt/IBM/IBMDirectoryIntegratorcom.ibm.di.loader.IDILoader com.ibm.di.admin.miadmin "$@"

To authenticate the local server connection, Domino requires the user’s short nameand internet password (these are Connector’s parameters).



userNameThe user name used for login/authentication to the Domino Server.

passwordThe password for the userName.

nabDatabaseThe name of the ″Name and Address Book″ database to use. Default valueis ″names.nsf″.

useFTSearchIf ″checked″, the Connector will access user documents through the″People″ view and full-text searches. If ″not checked″, the Connector willuse regular database searches; in this case the Connector will automaticallynarrow the database search to user documents only, by accessing onlydocuments which ″Form″ item value is ″Person″. This parameter affects theIterator and Lookup modes only.

fullTextFilterThis parameter’s value is taken into account only when ″useFTSearch″ is″checked″. Contains full-text query that will filter the user documentsreturned by the Connector in Iterator mode; if null or empty string, nofiltering is performed. Default value is ″″.

formulaFilterThis parameter’s value is taken into account only when ″useFTSearch″ is″not checked″. Contains a formula that will filter the users returned by theConnector in Iterator mode; the Connector will automatically add to thisformula ″& Form = ″Person″″ which will limit the search to userdocuments only. Default value is ″″.

debug Specifies whether more detailed debug information is written to the logfile.

SecurityIn order to have the IBM Directory Integrator access the Domino Server, you mighthave to allow it through Domino Administrator -> Configuration -> Current ServerDocument -> Security -> Java/COM Restrictions. The user account you haveconfigured the IBM Directory Integrator to use, must belong to a group listedunder ″Run restricted Java/Javascript/COM″ and ″Run unrestrictedJava/Javascript/COM″.

Using the Domino Connector

Iterator modeThe Connector iterates through the Person documents of the ’Name and AddressBook’ database. All Person documents (matching the filter, if filter is set) aredelivered as Entry objects, and all document items, except attachments, aretransformed into Entry Attributes.

Along with the Attributes corresponding to the Person document items, the Entryreturned by the Connector will contain some extra (derived) Attributes, whichvalues are calculated by the Connector itself. Here is the list of the derivedAttributes:

DER_IsEnabled(Boolean) Specifies whether the user is enabled/disabled:v ″true″ - if the user does not belong to a ″Deny List only″ group


v ″false″ - if the user belongs to at least one group of type ″Deny Listonly″

Lookup modeIn Lookup mode, the Connector will perform search for user document(s), and thetype of search will depend on the value of the ″useFTSearch″ parameter:v ″useFTSearch″ = ″true″: The Connector will perform a full-text search in the

″People″ view. Full-text search will work both with full-text indexed and notfull-text indexed databases; however, the search is less efficient if the database isnot full-text indexed. It is also possible that the database full-text index will notbe updated, in which case the search results would not match the actualdatabase content.

v ″useFTSearch″ = ″false″: The Connector will perform a regular database searchusing Lotus formula. The element (Form = ″Person″) is automatically added tothe formula by the Connector, so the search is limited to user documents only.

When simple link criteria is used, you may use both canonical(CN=UserName/O=Org) and abbreviated (UserName/Org) name values to specifythe user’s FullName - the Connector will automatically process and convert (ifnecessary) the value you have specified.

When advanced link criteria is used, you have to be careful and specify the user’sFullName in the correct format, which is:v for full-text search: use abbreviated names (UserName/Org)v for regular database search: use canonical names (CN=UserName/O=Org)

AddOnly modeThe AddOnly mode will always add a new Person document in the Name andAddress Book. The add process will accept whatever Attributes are provided bythe Attribute Mapping, however in order to have correct user processing byDomino, the Attribute names should match the Item names Domino operates with.As the Connector operates with users only, it always sets the Attributes ″Type″ and″Form″ to the value of ″Person″, thus overriding any values set to these Attributesduring the Attribute Mapping process. The ″LastName″ Domino user attribute isrequired for successful creation of a Person document.

Depending on a fixed schema of Attributes, the Connector will register (or not) thenew user. The table below specifies these Attributes and the Connector behavioraccording their presence/absence in the conn Entry, and their values:

Attribute name Type Required forregistration?

Value

REG_Perform Boolean Yes If set to ″true″ theConnector willperform userregistration. If thisAttribute is missing,or its value is ″false″,the Connector willnot perform userregistration,regardless of thepresence and thevalues of the other″REG_″ Attributes.


REG_IdFile String Yes Contains the fullpath of the ID file tobe registered. Forexample,

"c:\\newuserdata\\newuser.id"

REG_UserPw String Yes The user’s password.

REG_CertifierIDFile String Yes The full file path tothe certifier ID file.

REG_CertPassword String Yes The password for thecertifier ID file.Note: If the certifierpassword is wrongwhen registeringusers, a popupwindow can appear.Ensure that theCertifier password iscorrectly specified.

REG_Server String No The name of theserver containing theuser’s mail file. If thisAttribute is missing,the value is obtainedfrom the Connector’sDomino Sessionobject.

REG_CreateMailDb Boolean/String No ″true″ - Creates amail database ″false″- Does not create amail database; it iscreated during setup.If this Attribute ismissing, a defaultvalue of ″false″ isassumed. If thisattribute is true, theMailFile attributemust be mapped to avalid path.

REG_Expiration Date No The expiration dateto use when creatingthe ID file. If theAttribute is missing,or its value is ″null″,a default value of thecurrent date + 2years is used.


REG_IDType Integer/String No The type of ID file tocreate: ″0″ - create aflat ID ″1″ - create ahierarchical ID ″2″ -create an ID thatdepends on whetherthe certifier ID is flator hierarchical. If theAttribute is missing,a default value of ″2″is used.

REG_Is

NorthAmerican

Boolean/String No ″true″ - the ID file isNorth American″false″ - the ID filewill not be NorthAmerican If thisAttribute is missing,a default value of″true″ is used.

REG_OrgUnit String No The organizationalunit to use whencreating the ID file. Ifthis Attribute ismissing, a defaultvalue of ″″ is used.

REG_RegistrationLog String No The log file to usewhen creating the IDfile. If this Attributeis missing, a defaultvalue of ″″ is used.

REG_StoreID

InAddressBook

Boolean/String No ″true″ - stores the IDfile in the server’sDomino Directory″false″ - does notstore the ID file inthe server’s DominoDirectory If thisAttribute is missing,a default value of″false″ is used.

REG_Registration

Server

String No The server to usewhen creating the IDfile. This Attribute isused only when thecreated ID is storedin the server DominoDirectory, or when amail database iscreated for the newuser.


REG_MinPassword

Length

Integer/String No TheREG_MinPassword

Length value definesthe minimumpassword lengthrequired forsubsequent changesto the password bythe user. Thepassword used whenthe user registers isnot restricted by theREG_MinPassword

Length value. If thisAttribute is missing,a default value of ″0″is used.

TheREG_MinPassword

Length value definesthe minimumpassword lengthrequired forsubsequent changesto the password bythe user. Thepassword used whenthe user is registeredis not restricted bytheREG_MinPassword

Length value.

REG_Forward String No The forwardingdomain for the user’smail file.

REG_AltOrgUnit Vector of <String> No Alternate names forthe organizationalunit to use whencreating ID file.

REG_AltOrgUnitLang Vector of <String> No Alternate languagenames for theorganizational unit touse when creating IDfile.

The Attributes for which the Required for registration field is set to Yes, arerequired for successful user registration. Along with these ″REG_″ Attributes, the″LastName″ Domino user Attribute is also required for successful user registration.

If ″REG_Perform″ is set to ″true″ and any of the other required for registrationAttributes are missing, the Connector will throw an Exception with a messageexplaining the problem.


Update modeIn Update mode, the following happens:1. A search for the Entry to be updated is performed in Domino.2. If it is not found an ″AddOnly″ operation is performed as described in the

AddOnly mode (including user registration if the necessary ″REG_″ Attributesare supplied).

3. If the Entry is found, a ″modify″ operation is performed.

When modifying a user, the Domino Users Connector will always modify itsPerson document in the Name and Address Book with the Attributes provided.The modify process will accept whatever Attributes are provided by the AttributeMapping, however in order to have correct user processing by Domino, theAttribute names should match the Item names Domino operates with.

As the Connector operates with users only, it will not modify the Attributes ″Type″and ″Form″ (their value should be ″Person″) regardless of the Attribute Mappingprocess.

In the process of modifying users the Domino Users Connector provides theoptions to disable and enable users. A user is ″disabled″ by adding his name into aspecified group of type ″Deny List only″ (consult the Domino documentation forinformation on ″Deny List only″ groups). A user is ″enabled″ by removing hisname from all groups of type ″Deny List only″.

The Connector will perform user disabling or enabling depending on the presencein the conn Entry, and the values of the following Entry Attributes:

ACC_SetType(Integer/String) If this Attribute is missing, no actions will be performedand the user will keep its current disable/enable status. If this Attribute isprovided, its value is inspected:v ″0″ - the Connector will perform the operation ″disable user″ (the user’s

name is placed in the group specified by the ″ACC_DenyGroupName″Attribute)

v ″1″ - the Connector will perform the operation ″enable user″ any othervalue will result in Exception

ACC_DenyGroupName(String) The name of the ″Deny List only″ group where the user’s name isadded when disabling the user. When the value of ″ACC_SetType″ is ″0″,the ″ACC_DenyGroupName″ Attribute is required; if it is missing or itsvalue specifies a non-existing ″Deny List only″ group, an Exception isthrown. When the ″ACC_SetType″ Attribute is missing, or its value is ″1″,the ″ACC_DenyGroupName″ Attribute is not required and its value isignored.

The Connector can perform user registration on modify too. To determine whetheror not to perform registration, the same rules apply as in the AddOnly mode; thesame schema of Attributes is used and all ″REG_″ Attributes have the samemeaning.

If the ″REG_″ Attributes determine that registration is performed, the followingcases may happen:


v The user has not yet been registered (for example, this may be an internet/webuser that you want to register and allow him to logon and work through aNotes client). The user is then registered - a new ID file is created, etc.

v The user has already been registered - in this case the user is re-registered, i.e.the Domino registration values will be reset with the new values provided; inparticular a new ID file will also be created.

Note: When registering users on modify, you should know beforehand what is theuser’s FullName after registration; and you have to provide the Attribute″FullName″ in the conn Entry with this value (which will probably byconstructed by scripting). This is not very convenient and requires deepknowledge of the Domino registration process; without setting the expecteduser’s FullName beforehand, however, you risk to register a new userinstead of the existing one.

Delete modeFor user deletion the Connector will use the Domino Administration Process.

The Connector will post in the Administration Requests Database ″Delete inAddress Book″ requests. Each request of type ″Delete in Address Book″ whenprocessed by the Domino Administration Process will trigger the whole chain ofposting and processing administration requests and actions performed by theAdministration Process to delete a user. The result of posting a ″Delete in AddressBook″ administration request is the same as deleting manually a user through theDomino Administrator. In particular: (1) the time of processing the administrationrequests depends on the Domino Server configuration; (2) depending on the typeof deletion requested, the chain of administration requests may include requeststhat require Administrator’s approval (for example the ″Approve File Deletion″request for deleting the user’s mail file).

The Connector will allow tuning of each single user deletion it will initiate - theparameters that may be configured are:v Delete mail file: you may specify one of the three options:

– Don’t delete mail file.– Delete just the mail file specified in Person document.– Delete mail file specified in Person document and all replicas.

v Add to group: Specifies if the user’s name should be placed in a group whendeleting the user, and if yes - specifies the name of the group too. This option isusually used to add the user in a ″Deny List only″ group when deleting the user- thus the user is denied access to the servers.

The delete parameters described above, have default values that may also bechanged through APIs provided by the Domino Users Connector. Each time aninstance of the Domino Users Connector is created (in particular on eachAssemblyLine start), the parameters will have the following default values:v Delete mail file: Don’t delete mail file.v Add to group: On deletion, do not add the user’s name in any group.

If the default values fit the type of deletion you want, then no specialconfiguration for the deletion is needed - you just have to specify the correct linkcriteria in the Delete Connector.

You may however use (through scripting) the APIs provided by theDominoUsersConnector, to change these default values at runtime:


int getDeleteMailFile()Returns the code of the default value for the Delete mail file parameter:v 0 - Don’t delete mail file.v 1 - Delete just the mail file specified in Person document.v 2 - Delete mail file specified in Person document and all replicas.

void setDeleteMailFile (int deleteType)Sets the default value for the ″Delete mail file″ parameter. The ″deleteType″method’s parameter should contain the code of the desired value (thecodes are as described for ″getDeleteMailFile()″).

String getDeleteGroupName ()Returns the default value for the ″Add to group″ parameter:v NULL - means ″Do not add the user’s name in any group″.v non-NULL value - the name of the Group where the user’s name is

added.

void setDeleteGroupName (String groupName)Sets the default value for the ″Add to group″ parameter:v NULL - specifies that the user’s name should not be added in any group

on deletion.v non-NULL String value - specifies the name of the group where the

user’s name is added on deletion.

The default values for the ″delete″ parameters will be used in all deletionsperformed by the Connector, until another change in their values is made, or theConnector instance (object) is destroyed.

Here are a couple of possible scenarios that use these methods:v Script code in the ″Before Delete″ hook checks the values of the work and conn

objects (and everything else it needs to check), and depending on the specificdecision logic uses the ″setDeleteMailFile″ and ″setDeleteGroupName″ to tuneeach particular user deletion.

v If all users for deletion should be deleted using one pattern (and there is noneed to tune each particular user deletion), script code in the AssemblyLineProlog may use the ″setDeleteMailFile″ and ″setDeleteGroupName″ methods andset the desired values for the whole process.

Another method to manipulate the delete parameters, is to provide the followingAttributes in the conn Entry:

DEL_DeleteMailFile(Integer/String)

If this Attribute is missing in the conn Entry, the default value for ″Deletemail file″ is used.

If this Attribute is provided in the conn Entry, its value determines thevalue for the ″Delete mail file″ parameter for the current deletion only:v 0 - Don’t delete mail file.v 1 - Delete just the mail file specified in Person document.v 2 - Delete mail file specified in Person document and all replicas.

DEL_DeleteGroupName(String)


If this Attribute is missing in the conn Entry, the default value for ″Add togroup″ is used.

If this Attribute is provided in the conn Entry, its value determines thevalue for the ″Add to group″ parameter for the current deletion only:v NULL - Specifies that the user’s name should not be added in any

group.v non-NULL String value - Specifies the name of the group where the

user’s name is added.

The use of the ″DEL_DeleteMailFile″ and ″DEL_DeleteGroupName″ Attributes inthe conn Entry overrides the default values of the corresponding delete parametersfor the current deletion only.

Setting the ″DEL_DeleteMailFile″ and ″DEL_DeleteGroupName″ Attributes in theconn Entry can be done through scripting in the ″Before Delete″ hook. AddingAttributes by scripting may not be very convenient, so probably you will prefer touse the default delete parameters values and the APIs that change them.

List of Domino user Attributes (or Person document items)The following is a list (possibly not full) of Domino user document items, whichare understood or processed by Domino when the server operates with users. Formore information on these Items consult the Lotus Domino documentation.

The same names should be used for Entry Attribute names when performing add,modify, delete or lookup operations with the Connector.v AltFullNamev AltFullNameLanguagev AltFullNameSortv Assistantv AvailableForDirSyncv CalendarDomainv CellPhoneNumberv CcMailUserNamev Certificatev CheckPasswordv Childrenv Cityv ClientTypev Commentv CompanyNamev countryv Departmentv DocumentAccessv EmployeeIDv EncryptIncomingMailv FirstNamev Formv FullName


v HomeFAXPhoneNumberv HTTPPasswordv InternetAddressv JobTitlev LastNamev Level0v Level0_1v Level0_2v Level0_3v Level1v Level1_1v Level1_2v Level1_3v Level2v Level2_1v Level2_2v Level2_3v Level3v Level3_1v Level3_2v Level3_3v Level4v Level4_1v Level4_2v Level4_3v Level5v Level5_1v Level5_2v Level5_3v Level6v Level6_1v Level6_2v Level6_3v LocalAdminv Locationv MailAddressv MailDomainv MailFilev MailServerv MailSystemv Managerv MessageStoragev MiddleInitialv NetUserNamev NoteID


v OfficeCityv OfficeCountryv OfficeFAXPhoneNumberv OfficeNumberv OfficePhoneNumberv OfficeStatev OfficeStreetAddressv OfficeZIPv Ownerv PasswordChangeDatev PasswordChangeIntervalv PasswordGracePeriodv PersonalIDv PhoneNumberv PhoneNumber_6v SametimeServerv ShortNamev Spousev Statev StreetAddressv Suffixv Titlev Typev WebSitev x400Addressv Zip


To access the example mentioned here, go to theroot_directory/examples/dominoUsersConnector directory of your IBM DirectoryIntegrator installation.

See also“Lotus Notes Connector” on page 107

File system ConnectorThe file system Connector is a transport Connector that requires a Parser in orderto operate. The file system Connector reads and writes files available on the systemit runs on. This Connector can only be used in Iterator or AddOnly mode, or forthe equivalent operations in Passive state.

Note: When using File System Connector (ibmdi.FileSystem) with XML parser initerator mode (on a Windows platform), if the user is validating an XMLdocument through an external DTD and uses the following syntax:


c:/<external DTD file>.dtd

in the XML file to reference the external DTD, it can give the following errorwhile connecting to the datasource:java.net.MalformedURLException:unknown protocol

This is because windows does not always interpret the URL correctly. Toconnect to the datasource, the user must use the syntaxfile:////c:/<external DTD file>.dtd

in the XML file to reference the external DTD.


connectorTypecom.ibm.di.connector.FileConnector

filePathName of file to read or write. If set to <Use Standard I/O streams>, readsand writes from standard input/output.

parser The name of a Parser to handle the contents of the file

fileAwaitDataTimeoutThis parameter is specified as a positive number, the Connector will waitfor available data when reading from a file. Specify zero to wait forever orany other number which specifies the number of seconds to wait beforesignalling end of file. Setting this parameter to zero causes the Connectorto simulate the UNIX® style ″tail -f″ command.

fileAppendIf set, will append in stead of overwrite when the file is opened forwriting.

See also“URL Connector” on page 132.

FTP Client ConnectorThe FTP Client Connector is a transport Connector that requires a Parser in orderto operate. The Connector reads or writes a data stream that can either be a file ora directory listing. Think of the FTP Client Connector as a remote read/writefacility, not something you use to transfer files.


connectorTypecom.ibm.di.connector.rscFTPConnector

ftpServerThe FTP hostname

ftpPortThe FTP TCP port (defaults to 21)

ftpUserThe login username


ftpPassThe login password

ftpPathInitial remote directory (for list) or file (for get/put) to access

ftpOperationThe intended operation. Specify get to read a file (Iterator), put to write afile (Add Only), or list to do a directory listing (Iterator).

parser Mandatory parser. For example, LineReader is a useful parser for list, or ifyou simply want to copy one file.

ftpTransferModeASCII or Binary. ASCII is the only supported mode.

NoteIterator mode supports ftpOperation get and list, Addonly supports put.

This connector is not intended for transferring binary files.

See also“The FTP object” on page 183, “URL Connector” on page 132, “Old HTTP ClientConnector”, “Old HTTP Server Connector” on page 82

Old HTTP Client Connector

Note: This connector is kept for legacy purposes only. If you are creating a newconnector, please use HTTP Client Connector instead.

The Old HTTP Client Connector allows greater control on HTTP sessions than theURLConnector provides. With the HTTP Connector you can set HTTP headers andbody using predefined attributes. Also, any request to a server that returns data isavailable for the user as attributes.

Note: The Old HTTP Client Connector does not support the Advanced LinkCriteria (see “Advanced link criteria” on page 27).

ModesThe Old HTTP Client Connector can be used in three different AssemblyLinemodes. These arev Iterator. Each call to the Connector requests the same URL configured for the

Connector. This will cause the Connector to run forever requesting the samepage unless you include a Parser in the Connector’s configuration. If youinclude a Parser, the Parser will notify when the last entry has been read fromthe connection and the Connector will eventually cause an AssemblyLine toterminate.

v Lookup. In this mode the Connector will request a page every time the lookupfunction is called. In your search criteria you can specify either which page/URLto request, and include any number of parameters all of which are appended tothe base URL as request parameters.

v AddOnly. In this mode the Connector request is performed much like theIterator mode.


Special attributesWhen using the Connector in Iterator or Lookup mode the following set ofattributes/properties is returned in the Connector entry:

http.responseCodeThe HTTP response code as an Integer object.

200 OK —-> 200

http.responseMsgThe HTTP response message as a String object.

200 OK —-> OK

http.content-typeThe content type for the returned http.body (if any)

http.content-encodingThe encoding of the returned http.body (if any)

http.content-lengthThe number of bytes in http.body

http.bodyThis object is an instance/subclass of java.io.InputStream class that can beused to read bytes of the returned body.var body = conn.getObject ("http.body");var ch;

while ( (ch = body.read()) != -1 ) {task.logmsg ("Next character: " + ch);

}

Consult the Java documentation for the InputStream classes and theirmethods.

http.text-bodyIf the http.content-type starts with the sequence ″text/″, the Connectorassumes the body is textual data and reads the http.body stream objectinto this attribute.

When using the Connector in AddOnly mode the Connector will transmit anyattribute named ″http.″ as a header. Thus, to set the content type for a requestname the attribute ″http.content-type″ and provide the value as usual. One specialattribute is http.body that may contain a string or any java.io.InputStream orjava.io.Reader subclass.

For all modes the Connector will always set the http.responseCode andhttp.responseMsg attributes. In AddOnly mode this is a bit special since the ″conn″object being passed to the Connector is the object being populated with theseattributes. To access these you must obtain the value in the Connector’s After Addhook.

ConfigurationConnector has the following parameters:

connectorTypecom.ibm.di.connector.OldHTTPCLient

url The HTTP page to request


usernameIf set the HTTP Authorization header is set using this parameter alongwith the password parameter.

passwordUsed if username is specified.

parser If specified this Parser is used to generate the posted data for an Addoperation.

ExamplesIn your attribute map you can use the following assignment to post the contents ofa file to the HTTP server:// Attribute assignment for "http.body"ret.value = new java.io.FileInputStream ("myfile.txt");

// Attribute assignment for "http.content-type"ret.value = "text/plain";

The Connector will compute the ″http.content-length″ attribute for you. There is noneed to specify this attribute.

Lookup ModeIn lookup mode you can dynamically change the request URL by setting the searchcriteria as follows:v If you have one and only one criteria and the attribute is named ″url″ then the

value specified in the criteria is used as the request URL.url equals $url

v If you have more than one or the only criteria is anything but ″url″, then allattribute names and values are appended to the URL given by the Connectorconfiguration as the request URL.Base URL: http://www.example_name.com/lookup.cgiSearch Criteria:name equals johnmail equals doe.com

Resulting URL:http://www.example_name.com/lookup.cgi?name=john&mail=doe.comTheLookup function will ignore the operand. So if you specify contains instead ofequals the Connector will still construct the URL as if equals where used.

See also“URL Connector” on page 132, “Old HTTP Server Connector” on page 82, “HTTPClient Connector”

HTTP Client ConnectorThe HTTP client Connector allows greater control on HTTP sessions than theURLConnector provides. With the HTTP Connector you can set HTTP headers andbody using predefined attributes. Also, any request to a server that returns data isavailable for the user as attributes.

Note: The HTTP Client Connector does not support the Advanced Link Criteria(see “Advanced link criteria” on page 27).


Changes from earlier versionsThe HTTP Client Connector uses metamerge.HTTP as internal parser if no parseris specified. Version 1 had hardcoded internal java-code and is deprecated.

When a java.io.File object is passed in the http.body property no memory bufferingis performed. Version 1 would perform buffering.

ModesThe HTTP client Connector can be used in three different AssemblyLine modes.These arev Iterator. Each call to the Connector requests the same URL configured for the

Connector. This will cause the Connector to run forever requesting the samepage unless you include a Parser in the Connector’s configuration. If youinclude a Parser, the Parser will notify when the last entry has been read fromthe connection and the Connector will eventually cause an AssemblyLine toterminate.

v Lookup. In this mode the Connector will request a page every time the lookupfunction is called. In your search criteria you can specify either a page/URL torequest, or include any number of parameters all of which are appended to thebase URL as request parameters.

v AddOnly. In this mode the Connector request is performed much like theIterator mode.

v CallReply. In this mode the Connector has two attribute maps, both Input andOutput.

Special attributesWhen using the Connector in Iterator or Lookup mode the following set ofattributes/properties is returned in the Connector entry:

http.responseCodeThe HTTP response code as an Integer object. (200 OK —-> 200)

http.responseMsgThe HTTP response message as a String object. (200 OK —-> OK)

http.content-typeThe content type for the returned http.body (if any)


http.content-lengthThe number of bytes in http.body

http.bodyThis object is an instance/subclass of java.io.InputStream class that can beused to read bytes of the returned body.var body = conn.getObject ("http.body");var ch;

while ( (ch = body.read()) != -1 ) {task.logmsg ("Next character: " + ch);

}

Consult the Java documentation for the InputStream classes and theirmethods.


http.text-bodyIf the http.content-type starts with the sequence ″text/″, the Connectorassumes the body is textual data and reads the http.body stream objectinto this attribute.

When using the Connector in AddOnly mode the Connector will transmit anyattribute named ″http.″ as a header. Thus, to set the content type for a requestname the attribute ″http.content-type″ and provide the value as usual. One specialattribute is http.body that may contain a string or any java.io.InputStream orjava.io.Reader subclass.

For all modes the Connector will always set the http.responseCode andhttp.responseMsg attributes. In AddOnly mode this is a bit special since the ″conn″object being passed to the Connector is the object being populated with theseattributes. To access these you must obtain the value in the Connector’s After Addhook.

ConfigurationThe HTTP Client Connector has the following parameters:

connectorTypecom.ibm.di.connector.HTTPClientConnector

url The HTTP page to request.

Note: If you use a https:// address, you might need to import a certificateas well.

methodThe HTTP method to use when requesting the page. Seehttp://www.w3.org/Protocols/HTTP/Methods.html for more information

usernameIf set the HTTP Authorization header is set using this parameter alongwith the password parameter.

passwordUsed if username is specified.

parser If specified, this Parser is used to generate the http.body content whensending data. The parser gets an entry with those attributes where thename does not begin with ″http.″ Also, this Parser (if specified) will get thehttp.body for additional parsing when receiving data.

proxy If specified, connect to a proxy server rather than directly to the hostspecified in the URL. The format is proxyhost:port (for example, proxy:8080),where proxy is the name of the proxyhost, and 8080 is the portnumber touse.

ExamplesIn your attribute map you can use the following assignment to post the contents ofa file to the HTTP server:// Attribute assignment for "http.body"ret.value = new java.io.FileInputStream ("myfile.txt");

// Attribute assignment for "http.content-type"ret.value = "text/plain";


The Connector will compute the ″http.content-length″ attribute for you. There is noneed to specify this attribute.

Lookup ModeIn lookup mode you can dynamically change the request URL by setting the searchcriteria as follows:v If you have one and only one criteria and the attribute is named ″url″ then the

value specified in the criteria is used as the request URL.url equals $url

v If you have more than one or the only criteria is anything but url, then allattribute names and values are appended to the URL given by the Connectorconfiguration as the request URL.Base URL: http://www.example_page_only.com/lookup.cgiSearch Criteria:name equals johnmail equals doe.com

Resulting URL:http://www.example_page_only.com/lookup.cgi?name=john&mail=doe.comTheLookup function ignores the operand. So if you specify contains instead of equalsthe Connector will still construct the URL as if equals where used.

See also“URL Connector” on page 132, “HTTP Server Connector” on page 83, “HTTPparser” on page 164.

Old HTTP Server Connector

Note: This connector is kept for legacy purposes only. If you are creating a newconnector, please use HTTP Server Connector instead.

The Old HTTP Server Connector listens for incoming HTTP connections andreturns the GET parameters as an entry. If a Parser is specified then the Connectorswill process POST requests and parse the contents using the specified Parser. GETrequests will not use the Parser. If a POST request is received and no Parser isspecified the contents of the POST data is returned as an attribute (″postdata″) inthe returned entry.

The Connector will parse URL requests and populate an entry in the followingmanner:

http://host/path?p1=v1&p2=v2entry.path = "/path"entry.p1="v1"entry.p2="v2"

http://host?p1=v1&p2=v2entry.path="/"entry.p1="v1"entry.p2="v2"

If a POST request is used then it is expected that the requestor is sending data onthe connection as well. Depending on the value for the parser parameter theConnector will do the following:


Parser presentInstantiate the Parser with the HTTP input stream. Connector will delegategetNext to the Parser’s getEntry and return whatever the Parser returns.

Parser not presentPut contents of post data in a attribute called postdata.

entry.postdata = ″<post data>″

The session with the HTTP client is closed when the Connector receives a getNextrequest from the AssemblyLine and there is no more data to fetch. I.e. if the Parserhas returned a null value, or on the second call to getNext if no Parser is present.If you call getNext (i.e. iterate) after having received a null from the Connector.


connectorTypecom.ibm.di.connector.OldHTTPServer

port The TCP port to listen to (default = 80)

parser The name of a Parser to handle the contents of POST requests

See also“URL Connector” on page 132, “HTTP Server Connector”.

HTTP Server ConnectorThe HTTP server Connector listens for incoming HTTP connections and returns theGET parameters as an entry. If a Parser is specified then the Connectors willprocess POST requests and parse the contents using the specified Parser. GETrequests will not use the Parser. If a POST request is received and no Parser isspecified the contents of the POST data is returned as an attribute (″postdata″) inthe returned entry.

The HTTP Server Connector uses metamerge.HTTP as internal parser if no parseris specified.

The Connector will parse URL requests and populate an entry in the followingmanner:

http://host/path?p1=v1&p2=v2entry.path = "/path"entry.p1="v1"entry.p2="v2"

http://host?p1=v1&p2=v2entry.path="/"entry.p1="v1"entry.p2="v2"

If a POST request is used then it is expected that the requestor is sending data onthe connection as well. Depending on the value for the parser parameter theConnector will do the following:

Parser presentInstantiate the Parser with the HTTP input stream. Connector will delegategetNext to the Parser’s getEntry and return whatever the Parser returns.


Parser not presentPut contents of post data in a attribute called postdata.

entry.postdata = ″<post data>″

The session with the HTTP client is closed when the Connector receives a getNextrequest from the AssemblyLine and there is no more data to fetch. I.e. if the Parserhas returned a null value, or on the second call to getNext if no Parser is present.


connectorTypecom.ibm.di.connector.HTTPServerConnector

port The TCP port to listen to (default = 80)

parser The name of a Parser to handle the contents of POST requests

See also“URL Connector” on page 132, “HTTP Client Connector” on page 79, “HTTPparser” on page 164.

JDBC ConnectorThe JDBC Connector provides access to a variety of systems. In order to reach asystem using JDBC you need a JDBC driver from the system provider. Thisprovider is typically delivered with the product in a jar- or zip file. These filesmust be in your classpath or copied to the extensions directory.

Note: JDBC Connector is supported on Microsoft Access 2000 and later versions.This is for a specific JDBC connector for Access, not using the ODBC bridge.However, both approaches can be used. Use the ODBC bridge to get intoolder versions of Access, just like you would use the bridge to get into Excelor other source exposed as ODBC.

ConfigurationAll parameters described below give the means to configure the JDBC Connector.They are usually set through the IBM Directory Integrator Admin tool–either fromthe ″Configure Connector″ screen or by scripting.

The Connector needs the following parameters. Clicking in the ConnectorConfiguration in the Admin tool will show you the internal name. So you can seethat JDBC URL is jdbcSource.

connectorTypecom.ibm.di.connector.JDBCConnector

jdbcSourceSee documentation for your JDBC provider. It is called JDBC URL in theIBM Directory Integrator Admin tool. See also ″jdbcSource″, page 87.

jdbcLoginThe username parameter. Only the tables available to this user are shown.

jdbcPasswordThe password for the user


jdbcDriverThe JDBC driver class name.

jdbcExposeNullValuesIf this parameter is set to ″true″ then NULL values will be returned as anempty attribute (i.e. empty value set). If set to false, then the attribute willnot be part of the entry returned.

jdbcSelectThe select statement to execute when selecting entries for iteration. If youleave this blank, the default construct (SELECT * FROM TABLE) is used.

jdbcTableThe table/view to operate on. This is only used when the Connectoroperates in lookup or update mode. If the jdbcSelect parameter is notspecified then the iterator mode Connector will also use this parameter toconstruct a default SELECT statement.

jdbcSessionParametersThis parameter is a multi line field where you can specify ALTER SESSIONcommands. One good example is ″SET NLS_FORMAT ’YYYY-MM-DD’″.

jdbcDateFormatA format string used to parse dates when they are supplied as strings.

jdbcUsePropertiesIf this parameter is set to ″true″ the JDCB Connector will add JDBC driverparameters from the configuration. You must prefix each additional driverparameter with ″jdbc.″ as in ″jdbc.extradriverparam″. The latter will causethe JDBC driver to receive a parameter called ″extradriverparam″ and itsassociated value.

Note: If you use this method the jdbcLogin and jdbcPassword is not used.You must provide these values using the ″jdbc.″ prefix as well.

connectorFlagsA list of flags to enable specific behavior.

{ignoreFieldErrors}

If getting field values causes an error this flag will cause the Connector toreturn the Java exception object as the value instead of throwing theexception (i.e. calling the Connectors *Fail EventHandlers).

jdbcSchemaThe schema from the table of the db that you wish to use. If left blank, thevalue of the jdbcLogin is used.

Link CriteriaThe operand Equal is translated to the equal sign (=), while the Contains, StartWith and End With operators are mapped to the like operator.

OtherApart from the standard functions exposed by all Connector, this Connector alsoexposes several other functions you can use in your scripts.

execSQL (string)Executes an arbitrary SQL command. Returns the error string if it fails.

execSQLSelect (string)Executes SQL SELECT command. Returns the error string if it fails.


getNextSQLSelectEntry ()Having executed execSQLSelect you can use this method to get the nextentry from the result set.

The Connector’s ″jdbcTable″ parameter must be empty for this to workcorrectly.

The above functions does not interfere with the normal flow of entries andattribute mappings for the Connector.

metamerge.MySQL–This is another variation of the JDBC connector. It works thesame as the JDBC connector.

Notes

TimestampIf you want to store a timestamp value containing both a date and a time, youshould make sure you provide an object of type java.sql.Timestamp, as you couldwith this Attribute Mapping:a = java.util.Date();ret.value = new java.sql.Timestamp (a.getTime());

SQL Databases: column names with special charactersIf you have columns with special character in their names and use the AddOnly orUpdate modes:1. Go to the attribute map of the Update or AddOnly Connector2. Rename the Connector attribute (not the work attribute!) from

name-with-dashto ″name-with-dash″ (add quotes).

The necessity of using this functionality might be dependent on the JDBC driveryou are using, but standard MS Access 2000 has this problem.

Using prepared statementsThis section describes how the Connector creates SQL queries. You can ignore thissection unless you are curious about the internals.

For a database, the Connector will use prepared statements or dynamic querydepending on the situations:v if the connector gets the schema definition from the database, it will use

prepared statements.v otherwise, it will create a dynamic SQL query.

On Multiple EntriesSee Appendix E, “Connector modes flowcharts” on page 227 for more informationabout what happens when a Connector has a link criteria returning multipleentries.

For the JDBC Connector in Delete or Update mode, if you have used thesetCurrent() method of the Connector and not added extra logic, all entriesmatching the link-criteria are deleted or updated.


ODBC–specifying database paths directlyWhen you use the JDBC/ODBC Connector you can, if the ODBC driver permits,specify a database/file path the ODBC driver should use. This type ofconfiguration avoids having to define a data source name for each database/filepath your Connector will use.

jdbcDriversun.jdbc.odbc.JdbcOdbcDriver

jdbcSourcejdbc:odbc:<driver name>;DBQ=<path>

MS Access is installedOpen the ODBC data source control panel a select the User DSN tab. Inthis table you will see the driver names you can use in the JDBC Sourceparameter. The picture below shows the MS Access database driverhighlighted. For example, if you want to access an MS Access database″c:\my documents\mydb.mdb″ you would provide the following value forthe JDBC source:jdbc:odbc:MS Access Database;dbq=c:\my documents\mydb.mdb

MS Access is not installedIf MS Access is not installed, provided that you are on a Windows system,use the syntax:jdbc:odbc:Driver={MS Access Driver(*.mdb)};dbq=c:\my documents\mydb.mdb

JMS ConnectorThe JMS Connector provides access to JMS based systems such as IBM MQ Server.

Refer to Specific topics to see what you might need to do to your IBM DirectoryIntegrator installation in order to make the JMS Connector work.

The Connector enables communication of both native Entry objects and XML textto be passed using a Java Message Server product.

The JMS Connector supports JMS message properties. Each message received bythe JMS Connector will populate the conn object with properties from the JMSmessage (see the getProperty() and setProperty() methods of the entry class to accessthese). conn object properties are prefixed with ″jms.″ followed by the JMS messageproperty name. The property holds the value from the JMS message. Whensending a message the user can set properties which will then be passed on to theJMS message sent. The JMS Connector will scan the conn object for properties thatstarts with ″jms.″ and set the corresponding JMS message property from the connproperty.v JMS: correlationID=12 ——> conn jms.correlationID=12v conn:jms.inReplyTo=12 ——> JMS:inReplyTo=12

The conn object is only available in a few hooks. See conn object available underAttribute Mapping for where.

Currently, only the IBM MQ Series server is supported.


JMS messagesEverything sent and received by the JMS connector is a JMS message. The JMSconnector converts the IBM Directory Integrator Entry object into a JMS messageand vice versa. Each JMS message contains predefined JMS headers, user definedproperties and some kind of body that is either text, a byte array or a serializedJava object.

JMS message typesThe JMS environment that allows you to send different types of data on the JMSbus. This connector recognize three of those types. The three types are referred toas TextMessage, BytesMessage and ObjectMessage. The most open-minded strategyis to use TextMessage (e.g. jms.usetextmessages=true) so that other applicationsthan IBM Directory Integrator can read messages generated by the JMS connector.When you communicate with other IBM Directory Integrator servers over a JMSbus the BytesMessage provides a very simple way to send an entire Entry object tothe recipient. This is also particularly useful when the entry object contains specialJava objects that are not easy to represent as text. Most Java objects provide atoString() method that returns the string representation of it but the opposite isvery rare. Also, the toString() method does not always return very usefulinformation. For example, the string representation of a byte array is″[B@<memory-address>″.

Text messageA text message carries a body of text. The format of the text itself is undefined soit can be virtually anything. When you send/receive messages of this type theconnector will do one of two things depending on whether you have specified aparser or not.v When you specify a parser the connector will call the parser to interpret the text

message and return these attributes along with any headers and properties.When sending a message the provided conn object will be passed to the parserto generate the text body part. This makes it easy to send data in variousformats onto a JMS bus (e.g. use the LDIF parser, XML parser etc ....). You caneven use the SOAP parser to send SOAP requests over the JMS bus.

v If you don’t have a parser defined, the text body is returned in an attributecalled message. When sending a message the connector will use the providedmessage attribute to set the JMS text body part.

var str = work.getString ("message");task.logmsg ("Received the following text: " + str );

If you expect to receive text messages in various formats (XML, LDIF, CSV ...) youshould leave the parser parameter blank and make the guess yourself as to whatformat the text message is. When you know the format you can use thesystem.parseObject(parserName, data) to do the parsing for you as in:var str = work.getString ("message");// code to determine formatif ( isLDIF )

e = system.parseObject( "metamerge.LDIF", str );else if ( isCSV )

e = system.parseObject ( "metamerge.CSV", str );else

e = system.parseObject ( "metamerge.XML", str );}// Dump parsed entry to logfiletask.dumpEntry ( e );


The jms.usetextmessages flag determines whether the connector should use thismethod when sending a message.

Object messageAn object message is a message containing a serialized Java object. A serializedJava object is a Java object that has been converted into a byte stream in a specificformat which makes it possible for the receiver to ″resurrect″ the object at the otherend. Testing shows that this is fine as long as the Java class libraries are availableto the JMS server in both ends. Typically, a java.lang.String object will cause noproblems but other Java objects might. For this reason, the JMS connector will notgenerate object messages but is able to receive them. When you receive an objectmessage the connector will return two attributes:v java.object - This attribute holds the java object and you should access the object

using the getObject method in your work/conn entry.v java.objectClass - This attribute is a convenience attribute and holds the class

name (String) of the Java objectvar obj = work.getObject ("java.object");obj.anyMethodDefinedForTheObject ();

You will only receive these messages.

Bytes messageA bytes message is a message carrying an arbitrary array of bytes. The JMSconnector will generate this type of message when the jms.usetextmessages flag isfalse. The connector will take the provided entry and serialize it into a byte arrayand send the message as a bytes message. When receiving a bytes message, theconnector will first attempt to deserialize the byte array into an Entry object. If thatfails, the byte array is returned in the message attribute. You should access the bytearray using the getObject method in your work/conn entry.var ba = work.getObject ("message");for ( i = 0; i < ba.length; i++)

task.logmsg ( "Next byte: " + ba [ i ] );

This type of message is generated only if jms.usetextmessages is false (notchecked).

Iterator modeA new parameter was added to the configuration where you can specify a MessageFilter to filter out specific messages you want returned on a Queue/Topic (Topic isalso called Pub/Sub). A message filter specification is a subset of SQL92.

CallReply modeIn this mode the Connector has two attribute maps, both Input and Output.

Lookup modeThe connector now supports Lookup mode (e.g. findEntry) where the user cansearch for matching messages in a JMS Queue (Topic (Pub/Sub) is not supportedby Lookup).

The Link Criteria specifies the JMS headers and properties for selecting matchingmessages on a queue. Important When you specify the link criteria you must notuse the ’jms.’ prefix. If you search for a property called MyProp you must say″MyProp = ’value’″ even thought the connector returns the property asjms.MyProp. A future version will correct this potential confusion.


For the advanced link criteria you must conform to the Message Selectionspecification as described in the JMS specification(http://java.sun.com/products/jms). The JMS connector will in this release reusethe SQL filter specification (JMS message selection is a subset of SQL92) to buildthe message selection string. Turn on debug mode to view the generated messagefilter string.

There are basically two ways to perform a lookup. The first way is to do anon-destructive search in a Queue (using QueueBrowser) which will returnmatching messages without removing the messages from the JMS queue. Thesecond mode removes all matching entries from the JMS queue. You decide whichto use by setting the jms.lookupConsumesMessages flag in the connectorconfiguration. For Topic connections the jms.lookupConsumesMessages flag doesnot apply as messages on topics are always removed when a subscriber receives it.However, the Lookup mode will heed the Durable Subscriber flag in which casethe JMS server will hold any messages sent on a topic when you are disconnected.

The JMS Connector works in the same way as other Connectors in that you canspecify a maximum number of entries to return in your AssemblyLine settings. Toensure you retrieve a single message only during lookup, specify max duplicateentries = 1 in the AssemblyLine settings. Setting max duplicates to 1 enables you toretrieve one matching entry at a time regardless of the number of matchingmessages in the JMS queue.

Since the JMS bus is asynchronous the JMS connector provides parameters todetermine when the Lookup should stop looking for messages. There are twoparameters that tells the connector how many times it will query the JMS queueand for how long it will wait for new messages during the query. Specifying 10 forthe retry count and 1000 for the timeout will cause the connector to query the JMSqueue ten times each waiting 1 second for new messages. If no messages arereceived during this interval the connector returns. If during a query the connectorreceives a message, it will continue to check for additional messages (this timewithout any timeout) until the queue returns no more messages or until thereceived message count reaches the Max Duplicate Entries limit defined by theAssemblyLine. The effect of this is that a lookup operation only retrieves thosemessages that are available at the moment.

JMS headers and propertiesA JMS messages consists of headers, properties and the body. Headers are accesseddifferently than properties and was not available in previous versions. In thisversion you can specify how to deal with headers and properties.

JMS headersJMS headers are predefined named values that is present in all messages (althoughthe value might be null). The following is a list of JMS header names thisconnector supports:

JMSCorrelationID(String) This header is set by the application for use by other applications.

JMSDeliveryMode(Integer) This header is set by the JMS provider and denotes the delivermode


JMSExpires(Long) A value of zero means that the message does not expire. Any othervalue denotes the expiration time for when the message is removed fromthe queue.

JMSMessageID

(String) The unique message ID. Note that this is not a required field andmay be null.

Since the JMS provider may not use your provided message id theconnector will set a special property called $jms.messageid after sending amessage. This is to insure that the message id always is available to theuser. To retrieve this value use conn.getProperty(″$jms.messageid″) in yourAfter Add hook.

JMSPriority(Integer) The priority of the message

JMSTimestamp(Long) The time the message was sent

JMSType(String) The type of message

JMSReplyTo

(Destination) The queue/topic the sender expects replies to. Whenreceiving a message this value holds the provider specific Destinationinterface object and is typically an internal Queue or Topic object. Whensending a message you should either reuse the incoming Destination objector set the value to a valid topic/queue name. If the value is NULL (e.g. anattribute with no values) or the string ″%this%″ the connector will use itsown queue/topic as the value. The difference between this method andexplicitly setting the queue/topic name is that you need not update theattribute assignment if you change your connector configuration’squeue/topic name.

There is one restriction in the current version which allows you to onlyrequest a reply to the same type of connection as you are currentlyconnected to. This means that you cannot publish a message on a topicand request the reply to a queue and vice versa.

It is not mandatory to respond to this header so the receiver of themessage can completely ignore this field without any form of punishment.

These headers are all set by the provider and may or may not be acted upon bythe JMS driver for outgoing messages. In the configuration screen you can specifythat you want all headers returned as attributes or specify a list of those of interest.All headers are named using a prefix of ’jms.’. Also note that JMS header namesalways start with the string JMS. This means that you should never use propertynames starting with jms.JMS as they would be intepreted as headers.

JMS propertiesIn previous versions of this connector all JMS properties were copied between theEntry object and the JMS Message. In this release you can refine this behavior bytelling the connector to return all user defined properties as attributes or specify alist of properties of interest. All properties are prefixed with ’jms.’ to separate themfrom other attributes. If you leave the list of properties blank and uncheck thejms.propertiesAsAttributes flag you will get the same behavior as for previous


versions. As opposed to JMS headers, JMS properties can be set by the user. If youuse the backwards compatible mode you must set the entry properties in theBefore Add hook as in:conn.setProperty ( "jms.MyProperty", "Some Value" );

If you either check the jms.propertiesAsAttributes flag or specify a list ofproperties, you should provide the JMS properties as attributes. One way to dothat is to add attributes using the jms. prefix in your attribute map. For example, ifyou add jms.MyProperty attribute map it will result in a JMS property namedMyProperty.


connectorTypecom.ibm.di.connector.JMSConnector.

jms.brokerThe URL for the JMS server.

jms.usernameUsername for authenticating access to the JMS.

jms.passwordPassword for authenticating access to the JMS.

jms.topicThe topic with which messages are exchanged.

jms.connectionIDThe connection ID if you share a username with other sessions.

jms.modeSpecify subscriber or publisher.

jms.connectionTypeSpecify whether you are connecting to a Queue or Topic (Topic issometime called Pub/Sub for Publish/Subscribe).

jms.durableOnly relevant for jms.connectionType Topic (Pub/Sub) If true this willcause the connector to create a durable subscriber. This means that theserver will store messages for a topic for later retrieval when the connectoris offline. See also client ID being mandatory with durable.

jms.clientIDThe client ID to use for Topic connections (mandatory for durable).

Parser If specified, the Text message of a JMS message will be parsed using thisParser upon receipt of a message and used to generate the text messagewhen sending a message.

jms.driverSelect the JMS server type.

jms.usetextmessagesTrue - The connector will produce a TextMessage and send the Entry objecteither by using the specified parser to generate the text body or use thepredefined message attribute as the text body.

jms.autoAcknowledgeIf true, each message is automatically acknowledged by this Connector. If


false, you must manually acknowledge the receipt of a JMS message. If off,we use the JMS CLIENT_ACKNOWLEDGE mode.

jms.messageFilterSpecifies a message filter for selection of messages from a queue/topic.Used in Iterator mode only.

jms.lookupConsumesMessageIf true, each message found during lookup is removed from the queue.Note that you can set the maxDuplicateEntries parameter in yourAssemblyLine settings to prevent lookup to return more than one entry. Iffalse, messages are returned as usual but they are not removed from thequeue.

jms.lookupRetriesNumber of times Lookup will search the queue for matching messages

jms.lookupTimeoutFor how long (in milliseconds) the Connector will wait for new messagesduring a lookup query. This parameter is only used when ″LookupRemoves″ is set to ″true″.

jms.specificHeadersAsAttributesjms.headersAsAttributes If true all JMS headers are returned as attributes(prefixed by jms.) in Iterator and Lookup modes. For AddOnly mode anyattribute starting with jms.JMS will be treated as JMS header. This causethese attributes to be set as JMS headers and removed from the Entryobject before sending the message. Note that very few headers may be setand setting them does not mean the JMS provider will ever use them.

Same as jms.headersAsAttributes but only the listed JMS headers will betreated as headers. Specify one header per line.

jms.propertiesAsAttributesIf true all JMS properties are returned as attributes (prefixed by jms.) inIterator and Lookup modes. For AddOnly mode any attribute starting withjms. will be treated as a JMS property. This causes these attributes to be setas JMS properties

jms.specificPropertiesAsAttributesSame as jms.propertiesAsAttributes but only the listed JMS properties willbe treated as properties. Specify one property per line.


To access the example mentioned here, go to the root_directory/examples/jmsdirectory of your IBM Directory Integrator installation.

Specific topicsHere are some files that you need to add to the IBM Directory Integrator jarsdirectory or to the classpath:

IBM MQ Series

WebSphere® MQ 5.3:v com.ibm.mqjms.jarv com.ibm.mq.jar


v jms.jarv connector.jar

Other versions of MQ might require different .jar files (all from the java/libdirectory of the MQ installation).

JNDI ConnectorThe JNDI Connector provides access to a variety of JNDI services. In order to reacha specific system you may have to install the JNDI driver for that system. Thedriver is typically distributed as one or more *.jar or *.zip files. Place these file in aplace where the Java runtime can reach them, for example, in the ″lib/ext″directory.


connectorTypecom.ibm.di.connector.JNDIConnector

java.naming.factory.initialThe class name for the JNDI driver

java.naming.provider.urlThe URL for the connection

java.naming.security.principalThe principal name (i.e. username)

java.naming.security.credentialsThe credentials (i.e. password)

java.naming.security.authenticationThe authentication method

jndiSearchBaseThe search base to be used when iterating the directory. Specify adistinguished name. Some directories allow you to specify a blank stringwhich defaults to whatever the server is configured to do. Other directoryservices require this to be a valid distinguished name in the directory.

jndiSearchFilterThe search filter to be used when iterating the directory.

jndiSearchScopeThe search scope to be used when iterating the data source. Possible valuesare:subtreeonelevel

jndiNameParameterSpecify which parameter in the AssemblyLine entry is used for naming theentry. This is used during add, modify and delete operations and returnedduring read, search operations. If not specified ″$DN″ is used.

See also“LDAP Connector” on page 95.


LDAP ConnectorThe LDAP Connector provides access to a variety of LDAP based systems. TheConnector supports both LDAP version 2 and 3.

Note that, unlike most Connectors, while inserting an object into an LDAPdirectory, you have to specify the object class attribute, the $dn attribute(distinguished name) as well as the other attributes. The following code example, ifinserted in the Prolog, will define an objectClass attribute that you will be able touse later.// This variable used to set the object class attributevar objectClass = system.newAttribute ("objectclass");objectClass.addValue ("top");objectClass.addValue ("person");objectClass.addValue ("inetorgperson");objectClass.addValue ("organizationalPerson");

Then your LDAP Connectors can have an attribute called objectclass with thefollowing assignment: ret.value = objectClass

To see what kind of attributes the person class has, see(http://ldap.akbkhome.com/objectclass/person.html) . You will there see that youmust supply an sn and cn attribute in your update/add Connector)

In the Connector, you will also need the $dn attribute that corresponds to thedistinguished name. When building $dn in the Attribute Map, assuming anattribute in the work object called iuid, you will typically have code like:var tuid = work.getString("iuid");ret.value = "uid= " + tuid + ",ou=people,o=example_name.com";

Note that the two special attributes $dn and objectclass should usually not beincluded in Modification in Update mode unless you want to move entries inaddition to updating them.


connectorTypecom.ibm.di.connector.LDAPConnector

ldapUrlThe LDAP URL for the connection. (ldap://host:port)

ldapUsernameThe distinguished name used for authentication to the server

ldapPasswordThe credentials (password)

ldapSearchBaseThe search base to be used when iterating the directory. Specify adistinguished name. Some directories allow you to specify a blank stringwhich defaults to whatever the server is configured to do. Other directoryservices require this to be a valid distinguished name in the directory.

ldapSearchFilterThe search filter to be used when iterating the directory.


ldapSearchScopeThis parameter is only used if the Connector is in Iterator mode. Thepossible values are:v subtree - Return entries on all levels from search base and below.v onelevel - Only return entries that are immediately below searchbase.

ldapTimeLimitSearching for Entries should take no more than this number of seconds. 0= no limit.

ldapSizeLimitA search or iteration should return no more than this number of Entries. 0= no limit.

ldapPageSizeA number. If specified the LDAP Connector will try to use paged modesearch. Paged mode causes the directory server to return a specific numberof entries (called pages) instead of all entries in one chunk. Not alldirectory servers support this option.

ldapAuthenticationMethodType of LDAP authentication. Can be one of the following:v Simple (using ldapUsername/ldapPassword). Treated as anonymous if

username/password not provided)v MD5-CRAMv SASLv Anonymous (treated as Simple if username and password are supplied)

ldapUseSSLIf this is checked, use secure sockets layer for communication with theLDAP server.

ldapReferralsSpecifies how referrals encountered by the LDAP server are to beprocessed. The possible values are:v follow -follow referrals automaticallyv ignore -ignore referralsv throw -throw a ReferralException when a referral is encountered. You

need to handle this in an error Hook.

connectorFlagsFlags to enable specific behavior.

deleteEmptyStrings - This flag causes the Connector to remove attributescontaining only an empty string as value before updating the directory. See“Notes” on page 97 for a full explanation. If you are using an LDAPversion 3 server, you should definitely use this flag as the value of anattribute cannot be an empty string.

jndiExtraProviderParamsAdditional JNDI provider parameters. The format is one colon separatedname:value pair on each line.

ldapReturnAttributesList of attributes to return (one attribute per line). If you leave this empty,all attributes are returned.

ldapBinaryAttributesA list of attributes that are treated as binary. The format is one attribute


name on each line. If this is not specified, a default list of attributes isused. As of version 4.6.3, the default list is ″photo personalSignature audiojpegPhoto javaSerializedData thumbnailPhoto thumbnailLogo userPassworduserCertificate authorityRevocationList certificateRevocationListcrossCertificatePair x500UniqueIdentifier objectGUID objectSid″;

Note: An AssemblyLine can only have one list of binary attributes. If youhave several LDAP connectors in an AssemblyLine, the lastconnector should define the list of binary attributes for all the LDAPconnectors in this AssemblyLine if you need to change this from thedefault.

automapADPassword

Used for adding/updating a user’s password in AD using LDAP. Whenchecked, will map LDAP password (a con attribute that must be calleduserPassword) to another name (unicodePwd). unicodePwd has a specialformat that the Connector will translate into.

This will not work with the JSSE libraries delivered with IBM DirectoryIntegrator version 4.6: You need at least version 1.0.2 of the JSSE librariesfor automapADPassword to work (seehttp://java.sun.com/products/jsse/INSTALL.html). The old JSSE versiononly supports 40bit RC4, while AD uses 128bits.

ldapBERTraceTrace LDAP BER packets to file.

ldapSortAttributeA new parameter to specify server side sorting. Does not work withNetscape 4.2!

Note: Increases the strain on the server.

ldapVLVPageSizeUse Virtual List View for iterations. This might be efficient on some serversbut testing shows that Netscape 4.2 is very slow in this respect. However,it does provide a workaround to the out-of-memory problem.

Notesv If you cannot connect to your directory, make sure the Use SSL flag under

Configuration is set according to what the directory expects.v When doing a Lookup, you can use $dn as the Connector Attribute, to look up

using the distinguished name. Do not specify a Simple Link Criteria using both$dn and other attributes.

v When connectorFlags contains the value {deleteEmptyStrings} then for eachattribute, the LDAP Connector will remove empty string values. This willpossibly leave the attribute with no values (i.e. empty value set) If an attributehas an empty value set then a modify operation will DELETE the attribute fromthe entry in the directory. An add operation will never include an emptyattribute since this is not ″legal″. Else modify entry will REPLACE the attributevalues.

v Certain servers have a size limit parameter to hinder you from selecting all theirdata. This can be a nuisance as you iterator will only return the first n entries.Some servers will allow you to exceed the size limit if you are authenticated as amanager, for example, Netscape/iPlanet.


v Those servers that return their whole directory in one show (e.g. non pagedsearch) will typically cause memory problems on the client side. See “Handlingmemory problems in the LDAP Connector”.

v When connectorFlags does not contain {deleteEmptyStrings} then empty strings arepassed as legal values to the directory server. Most servers interpret a REPLACErequest with an empty string as the same as removing the attribute altogether. Ifyou want to control this behavior yourself you can always call a function inyour ″Before Update″ handler to modify the entry as in:

removeBlanks (work);

function removeBlanks (entry) {var list = entry.getAttributeNames();for (i = 0; i < list.length; i++) {if (entry.getString(list[i]) == "") {entry.removeAttribute (list[i]);}}}

Handling memory problems in the LDAP ConnectorSome servers return the whole search result in one show (e.g. non paged search)and this will typically cause memory problems. It might look to you that IBMDirectory Integrator leaks memory, but that is just because it is processing theentries from the server while the server continues to pour more and more entriesinto it.

LDAP servers like AD support the ″Paged Search″ extension that allows you toretrieve a ″page″ (some client/server agreement on number of objects to return at atime), and this is of course the preferred way to handle big return sets (see theldapPageSize parameter for more info on this). You can always test if a serversupports the paged search by clicking the button right of the ″Page Size″ parameterin the LDAP Connector.

If the Page Size parameter is not supported, you might have some real problem,since there is little a client can do when being bombed by the Server. Here are acouple of workarounds:

See the ldapVLVPageSize parameter (page 97) that lets you do a virtual list view.This might or might not be efficient, depending on the LDAP server you use.

If you know that your directory is of a size that can be kept in memory, you canincrease the memory available to the Java VM as described in the Appendix A,“FAQ IBM Directory Integrator” on page 209. This of course, will only work if yourdirectory searches return a limited amount of data.

A general solution to this problem is to use a server specific utility to dump theLDAP database to an LDIF file or some other file format and then read (iterate)that file using a file/URLConnector. A command line could be executed in theprolog (before connectors activated using system.shellCommand), producing theLDIF export and then the AssemblyLine would read that file. It turns out to be aneffective solution when possible. Remember that if you are in a mode where youiterate whole (and big) directories, you probably are able to do it as batch (as thiswill be).

In some cases you could even use IBM Directory Integrator to dump the directorysearch to file: This is actually possible since writing quickly to a file might let IBMDirectory Integrator swallow enough of the data to keep up with the feed


(depending on the amount of data and the speed of the feed). If yourAssemblyLine takes to long time to process an entry (such as it will if it isupdating another directory), the entry flood will happen earlier. However, thissolution is very timing dependent and should be avoided if you have a bettermethod.

See also“JNDI Connector” on page 94

IBM Directory Changelog ConnectorThe IBM Directory Changelog Connector is a specialized instance of the LDAPConnector. The IBM Directory Changelog Connector contains logic to iterate theChangeLog. It returns various attributes, one being the changes attribute: TheConnector will return changes as something that looks like a standard attribute,but it is in fact of the Entry class.

The Connector can be used in batch oriented runs where it starts at a specificchange number and terminates after the last ChangeLog entry. It can also be run incontinuous mode where you specify the timer values for periodically checking forthe next ChangeLog entry.

The Connector will read ChangeLog entries and automatically increase theChangeLog counter by one for each iteration. When the Connector tries to read anon existing ChangeLog entry the Connector goes to sleep for a while(nsSleepInterval). If the total time the Connector is waiting for a new entry exceedsthe nsTimeout value the Connector returns to the caller with a null value (end ofiteration).


connectorTypecom.ibm.di.connector.LDAPConnector

ldapUrlThe LDAP URL for the connection. (ldap://host:port)

ldapUsernameThe distinguished name used for authentication to the server


ldapAuthenticationMethodThe authentication method. Possible values are:v CRAM-MD5 - use the CRAM-MD5 (RFC-2195) SASL mechanismv none - use no authentication (anonymous)v simple - use weak authentication (cleartext password)v If not specified default (simple) is used. If ldapUsername and

ldapPassword is blank then anonymous is used.

ldapSearchBaseThe search base where the ChangeLog is kept. The standard DN for this iscn=changelog

nsChangenumberSpecifies the starting changenumber. Each ChangeLog entry is named


changenumber=intvalue and the Connector will start at the number specifiedby this parameter and automatically increment by one.

nsTimeoutSpecifies the number of seconds the Connector will wait for the nextChangeLog entry.

nsSleepIntervalSpecifies the number of seconds the Connector will sleep between eachpoll.

UseSSLIf Use SSL is true, the EventHandler will use SSL to connect to the LDAPserver. Note that the port number may need to be changed accordingly.

See also“JNDI Connector” on page 94

Netscape/iPlanet Changelog ConnectorThe Netscape/iPlanet Changelog Connector is a specialized instance of the LDAPConnector.

iPlanet Directory 5.0 has changed the change log to a proprietary format. You mustinstall the Retro Change Log Plug-in for accessing the change log. In iPlanetDirectory Server 5.0, the format of the change log was modified. In earlier versionsof iPlanet Directory Server, the change log was accessible with LDAP. Now thechange log is intended for internal use by the server only. If you have applicationsthat must read the change log, you must use the Retro Change Log Plug-in forbackward compatibility.

Active Directory Changelog ConnectorThe Active Directory Changelog Connector is a specialized instance of the LDAPConnector. This Connector contains logic to poll for changes to Active Directoryusing the ″uSNChanged″ mechanism.

The Active Directory Changelog Connector operates in Iterator mode.

BehaviorWhen started the Active Directory Changelog Connector reads from a file the USNvalues stored from the most recent Connector’s session. The Connector firstretrieves the newly added Active Directory (AD) objects, then the modified anddeleted AD objects. After an AD object is retrieved, it is parsed and its Attributesand Attribute values are copied to a new Entry object. This Entry object is thenreturned by the Connector. When there are no more AD objects to retrieve theConnector cycles trying to retrieve the next changed AD object. The Sleep IntervalConnector parameter specifies the number of seconds between two successivecycles. The Connector loops until a new AD object is retrieved or the timeout(specified by the Timeout Connector parameter) expires. If the timeout expires theConnector returns an empty (null) Entry, indicating there are no more Entries toreturn. If a new AD object is retrieved, it is processed as previously described, andthe new Entry is returned by the Connector.

Note: You can retrieve only objects and Attributes which you have permission toread. The Connector does not retrieve an object or an Attribute which youdon’t have permission to read, even if it exists in Active Directory. In such acase the Connector acts as if the object or the Attribute does not exist inActive Directory.


Using the Active Directory Changelog ConnectorThe Active Directory Changelog Connector adds the changeType Attribute to everyEntry returned. The possible values of the changeType Attribute are add, modifyand delete. These are used to represent new, changed and deleted objectsrespectively. Each Entry delivered by the Active Directory Changelog Connectorhas an objectGUID Attribute. The objectGUID Attribute value is a 16-byte bytearray and represents the 128-bit objectGUID of the corresponding Active Directoryobject. For convenience, the Connector adds an extra Attribute to each Entrydelivered (objectGUIDStr). The objectGUIDStr value is the string representation ofthe hexadecimal value of the 128-bit objectGUID. It is delivered in the format{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}, where each x represents a hexadecimaldigit.

If you need to detect and handle moved or deleted objects, you must store theobjectGUID Attributes in the replicated data source and perform search by theseAttributes.

To handle moved or deleted objects, store the objectGUID attribute for each objectyou are tracking. An object’s objectGUID attribute remains unchanged no matterwhere it is relocated.

Note: Deleted objects in Active Directory live for a configurable period of time (60days by default), after which they are completely removed. To avoid missingdeletions, perform incremental synchronizations more frequently than thisperiod.

When an object is deleted, the following happens:v The object’s isDeleted attribute is set to TRUE. Objects where isDeleted==TRUE

are known as tombstones.v The object’s attribute values are removed. However, the RDN, objectGUID and

objectSID (security principles) are always retained.v The object is moved to the Deleted Objects container for its naming context, and

its RDN is altered to ensure uniqueness within the Deleted Objects container.

It is possible for an object to be reported as modified, even though the object’scontent has not changed since it was reported as a new object. This happens whenthe object has been created before the current Connector session has started and islater modified after the current Connector session has started, but before theConnector has actually retrieved it. In this case the Connector retrieves the object’smodified contents and reports it as a new object. After a short period of time(during the same session) the Connector reports the same object as modified andretrieves the same changed and already retrieved object’s contents. Do not beconcerned about this behavior, as it neither hurts the synchronization process, norhas it any significant performance overhead.

It is also possible for an already deleted object to be reported as a new object andlater reported as a deleted object during the same Connector session. This happenswhen the object has been created before the current Connector session has startedand is later deleted after the current Connector session has started, but before theConnector has actually retrieved it. In this case the Connector retrieves the object’sdeleted state and reports it as a new object. After a short period of time (duringthe same session) the Connector reports the same object as deleted.

Note: A deleted AD object has almost all of its attributes removed.The Attributes $dn and distinguishedname must not be used for storing and


tracking deleted objects. You must track deleted objects by their objectGUIDAttribute as described previously. If you need to recognize when deleted objectsare passed by the Connector for creation, look for an Attribute named isDeleted.The Entry contains this Attribute and its value is TRUE.

The Active Directory Changelog Connector can be interrupted any time during thesynchronization process. It saves the state of the synchronization process in a file(after each Entry retrieval), and the next time the Connector is started itsuccessfully continues the synchronization from the point it was interrupted.


connectorTypecom.ibm.di.connector.ADChangelogConnector

ldapUrlThe LDAP URL of the Active Directory service you would like to access.The LDAP URL has the form ldap://hostname:port orldap://server_IP_address:port. For example, ldap://localhost:389.

Note: The default LDAP port number is 389. When using SSL the defaultLDAP port number is 636.

ldapUsernameThe distinguished name used for authentication to the service. Forexample, cn=administrator,cn=users,dc=your_domain,dc=com.

Note: If you use Anonymous authentication, you must leave thisparameter blank.

ldapPasswordThe credentials (password).


ldapAuthenticationMethodThe authentication method to be used. Possible values are:v Anonymous (use no authentication)v Simple (use weak authentication (cleartext password))v MD5-CRAM (use the MD5-CRAM (RFC-2195) SASL mechanism)

ldapUseSSLSpecifies whether to use Secure Sockets Layer for communication withActive Directory.

ldapSearchBaseThe Active Directory sub-tree that is polled for changes. For example,dc=your_domain,dc=com.

Note: If you need to receive deleted objects, this search base should be aNaming Context in the directory.

usnFileNameSpecifies the name of the text file where the most recent Connector sessionUSN values are stored. If the file does not exist or is not in the correctformat, the Connector performs a full synchronization with Active


Directory. The file must not be read-only, since the Connector writes theupdated USN values each time it has retrieved an AD object.

timeoutSpecifies the maximum number of seconds the Connector waits for thenext changed AD object. If this parameter is 0, then the Connector waitsforever. If the Connector has not retrieved the next changed AD objectwithin timeout seconds from the beginning of the waiting, then it returnsan empty (null) Entry, indicating that there are no more Entries to return.

sleepIntervalSpecifies the number of seconds the Connector sleeps between successivepolls.

userCommentPut any comments you want here.

debug Specifies whether more detailed debug information is written to the logfile.

See also“IBM Directory Changelog Connector” on page 99, “LDAP Connector” on page 95

Exchange Changelog ConnectorThe Exchange Changelog Connector is a specialized instance of the LDAPConnector. This Connector contains logic to poll for changes using the″uSNChanged″ mechanism.

The Exchange Changelog Connector operates in Iterator mode.

Notes:

1. Exchange changelog connector works with Exchange 5.5 only. If you areattempting to connect to Exchange 2000, use the Active Directory Changeloginstead.

2. The Exchange 5.5 Service Pak 4 must be installed on the Exchange server.

BehaviorWhen started the Exchange Changelog Connector reads from a file the USN valuesstore from the most recent Connector’s session. The Connector first retrieves thenewly added Exchange objects, then the modified and deleted Exchange objects.After an Exchange object is retrieved it is parsed and its Attributes and Attributevalues are copied to a new Entry object. This Entry object is then returned by theConnector. When there are no more changed objects to retrieve the Connectorcycles waiting for a new change to happen. The sleepInterval Connector parameterspecifies the number of seconds the Connector sleeps after an unsuccessful poll.The Connector loops until either a new change is retrieved or the timeout expires.If the timeout expires the Connector returns an empty (null) Entry, indicating thatthere are no more Entries to return. If a changed object is retrieved it is processedas described above and the new Entry is returned by the Connector.

Using the Exchange Changelog ConnectorThe Exchange Changelog Connector adds a changeType Attribute to every Entryreturned. The possible values of the changeType Attribute are add, modify anddelete. These are used to represent new, changed and deleted objects respectively.

It is possible an object to be reported as modified, even though the object’scontents has not changed since it was reported as a new object. This happens whenthe object has been created before the current Connector session has started and is


later modified after the current Connector session has startedb but before theConnector has actually retrieved it. In such a case the Connector retrieves theobject’s modified contents and reports it as a new object. After a short period oftime (during the same session) the Connector reports the same object as modifiedand retrieves the same changed and already retrieved object’s contents. Do not beconcerned about this behavior since it neither hurts the synchronization process,nor has it any significant performance overhead.

It is also possible for an already deleted object to be reported as a new object andlater reported as a deleted object during the same Connector session. This happenswhen the object has been created before the current Connector session has startedand is later deleted after the current Connector session has started, but before theConnector has actually retrieved it. In this case the Connector retrieves the object’sdeleted state and reports it as a new object. After a short period of time (duringthe same session) the Connector reports the same object as deleted.

The Exchange Changelog Connector can be interrupted any time during thesynchronization process. It saves the state of the synchronization process in a file(after each Entry retrieval) and the next time the Connector is started itsuccessfully continues the synchronization from the point it was interrupted.

Deleted objects in Exchange live for a configurable period of time (30 days bydefault), after which they are completely removed. To avoid missing deletions,perform incremental synchronizations more frequently than this period.

By default Exchange does not expose the Is-Deleted object Attribute through LDAP.However, the Is-Deleted Attribute can be used in LDAP search queries when it isnot returned as part of the returned Exchange object. That is why the Connectorproperly detects the type of change even if the Is-Deleted Attribute is not visiblethrough LDAP. If, the Is-Deleted Attribute is visible through LDAP, then theConnector can retrieve changes quicker if you set the deletedAttributeVisibleConnector property to TRUE. The Connector uses the returned Is-Deleted Attributeand completes the work faster.

Note: If the server does expose the Is-Deleted Attribute, butdeletedAttributeVisible is set to false, then the Connector still worksproperly, but you can accelerate the Connector by settingdeletedAttributeVisible to true. If the server does not expose the Is-DeletedAttribute, but deletedAttributeVisible is set to true, then the Connectorcannot detect the type of change (modify or delete).

To expose the Is-Deleted Attribute you must obtain Exchange server administratorprivileges and do the following:1. Start the Exchange Administration program admin.exe in RAW mode (admin

/r).2. Select View | Raw Directory from the menu.3. Select Schema from the window on the left.4. Double-click Is-Deleted from the window on the right.5. A message box appears, informing you that only raw properties are displayed

and asking if you want to view these raw properties. Click Yes.6. Select the Heuristics property. You can see the current property value on the

right. You can also edit the property value.


7. In order to decide what value to set the Heuristics property to, please refer tothe following. The heuristic property is a bit mask, which is interpreted asfollows:

Bit 0

v 0: Replicate between sitesv 1: Do not replicate between sites

Bit 1

v 0: Attribute is not visible through LDAPv 1: Attribute is visible to anonymous and authenticated LDAP clients

Bit 2

v 0: Attribute is not accessible by authenticated clientsv 1: Attribute is accessible to authenticated clients but not anonymous

clients

Bit 3

v 0: Attribute is not an operational attributev 1: Attribute is an operational attribute

Bit 4

v 0: Attribute is not visible in Admin tool UI (Attributes page of DS SiteConfiguration object)

v 1: Attribute is visible in Admin tool UI (Attributes page of DS SiteConfiguration object)

By taking note of heuristics, you can determine the visibility of particularattributes. For example, a heuristic value of 3 means the attribute is not replicatedbetween sites and is visible by anonymous LDAP clients. A heuristic value of 11means the attribute is an operational attribute and is visible to authenticated LDAPclients.

As can be seen from the table above bit 1 of the heuristics value determineswhether an object is visible through LDAP. That is why you need to set bit 1 inorder to make the Attribute visible through LDAP.

Another important property of an Exchange object or an Exchange object Attributeis the Description property. It determines the LDAP name of the attribute or object.

Note: Changing the LDAP name might cause interoperability problems.

In Exchange the basis for replication is distinguished names. Therefore, to avoidproblems, Exchange does not rename objects. That is why the distinguished nameobject Attribute uniquely identifies each object and therefore it can be used fortracking objects.


connectorTypecom.ibm.di.connector.ExchangeChangelogConnector

LdapUrlThe LDAP URL of the Exchange server you want to access. The LDAPURL has the form ldap://hostname:port or ldap://server_IP_address:port.For example, ldap://localhost:389.


Note: The default LDAP port number is 389. When using SSL the defaultLDAP port number is 636.

ldapUsernameThe distinguished name used for authentication to the service. Forexample, cn=administrator,ou=domain_name,o=organization_name.


ldapPasswordThe credentials (password).


ldapAuthenticationMethodThe authentication method to be used. Possible values are:v Anonymous (use no authentication)v Simple (use weak authentication (cleartext password))v MD5-CRAM (use the MD5-CRAM (RFC-2195) SASL mechanism)

ldapUseSSLSpecifies whether to use Secure Sockets Layer for communication withExchange

ldapSearchBaseThe specified Exchange sub-tree which is polled for changes. For example,cn=recipients,ou=domain_name,o=organization_name

usnFileNameSpecifies the name of the text file where the most recent Connector sessionUSN values are stored. If the file does not exist or is not in the correctformat, the Connector performs a full synchronization with Exchange. Thefile must not be read-only, since the Connector writes the updated USNvalues each time it has retrieved an Entry.

Note: If you change the search base or the server or both, you might wantto change or edit the USN file as well, because the stored USNvalues might be invalid in regard to the new search base or server.

deletedAttributeVisibleSpecifies whether the Exchange server exposes the Is-Deleted objectAttribute through LDAP.

Note: If the server does expose the Is-Deleted Attribute, butdeletedAttributeVisible is set to false, then the Connector still worksproperly, but you can speed-up the Connector by settingdeletedAttributeVisible to true. If the server does not expose theIs-Deleted Attribute, but deletedAttributeVisible is set to true, thenthe Connector cannot tell the difference between a modified objectand a deleted object and reports all deletions as modify changeoperations.

timeout

Specifies the number of seconds the Connector searches for a new change.Regardless of the value of this parameter the Connector does not timeoutuntil it has scanned every change that has happened before the currentConnector session has started.


If this parameter is 0, then the Connector waits indefinitely for the nextchange.

When the Connector timeouts, it returns an empty (null) Entry, thusindicating that there are no more Entries to return.

sleepIntervalSpecifies the number of seconds the Connector sleeps after an unsuccessfulpoll.

userCommentPut any comments you want here.

debug Specifies whether detailed debug information is written to the log file.

See Also“Active Directory Changelog Connector” on page 100, “IBM Directory ChangelogConnector” on page 99, “LDAP Connector” on page 95

Lotus Notes ConnectorThe Lotus Notes Connector provides access to Lotus Domino databases.

The Lotus Notes Connector reads, writes and deletes records in any Notesdatabase, and is therefore not limited to the Domino directory. Managing users inLotus Notes requires modifying certificates, ACLs and mailboxes. This must bedone manually or using the ″adminp″ system tool. Users can be provisioned inand out of Notes by applying staging databases and integrating with adminpthrough Notes scripting.

Note: Lotus Notes Connector requires Lotus Notes to be release 5.0.8 or higher.

Known limitationsFor Notes connector using Local Client or Local Server modes only: You might notbe able to use ibmditk to connect to to your Notes database. Sometimes, the NotesConnector prompts the user for a password even though the connector provides itto the Notes APIs. The prompt is written to standard-output and input from theuser is read from standard-input. This prompting is performed by the Notes APIand is outside the control of IBM Directory Integrator.

When you run ibmdisrv, both standard input and output are connected to theconsole which enables the user to see the prompt and enter a password. The NotesConnector regains control and continues execution. This means the Connectorworks as expected.

When you run ibmditk, the standard input and output are disconnected from theconsole so the user cannot see or type anything in response. A connect operationcan hang indefinitely waiting for user input.

When the SessionType is LocalClient, you can start your Notes or Designer clientand permit other applications to use its connection by setting a flag in theFile–>Tools–>UserID panel. The checkbox is labeled Don’t prompt for a passwordfrom other Notes-based programs. (Share this user ID password with theseNotes add-ins). In this case, the Notes Connector (that is, the Notes API) ignoresthe provided password and reuses the current session established by the Notes orDesigner client. The Notes or Designer client must be running to enable IBMDirectory Integrator to reuse its session.


Note: You can switch to using DIIOP mode to configure your AssemblyLines andswitch back to Local Client or Local Server mode when you run theAssebmlyLine with ibmdisrv.

Session typesThe following session types are supported:

IIOP This session type uses a TCP connection to the Domino server. The LotusNotes Connector uses HTTP and IIOP to access the Domino server, somake sure these services are started and accessible from the host whereyou are running the Lotus Notes Connector.

LocalClientThis session type uses a local installation of Lotus Notes® or Designer. TheLotus Notes Connector uses the ID file in use by the local client.Requirements are that the Lotus-provided Notes.jar file is in the JavaCLASSPATH and that the local client binaries are in the PATH. TheNotes.jar uses native calls (for example, local client libraries) to accessdatabases. You must also remove the ncso.jar file found inIBMDirectoryIntegrator5.1/jars With this session type the Usernameparameter (dominoLogin) is ignored. The Password (dominoPassword)must match the password in the ID file used or the local Notes clientprompts for a password. Note that this is tricky when you for example runan AssemblyLine with standard input/output detached from the console.Always try to run an AssemblyLine in a command line window to detectwhether the local client is prompting for the password. Testing shows thatthe local client ignores the correct Password parameter and alwaysprompts for a password. One way of making sure the prompt is avoided isto start the notes/designer client, go to the File|Tools|UserID menu andcheck Don’t prompt for a password for other Notes programs.

LocalServerSame as for LocalClient but uses the local Domino server installation. Onedifference is that you can specify a valid Username and matchingPassword.

ConnectingThe Connector uses IIOP to communicate with a Domino server. To establish anIIOP session with a Domino server, the Connector needs the IOR string that locatesthe IIOP process on the server.

When you configure the Connector, you specify a hostname and optionally a portnumber where the server is located. This hostname:port string is in reality theaddress to the Domino server’s http service from which the Connector retrieves theIOR string. The IOR string is then used to create the IIOP session with the server’sIIOP service (diiop). The need for the http service is only for the discovery of theIOR string. This operation is very simple. The Connector requests a documentcalled /diiop_ior.txt from the domino http server that is expected to contain theIOR string. You can replace the hostname:port specification with this string andbypass the first step and also the dependency of the http server . The diio_ior.txtfile is typically located in the data/domino/html directory in your domino serverinstallation directory. Check the Web configuration in the Lotus Administrator forthe exact location.

To verify the first step point your browser at http://hostname:port/dioop_ior.txtwhere hostname:port is the hostname and port number of your domino server. You


receive a document that says IOR: <a bunch of numbers>. If you get a similarresponse to this the first step is verified. If this fails you should check both theHTTP configuration on the server that it allows anonymous access and also verifythat the process itself is running.


alwaysUseFormulaThis flag has meaning when you are not using a View and the databaseyou access is full-text indexed. If you check this flag the Connector usesFormula statements regardless of whether the database is indexed or not.When a view is specified, full-text searches are always used because Viewsdoes not support Formula search statements.

connectorTypecom.ibm.di.connector.remove

dominoLoginThe username to use for authentication against the server. Ignored if youuse Session type LocalClient.

dominoPasswordThe password to use.

dominoHostThe IP hostname or address to the domino server.

dominoSessionTypeCan be one of IIOP, LocalClient or LocalServer. See the previousdiscussions on Session Types.

iiopSSLChecking this flag causes the Connector to request an encrypted IIOPconnection. This flag has meaning when the session type is IIOP only. Oneof the requirements for using SSL is that the TrustedCerts.class file that isgenerated every time the DIIOP process starts must be in the classpath.You must copy the TrustedCerts.class to a local path included in theCLASSPATH or have the \Lotus\Domino\Data\Domino\Java of yourDomino installation in the classpath.

notesDatabaseThe name of the database to use

notesSelectionThe selection used when iterating the data source. You must use validLotus Notes select statements. To select entries from the name & addressbook use the following select statement:Select Form="Person"

notesServerThe name of the server where notesDatabase is found. Leave blank to usethe server you are connecting to (dominoHost).

notesSearchViewThe database view to use.

SecurityIn order to have IBM Directory Integrator access your Domino server, you mighthave to allow it through Domino Administrator -> Security -> IIOP restriction . The


user account you have configured the IBM Directory Integrator to use must belongto a group listed under Run restricted Java/Javascript and Run unrestrictedJava/Javascript

The Domino Web server must be configured to allow anonymous access. If not, thecurrent version of the Connector cannot connect to the Domino IIOP server.

Note: If you want to encrypt the HTTPPassword field of a Notes Address Book,add the following snippet of scripting to your AssemblyLine:// Assume there is a connector named "notes" in the AssemblyLinevar pwd = "Mypassword";var v = notes.connector.getDominoSession().evaluate

( "@Password(\"" + pwd + ")\"" );ret.value = v.elementAt(0);

This code uses Domino’s password encryption routines to encrypt thevariable pwd. It can be used anywhere that you want to encrypt a stringusing the @Password function that Domino provides. A good place to usethis code snippet is in the Output Map for the HTTPPassword attribute.

MailboxConnector ConnectorThis Connector provides access to internet mailboxes (pop or imap). The Connectorcan be used in Iterator, Lookup and Delete modes. The Connector uses predefinedattribute names for the most used headers. For those who need more than this usethe mail.message property to retrieve the native message object.

When the connector is used in Lookup/Delete mode the only searchable headersare:v mail.fromv mail.tov mail.ccv mail.subjectv mail.messageidv mail.messagenumber

Note: Only one connection per user ID is supported. If the user fails to disconnectwhen using the schema tab, and then runs the assembly line, this results ina connection refused error.

Note: The MailboxConnector Connector does not support the Advanced LinkCriteria (see “Advanced link criteria” on page 27).

Configurationclass com.ibm.di.connector.MailboxConnector

mailServerThe mail server hosting the mailbox. It might include a port numberseparated by a space (<url> <port>), for example:domino.raleigh.ibm.com 110

mailUserThe user name


mailPasswordThe password for mailUser

mailFolderThe mail folder to monitor. For POP3 this can only be INBOX. For IMAP4servers this can be any folder available on the server.

mailProtocolSpecify pop3 or imap.

Predefined Properties/AttributesThe Connector uses the following predefined attributes and properties:

mail.fromThe From header

mail.toThe TO recipient headers

mail.ccThe CC recipient headers

mail.subjectThe subject header

mail.messageidThe message-id header

mail.messagenumberThe message’s internal number

mail.sentThe date the message was sent

mail.receivedThe date the message was received

mail.bodyIn case of a single part message this attribute will contain the messagebody

mail.bodypartsIn case of a multipart message this attribute will contain a javax.mail.Partobject.

mail.messageThis is the javax.mail.Message representing the message returned in theentry.

See also“MailboxConnector EventHandler” on page 149

Memory Stream ConnectorThe Memory Stream Connector can read from or write to any Java stream, but ismost often used to write into memory, where the formatted data can be retrievedlater. The allocated buffer is as needed.

The Connector can only operate in Iterator mode, AddOnly mode, or Passive state.The behavior of the Connector depends on the way it has been initialized.


v initialize(null) - This is the default behavior. The connector writes into memory,and the formatted data can be retrieved with the method getDataBuffer(), onlyavailable in Memory Stream Connectors. Assuming the connector is named MM,this code could be used anywhere (for example, Prolog, Epilog, all Hooks, scriptcomponents, and even inside attribute mapping):var str = MM.connector.getDataBuffer();// use str for something.// To clear the data buffer and ready the connector

for more output, re-initializeMM.connector.initialize(null);

v initialize(Reader r) - Causes the Connector to read from r. This could be used ifyou want to read from a stream.

v initialize(Writer w) - Causes the Connector to write to w.

v initialize(Socket s) - The Connector can both read from and write to a Socket.

Note: Do not reinitialize unless you want to start reading from or writing toanother data stream. If you want to use the Raw Connector object, see “TheRaw Connector object” on page 182. This connector has an additionalmethod, the getDataBuffer() method.

ConfigurationconnectorType

com.ibm.di.connector.StreamConnector

parser The name of a Parser to format the output (or parse the input)

NT4 ConnectorThe NT4 Connector operates with Windows NT security database. It deals withNT’s users and groups – the two basic entities of the NT security database. TheConnector can both read and modify NT security database on the local NTmachine, the Primary Domain Controller machine and the Primary DomainController machine of another domain.

This Connector is dependent on an NT API, and will only work under theWindows platform.

The Connector is designed to connect to the NT4/win2000 SAM databases throughthe Win32 API for NT/2000 user/group accounts. You can connect to a Win2000’sSAM database, but the Connector will only read/write attributes that arebackward-compatible with NT4 (in other words, the Connector has predefined andstatic attribute map table consisting of NT4 attributes). Win2000 native attributes oruser defined attributes are therefore not supported by the Connector.

Go to “NT4 Connector functional specifications and software requirements” onpage 115 for a full functional specification of NT4Connector, architecturedescription as well as hardware and software requirements.

PreconditionsIn order to successfully run NT4 Connector and obtain all its functionality theConnector should be run in a process owned by a user - member of the localAdministrators group and have login privileges to the domain controller and otherdomains (if accessed). This precondition can be omitted if the UserName andPassword parameters of the Connector are set to specify account with therequirements stated above.


NT4 Connector is designed and implemented to work in the following modes:Iterator, Lookup, AddOnly, Delete, Update. Tuning and using the Connector ineach of the specified modes is just as with any other Connector. However there aresome specifics due to the underlying NT architecture, WinAPI calls andUsers/Groups data structures that have to be paid attention.

Note: The NT4 Connector does not support the Advanced Link Criteria (see“Advanced link criteria” on page 27).


ComputerNameThe name of the machine (for example, ntserver01 ) or its IP address (forexample, 212.52.2.218 ) where the Connector will operate. The computerIBM Directory Integrator is running on must be in the same Domain orWorkgroup as the target system.

EntryTypeShould be set to User (specifying that the Connector will operate with datastructured by Users) or Group (specifying that the Connector operates withdata structured by Groups).

UserNameIf set blank no logon on the specified machine is performed and NT4Connector will have the privileges of the process in which IBM DirectoryIntegrator is run. If some value is set then the Connector will attempt tologon on the ComputerName machine with this user name and thepassword specified by the Password parameter.

PasswordThe value of this parameter is taken in account only when the parameterUserName is set no-blank value. It then specifies the password used forthe logon operations.

PageSizeSpecifies the number of Entries (Users and Global Groups) that NT/ADwill return in one chunk when the Connector retrieves Users and GlobalGroups. Should be a number between 1 and 100.

Constructing Link CriteriaOne has to construct link criteria when using the Connector in Lookup, Updateand Delete modes. NT4 Connector supports just Link Criteria that uniquelyidentifies one entry. The format is strict and passing a Link Criteria that doesn’tmatch this format results in exception saying ″Unsupported Link Criteriastructure.″

Here is the Link Criteria structure that has to be used:

User Connector’s EntryType parameter is set to User. Consists of just one rowwhere:v Connector Attribute is set to UserNamev Operand is set to equalsv Value is set to a name of a user account (i.e. user name) or configured

by a template to receive the name of a user account.

Group Connector’s EntryType parameter is set to Group. Consists of two rows asfollows:1. Initial row:


v Connector Attribute is set to GroupNamev Operand is set to equalsv Value is set to a name of a group account (i.e. group name) or

configured by a template to receive the name of a group account.2. Second Row:

v Connector Attribute is set to IsGlobalv Operand is set to equalsv Value is set to True to indicate that the group account specified in the

first row is global, and False to indicate that the group account islocal. Can also be configured by a template to receive True or Falsevalues indicating global or local group accounts.

Other

User/Group account names:

On Domain Controller MachineUsers and groups are retrieved and should be accessed in the followingformats: <USER_NAME> , <GROUP_NAME>.

On Non Domain Controller MachineLocal users and groups are retrieved and should be accessed in the format<USER_NAME> , <GROUP_NAME>.

Global groups and domain users (can be members of a local group on a nondomain controller machine) are retrieved and should be accessed in the format<DOMAIN_NAME>\<GLOBAL_GROUP_NAME> ,<DOMAIN_NAME>\<USER_NAME>.

Creating a new user: When creating a new user with the Connector, if any of thefollowing Attributes are omitted or assigned a ″null″ value, they are automaticallyassigned a default value as follows:v Flags: The account is marked as ″normal account″ and ″user password never

expires″.v AccountExpDate: A value that indicates that the ″account never expires″ is set.v LogonHours: A value that indicates that there is ″no time restriction″ is set (i.e.

the user may log on always).

Setting user passwordRemember that user password value cannot be retrieved. NT stores this in amanner that cannot be read. If an AssemblyLine copies users from one NTmachine to another you will need to set the Password attribute value manually.

When adding a user passing the Password attribute with no value will result increating a user with an empty password.

When modifying a user passing the Password attribute with no value will result inkeeping the old password.

Setting user Primary Group / global groups membershipApplies only for domain users (users on the Primary Domain Controller machine).A user should always be a member of his Primary Group. This means that thevalue set to the PrimaryGroup attribute should present in the GlobalGroupsattribute. However the PrimaryGroup attribute can be set with no value whenadding a user then default Primary Group is set to the user (Domain Users).


Operating with groupsThere are certain groups that are predefined and special for Windows NT. Andthere are certain operations that are not allowed on these groups. Such operationsare: delete, rename and modification of some of their attributes. Any attempt to tryillegal operation over any of these groups will result in exception.

Here is the list of these groups, structured by NT installations:

Domain Controller:v Global groups

– Domain Admins– Domain Users

v Local groups– Administrators– Users– Guests– Backup operators– Replicator– Account operators– Print operators– Server operators

Non Domain Controller:v Local groups

– Administrators– Users– Guests– Backup operators– Replicator– Power Users

Character setsUnicode is supported.


To access the example mentioned here, go to the root_directory/examples/NT4directory of your IBM Directory Integrator installation.

NT4 Connector functional specifications and softwarerequirements

The NT4 Connector implements connector functionality for both user and groupmanagement on NT systems according to NT definitions and restrictions asoutlined below.

FunctionalityThe NT4 Connector provides the following connector modes: Iterator, Lookup,AddOnly, Update, Delete.


Extract user/group data: NT4 Connector reads both user and group informationfrom the NT4 repository, including group and user metadata as well asrelationship information (i.e., users group and groups group membership). NT4Connector reads both local and domain user/group data. Data will be read fromNT and organized and provided in the containers expected by the IBM DirectoryIntegrator engine.

Add user/group data: NT4 Connector adds user information to both localmachines and domain controllers.

NT4 Connector adds group information to both local machines and domaincontrollers. When operating with a domain controller, the connector can create bothlocal and global groups. When operating with a machine that is not a domaincontroller, the connector can only create local groups, according to securityrestrictions set by NT itself.

Modify group membership: NT4 Connector modifies group membership for bothlocal and global groups. In line with NT security restrictions, members can beassigned to groups as follows:v A global group can only have users from its domain as members.v A local group can have global groups and users from its domain or any trusted

domain as members. A local group, however, cannot contain other local groups.v Users on a local machine can exist without being members of a group.v Each user on a domain controller must belong to a Primary Group. The Primary

Group for a user can be any global group in the domain. While the user’sPrimary Group can be changed, he is always a member of his Primary Group.

Modify user/group data: NT4 Connector modifies external and group propertieson both local machines and domain controllers. When connected to a domaincontroller, the connector is able to modify the properties of both local and globalgroups. Modifying user membership in groups is addressed in the previoussection.

Delete user/group data: NT4 Connector can remove users from both localmachines and domain controllers.

NT4 Connector can remove local groups from both local machines and domaincontrollers. When operating with a domain controller, the connector can removeboth local and global groups.

Business Objects

Connector:

Name NT4 Connector

DescriptionNT connector for IBM Directory Integrator

Role The connector provides bi-directional interaction with the internal NT userdatabase.

States Applicable connector states are fully consistent with IBM DirectoryIntegrator-defined states. There is no custom behavior.

OperationsApplicable connector operations are fully consistent with IBM DirectoryIntegrator-defined connectors. There is no custom behavior.


Parameters:

Name Type Size Range Required Comments

ComputerName String 15 not NULL Yes The name ofthe NTmachinewhichdatabase willbe accessed.Oneconnector’saction can beapplied toexactly oneNT machinethe onespecified bythisparameter.

UserName String not limited can be NULL No User namefor remotelogon inanotherdomain. IfNULL orblank nologon isperformed.

Password String not limited can be NULL No Password ofthe useraccount forremote logonin anotherdomain. Thisvalue, ifentered, willbe sent asclear text.

EntryType Lookup - User, Group Yes Specifieswhether usersor groups willbe presentedby theconnector’sentries.

Entry:

Name NT4 Connector’s entry

DescriptionThe entry object with which NT4 Connector operates

Role This is the atomic data structure used by the connector to represent andtransfer data

States The possible states of the entry objects are determined by the EntryTypeparameter of the connector. There are 2 possible states: User state and


Group state. This parameter is set prior to the execution of the connectoroperation and is constant throughout the operation.

OperationsApplicable connector operations are fully consistent with IBM DirectoryIntegrator-defined connectors. There is no custom behavior.

Entry’s User State Attributes:

Name Type Size Range Comments

UserName String 256 not NULL Specifies the name of the useraccount.

Account

Comment

String not limited can beNULL

Contains a comment to associatewith the user account.

FullName String not limited can beNULL

Contains the full name of the user.

User

Comment


Contains a user comment.

Password String 14 0–14 Specifies the password for the useridentified by the Account nameattribute. Password is notencrypted.

PasswordAge Long doubleword

>= 0 Specifies an integer value thatindicates the number of days thathave elapsed since the user’spassword was last changed. Thisvalue is determined by the NTSystem and cannot be modified

Privilege

Level

Integer doubleword

0,1,2 Specifies an integer value thatindicates the level of privilegeassigned to user. Indicates one ofthe following levels: guest (value 0),user (value 1), administrator (value2). This value is determined by theNT System and cannot be modified.

Home

Directory


Specifies the path of the homedirectory of the user.

Flags Integer doubleword

notspecified

Specifies an integer value thatdetermines several features. Fulland detailed description of allpossible values and their meaningscan be found in the MSDN:USER_INFO_3 structure.

ScriptPath String not limited can beNULL

Specifies the path for the user’slogon script file.

AuthFlags Integer doubleword

notspecified

Specifies an integer value thatcontains a set of bit flags definingthe user’s operator privileges. Thisvalue is determined by the NTSystem and cannot be modified.


Applications

Params


Specifies string that is reserved foruse by applications. This value isused by Mircosoft products and theconnector will not allow itsmodification.

Logon

Workstations


Contains the names of workstationsfrom which the user can log on.

LastLogon Date – notspecified

Specifies when the last logonoccurred. This value is determinedby the NT System and cannot bemodified.

LastLogoff Date – notspecified

Specifies when the last logoffoccurred. This value is determinedby the NT System and cannot bemodified.

Account

ExpDate

Date – notspecified

Specifies when the account expires.

MaxAcc

DiskSpace

Long doubleword

notspecified

Specifies an integer value thatindicates the maximum amount ofdisk space the user can use.

UnitsPerWeek Integer doubleword

notspecified

Specifies an integer value thatindicates the number ofequal-length time units into whichthe week is divided. This value isdetermined by the NT System andcannot be modified. For moreinformation look in the MSDN:USER_INFO_3 structure.

LogonHours byte array 21 notspecified

Specifies the times during whichthe user can log on. Detailedspecification of this data structurecan be found in the MSDN:USER_INFO_3 structure.

BadPassword

Cnt

Integer doubleword

notspecified

Specifies an integer value thatindicates the number of times theuser tried to log on to the accountusing an incorrect password. Avalue of 1 indicates that the valueis unknown. This value isdetermined by the NT System andcannot be modified.

LogonsNum Integer doubleword

notspecified

Specifies an integer value thatindicates the number of times theuser logged on successfully to thisaccount. A value of 1 indicates thatthe value is unknown. This value isdetermined by the NT System andcannot be modified.

LogonServer String not limited can beNULL

Contains the name of the server towhich logon requests are sent. Thisvalue is determined by the NTSystem and cannot be modified.


CountryCode Integer doubleword

notspecified

Specifies an integer value thatcontains the country/region codefor the user’s language of choice.

CodePage Integer doubleword

notspecified

Specifies an integer value thatcontains the code page for theuser’s language of choice.

RelativeUserID Integer doubleword

notspecified

Specifies an integer value thatcontains the relative ID (RID) of theuser. This value is determined bythe NT System and cannot bemodified.

Primary

GroupID

Integer doubleword

notspecified

Specifies an integer value thatcontains the RID of the PrimaryGlobal Group for the user.

ProfilePath String not limited can beNULL

Specifies a path to the user’sprofile.

Home

Directory

Drive


Specifies the drive letter assigned tothe user’s home directory for logonpurposes.

Password

Expired

Integer doubleword

notspecified

Specifies an integer value thatcontains password expirationinformation. For more informationlook at the MSDN: USER_INFO_3structure.

LocalGroups Vector not limited Stringelements

Contains the names of the localgroups that the user is member of.

GlobalGroups Vector not limited Stringelements

Contains the names of the globalgroups that the user is member of.

PrimaryGroup String 256 can beNULL

Contains the account name of thePrimary Group of the user. Appliesonly to domain users. TheNT4UserMetaDataConnectoroperates with domain users onlywhen its parameter ComputerNamespecifies primary domain controller.The Primary Group must be aglobal group.

Entry’s Group State Attributes:

Name Type Size Range Comments

GroupName String 256 not NULL Specifies the account name of thegroup.

Comment String 256 not NULL Specifies a remark associated withthe group.

IsGlobal Boolean 1 false, true Indicates whether the group isglobal.

Users Vector not limited Stringelements

Contains the account names of theusers that are members of this group.


Groups Vector not limited Stringelements

Contains the account names of thegroups that are members of thisgroup.

Use casesThe purpose of this section is to define what data can be obtained from NTdatabase, and define the impact of the connector’s actions to the NT database.

These use cases are defined according to the control points leaved to NT4Connector through the inheritance of the base Connector class.

Obtain user’s data from NT database:

Preconditions:NT4 Connector’s parameter EntryType is set to User.

Start action:This use case begins when the assembly line forces the NT4 Connector toget data from its source (NT database). The action can happen in twostates of the connector:v Iterating through all users.v Searching a particular user by its name.

Actions:NT4 Connector reads from the specified NT machine user data andpopulates all available user entry’s attributes except the attribute Password.The attribute Password is set to NULL.

Exit states:The NT4 Connector creates and provides a user entry with the structurespecified in “Entry” on page 117.

Exceptions:

v The IBM Directory Integrator process does not have access to therequested information.

v The computer name (NT4 Connector ComputerName parameter) isinvalid.

v The username/password provided to access the machine are incorrect.v The user name could not be found in NT database (if a search of a

particular user is performed).

Obtain group’s data from NT database:

Preconditions:NT4 Connector’s parameter EntryType is set to Group.

Start action:This use case begins when the assembly line forces the NT4 Connector toget data from its source (NT database). The action can happen in 2 statesof the connector:v Iterating through all groups.v Searching a particular group by its name

Actions:NT4 Connector reads from the specified NT machine group data andpopulates all group entry’s attributes.


Exit states:The NT4 Connector creates and provides a group entry with the structurespecified in “Entry” on page 117.

Exceptions:



v The group name could not be found in NT database (if a search of aparticular group is performed).

Add user in NT database:


Start action:This use case begins when the assembly line forces the NT4 Connector toadd a user into the NT database.

Actions:

1. A new user account is created in the NT database. Values can be set forall user entry’s attributes except the following (they accept systemdefault values):v PasswordAgev PrivilegeLevelv AuthFlagsv ApplicationsParamsv LastLogonv LastLogoffv UnitsPerWeekv BadPasswordCntv LogonsNumv LogonServerv RelativeUserID

2. If the following Attributes are not set values (or NULL values are set),they get default values with the following meaning:v Flags: ″don’t expire password″, ″normal account″, ″script″ ( ″script″ is

required value for Windows NT/2000)v AccountExpDate: ″account never expires″

v LogonHours: ″no time restriction″ (the user may logon always)3. The user is added as member to all local groups specified in the

LocalGroups attribute. It is assumed that all local group accountsspecified in the LocalGroups attribute exist in the local NT database. Ifthe attribute LocalGroups is set to NULL then no local membership isset for the newly created user.

4. The user is added as member to all global groups specified in theGlobalGroups attribute. It is assumed that all global group accountsspecified in the GlobalGroups attribute exist in the domain NTdatabase. If the attribute GlobalGroups is set to NULL then no globalmembership is set for the newly created user.


5. If the user specified is domain user its Primary Group is set to thegroup specified by the PrimaryGroup attribute. If the PrimaryGroupattribute is NULL then the PrimaryGroup attribute is set to the NTdefault Primary Group.

Exit states:A new user account is created in the NT database with the attribute valuesprovided and user’s membership is set as specified in the user entry’sGroups attribute.

Exceptions:



v The specified user account already exists in the NT database. A useraccount is uniquely identified by the value of the UserName attribute.

v The operation is allowed only on the primary domain controller whilethe connector’s ComputerName parameter specifies other machine.

v The PrimaryGroup attribute value does not specify a valid groupaccount for a domain user’s Primary Group.

v Some of the group accounts specified in the LocalGroups andGlobalGroups attributes do not exist.

Add group in NT database:


Start action:This use case begins when the assembly line forces the NT4 Connector toadd a group into NT database.

Actions:

1. A new group account is created in the NT database. Values can be setto all group entry’s attributes. Local groups can be created for all NTmachines. Global groups can be created only for primary domaincontrollers.

2. The users specified in the Users attribute are added as members of thegroup. It is assumed that all user accounts specified in the Usersattribute exist in the NT database. If the attribute Users is set to NULLthen no users are added as members of the newly created group.

3. The groups specified in the Groups attribute are added as members ofthe group. It is assumed that all group accounts specified in the Groupsattribute exist in the NT database. Only the following group-in-groupmembership type is allowed: global group is a member of local group.If the attribute Groups is set to NULL then no groups are added asmembers of the newly created group.

Exit states:A new group account is created in the NT database with the attributevalues provided. Users and groups membership is set as specified in theuser entry’s Users and Groups attributes.

Exceptions:




v The group already exists. A group account is uniquely identified by thevalue of the GroupName attribute.

v The operation is allowed only on the primary domain controller of thedomain, for example, when trying to add global group on non-primarydomain controller machine).

v The operation is not allowed on certain groups. These groups includeuser groups, admin groups, local groups, and guest groups. These aregroups created, managed and used by NT for more information consultthe MSDN.

Delete user from NT database:


Start action:This use case begins when the assembly line requests that the NT4Connector delete a user account from NT database.

Actions:The specified user account is removed from NT database. This willadditionally remove all group memberships for the identified users.

Exit states:The specified user account is removed from the NT database.

Exceptions:



v The operation is allowed only on the primary domain controller.v The user name could not be found.

Delete group from NT database:


Start action:This use case begins when the assembly line requests that the NT4Connector delete a group account from NT database. Global groups canonly be removed from the primary domain controller machine.

Actions:The specified group account is removed from the NT database. This willadditionally remove all group membership relationships.

Exit states:The specified group account is removed from NT database.

Exceptions:



v The operation is allowed only on the primary domain controller.


v The specified group does not exist.v The operation is not allowed on certain NT’s special groups. These

groups include user groups, admin groups, local groups, and guestgroups. These are groups created, managed and used by NT for moreinformation consult the MSDN.

Modify user data in NT database:


Start action:This use case begins when the assembly line requests that the NT4Connector modify user account information.

Actions:

1. The specified external account properties are modified. Values can beset for all user entry’s attributes except the following attributes:v PasswordAgev PrivilegeLevelv AuthFlagsv ApplicationsParamsv LastLogonv LastLogoffv UnitsPerWeekv BadPasswordCntv LogonsNumv LogonServerv RelativeUserID

2. User’s membership in all groups is canceled (i.e. the user is removedfrom the members list of all local and global groups it was member of).

3. The user is added as member to all local groups specified in theLocalGroups attribute. It is assumed that all group accounts specified inthe LocalGroups attribute exist in the local NT database. If the attributeLocalGroups is set to NULL then no local membership is set for the user.

4. The user is added as member to all global groups specified in theGlobalGroups attribute. It is assumed that all group accounts specified inthe GlobalGroups attribute exist in the domain NT database. If theattribute GlobalGroups is set to NULL then no global membership is setfor the user.

5. If the user specified is a domain user its Primary Group is set to thegroup specified by the PrimaryGroup attribute. If the PrimaryGroupattribute is NULL then the PrimaryGroup attribute is set to the NTdefault Primary Group.

Exit states:The external account properties are modified as set in the user entry’sstructure and user’s membership is reset to the groups specified in theGroups attribute.

Exceptions:




v The user name could not be found.v The operation is allowed only on the primary domain controller.v The operation is not allowed on certain NT’s special groups. These

groups include user groups, admin groups, local groups, and guestgroups. These are groups created, managed and used by NT for moreinformation consult the MSDN.

v Some of the attributes were set invalid (not allowed from NT) values.v Invalid value set to the Password attribute.v The PrimaryGroup attribute value does not specify a valid group

account for a domain user’s Primary Group.v Some of the group accounts specified in the LocalGroups and

GlobalGroups attributes do not exist.

Modify group data in NT database:


Start action:This use case begins when the assembly line requests that the NT4Connector modify a group account properties.

Actions:

1. The specified group account properties are modified. Values can be setto all group entry’s attributes. Local groups can be modified on all NTmachines. Global groups can only be modified on the primary domaincontroller machine.

2. All group’s members (users and groups) are removed from the group’smembers list (i.e. all user and group memberships with this group arecanceled).

3. The users specified in the Users attribute are added as members of thegroup. It is assumed that all user accounts specified in the Usersattribute exist in the NT database.

4. The groups specified in the Groups attribute are added as members ofthe group. It is assumed that all group accounts specified in the Groupsattribute exist in the NT database. Only the following group-in-groupmembership type is allowed: global group is a member of local group.

Exit states:The group account properties are modified as set in the group entry’sstructure and group’s members are reset to the users and groups specifiedrespectively in the Users and Groups attributes.

Exceptions:



v The group name could not be found.v Some of the attributes were set invalid (not allowed from NT) values.v The operation is allowed only on the primary domain controller.


v The operation is not allowed on certain NT’s special groups. Thesegroups include user groups, admin groups, local groups, and guestgroups. These are groups created, managed and used by NT for moreinformation consult the MSDN.

Hardware and software configuration

Software requirements:

Architecture: NT4 Connector is implemented in Java and plugged into the javaclass hierarchy of the IBM Directory Integrator.

NT4 Connector consists of the following layers:v Native C++ code wraps WinAPI functions that operate with NT security

database. This native code is compiled into a DLL.v JNI is used to call the functions from the DLL. A java class wraps all JNI calls

and provides interfaces to access all the functions provided by the DLL.v The java implementation of the NT4 Connector uses the interfaces provided by

the JNI wrapper class and implements the control points (provided by the baseConnector class) for defining functionality of the connector in the followingmodes: Iterator, Lookup, AddOnly, Update, Delete, Passive.

v The IBM Directory Integraotr host machine must be in the same domain orworkgroup as the target system in order to connect.

Error handling: Errors that occurred during the execution of WinAPI functions willbe transformed to exceptions in the native C++ code. These exceptions are thentransformed to java exceptions and thrown through JNI in the java layer of theconnector. From the java layer of the connector they are handled by the IBMDirectory Integrator exception handling mechanism.

Hardware requirements: NT4 Connector requires the standard hardwareconfiguration for IBM Directory Integrator.

The specific data it operates with, however, puts additional requirements. IBMDirectory Integrator that involves NT4 Connector in its assembly lines should:v run on a NT machine server or workstation.v run in a process owned by a user which is member of the local Administrators

group and have login privileges to the domain controller for some operations.v run in a network environment with access to the domain controller, other local

machines, or other domains the connector is configured to operate with.

(runtime provided) ConnectorA runtime provided Connector is a raw Connector that is provided at runtime.When an AssemblyLine is started (through startAL) by an EventHandler or from ascript, you can supply only one Connector to the AssemblyLine as a parameter.The Connector will be used for those AssemblyLine Connectors configured as type(runtime provided). You can use the supplied Connector several times in theAssemblyLine.

Example of how to use a runtime provided Connector from an EventHandler:var myConnector = system.getConnector ("metamerge.FileSystem");myConnector.setParam ("filePath", "mypath.txt");myConnector.initialize ( null );


// Here we start he AssemblyLine itselfvar al = main.startAL ( "AssemblyLine1", myConnector );

Example also including an initial working entryvar myConnector = system.getConnector ("metamerge.FileSystem");myConnector.setParam ("filePath", "mypath.txt");myConnector.initialize ( null );

var entry = system.newEntry();entry.setAttribute ("cn", "My Name");entry.setAttribute ("mail", "([email protected])");

var al = main.startAL ( "AssemblyLine2", myConnector, entry );

ConfigurationThe Connector may need parameters, but their names and values will naturallydepend on the actual Connector.

See also“The AssemblyLine” on page 17.

Script ConnectorThe Script Connector allows you to write your own Connector using a script youare familiar with.

A Script Connector must implement a few functions in order to operate. If youplan to use it for iteration purposes only (i.e. reading not searching/updating) youget by with two functions alone. If you plan to use it as a fully qualified Connectoryou must implement all functions. The functions do not use parameters. Thereason for this is that some scripting languages will not necessarily support this.Passing data between the hosting Connector and the script is obtained by usingpredefined objects. One of these predefined objects is the result object which isused to communicate status information. Upon entry in either function the statusfield is set to ″normal″ which will cause the hosting Connector to continue calls.Signaling end-of-input or errors is done by setting the status and message fields inthis object. Two other script objects are defined upon function entry. These are theentry object and the search object.

When you modify a Script Connector or parser, the script gets copied from theLibrary where it resides and into your configuration file. This has the advantage ofyou being able to customize the script, but the caveat that new versions will not beknown to your AssemblyLine.

Predefined script objects

The result objectsetStatus (code)

v 0 - End of Inputv 1 - Status OKv 2 - Error

setMessage (text)Error message

The entry objectGo to “The Entry object” on page 183 for a description of the entry object.


The search objectGo to “The Search (criteria) object” on page 184 for a description of the searchobject.

FunctionsThe following functions must be implemented by the Connector. Even thoughsome functions may never be called it is recommended that you insert thefunctions with a error signaling code that notifies that caller the function isunsupported.

selectEntriesThis function is called to prepare the Connector for sequential read. Whenthis function is called it is typically because the Connector is used as anIterator in an AssemblyLine.

getNextEntryThis function should populate the (entry) object with attributes and valuesfrom the next entry in the input set. When the Connector has no moreentries to return it should use the result object to signal end of input backto the caller.

findEntryThe findEntry function is called to find an entry in the connected systemthat matches the criteria specified in the (search) object. If the Connectorfinds a single matching entry it is expected that the Connector populatesthe entry object. If no entries were found the Connector should set the errorcode in the result object to signal a failure to find the entry. If more thanone entry were found then the Connector may populate the array ofduplicate entries. Otherwise, the same procedure as no entries foundshould be followed.

modEntryThis function is called to modify an existing entry in the connected system.The new entry data is given by the (entry) object, and the (search) objectspecifies which entry to modify. Some connectors may silently ignore the(search) object, and use the (entry) object to determine which entry tomodify.

putEntryThis function should add the (entry) object to the connected system.

deleteEntryThis function is called to delete an existing entry in the connected system.The (search) object specifies which entry to delete. Some connectors maysilently ignore the (search) object, and use the (entry) object to determinewhich entry to delete.


connectorTypecom.ibm.di.connector.ScriptConnector

ScriptEngine[javascript | vbscript | jscript | perlscript | ......]

script [user defined script]


NoteWhen you use a Script connector or parser, the script gets copied from the Librarywhere it resides and into your configuration file. This has the advantage of youbeing able to customize the script, but the caveat that new versions will not beknown to your AssemblyLine.

Removing the old script Connector from the AssemblyLine and re-introducing itwill get you around this, but remember to copy over code from your hooks!


To access the example mentioned here, go to theroot_directory/examples/script_connector directory of your IBM DirectoryIntegrator installation.

See also“Script parser” on page 169, “JavaScript Connector” on page 197.

SNMP ConnectorThis Connector listens for SNMP traps sent on the network and returns an entrywith the name and values for all elements in an SNMP PDU.

Note: The SNMP Connector does not support the Advanced Link Criteria (see“Advanced link criteria” on page 27).


connectorTypecom.ibm.di.connector.SNMPConnector

SNMP Community″public″ is a good choice if you want to test the Connector.

Mode Trap Listener or Client. The Client mode can use Connectors in Add mode(SNMP Set), Lookup mode (SNMP Get) or Iterator mode (Walk)

Trap listener can only Iterate, listening to traps on the local host.

SNMP Trap PortPort in Trap mode. Unused in Client mode

Trap Wait TimeoutTimeout in Trap mode. The number of milliseconds to wait for the nextPDU. If value is zero or less, the Connector will wait forever.

SNMP HostOnly used for Get in Client mode. Unused in Trap mode

SNMP PortClient port (for client mode) unused in Trap mode

SNMP Walk OIDUsed only in Client mode, iterator Connector. Indicates the OID tree towalk.


SNMP VersionDefault version for get/walk: Client mode. Unused in trap mode.

Note: Link Criteria are treated differently for this connector. In Lookup mode theconnector performs a get request returning the oid/value for the requestedoid. The link criteria specifies: ″oid″ and optionally ″server″, ″port″ and″version″. An example link critertion would be ″oid″ = ″1.1.1.1.1.1.1″.


To access the example mentioned here, go to theroot_directory/examples/snmpTrap directory of your IBM Directory Integratorinstallation.

Notesv In Client mode, a requests will be retried 5 times with increasing intervals over a

period of 13 seconds. Timeout will occur if no answer is received.v If what you want to is to send SNMP Traps, the (system.snmpTrap()) is available

to you.

TCP ConnectorThe TCP Connector is a transport Connector using TCP sockets for transport. Youcan only use the Connector in Iterator and AddOnly mode.

Iterator ModeWhen using the Connector in Iterator mode the Connector waits for incoming TCPcalls on a specific port. When a connection is established the getnext methodreturns an entry with the following properties:v socket The TCP socket object (e.g. the TCP input/output streams)v in An instance of a BufferedReader using the socket’s input streamv out An instance of a BufferedWriter using the socket’s output stream

The in and out objects can be used to read and write data from/to the TCPconnection. For example, you can do the following to implement a simple echoserver. Put the code in your after-getnext hook:var ins =conn.getProperty("inp");var outs =conn.getProperty("out");var str =ins.readLine();outs.write("You said==>"+str+"<==");outs.flush();

Since you are using a BufferedWriter it is important to call the out.flush() method tomake sure data is actually sent out on the connection.

If you specify a Parser then the BufferedReader will be passed to the Parser whichin turn reads and interprets data sent on the stream. The returned entry will theninclude any attributes assigned by the Parser as well as the properties listed above.


If the Connector is configured in serverMode=true then the connection will be closedbetween each call to the getnext method. If serverMode=false the connection to theremote host will be kept open for as long as the Connector is active (e.g. until theAssemblyLine terminates).

AddOnly ModeWhen the Connector works in this mode the default implementation is to writeentries in their string form which is not very useful. Typically, you will specify aParser or use the override-add hook to do specific output. In the override-addhook you access the in/out objects by calling the raw-Connector’s getReader() andgetWriter() methods as in:var in = mytcpconnector.connector.getReader();var out = mytcpconnector.connector.getWriter();

You can also use the before-add and after-add hooks to insert headers/footers aroundthe output from your Parser.

ConfigurationserverMode

If true then Iterating will listen for incoming requests. If false then Iteratingwill connect to remote server.

tcpPortThe TCP port number to connect or listen to (depends on servermode)

tcpHostThe remote host to which connections are make (servermode = false)

parser The parser used for reading/writing entries

See also“File system Connector” on page 75, “Direct TCP /URL scripting” on page 62,“URL Connector”

URL ConnectorThe URL Connector is a transport Connector that requires a Parser in order tooperate. The Connector opens a stream specified by a URL.

Note: When forced through a firewall that enforces proxy server, the URLConnector does not work. The URL Connector needs to have the right proxyserver set.


connectorTypecom.ibm.di.connector.URLConnector

url The URL to open (e.g. http://host/file.csv)

parser The name of a Parser to handle the contents of the file

Supported URL protocolThe supported URL protocols are:v HTTP


See also“File system Connector” on page 75, “TCP Connector” on page 131, “Direct TCP/URL scripting” on page 62.

Web Service ConnectorThe Web ServiceConnector (WS Connector) connects to a Web service provider andcalls a particular Web service operation.

The WS Connector reads the definition of the Web service that is accessed from aWSDL document.

Object and transport protocols supported so far are SOAP and HTTP.

The WS Connector operates in CallReply mode.

Note: A direct internet connection must be available to use this Connector. Forexample, if your internet connection involves an HTTP proxy server, andyour browser is configured to use this proxy, then you can see the wsdl filein the browser, but the Web Service Connector cannot retrieve the file.

The Web Service Connector only supports the ″Request-response″ type ofoperation.

Using the ConnectorThe WS Connector operates in CallReply mode, which means that it is likely to bean intermediate Connector in an AssemblyLine. It does the following:1. Validate the Attributes in the WS Connector ″Output Map″ against the given

WSDL definition.2. Create the necessary SOAP request according to the WSDL definition.3. Send this request to the web service provider.4. Receive the web service provider’s SOAP response.5. Parse the SOAP response and create the conn Entry object.6. Validate the conn Entry Attributes against the WSDL definition.

Following this simple scenario, you can extend your AssemblyLines, allowing themto access a number of Web services at different stages in their work flow.

Any running WS EventHandler can be a Web service provider for the WSConnector, but also non-IBM Directory Integrator WS can be used.

RPC-style SOAP operationsThe WS Connector supports RPC-style SOAP operations only. It does not supportDocument-style SOAP operations. When given a WSDL document the WSConnector will skip any Document-style SOAP operations. On initialization the WSConnector will dump to the log the names of all Document-style SOAP operationsthat were skipped while parsing the WSDL.

Attribute mapping & validation:WSDL messages define the names and types of the input and output Attributes ofa web service operation. The WS Connector retrieves the input Attributes definedin the WSDL messages from the WS Connector ″Output Map″. This ″Output Map″maps Attributes from the work Entry to the WS Connector. Please note that theConnector looks for Attributes in the ″Output Map″ whose names and types match


those defined in the WSDL document. It is OK if there are extra Attributes in the″Output Map″. If, however, some of the WSDL input Attributes cannot be found inthe ″Output Map″ the WS Connector throws an exception.

On return from the web service the WS Connector stores the data returned by theweb service in the conn Entry. The WS Connector ″Input Map″ then maps the connEntry Attributes to the AssemblyLine’s work Entry. The WS Connector performschecks if the names, types and total number of Attributes in the conn Entry (i.e.the data returned by the web service) match the WSDL output Attributes. If not, anexception is thrown. So if the web service does not return data in accordance to theWSDL document, the WS Connector will fail.

Setting the required data types for the input parameters of a Webservice operationThe WS Connector gets the input parameters for a web service operation from the″Output map″. The WS Connector requires that the types of the Attributes in the″Output Map″ (which will be used as input parameters to the web serviceoperation) match the types which the web service operation expects. You can checkwhat data types a web service operation expects for its input parameters by usingthe ″Query Schema″ functionality as explained in the ″Configuration steps″ sectionbelow. That is why you need to set the Attributes’ data types as required by theweb service operation. You can do that in the following way:1. Go to the ″Output Map″ of the WS Connector2. Select the Attribute whose data type you want to set3. Check the ″Advanced Mapping″ check-box in the ″Attribute Map Settings″

section4. Suppose that you have an Attribute called ″age″ and you want to set its value

type to java.lang.Integer (because ″Query Schema″ says that the web serviceoperation needs the ″age″ input parameter to be a java.lang.Integer). Type thefollowing in the script edit box:ret.value = new java.lang.Integer(integer_as_string);

where integer_as_string is the string representation of the ″age″ Attribute value.And if you have used the default Attribute mapping mode for the ″age″Attribute, then all you need to type is:ret.value = new java.lang.Integer(conn.getString("age"));

In this way the ″age″ Attribute will be passed to the WS Connector as ajava.lang.Integer.

ConfigurationwsdlURL

The URL of the WSDL document containing the Web service definition.

wsOperationThe name of the Web service operation to invoke. The Operations... buttonon the WS Connector user interface form displays only the RPC-styleoperations. You have to choose the one that will be invoked by theConnector.

userCommentPut your own comments here.

debug Specifies whether more detailed debug information will be written to thelog file.


Do the following to configure:1. Click the ″Config...″ WS Connector tab to display the WS Connector

configuration form.2. Type in the URL of the WSDL document which contains the definition of the

web service you wish to connect to.3. Click the ″Operations...″ button. If an exception is thrown then you have either

typed the WSDL URL incorrectly or the WSDL document does not followstrictly the WSDL specification and so the WS Connector cannot parse it. Adialog box will appear that shows all the RPC-style operations defined in theWSDL document you specified. You have to choose the operation to invoke. Ifthe operations list is empty, then the WSDL document does not follow strictlythe WSDL specification and so the WS Connector cannot parse it. If noRPC-style operations are defined in the WSDL then a corresponding messagebox will be displayed.

4. Click the ″Schema″ tab of the WS Connector.5. Push the ″Connect″ button. If an error occurs then you have probably typed the

WSDL URL incorrectly. Push the ″Schema″ button. The form will display all theinput, output and input-output Attributes of the web service operation. The[in], [out] and [in, out] syntax prefixes mean that the corresponding Attribute isan input, output or input-output Attribute. An input Attribute is sent to theweb service as a parameter of the web service operation. An output Attribute isreceived from the web service as a return parameter of the web serviceoperation. An input-output Attribute is both sent to and received from the webservice. That is why an input-output Attribute’s input value is overwritten bythis Attribute’s output value.

6. Go to the ″Output Map″ tab and add all the input and input-output Attributesas displayed by the ″Schema″ button.

7. Go to the ″Input Map″ tab and add all the output and input-output Attributesas displayed by the ″Schema″ button.

Notes:

1. There are public WSDL documents on the Internet, which do not follow strictlythe WSDL specification. These incorrect WSDL documents will not be parsedby the WS Connector. Supplying the WS Connector with a URL of an incorrectWSDL document may result in (a) an exception being thrown or (b) an emptylist of operations being shown after clicking the ″Operations...″ button.

2. The WS Connector currently supports simple data types only - complex datatypes are not currently supported. That is why if you specify a Web serviceoperation whose input and/or output requires complex data types the WSConnector will fail.

The ″on error″ hookWhen the WS Connector receives a SOAP Fault from the server and the WSConnector ″on error″ hook is enabled, then the ″on error″ hook will be invoked.The ″message″ Attribute of the error object (available in the ″on error″ hook) willcontain the error information sent in the SOAP Fault.

Schema/namespaces types supportThe Web Service Connector supports a subset of the types defined in thehttp://www.w3.org/2001/XMLSchema (orhttp://www.w3.org/1999/XMLSchema) schema. All the supported types from thisschema are described in “Web Service EventHandler” on page 153. No otherschemas are supported by the Web Service Connector.


Note: When working with the WebServices EventHandler and Connector, youmust avoid starting attribute names with special characters (such as [0-9] [ -’ ( ) + , . / = ? ; ! * # @ $ % ]). Also, you must avoid having attribute namesthat include pecial characters (such as [ ’ ( ) + , / = ?; ! * # @ $ % ] ). This isbecause WebServices builds on SOAP, which is XML, which in turn does notaccept $ as in tags.


Chapter 8. EventHandlers

EventHandlers are used to extend the functionality of AssemblyLines andConnectors by providing a framework to control their execution. This isparticularly useful when an incoming event (i.e. incoming http, LDAP changetrigger or JMS message) can trigger a number of different AssemblyLinesdepending on the content in the incoming data. A few EventHandlers have beenpre-programmed to make things easier. You can always override behavior by usingyour own scripts.

EventHandler typesThese are the EventHandlers that are included in IBM Directory Integrator:v The most used EventHandler is where you specify conditions and actions using

a number of predefined conditions and actions. It also provides hooks whereyou can execute script code for full control.

v Generic Thread EventHandler (historically called trigger or port listener), whereyou script everything. With this EventHandler you have full control but youmust code your actions by hand.

When are they started?When IBM Directory Integrator server starts it walks through the table ofEventHandlers and checks each one for the auto startup flag. If the auto startupflag is set the EventHandler is spawned as a thread inside the IBM DirectoryIntegrator server process. When the EventHandler thread terminates, eithernormally or abnormally, IBM Directory Integrator server will not restart theEventHandler. You can force an EventHandler to start regardless of its auto startflag using line options.

See “Starting the EventHandler” on page 28 for further discussion on how to startEvent Handlers from the Admin tool.

What do they do?EventHandlers are expected to perform a variety of functions but typically theywill enable external events to trigger actions in the IBM Directory Integrator server.These actions could be specific to each site and each person, but one commonaction would be to AssemblyLine. The timer is such an example where the″external″ event is the clock reaching a specific time. Other events are eitherasynchronous, such as when the TCP port EventHandler waits for incoming TCPconnections. Others may initiate some connection and poll for events. An exampleof the latter is the MailboxConnector EventHandler. Please consult eachEventHandler’s configuration for more details on how they work and how to usethem.

Data flowThe EventHandlers do have a prolog and and epilog, just as AssemblyLines. It isexecuted before the action flow of each event.


Passing input/output file names to an AssemblyLineOn the EventHandler side, you want to pass a filename over to the AssemblyLine,and the easiest way is to use an entry object. Here the filename is calledmyFileName, and we use a property instead of an attribute:var entry = system.newEntry();entry.setProperty("inputFileName","myFileName");// start AssemblyLinevar al = main.startAL ("myAssemblyLine", entry);al.join (); // wait for al to finish

On the AssemblyLine side you will have code in your Prolog, in the BeforeConnectors Initialized part (because you want your parameters to be used when theConnectors are initialized):workEntry = task.getWork(); // gets the initial entryvar FileName = workEntry.getProperty("inputFileName");// Set the relevant parameter of the (connector)myFileConnector.connector.setParam("filePath",FileName);// If you don’t want the AssemblyLine to run with the intitial entry, clear ittask.setWork(null);

There are a couple of finer points here:1. Clearing the work entry makes sure that we pass control to the first Iterator .

Of course, if you have an entry that is to be processed, do not clear it! (See“Multiple Iterators in an AssemblyLine” on page 22 for further discussion)

2. Using the Properties instead of the Attributes makes sure that theAssemblyLine does not map the Attribute later (in case of it automaticallymapping mapping all Attributes)

EventHandler availabilityThese were introduced in version 4.5 and give a simple GUI requiring very little orno scripting.v “Connector EventHandler” on page 139v “FTP Poller” on page 139v “HTTP EventHandler” on page 140v “IBM Directory Server EventHandler” on page 141v “JMX EventHandler” on page 143v “LDAP EventHandler” on page 147v “MailboxConnector EventHandler” on page 149v “TCP Port EventHandler” on page 150v “Generic thread (simple EventHandler)” on page 151v “Timer EventHandler” on page 151v “Outlook MailboxConnector” on page 152v “Web Service EventHandler” on page 153


Connector EventHandlerThis EventHandler uses any Connector as an input event generator. TheEventHandler will call the Connector’s getNext method to obtain the next entryfrom the Connector. When a Connector reaches end of input it returns null. ThisEventHandler will continue to call the Connector’s input method even after theConnector returns null. For some Connectors this may make sense whereas forothers it does not.

For example, using the FileSystem Connector makes sense since the file read by theConnector may have data appended to it at any time. Connectors selecting a finiteset of entries will eventually run out of entries and the EventHandler will continueforever waiting for new data.

ConfigurationThe port listener needs the following parameters:

class com.ibm.di.eventhandler.connectorSwitchboard

pollIntervalNumber of seconds between each call to the Connector after a NULL entryhas been received from the Connector.

ConnectorThe Connector to use for input

Objects/properties/attributesThe EventHandler sets the following event properties:

event.originatorThe EventHandler object.

event.connectorThe Connector object used by this EventHandler

The event object also contains any attribute returned by the Connector.

See also“Starting the EventHandler” on page 28

FTP PollerThe FTP poller is an example of the Generic Thread Event Handler. It can be foundin the examples/event_handler_ftp sub-directory in your installation directory. Ithas no special parameters, just a script (JavaScript). The script looks for files on agiven ftp server’s directory and ftp them if found.

The EventHandler does not start any AssemblyLines, but you would typically startan AssemblyLine that would process the actual files.


Chapter 8. EventHandlers 139

To access the example mentioned here, go to theroot_directory/examples/event_handler_ftp directory of your IBM DirectoryIntegrator installation.

HTTP EventHandlerThe HTTP EventHandler is a simple Web server that provides a simpler way todeal with HTTP connections than the TCP EventHandler. The HTTP EventHandlerwill automatically parse the client request into an event object using the HTTPparser. In addition the EventHandler implements HTTP basic authentication if youspecify an authenticator connector.

The EventHandler is ’forking’, so the prolog/epilog is executed once for eachHTTP event received.

In order to provide simple Web server functionality you need to provide thehttp.body and http.content-type Attributes/Properties that the EventHandler returnsas the response to a request. You can also add HTTP headers by setting any http.*Attribute/Property. For example setting the value for http.my-header will cause thisEventHandler to generate a my-header: value in the response.

The http.body property can be set to any of the following

Any string (java.lang.String)The string is sent as-is in the request.

Any Input stream ( java.io.InputStream )The input stream is buffered into memory to compute the content-lengthHTTP header. The input stream data is sent as-is in the request.

A Java file object (java.io.File)The content-length is generated by getting the file size from the file object.Then the contents of the file is sent as-is in the request.

ExampleThe following example returns any file the client requests:var base = event.getProperty("http.base");if ( base == "/" )base = "/index.html";

// Construct the full pathpath = "/home/httpd/documents" + base;

// Construct the Java file objectfile = new java.io.File ( path );

// Set the response propertyevent.setProperty ( "http.body", file );

ConfigurationPort The TCP port on which this handler will be listening

AuthConnectorThe authenticator connector. If you specify a connector it must exist inyour connector library and be configured for Lookup. This EventHandlerwill issue authentication requests to any client (e.g. Web browser) that triesto access this service. When the client provides the username/passwordthe EventHandler will call the auth connector’s lookup method providingthe username and password attributes. Hence, your auth connector must


be configured using a Link Criteria where you use the $username and$password. A typical link criteria would be:username equals $usernamepassword equals $password

If the search fails the EventHandler denies the request and sends anauthentication request back to the client. If the search succeeds the requestis granted and your code in the EventHandler is executed. You can accessthe username by retrieving the HTTP Attribute/Property http.remote_user.You can access the entry returned by the authenticator connector byretrieving the Property auth.entry, by using code like this:var auth = event.getProperty("auth.entry");var fullName = auth.getString("FullName");

AuthRealmThe authentication realm sent to the client when requesting authentication.This is the name you typically see in the login dialog that the browserpops up.

headersAsPropertiesIf checked, all HTTP headers are accessible using the getProperty method ofthe event object. If not, all HTTP headers appear as Attributes (e.g.getAttribute)

useSSLCheck if you want to use SSL. Note that in order to use use SSL, you haveto generate your own certificate in your keystore (with keytool). The clientmust then import this. See “IBM Directory Integrator Secure Sockets LayerSupport” on page 48.

userCommentA comment for your own use. Not used anywhere

See also“EventHandler” on page 28, “HTTP parser” on page 164

IBM Directory Server EventHandlerThe IBM Directory Server EventHandler uses LDAP unsolicited event notificationsto detect changes in an LDAP directory. In order to use the IBM Directory ServerEventHandler your LDAP server must support LDAPv3 unsolicited notificationevents.

When the EventHandler starts, it connects to the LDAP server and retrieves allrecent directory changes, which have happened while it has been offline, andregisters for receiving unsolicited event notifications. When an event occurs in theLDAP directory the EventHandler receives an unsolicited notification event andretrieves the next changelog entry. This changelog entry is accessible as the evententry object. The event entry object has the following attributes:

changenumberThe change number as assigned by the supplier; this integer must increaseas new entries are added, and always be unique within a given server(Required)

targetdnThe distinguished name of the entry which was added, modified, or


deleted; in the case of a ″modrdn″ operation, the targetdn gives the DN ofthe entry before it was modified (Required)

changetypeThe type of change (″add″, ″delete″, ″modify″, or ″modrdn″). (Required)

changesThe changes that were made to the directory server; these changes are inLDIF format; available when changetype is either add or modify ((Optional))

newrdnThe new RDN (Relative Distinguished Name) of the entry, if thechangeType is ″modrdn″; if the changeType attribute does not have the″modrdn″ value then there are no values contained in the newRDNattribute (Optional)

deleteoldrdnA flag which tells whether the old RDN of the entry should either beretained as a distinguished attribute of the entry or deleted (Optional)

newsuperiorIf present, it gives the name of the entry which becomes the immediatesuperior of the existing entry (Optional)

changetimeThe time when the change was made (Required)

modifiersnameThe DN making the change (Optional)

An important feature of the IBM Directory Server EventHandler is that you don’trisk losing notifications when the EventHandler is not running, because each timeit is started it retrieves the changes that it has missed while being offline.

ConfigurationldapUrl

The LDAP URL (ldap://hostname:port)

ldapUsernameThe distinguished name used for authentication to the server (e.g. cn=root);please note that this distinguished name must have administratorprivileges since the EventHandler must be able to read the changelog.


ldapSearchBaseThe search base where the changelog is kept. The standard DN for this iscn=changelog

ldapEventBaseThe base of the directory tree branch about which you want to be notified.Specify a distinguished name. Some directories allow you to specify ablank string which defaults to whatever the server is configured to do.Other directory services require this to be a valid distinguished name inthe directory

ldapSearchScopeThe scope of events which you want to be notified about. Can be one ofsubtree, level and base


ldapChangeNumberFileNameThe name of the file where the last changenumber is/will be stored. Thefile format is human-readable text. This file is updated after each eventnotification

ldapInitialChangeNumberIf the file supplied in the ChangeNumber Filename parameter does not exist,then the EventHandler retrieves the changelog entries, starting fromInitialChangeNumber

ldapAuthenticationMethodThe authentication method. Possible values are:

MD5-CRAM - use CRAM-MD5 (RFC-2195)

SASL - use SASL

Anonymous - use no authentication

Simple - use weak authentication (cleartext password)

If not specified, the default (Anonymous) is used. If either the LoginUsername or Login password parameter is blank then Anonymous is used

ldapUseSSLSpecifies whether to use SSL for communication with the LDAP server.

For an IBM Directory Server installation and configuration guide please seehttp://www-3.ibm.com/software/network/directory/library/.

See also“EventHandler” on page 28, “LDAP EventHandler” on page 147

JMX EventHandlerThe JMX EventHandler processes JMX event notifications. On startup theEventHandler registers for the events it is configured for. When a notificationarrives the EventHandler creates a corresponding event Entry object and passes itto the standard sequence of EventHandler Prolog, Action Map and Epilog. TheJMX EventHandler also allows dynamic addition/removal of notification types.

Note: IBM Directory Integrator Server must be started with the command lineparameter -m to start the internal JMX manager, which must be running forthe JMX EventHandler to operate. See “IBM Directory Integrator commandline options” on page 188 for more information.

Behavior descriptionOn startup the JMX EventHandler registers for the notification types the user hasspecified in the EventHandler’s configuration. These notification types form a listof notification types currently received by the EventHandler (the EventHandlerallows runtime modification of this list and thus more complex behavior may beimplemented). Notification types are specified in the JMX standard for notificationtypes - a string ″interpreted as any number of dot-separated components, allowingan arbitrary, user-defined structure in the naming of notification types″ (consult theJMX specification for more details).

The JMX EventHandler registers for all notification types from its list with allregistered MBeans which are notification broadcasters (runtime registration of newbroadcaster MBeans (or unregistration) is properly handled by the EventHandler).


The JMX EventHandler will receive a notification only if the type of thisnotification is present in the EventHandler’s list or if the list contains a notificationtype which is more general (for example if the list contains ″mobj.AssemblyLine″,the EventHandler will receive both ″mobj.assemblyline.started″ and″mobj.assemblyline.finished″ events).

Each notification received by the EventHandler is processed in a separate thread ofexecution. The EventHandler may receive many notifications in the same time andthey will be processed concurrently.

Using the EventHandlerThe event Entry object has the following properties:

event.originatorThe JMX EventHandler instance which is processing this event.

event.rawNotificationThe raw JMX Notification instance received by the JMX EventHandler(javax.management.Notification). If the component which broadcasts thisnotification has extended javax.management.Notification and has put someadditional data in the subclass this extra information can be retrievedthrough this property.

event.typeThe type string of the event notification (java.lang.String)

event.messageThe message of the notification (java.lang.String)

event.userDataThe JMX notification user data (java.lang.Object)

event.sequenceNumberThe notification sequence number (java.lang.Long)

event.sourceThe MBean object name on which the notification initially occurred(javax.management.ObjectName)

event.timestampThe notification timestamp in milliseconds (java.lang.Long)

event.mbean.objectNameThe object name of the registered/unregistered MBean(javax.management.ObjectName). This property is only available if theevent.type is JMX.mbean.registered or JMX.mbean.unregistered.

event.mbean.nameThe string representation of the MBean object name (java.lang.String). Thisproperty is only available if the event.type is JMX.mbean.registered orJMX.mbean.unregistered.

IBM Directory Integrator notification typesNotifications of the following types are emitted by the IBM Directory Integratoritself:

mobj.assemblyline.startedIndicates that an AssemblyLine has been started. The AssemblyLine ID isstored in event.userData as an object of type java.lang.String.


mobj.assemblyline.finishedIndicates that an AssemblyLine has finished. The AssemblyLine ID isstored in event.userData as an object of type java.lang.String.

mobj.eventhandler.startedIndicates that an EventHandler has been started. The EventHandler ID isstored in event.userData as an object of type java.lang.String.

mobj.eventhandler.finishedIndicates that an EventHandler has finished. The EventHandler ID isstored in event.userData as an object of type java.lang.String.

mobj.server.reloadedIndicates that the IBM Directory Integrator server has reloaded the currentconfiguration or has loaded a new configuration. The path of theconfiguration file is stored in event.userData as an object of typejava.lang.String.

mobj.server.shutdownIndicates that the IBM Directory Integrator server is about to be shutdown. The IBM Directory Integrator server ID is stored in event.userDataas an object of type java.lang.String.

JMX system notification typesThere are two special notification types, which are broadcast by the JMX engine(the JMX MBeanServer):

JMX.mbean.registeredIndicates that an MBean has been registered.

JMX.mbean.unregisteredIndicates that an MBean has been unregistered.

When one of these events is received by the EventHandler, theevent.rawNotification property will contain an object of typejavax.management.MBeanServerNotification. You can use the getMBeanName()method, which returns an object of type javax.management.ObjectName. Thatobject represents the name of the MBean which was registered/unregistered.

Configurationclass com.ibm.di.eventhandler.JMXSwitchboard

eventTypesThe list of notification types the EventHandler will listen for. Thenotification types must be separated by one of the following charactersacting as notification type delimiters: tab, new line, carriage return, space,comma, semi-colon. Specifying a notification type here means that theEventHandler will listen for all notifications, whose type is the same as thespecified or more specific, i.e. specifying ″mobj.AssemblyLine″ means thatthe EventHandler will listen for all notifications, whose type starts with″mobj.AssemblyLine″ (for example ″mobj.assemblyline.started″,″mobj.assemblyline.finished″, etc.). If the list is empty, then theEventHandler will listen for all notification types. Please note that thenotification types are case-sensitive.

userCommentPut any comments you would like here.



Dynamic addition/removal of notification typesDuring runtime you can instruct the JMX EventHandler to start receivingadditional events or to stop receiving some events by using the methods describedbelow:

void addNotificationType(String notificationType)Adds the specified notification type to the EventHandler list of notificationtypes. An empty string for notification type means register for allnotification types. Note that this method will just add the specifiednotification type to the EventHandler’s list and will not check if the listcontains notification types higher in the notification types hierarchy.

void removeNotificationType(String notificationType)Removes the specified notification type from the EventHandler list ofnotification types. If the specified notification type does not exist in theEventHandler list then nothing is removed. If registration for allnotification types has been previously performed, call this method with anempty string to cancel this behavior. Note that calling this method with anotification type will remove this notification type from the EventHandler’slist but you may continue to receive notifications of this type if the listcontains a notification type higher in the notification types hierarchy.

String[] getNotificationTypes()Returns an array of strings representing the list of notification types theEventHandler is currently registered for.

The above methods of the JMX EventHandler can be called from either script orJava code. You can call any of these methods from script inside the JMXEventHandler. Here is an example script that will instruct the EventHandler tostop receiving notifications for AssemblyLines start and start receiving notificationsfor AssemblyLines finish (this script is placed in the EventHandler’s action map):var eh = event.getProperty("event.originator");eh.removeNotificationType("mobj.assemblyline.started");eh.addNotificationType("mobj.assemblyline.finished");

Note: The above methods add and remove notification types to/from theEventHandler list. That is why if you add a notification type which is morespecific than an already present notification type in the EventHandler list,then you will not receive any new notifications. If, however, you laterremove the more general notification type then you will still receive themore specific notification type. Here is an example:

var eh = event.getProperty("event.originator");eh.addNotificationType("mobj.AssemblyLine");

After executing the previous script code, the EventHandler receives all notificationtypes which start with mobj.AssemblyLine.eh.addNotificationType("mobj.assemblyline.started");

The previous line of script does not cause the EventHandler to receive morenotification types. If, however, the following line of script code is executed then theEventHandler still receives the mobj.assemblyline.started notification.eh.removeNotificationType("mobj.AssemblyLine");


This happens because the last method call removes mobj.AssemblyLine from theEventHandler list of notification types, but mobj.assemblyline.started is still presentin the EventHandler list.

LDAP EventHandlerThis EventHandler uses the LDAP event notification mechanism to detect changesin an LDAP directory. In order to use this EventHandler, your LDAP server mustsupport Persistent Search. The only LDAP server tested with this EventHandler isthe Netscape/iPlanet directory server (see the “Notes” on page 97 for more aboutiPlanet), but other LDAP servers may work as well.

When the EventHandler starts it connects to the LDAP server and specifies theselection criteria for event notifications. All distinguished names returned from theEventHandler are relative to the search base specified. To construct the full DN ina flexible way, you can append the search base to for example the new DN withthe following code in a custom scriptevent.setProperty("ldap.newdn", event.getProperty("ldap.newdn") +

"," + task.getParam("ldapSearchBase"));

When an event occurs in the LDAP directory, the EventHandler sets theldap.operation property to one of the following values:

objAddedA new entry was added to the directory

objRenamedAn existing entry was renamed

objModifiedAn existing entry’s attributes were modified

objRemovedAn existing entry was removed

handleErrorAn error was encountered

Depending on the ldap.operation the EventHandler sets the following properties:

Object Added (_objAdded)ldap.newdn

The new distinguished name in case of a rename operation

ldap.newentryThe new entry with changes applied

Object Rename (_objRenamed)ldap.dn

The old distinguished name

ldap.newdnThe new distinguished name

Object Modified (_objModified)ldap.dn

The distinguished name before the modify operation


ldap.entryThe contents of the LDAP entry before the modify operation. Thisfunctionality is only available for LDAP databases where a modificationoperation is done by first removing the object and then recreating it withthe modified attributes

ldap.newdnThe distinguished name after the modify operation

ldap.newentryThe contents of the LDAP entry after the modify operation

Object Removed (_objRemoved)ldap.dn

The distinguished name before the remove operation

ldap.entryThe contents of the LDAP entry before the remove operation

The ldap.entry and ldap.newentry properties are instances of the Entry class so youcan access these as you would normally do with conn and work objects in theAssemblyLine as shown in the following snippet:var old = event.getProperty ("ldap.entry");task.logmsg ("Old common name = " + old.getString("cn") );

One important aspect of the LDAP EventHandler is that you can risk losingimportant notifications when the handler is not running. This handler is best usedwhen you want to trap changes in a directory but still can tolerate loss ofinformation.

Error Encountered (_handleError)ldap.error

The java exception thrown by the eventHandler.

ConfigurationSee “LDAP Connector” on page 95 for a description of the LDAP configurationparameters.

NotesiPlanet Directory 5.0 has changed the changelog to a proprietary format. Go to thefollowing URL:http://docs.iplanet.com/docs/manuals/directory/51/html/ag/replicat_new.htm#1)

You will have to install the Retro ChangeLog Plug-in for accessing the change log.Here is an extract from the Change Log section of the iPlanet documentation:

″In iPlanet Directory Server 5.0, the format of the change log was modified. Inearlier versions of Directory Server, the change log was accessible over LDAP.Now, however, it is intended only for internal use by the server. If you haveapplications that need to read the change log, you need to use the Retro ChangeLog Plug-in for backward compatibility. For more information, refer to the RetroChange Log Plug-In.″


See also“EventHandler” on page 28, “IBM Directory Changelog Connector” on page 99

MailboxConnector EventHandlerThis EventHandler listens for changes in a mailbox. Depending on the protocol thehandler will either poll the mailbox periodically by reconnecting to the mailbox(pop3) or periodically issue idle messages on the connection (imap4).

Configurationclass com.ibm.di.eventhandler.MailboxSwitchboard

mailServerThe mail server hosting the mailbox

mailUserThe user name

mailPasswordThe password for mailUser

mailFolderThe mail folder to monitor. For POP3 this can only be INBOX. For IMAP4servers this can be any folder available on the server.

pollIntervalNumber of seconds between each poll. Be aware that for POP3 this willincur a new connection each time.

mailProtocolSpecify pop3 or imap.



mailbox.sessionThe Java session object ( javax.mail.Session )

mailbox.storeThe message store object ( javax.mail.Store )

mailbox.folderThe folder object ( javax.mail.Folder )

mailbox.messageThe message object ( javax.mail.Message )

mailbox.operationThe operation related to mailbox.message. For pop3 connections onlyexisting entries are reported. For imap connections this property willcontain the value new or deleted.

mail.subjectThe subject header from the mail.message

mail.fromThe from header from the mail.message


mail.toThe first recipient in the mail.message


To access the example mentioned here, go to theroot_directory/examples/event_handler_mailbox directory of your IBM DirectoryIntegrator installation.

See also“EventHandler” on page 28

TCP Port EventHandlerThis EventHandler waits for incoming TCP connections on a specified port andspawns a new thread to handle the incoming request. When the new thread hasstarted the original EventHandler goes back to listening mode. When the newlycreated thread has completed, the thread terminates and the TCP connection isclosed.

The EventHandler is forking, so the prolog/epilog is executed once for each HTTPevent received.

Configurationclass com.ibm.di.eventhandler.TCPSwitchboard

tcp.portThe TCP port on which to listen for incoming connections



event.inputstreamTCP socket input stream

event.outputstreamTCP socket output stream

tcp.remoteIPRemote IP address - dot notation

tcp.remotePortRemote TCP port number

tcp.remoteHostRemote hostname

tcp.localIPLocal IP address - dot notation

tcp.localPortLocal TCP port number


tcp.localHostLocal hostname

tcp.socketTCP Socket object (java.net.Socket)


To access the example mentioned here, go to theroot_directory/examples/event_handler_tcp directory of your IBM DirectoryIntegrator installation.

See also“EventHandler” on page 28

Generic thread (simple EventHandler)The generic thread is executed at startup and continues to run as long as the scriptruns. The script can call the task.sleep(milliseconds) to periodically perform itswork.

ConfigurationThe port listener needs the following parameters:

class com.ibm.di.trigger.GenericTrigger

ScriptEngineScript language (e.g. javascript)

script The script to execute

See also“FTP Poller” on page 139, “MailboxConnector EventHandler” on page 149.

Timer EventHandlerThe timer waits for a specified time at which point it executes a script or starts anAssemblyLine. The script must be provided by the administrator/user.

ConfigurationThis handler needs the following parameters:

class com.ibm.di.trigger.TimerTrigger

scheduleThis parameter decides when the EventHandler is executed. The format is″cron″ style and is specified as follows:

<month> <day> <weekday> <hour> <minute>

The fields have numeric values:v Month = 0 - 11 (January .. December)v Day = 1 - 31v Weekday = 1 - 7 (Sunday .. Saturday)


v Hour = 0 - 23v Minute = 0 - 59

Fields are separated by white space. Enter ″*″ to specify any value. Youmay specify multiple values for any field, separated by commas, but thevalues should be in ascending order.

When the current time matches all the fields in the schedule, the specifiedAssemblyLine is run.

Examples:v * * 5 22 0 - Run every Thursday at 22:00 hoursv * 3 * 22 0 - Run every 3rd of each month at 22:00 hours

Notes:

1. The month field has values from 0 to 11, while day and weekdayvalues begin at 1.

2. A common source of confusion is specifying both a day and a weekday.Both attributes must match, meaning that this event will not occuroften.

AssemblyLineThe AssemblyLine to start.

script If specified, the script must contain a function called ontimer. This functionis called with no parameters whenever the time specified by the scheduleparameter is reached, and then the AssemblyLine is started. The scheduleof the EventHandler can be modified through the timer object. Youreconfigure the timer on the fly by setting the schedule parameter from theontimer function. For example:function ontimer(){timer.setParam ("schedule", "* * * 22 0");}

ScriptEngineScript engine for the script (i.e. javascript, vbscript etc..)


To access the example mentioned here, go to theroot_directory/examples/event_handler_timer directory of your IBM DirectoryIntegrator installation.

Outlook MailboxConnectorThe Outlook MailboxConnector EventHandler is a very simple example of use ofthe Generic Thread Event Handler. It has no special parameters, just a script(VBScript). The script periodically checks the number of items in your inbox anddoes nothing else. In order to make it useful, you do the following from within thescript:v Extract the messagesv Extract information from the messagev Send that information to an AssemblyLine


v Move or delete the message

In order to work with the examples complementing this manual, you must referback to the installation package.

To access the example mentioned here, go to theroot_directory/examples/event_handler_OutlookMailbox directory of your IBMDirectory Integrator installation.

Web Service EventHandlerThe Web Service EventHandler exposes IBM Directory Integrator AssemblyLines asWeb services. All AssemblyLines exposed as Web services from the EventHandlerare described in a WSDL document. The EventHandler reads this document andsearches for these AssemblyLines in the current IBM Directory Integratorconfiguration.

Object and transport protocols supported so far are SOAP and HTTP. Thus anySOAP/HTTP client from the Internet can invoke an IBM Directory IntegratorAssemblyLine and obtain its result.

The Web Service EventHandler and Connector only supports the″Request-response″ type of operation.

AssemblyLines–WSDL mappingIf you are not familiar with WSDL and its terms, you can find its specification athttp://www.w3.org/TR/wsdl.v The WSDL document publishes several operations.v One WSDL operation describes one IBM Directory Integrator AssemblyLine. The

name of the operation must match the name of the AssemblyLine.v Each WSDL operation should be of type ″request-response″. Its input message

describes the structure of the initial Entry passed on the AssemblyLine on itsstart. The output message describes the structure of the result Entry produced bythe AssemblyLine.

v One WSDL message describes the structure of an Entry - its Attributes.

Note: When working with the WebServices EventHandler and Connector, youmust avoid starting attribute names with special characters (such as [0-9] [- ’ ( ) + , . / = ? ; ! * # @ $ % ]). Also, you must avoid having attributenames that include pecial characters (such as [ ’ ( ) + , / = ?; ! * # @ $ % ]). This is because WebServices builds on SOAP, which is XML, which inturn does not accept $ as in tags.

v One WSDL message part describes one Attribute specifying its name and type.The name of the message part must match the name of the Attribute.

SOAP operations styleAll SOAP operations in a WSDL file generated by the Web Service EventHandleruse the RPC-style.

Schema/namespaces types supportThe Web Service EventHandler supports a subset of the types defined in thehttp://www.w3.org/2001/XMLSchema (orhttp://www.w3.org/1999/XMLSchema) schema. All the supported types from thisschema are described on page . No other schemas are supported by the WebService EventHandler.


WSDL message part types–Java-types mappingThe data types supported by the EventHandler are a subset of the standard XMLSchema built-in datatypes. That is why every type is prefixed with ″xsd″, wherethe ″xsd″ prefix is associated with the standard XML Schema URI of″http://www.w3.org/2001/XMLSchema.″ For a complete description of XMLSchema datatypes see http://www.w3.org/TR/xmlschema-2/. The Web ServiceEventHandler currently supports the following XML Schema built-in (xsd) datatypes:

xsd:stringjava.lang.String

xsd:booleanjava.lang.Boolean

xsd:bytejava.lang.Byte

xsd:shortjava.lang.Short

xsd:intjava.lang.Integer

xsd:longjava.lang.Long

xsd:numberjava.lang.Long

xsd:integerjava.lang.Long

xsd:doublejava.lang.Double

xsd:decimaljava.lang.Double

xsd:floatjava.lang.Float

xsd:dateTimejava.util.Date

xsd:hexBinarybyte[]

xsd:base64Binarybyte[]

Notes:

1. According to the XSD specification the dateTime serialized string must conformto the following format: yyyy-MM-ddTHH:mm:ss, where ″yyyy″ designates the4-digit year, ″MM″ - the 2-digit month, ″dd″ - the 2-digit day, ″T″ - theseparator, ″HH″ - the 2-digit hour, ″mm″ - the 2-digit minutes and ″ss″ - the2-digit seconds (e.g. 1990-10-10T18:10:00). Even-though the XSD dateTime typedoes not accept a string specifying the date only (1990-10-10 would not be anacceptable xsd:dateTime string), the WS EventHandler accepts this kind of datestring and constructs a java.util.Date object with the time set to 00:00:00.

2. The Web Service EventHandler currently supports simple data types only -complex data types are not currently supported.


3. Here is an example which demonstrates how to create byte arrays in IBMDirectory Integrator scripts:var byteArray = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, length_of_the_array);

Using the EventHandler1. Create the AssemblyLines that you want to expose as web services through the

WS EventHandler. When you do this, make sure to specify the Attributes of the″Initial Work Entry″ and ″Result Entry″ in the AssemblyLine’s ″Call/Return″tab - the initial and result Entries actually define the input and output of theweb service represented by the AssemblyLine. When adding a new Attributeon the ″Call/Return″ tab be sure to enter the Java class type of the Attribute inthe ″Syntax″ column, for example: java.lang.String, java.lang.Integer, andso forth. The value of the ″Syntax″ column is used by the WSDL generationtool when creating the WSDL file.

2. After identifying the AssemblyLines and their input and result Entry Attributetypes, you have to create a WSDL document that describes thoseAssemblyLines. You can do this from the ″WSDL″ tab of the EventHandler,where a utility for WSDL generation can be found (see the ″Automatic WSDLGeneration″ section below).

3. Now you have to configure the WS EventHandler specifying the URL to theWSDL file you have created and the TCP Port where the WS EventHandler willaccept client requests.

4. Run the WS EventHandler. It will start accepting client (SOAP/HTTP) requests.For a description of the flow of actions the WS EventHandler executes, pleasesee the ″WS EventHandler Processing Sequence″ section below.

5. Now the WS EventHandler’s Web services can be accessed by any SOAP client(including the WS Connector).

WS EventHandler Processing SequenceIt is important to note that the WS EventHandler does not have an Action Map asdo other Eventhandlers. The WS EventHandler is capable of processing two typesof client requests: SOAP requests and HTTP requests for the hosted WSDL file (seethe ″WSDL Hosting″ section). Below are the the sequences that the EventHandlerfollows in order to process each type of request:

SOAP request

1. The SOAP request is parsed.2. The SOAP request is validated against the WSDL definition.3. The EventHandler Prolog is run.4. The AssemblyLine is run with initial Entry created from the SOAP

request input values.5. The EventHandler waits for the AssemblyLine to finish and retrieves its

result Entry.6. The EventHandler Epilog is run.7. The AssemblyLine’s result Entry is validated against the WSDL

definition.8. A SOAP response is generated from the AssemblyLine’s result Entry

and is sent back to the client over HTTP.

WSDL request

1. The EventHandler Prolog is run.


2. The contents of the WSDL file is retrieved (if the EventHandler isconfigured to host the WSDL file).

3. The EventHandler Epilog is run.4. The WSDL contents is sent back to the client via HTTP.

Event propertiesDuring processing a request the Web Service EventHandler delivers the eventassociated with this request to the Prolog and Epilog scripts. The followingproperties are assigned to the event object (available in the EventHandler’s Prologand Epilog):

Connection properties:

tcp.remoteIPConnection’s remote IP address.

tcp.remotePortConnection’s remote port.

tcp.remoteHostConnection’s remote host name.

tcp.localIPThe local IP address.

tcp.localPortThe local port where the EventHandler listens for requests.

tcp.localHostThe local host name.

Web service properties:

event.originatorThe Web Service EventHandler instance that is processing the request.

ws.requestedResourceA java.lang.String object whose value is ″WSDL″ if a WSDL request isbeing processed, or ″AL″ if a SOAP request is being processed.

ws.wsdlA java.lang.String object which contains the WSDL to return. This propertyis null if the EventHandler does not host the WSDL. This property is setonly in the Epilog of a WSDL request.

ws.rawSoapA java.lang.String object which contains the unparsed SOAP request(including SOAP headers). This property is set only during a SOAPrequest.

ws.requestMatchesWsdlA java.lang.Boolean value; ″true″ if the SOAP request matches the WSDLdefinition; ″false″ otherwise. This property is set only in the Prolog of aSOAP request.

event.assemblyLineNameThe name of the AssemblyLine executed. This property is set only duringprocessing of a SOAP request.


event.inputEntryAn Entry object whose Attributes correspond to the input parameters ofthe SOAP request. This property is only set during processing of a SOAPrequest.

event.outputEntryAn Entry object whose Attributes correspond to the output parameters ofthe response. This property is set only in the Epilog of a SOAP request.

event.successfulALExecutionA java.lang.Boolean value: ″true″ if the requested AssemblyLine has beensuccessfully executed; ″false″ - otherwise. This property is set only in theEpilog of a SOAP request.

Note: If you need to return a SOAP Fault to the client as a result of your scriptprocessing within the Prolog or Epilog, then you can use thesetError(java.lang.String aMsg) method of the WS EventHandler in thefollowing way:var wsEventHandler = event.getProperty("event.originator");wsEventHandler.setError("Some message...");

These two lines of code would cause the WS EventHandler to continueexecuting the Prolog/Epilog script until the end of the script is reached, andthen the WS EventHandler would generate a SOAP Fault message with<faultstring> containing ″Some message...″. You might need to do that if youimplement a security mechanism in the Prolog for example.

ConfigurationwsdlURL

The URL of the WSDL document.

tcpPortThe port where the EventHandler will accept SOAP/HTTP requests.

useSSLIf checked the WS EventHandler will use SSL. Please note that in order touse SSL, you have to generate your own certificate in your keystore (withkeytool). The client must then import your certificate. See the ″SSL″ sectionfor configuration information.

userCommentPut your own comments here.


Hosting WSDLThe WSDL file needs to be available for download via HTTP so that clients canretrieve the definition of your Web service. The Web Service EventHandler iscapable of hosting your WSDL so that when a request for the WSDL arrives theWS EventHandler would return the WSDL via HTTP. Configuring WSDL hosting:1. In the ″Config...″ tab of the WS EventHandler enter the ″TCP Port″ and ″Use

SSL″ configuration parameters.2. In the ″WSDL″ tab of the WS EventHandler check the ″Host WSDL″ check box.

That would make the ″Web Service URL″ edit box read-only and will set itscontents to ″http://<your_computer_IP>:<port>/″ or″https://<your_computer_IP>:<port>/″ if you have checked ″Use SSL″ in the


″Config...″ tab. <your_computer_IP> is the IP address of the computer onwhich IBM Directory Integrator Admin tool is being run. <port> is the ″TCPPort″ configuration parameter you entered on the ″Config...″ tab. Checking″Host WSDL″ will also display the WSDL URL. The WSDL URL is the URLclients will need to use in order to retrieve the WSDL file. While running theWS EventHandler you can type this URL in your HTML browser and yourbrowser should retrieve the contents of your WSDL file. The WSDL URL hasthe form ″http://<your_computer_IP>:<port>/?WSDL=″ or″https://<your_computer_IP>:<port>/?WSDL=″ if you have checked ″UseSSL″.

3. Click ″Create WSDL″. That would generate the WSDL file, save it and displayit in the editor box. If you need to make any changes to the generated WSDLyou can do so in the editor box. Don’t forget to save your changes by clicking″Save WSDL″.

Note: If you are using ″Host WSDL″ and you change the ″TCP Port″ or switchon/off ″Use SSL″, then you need to uncheck and then check again the″Host WSDL″ check box so that the ″Web Service URL″ and ″WSDLURL″ can be updated.

Automatic WSDL GenerationYou can automatically generate the WSDL file from the ″WSDL″ tab of the WebService EventHandler. In the ″Available AssemblyLines″ list box you can see theAssemblyLines from the current IBM Directory Integrator configuration that areavailable for exposing in a WSDL document. The ″Exposed AssemblyLines″ listbox (the left one) contains the AssemblyLines that will be exposed as Web serviceoperations in the WSDL document that will be created. If you want to expose anAssemblyLine in the WSDL document, select this AssemblyLine from the″Available AssemblyLines″ list box and push the ″ < ″ (left arrow) button - theAssemblyLine will move to the ″Exposed AssemblyLines″ list. If you don’t want toexpose an AssemblyLine already moved to the ″Exposed AssemblyLines″ list, selectthis AssemblyLine from the list and push the ″ > ″ (right arrow) button - theAssemblyLine will move to the ″Available AssemblyLines″ list.

To generate a WSDL file do the following:1. Move all the AssemblyLines you wish to expose as Web services to the

″Exposed AssemblyLines″ list box.2. Type or browse the file path of the WSDL file you wish to create in the ″WSDL

File Name″ text box.3. ″Web Service URL″ text box:

v If you don’t want to use WSDL hosting type the URL of your Web service inthe ″Web Service URL″ text box. The URL of the Web service shouldreference the computer and port on which you will run the Web ServiceEventHandler (for example ″http://215.50.1.100:8080/″).

v If you want to use WSDL hosting check the ″Host WSDL″ check box.4. Push the ″Create WSDL″ button. That will generate the WSDL file, will save it

and will display its contents in the editor text box.

Attribute typesThis utility fills in the operation input and output parameter types in the messageparts of the WSDL in the following way. For each Attribute the utility examines thevalue of the ″Syntax″ field defined in the ″Call/Return″ tab of the correspondingAssemblyLine. The utility expects this value to be the name of a Java class, e.g.java.lang.Integer. The utility maps this value to an XML Schema type according to


the type map presented in the ″WSDL message part types–Java types Mapping″section. The XML Schema type is then written to the WSDL as the type of theWSDL message part.

Note: If you leave the ″Syntax″ column of an Attribute row empty then the WSDLgeneration utility will assume that the type of the Attribute isjava.lang.String.

SOAP operations styleAll SOAP operations in a WSDL file generated by the Web Service EventHandleruse the RPC-style.


Chapter 9. Parsers

Parser availability and referenceParsers are used in conjunction with a transport Connector to interpret or generatethe content that travels over the Connector’s byte stream.

When the bytestream you are trying to parse is not in harmony with the chosenparser, you get a sun.io.MalformedInputException. For example, the error messagecan show up when using the Schema tab to browse a file.

Base parsersv CSV (Comma Separated Values) Parserv DSML Parserv Fixed Parserv HTTP Parserv LDIF Parserv LineReaderv Regular Expression Parserv SOAP Parserv Script Parserv Simple Parserv XML Parser

Character Encoding conversionJava2 uses Unicode as its internal Character Encoding. When you work withstrings and characters in AssemblyLines and Connectors, they are always assumedto be in Unicode. Most Connectors will provide some means of CharacterEncoding conversion. When you read from text files on the local system, Java2 hasalready established a default Character Encoding conversion which is dependenton the platform you are running.

However, every now and then you read/write data from/to text files in whichinformation is encoded in different Character Encodings. The Connectors in ASthat require a Parser usually accept a characterSet parameter in the Parserconfiguration. This parameter should be set to one of the accepted conversiontables found in the Java2 runtime.

AvailabilityPlease refer to the Java 2 documentation for a list of available conversion tables.

CSV parserThe CSV parser reads and writes CSV style data.

ConfigurationThe parser needs the following parameters:


class com.ibm.di.parser.CSVParser

csvColumnsThis parameter specifies the name for each column the parser shouldread/write. If not specified the parser will read the first line and use thevalue as field names. You should either use the Field Separator betweenthe field names, or you could specify each name on a separate line.

csvColumnSeparatorThis parameter specifies the character used to separate each column. If notspecified the parser will attempt to guess when reading and use a commawhen writing. You can use backslash ( \ ) as escape character to specifynon-printable characters. For example, ( \t ) denotes the TAB character.

csvEnableQuotingWhen this parameter is set to true, the field will be output with quotesaround it under the same conditions as in previous versions, however,quotes inside a quoted field are now doubled. Note: if csvEnableQuoting isset to false, the field will be output ″as is″ which may cause problems.

When reading, quotes around the field will be stripped if this parameter isset to true, and the parser is able to read quoted attributes containing forexample the column separator. If this parameter is set to false, the parsingwill probably return unexpected values when the input contains fieldsdelimited by quotes.

csvWriteHeaderThe default value for this parameter is true. If csvWriteHeader is set, thefirst line output by the parser will contain all the field names separated bythe column separator.

Character EncodingCharacter Encoding conversion. This parameter is not directly availablefrom the parser configuration, you must edit the configuration filemanually to set it. See “Character Encoding conversion” on page 161 formore information.

NotesIn the Admin tool, the parameters are set in the Parser tab of the File Connector. Ifyou want to use TAB as a Field Separator you need to specify \t, but whensupplying Field Names you have to use the actual tab character between fieldnames.

On output, multi-valued attributes will only deliver their first value.

DSML parserThe DSML parser reads and writes XML documents. The parser silently ignoresschema entries.

Configurationclass com.ibm.di.parser.DSMLParser

Character EncodingCharacter Encoding conversion. See “Character Encoding conversion” onpage 161 for more information.

dnattributeThe attribute used for the distinguished name DSML attribute ($dn).


isvalidatingIf checked this parser will request a DTD/Schema validating parser

isnamespaceawareIf checked this parser will request a namespace aware parser

omitxmldeclarationIf checked, the XML declaration will be omitted in the output stream.

prefix Prefix used on XML elements to indicate that they belong to the DSMLnamespace. Default dsml. Available from 4.6.5

uri The URI which identifies this namespace. Defaulthttp://www.dsml.org/DSML.Available from 4.6.5

ExampleThis example shows how you can generate DSML documents on the fly.var dsml = system.getParser ( "metamerge.DSML" );var entry = system.newEntry();

entry.setAttribute ("$dn", "uid=johnd,o=doe.com");entry.setAttribute ("mail", "[email protected]");entry.setAttribute ("uid", "johnd");entry.setAttribute ("objectclass", "top");entry.addAttributeValue ("objectclass", "person");

dsml.setOutputStream ( new java.io.StringWriter() );// Uncomment if you dont want the "<?xml version= ...." header// dsml.setOmitXMLDeclaration ( true );dsml.initParser();dsml.writeEntry ( entry );dsml.closeParser();

var result = dsml.getXML();task.logmsg ( result );

This example shows how you can read a DSML document using script:var dsml = system.getParser ("metamerge.DSML");dsml.setInputStream ( new java.io.FileInputStream("dirdata.dsml") );dsml.initParser ();

var entry = dsml.readEntry();while ( entry != null ) {task.dumpEntry ( entry );entry = dsml.readEntry();}

See also“XML parser” on page 173, “SOAP parser” on page 171

Fixed parserThe Fixed parser reads and writes fixed length records.


class com.ibm.di.parser.FixedRecordParser

fixedColsThis multi line parameter specifies each field name, it’s offset and length asin:

Chapter 9. Parsers 163

field1, 1, 12field2, 13, 4field3, 17, 3


HTTP parserThe HTTP parser interprets a byte stream according to the HTTP specification. Thisparser is used by the HTTP Client Connector and by HTTP Server Connector.

ConfigurationThe parser has the following parameters:

parserTypecom.ibm.di.parser.rspHTTPParser

headersAsPropertiesIf set, the header values will be get/set as Properties, otherwise the headervalues will be read/returned as Attributes. See following for a list ofpossible Attributes/Properties.

clientModeIf set, the parser operates in client mode, otherwise it is in server mode.

Attributes/propertiesWhen constructing a page, depending of the value of headersAsProperties, theparser will use these Attributes/Properties where relevant, to construct the header.When reading a page, the parser will parse the header to fill in theseAttributes/Properties where possible.

http.methodThe HTTP method when sending this information in client mode Default is″GET″. This Attribute/Property is returned in server mode. Seehttp://www.w3.org/Protocols/HTTP/Methods.html for more informationabout HTTP methods.

http.urlThe URL to use. This Attribute/Property is mandatory in client mode

http.content-typeThe content type for the returned http.body (if any). If this is set to″application/x-www-form-urlencoded″, the http.body will also be parsedfor more headers. The default value when writing (when http.bodycontains something), is ″text/plain″.

http.responseCodeThe HTTP response code as an Integer object. Read in client mode. 200 OK—-> 200.

http.responseMsgThe HTTP response message as a String object. Read in client mode. 200OK—-> OK



http.content-lengthThe number of bytes in http.body. This Property/Attribute is returnedwhen reading, and ignored when writing (it is recomputed by the parser).

http.bodyWhen reading, depending of the content-type of the data, this object is aninstance of java.lang.StringBuffer, a char[] or a byte[] that contains thereturned body. When the content is a StringBuffer, you can use code likethis:var body = conn.getObject ("http.body");task.logmsg ("Returned text: " + body.toString() );

See “Using binary values in scripting” on page 35 for how to handle achar[] or byte[]. When writing, http.body should contain either an instanceof java.io.File, in which case that file will be used as the body, or some textthat will be used as the body.

http.text-bodyWhen reading, if the http.content-type starts with the sequence ″text/″, theConnector assumes the body is textual data and reads the http.body streamobject into this attribute.

http.redirectWhen this Attribute/Property has a value, and we are writing and inserver mode, just send a redirect message pointing to the value of thisAttribute/Property.

http.statusUsed when writing in server mode. Default is ″OK″. Interesting values are:v ″OK″ or ″200 OK″- Return a ″200 OK″ response.v ″FORBIDDEN″ or ″401 Forbidden″- Ask for authentication using the

http.auth-realm Attribute/Propertyv ″NOT FOUND″ or ″404 File Not Found″ - Return a 404 File Not Found

response

http.auth-realmUsed when requesting additional authentication. Default value is″IBM-Directory-Integrator″.

http.authorizationContains the authorization read in server mode. It is probably easier to usehttp.remote_user and http.remote_pass.

http.remote_userThe Username from the other end when reading in server mode, or theusername to use when writing in client mode.

http.remote_passThe Password from the other end when reading in server mode, or thepassword to use when writing in client mode.

http.baseThe base URL. Returned when reading in server mode.

http.qs.*Parts of the query string when reading in server mode. The key is the partof name after ″http.qs.″. The value is contained in the Attribute/Property.

http.* All other Attributes/Properties beginning with ″http.″, will be used to


generate a header-line when writing. When reading, headers are put intoAttributes/Properties with a name beginning with ″http.″, and continuingwith the name of the header.

See also“HTTP Client Connector” on page 79, “HTTP Server Connector” on page 83

LDIF parserThe LDIF parser reads and writes LDIF style data. LDIF parser is usually to tofile-exchange with an LDAP directory.

It correctly parses and writes MIME BASE64 encoded strings: It will try to performBASE64 encoding if it find it necessary. One such situation is trailing spaces afterattribute values: To make sure another LDIF parser gets the space, it will BASE64encode your attribute.

Note: A conforming LDIF file must always have characterSet set to UTF-8. ThecharacterSet parameter is also applied when encoding or decoding BASE64encoded strings.

BASE64 encoding looks like garbled text if you don’t know how to decode it.

ldifDNAttributeNameThe attribute name to use for LDIF ″dn″ line

ldifVersionDisplays [as stated in RFC 2849] a version attribute in the beginning of theoutput if checked. This parameter is On by default.

Note: LDIF parser now can suppress the LDIF version number by usingthe ldifVersion parameter.

ldifBinaryAttributesIf you need to specify additional attributes to be treated as binary (a binaryattribute is returned as a byte array, not a string), specify them in thisparameter. By default, the following attributes are treated as binary:v photov personalSignaturev audiov jpegPhotov javaSerializedDatav thumbnailPhotov thumbnailLogov userPasswordv userCertificatev authorityRevocationListv certificateRevocationListv crossCertificatePairv x500UniqueIdentifierv objectGUIDv objectSid


See alsohttp://www.ietf.org/rfc/rfc2849.txt

LineReaderThe LineReader parser reads single lines of data. The line read is returned in asingle attribute. There is also an attribute named ″linenumber,″ containing the linenumber, starting with 1.

Note: Use the LineReader parser if you want to copy a text file only. If you wantto copy a binary file, see “Example” on page 183 for an example of how hotto copy a binary file.

The LineReader parser is useful when reading text files only.


class com.ibm.di.parser.LineReader

attributeNameThis parameter specifies the name of the attribute that will contain the line.Default is ″line″

Regular Expression parserThe Regular Expression parser validates and parses Connectors’ input/outputagainst some regular expression. It uses the free Regular Expressions for Java library″gnu.regxep″ available at http://www.cacas.org/java/gnu/regexp/. Consult″gnu.regexp″ documentation for the regular expression notation supported and forthe library’s specification.

Note: The reference to the free Regular Expressions for Java library ″gnu.regxep″available at http://www.cacas.org/java/gnu/regexp/ is provided as aconvenience. IBM does not support code obtained from this site and is notresponsible for the continued availability or any consequences of use of suchcode.

The Regular Expression parser is designed as a useful example that shows how toimplement your own parser in Java and integrate it in the IBM DirectoryIntegrator.

Functional specification

ConfigurationThe parser provides the following parameters:

class com.ibm.com.di.parser.RegExpParser

regularExpressionSpecifies the regular expression the parser will use.

Subexpressions are enclosed in parentheses, for example: ″ab(c*)d(e*)f″.When the parser is used in read mode, those subexpressions correspond tothe Entry’s Attributes (in the example above, ″c*″ corresponds to the firstAttribute and ″e*″ corresponds to the second Entry’s Attribute).


attributeNamesSpecifies the names of the Attributes delimited with semi-colons, forexample, ″Name;Value″.

The interpretation of this parameter depends on the parser mode:v read mode: The names are used for the Attributes corresponding to the

subexpressions of the regular expression. Mapping is done in the orderof appearance, i.e. the first subexpression will correspond to an Attributenamed with the first name from the ″attributeNames″ parameter, etc.)

v write mode: The names are used to define the output text. It is formed byconcatenating the values of the Attributes enumerated in the″attributeNames″ parameter.

Input: A single line from the input will correspond to a single Entry.v If the line doesn’t match the regularExpression then an Entry with no Attributes is

returned.v If the line matches the regularExpressionthen an Entry is populated with

Attributes and returned. The number of Attributes assigned is equal to thenumber of subexpressions in the regularExpression and each Attribute’s value isthe substring of the input line that matches the corresponding subexpression.

If the number of the names in the attributeNames parameter is less than the numberof the subexpressions in the regularExpression parameter then Attribute names areadded - as many as needed to make those numbers equal. The Attribute namesadded consist of the prefix ″ATTR_NAME_″ and the number of the Attribute nameadded (starting from 0), for example, ATTR_NAME_0, ATTR_NAME_1,ATTR_NAME_2, and so forth.

Output: All Attributes enumerated in the attributeNames parameter that exist inthe Entry are concatenated to form a single string (in the order they appear in theattributeNames parameter).v If this string matches the regularExpression, it is printed on a single line in the

output.v If this string does not match the regularExpression, nothing is printed in the

output and the ″no-match event″ is logged.

Source code

InstallationDo the following to install:1. Create a new folder, named RegExpParser, in the jars subfolder of the IBM

Directory Integrator installation directory.2. Go to the the Regular Expressions for Java Web site

(http://www.cacas.org/java/gnu/regexp/) and download the packagegnu.regexp-1.1.4.tar.gz

3. Extract the archive’s contents keeping path information. Copy the filegnu-regexp-1.1.4.jar (placed in the lib folder) to the newly created RegExpParserfolder.

4. Copy the RegExpParser.jar file from to the RegExpParser folder.

The next time you start ibmditk, you can choose RegExpParser as a Parser type.


Regular Expression parser source codeYou can find the source code for the regular expression parser atexamples/regexp_parser/RegExpParser.java


To access the example mentioned here, go to theroot_directory/examples/regexp_parser directory of your IBM Directory Integratorinstallation.

Script parserThe script parser allows you to write your own parser using a script you arefamiliar with.

A script parser must implement a few functions in order to operate. The functionsdo not use parameters. The reason for this is that some scripting languages willnot necessarily support this. Passing data between the hosting Connector and thescript is obtained by using predefined objects. One of these predefined objects isthe result object which is used to communicate status information. Upon entry ineither function the status field is set to ″normal″ which will cause the hostingparser to continue calls. Signaling end-of-input or errors is done by setting thestatus and message fields in this object. The entry object is populated on calls towriteEntry and is expected to be populated in the readEntry function. When readingentries you have the inp BufferedReader object available for reading character datafrom a stream. When writing entries you have the out BufferedWriter objectavailable for writing character data to a stream.

You can add your own parameters to the configuration and obtain these by usingthe parser object.

ObjectsThe following objects are the only ones accessible to the script parser:

The result objectsetStatus

codev 0 - End of Inputv 1 - Status OKv 2 - Error

setMessagetext

The entry objectaddAttributeValue (name, value)

Adds a value to an Attribute.

getAttribute (name)Returns the named Attribute.

A complete list of available methods, including parameters and return values, canbe found in the installation package.


The inp objectread() Returns next character from stream

readLine()Returns next CRLF terminated line from the input stream.

The out objectwrite (str)

Writes a string to the output stream

writeln (str)Writes a string followed by CRLF to the output stream.

The parser objectgetParam(str)

Returns the parameter value associated with parameter name str

setParam(str, value)Sets the parameter str to value value

logmsg(str)Writes the parameter str in the log file

A complete list of methods can be found in the installation package.

The connector objectFor more information, see the Javadocs material included in the installationpackage.

FunctionsThe parser must supply these functions

readEntry()Read the next logical entry from the input stream and populate the entryobject.

writeEntry()Write the contents of the entry object to the output stream.


class com.ibm.di.parser.ScriptParser

ScriptEngine[javascript | vbscript | jscript | perlscript | ......]

script [user defined script]

includeFiles[files extending the script]

NoteWhen you use a Script Connector or parser, the script gets copied from the Librarywhere it resides and into your configuration file. This has the advantage of youbeing able to customize the script, but the caveat that new versions will not beknown to your AssemblyLine.


Removing the old script parser from the AssemblyLine and re-introducing it willget you around this, but remember to copy over code from your hooks!


To access the example mentioned here, go to theroot_directory/examples/script_parser directory of your IBM Directory Integratorinstallation.

See also“Script Connector” on page 128, “JavaScript parser” on page 198

Simple parserThe Simple parser reads/writes entries. The format is lines withattributename:value pairs. The name of the Attribute is the text leading up to thefirst colon on the line, the rest of the line is the value. Multi-valued Attributes usemultiple lines. Lines with a single period mark the end of an entry. \r and \n inthe value part is an encoding of CR and LF.


class com.ibm.di.parser.SimpleParser

SOAP parserThe SOAP parser reads/writes SOAP XML documents. The parser converts SOAPXML documents to/from entry objects in a simple straightforward fashion. Whenwriting the XML document the parser will use attributes from the entry to buildthe document. The SOAP_CALL attribute is expected to contain the value for theSOAP call. Similarly, on read this attribute is set to reflect the first tag followingthe SOAP-ENV:Body tag. Then for each attribute in the entry, a tag with that nameand value is created. Vice versa, when reading the document, each tag under thesoap-call tag translates to an attribute in the entry object.

Note: When working with the WebServices EventHandler and Connector, youmust avoid starting attribute names with special characters (such as [0-9] [ -’ ( ) + , . / = ? ; ! * # @ $ % ]). Also, you must avoid having attribute namesthat include pecial characters (such as [ ’ ( ) + , / = ?; ! * # @ $ % ] ). This isbecause WebServices builds on SOAP, which is XML, which in turn does notaccept $ as in tags.

The examples below show an entry and a SOAP XML document as they would beread/written.

Example Entry*** Begin Entry DumpSOAP_CALL: ’updateLDAP’mail: (’[email protected])’uid: ’johnd’*** End Entry Dump


Example SOAP document<SOAP-ENV:Envelopexmlns:SOAP-ENV="(http://schemas.xmlsoap.org/soap/envelope/)"xmlns:xsi="(http://www.w3.org/1999/XMLSchema-instance)"xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><ns1:updateLDAP xmlns:ns1="" SOAP-ENV:encodingStyle=

"http://schemas.xmlsoap.org/soap/encoding/"><uid xsi:type="xsd:string">johnd</uid><mail xsi:type="xsd:string">[email protected]</mail></ns1:updateLDAP></SOAP-ENV:Body></SOAP-ENV:Envelope>

ConfigurationThe parser has the following parameters:

class com.ibm.di.parser.SOAPParser


omitxmldeclarationOmit XML declaration header in output stream

isvalidatingRequest a DTD/XSchema validating XML parser

isnamespaceawareRequest a namespace aware XML parser

Parser-specific callsYou can access the parser from your script by dynamically loading the parser andcalling the methods to read/write SOAP documents. The following example showshow to generate the XML document from an entry:var e = system.newEntry();e.setAttribute ("soap_call", "updateLDAP");e.setAttribute ("uid", "johnd");e.setAttribute ("mail", "([email protected])");

// Retrieve the XML document as a stringvar soap = system.getParser ("metamerge.SOAP");soap.initParser();var soapxml = soap.getXML ( e );

task.logmsg ( "SOAP XML Document" );task.logmsg ( soapxml );

// Write to a filevar soap = system.getParser("metamerge.SOAP");soap.setOutputStream ( new java.io.FileOutputStream("mysoap.xml") );soap.writeEntry ( e );soap.close();

// Read from filesoap.setInputStream ( new java.io.FileInputStream ("mysoap.xml") );var entry = soap.readEntry();

// Read from string (from soapxml generated above)var entry = soap.parseRequest( soapxml );task.dumpEntry ( entry );



To access the example mentioned here, go to the root_directory/examples/soapdirectory of your IBM Directory Integrator installation.

XML parserThe XML parser reads and writes XML document. As of version 4.0.3 this parsernow uses the Apache Xerces and Xalan libraries. The parser gives access to XMLdocument through a script object called xmldom.The xmldom is an instance of theorg.w3c.dom.Document interface. Please refer to http://java.sun.com/xml/jaxp-1.0.1/docs/api/index.html for a complete description of this interface.

You can also use the XPathAPI (http://xml.apache.org/xalan-j/apidocs/index.htmland Access Java Classes in your Scripts) to search and select nodes from the XMLdocument. selectNodeList, a convenience method in the (system) object, can be usedto select a subset from the XML document.

When the Connector is initialized. the parser will try to perform Document TypeDefinition (DTD) verification if a DTD tag is present.

Use the connector’s override functions in order to interpret/generate the XMLdocument yourself. You do this by creating the necessary script in either the(getnext) or (Override add) in your assembly line’s hook definitions. If you don’toverride the parser will read/write a very simple XML document that mimics theentry object model. The default parser will only permit you to read/write XMLfiles two levels deep. It cannot read multi-valued Attributes, even if it has writtenthe file itself. See “Examples” on page 174 below for an example of how to readmulti-valued Attributes.

Note that certain methods, such as setAttribute are available in both the IBMDirectory Integrator entry and the objects returned by xmldom.createElement. Thesefunctions just happen to have the same name/signature. Do not confuse thexmldom objects with the IBM Directory Integrator objects.

Configurationclass com.ibm.di.parser.XMLParser

xmlRootTagThe root tag (output).

xmlEntryTagThe entry tag for entries (output).

xmlValueTagThe value tag for entry attributes (output).


isvalidatingIf checked, this parser requests a DTD/Schema validating parser.

isnamespaceawareIf checked, this parser requests a namespace-aware parser.


omitxmldeclarationIf checked, the XML declaration is omitted in the output stream.

ExamplesOverride add hook:var root = xmldom.getDocumentElement();var entry = xmldom.createElement ("entry");var names = work.getAttributeNames();

for ( i = 0; i < names.length; i++ ) {xmlNode = xmldom.createElement ("attribute");xmlNode.setAttribute ( "name", names[i] );xmlNode.appendChild ( xmldom.createTextNode ( work.getString(

names[i] ) ) );entry.appendChild ( xmlNode );}root.appendChild ( entry );

After Select Entries hook://// Set up variables for "override getnext" hook//

var root = xmldom.getDocumentElement();var list = system.selectNodeList ( root, "//Entry" );var counter = 0;

Override getnext hook//// Note that the iterator hooks are NOT called when we override the

getnext function// Initialization done in After Select Entries hook

var nxt = list.item ( counter );

if ( nxt != null ) {var ch = nxt.getFirstChild();while ( ch != null ) {

var child = ch.getFirstChild();while (child != null ) {

// Use the grandchild’s value if it exist, to be able toread multivalue attributes

grandchild = child.getFirstChild();if (grandchild != null)

nodeValue = grandchild.getNodeValue();else nodeValue = child.getNodeValue();

// Ignore strings containing newlines, they are just fillersif (nodeValue != null && nodeValue.indexOf(’\n’)

== -1) {work.addAttributeValue ( ch.getNodeName(), nodeValue );

}child = child.getNextSibling();

}ch = ch.getNextSibling();

}

result.setStatus (1); // Not end of input yetcounter++;

} else {result.setStatus (0); // Signal end of input

}


The previous example parses files containing entries which look like this:<DocRoot>

<Entry><firstName>John</firstName><lastName>Doe</lastName><title>Engineer</title>

</Entry><Entry>

<firstName>Al</firstName><lastName">Bundy</lastName><title">Shoe salesman</title>

</Entry></DocRoot>

Suppose instead that the input looks like this:<DocRoot>

<Entry><field name="firstName">John</field><field name="lastName">Doe</field><field name="title">Engineer</field>

</Entry><Entry>

<field name="firstName">Al</field><field name="lastName">Bundy</field><field name="title">Shoe salesman</field>

</Entry></DocRoot>

Here the attribute names can be retrieved from attributes of the ″field″ node, andwe would use this code in the Override Getnext Hook:var nxt = list.item ( counter );

if ( nxt != null ) {var ch = nxt.getFirstChild();while ( ch != null ) {if(String(ch.getNodeName()) == "field") {attrName = ch.getAttributes().item(0).getNodeValue();nodeValue = ch.getFirstChild().getNodeValue();work.addAttributeValue ( attrName, nodeValue );}ch = ch.getNextSibling();}

result.setStatus (1); // Not end of input yetcounter++;} else {result.setStatus (0); // Signal end of input}

This example package demonstrates how the base XMLParser functionality can beextended to read XML more than two levels deep, by using the ″Override getnext″and ″Override add″ hooks.

Notesv If you read big (greater than 4MB) or write big ( greater than 14MB) xml files,

your Java VM runs out of memory. Refer to the Appendix A, “FAQ IBMDirectory Integrator” on page 209 for a solution to this.

v The parser silently ignores empty entries.v Certain characters are illegal in XML-tags (such as $). These characters must be

avoided in your attribute names when using the XML parser as it might createillegal XML.



To access the example mentioned here, go to the root_directory/examples/xmlparserdirectory of your IBM Directory Integrator installation.

See also“SOAP parser” on page 171, “DSML parser” on page 162


Chapter 10. Script languages

IBM Directory Integrator supports variety of script languages. Some information isfound under Parsers, mostly what functions you must provide in order to make aParser. However, in order to use a script language, the IBM Directory Integratorinstalls the language (if it is present).

IBM Directory Integrator supports variety of script languages. Some information isfound under Parsers, mostly what functions you must provide in order to make aParser. However, in order to use a script language, the IBM Directory Integratormust install the language.

Only one script language can be used inside the AssemblyLine itself, but you canof course have any supported language within a Connector, but not in aComponent. When you set up your AssemblyLine, chose the script language andstick to it. Changing the script language will not change the existing code: Thisalso applies to code that IBM Directory Integrator writes for you, such as thesimple attribute mapping.

Internally in the IBM Directory Integrator product, Beans Scripting Framework(BSF) is used to plug in new script languages. BSF supports Windows ScriptingHosts (WSH), and some of the script languages are supported through WSH:Visual Basic and Perl are two examples. Of course, script languages supportedthrough WSH are only available on Windows platforms.

BSF-based script languagesJavaScript is the default language provided. There are no other specialrequirements. See “Comparing JavaScript strings” on page 32 for more information.

The included JavaScript interpreter is Rhino 1.5. Refer to the Appendix A, “FAQIBM Directory Integrator” on page 209 if you want to replace this with a newerversion.

WSH-based script languagesPerl

Visual Basic

BeanShellBeanShell has it’s home on http://www.beanshell.org/

It is not certified or included in the standard IBM Directory Integrator because wedo not have enough experience with it. However, we have received no feedbackindicating problems.

In order to use it with the IBM Directory Integrator you need to:1. Add the following snippet to your configuration file:


[properties scriptengines]beanshell:bsh.util.BeanShellBSFEngine[end]

2. Add bsh-1.2b1.jar to your IBM Directory Integrator jars directory

Note: Due to a bug, the [properties scriptengines] section must be inserted in theconfiguration file that the Admin tool reads when it starts up.

PerlScriptIn order to get a Perl parser to work, you need a version of PerlScript thatsupports Windows Scripting Host (WSH) engines. Only ActivePerl (that you canget for free from http://www.activestate.com/) has been verified. Also note thatWSH only works on NT/Windows 2000 platforms, so currently you cannot run aPerl parser from a Unix server.

Note: The reference to the free ActivePerl available athttp://www.activestate.com/ is provided as a convenience. IBM does notsupport code obtained from this site and is not responsible for the continuedavailability or any consequences of use of such code.

You have access to the standard Java objects from PerlScript, so the good news isthat the general documentation can be used. The Java object JavaObject is accessedas $JavaObject in PerlScript, and JavaObject.Method() through $JavaObject->Method()

For example, input in an iterator Connector is done though the inp object, so$_ = $inp->readLine();

will assign next line on the input stream to $_

Connector attributes are set/read by the (entry) attribute:$entry->setAttribute("Number", $number);

sets the self-chosen Connector attribute Number to the internal PerlScript scalar$number.

When writing a Parser, you typically must write the subroutines readEntry andwriteEntry : Those are the ones that will be called for input/output.

Example:

Here is how to create multiple values (″foo″ and ″bar″) in attributes (″Multi1″ and″Multi2″):

# Create an attribute called Multi1 (see “The Entry object” on page 183)$entry->setAttribute("Multi1", "foo");

# Add an other value to it (see “The Attribute object” on page 181)$attr = $entry->getAttribute("Multi1");$attr ->addValue("bar");

But there’s more than one way:

# Create an attribute called Multi2 (assuming it does not exist)$entry->addAttributeValue("Multi2", "foo");


# Add an other value to it$entry->addAttributeValue("Multi2", "bar");

Note: PerlScript is an ActiveX scripting engine that enables you to use Perl withany ActiveX scripting host. When you launch the ActivePerl installer,PerlScript is one of the components you can optionally install. You mustinstall, or have previously installed, ActivePerl to use PerlScript.

PerlScript exampleThese two procedures simply read/dump a whole line. A more advanced scriptwould of course manipulate the $_ object.

We assume a Connector attribute called Line and us writing the writeEntry andreadEntry necessary to write a parser (see “Script parser” on page 169).sub writeEntry{

$result = $entry->getString("Line");$out->write ( $result );

}

sub readEntry{$_ = $inp->readLine();$entry->setAttribute("Line", $_);

}


To access the example mentioned here, go to the root_directory/examples/perldirectory of your IBM Directory Integrator installation.

VB Script″Dim″ in VB has to be rewritten in VBScript (see following list) when dealing withsystem objects. Dimming variables is OK.

VBDim x as Excel.ApplicationSet x = CreateObject ("Excel.Application")

VBScriptSet x = CreateObject ("Excel.Application")

JavaScriptThere are certain issues you might want to look into when using JavaScript. Theseare:v “Comparing JavaScript strings” on page 32v “JavaScript string methods” on page 35v Java and JavaScript, “Java and JavaScript”

Java and JavaScriptIn JavaScript you can access Java objects. This is very useful, since all the IBMDirectory Integrator internal objects are Java objects.

Chapter 10. Script languages 179

However, there is a pitfall when some of the Java Objects have methods withnames that are a reserved words or operators in JavaScript . In these cases, theJavaScript interpreter will try to process the reserved word instead of calling theJava method.

Such an example can be found with the java.io.File class which has a deletemethod. delete is also a JavaScript operator, sovar myFile = java.io.File("file.txt"); myFile.delete();

fails. What you could do here is either to saymyFile[’delete’]();

which exploits the fact that you can access the Java methods as array elements. Or,in this special case,system.deleteFile("file.txt");

would actually do the trick as well, since the system library has a deleteFilemethod.


Chapter 11. Objects

These objects are fully documented in the enclosed JavaDocs in theroot_directory\docs\api directory of your installation. Check the JavaDocs for theavailable methods.

The AssemblyLine Connector objectThe AssemblyLine Connector object is a wrapper that provides additionalfunctionality to the Raw Connector. The Raw Connector can be accessed from theAssemblyLine Connector as the connector object.

The AssemblyLine Connector is the one calling the hook functions you define inthe AssemblyLine and also the one that performs the attribute mapping. EachAssemblyLine Connector in the AssemblyLine is given a name that isautomatically available in your scripts as that name. If you name a AssemblyLineConnector ″ldap″ it will also be used as the script object name. Make sure you nameyour Connectors in a way that is compatible with the selected scripting language.Typically, you should avoid using white-space and special characters.

The AssemblyLine Connector has methods and properties described in thecom.ibm.di.server.AssemblyLineComponent.

The Attribute objectAn attribute object is usually contained in Entry objects. An attribute is a namedobject with associated values. Each value in the attribute corresponds to a Javaobject of some type. Attribute names are case insensitive and can not contain slash(’/’) as part of it’s name. Remember that some of the Connectors, for example,those accessing a database, might consider other characters as unsuited. If you can,try to stick to alpha-numeric characters in attribute names.

If the Attribute was populated with Connector values by the attribute map, thevalues will be of the same data-type that the Connector supplied.

For more information, see the Javadocs material included in the installationpackage (the com.ibm.di.entry.Attribute class).

Examples

Creating a new Attribute objectvar attr = system.newAttribute("AttributeName");

This example will create an Attribute object with name ″AttributeName″ andassign it to the attr variable. Note that upon initial creation, the attribute holds novalue. Now, through the attr variable you can access and interact with the newlycreated attribute.

Adding values to an Attributeattr.addValue("value 1");attr.addValue("value 2");


This example adds the string values ″ value 1 ″ and ″ value 2 ″ to the attrAttribute, thereby creating a multiple values attribute. Consecutive calls toaddValue(obj) add values in the same order in the attribute.

Scanning Attribute’s valuesvar values = attr.getValues();for (i=0; i<values.length; i++) {

task.logmsg("Value " + i + " —> " + values[i]);}

This example will process any attribute object, whether it holds single or multiplevalues. In reality, there is no difference between single and multiple valueattributes. Every attribute may hold zero, one or more values - a single valueattribute is therefore merely an ″underloaded″ multiple values attribute.

See also“The Entry object” on page 183

The Raw Connector objectThe Raw Connector object is obtained either by loading a Raw Connector explicitly(system.loadConnector) or by retrieving the named AssemblyLineConnectors.connector (myConnector.connector). When writing scripts in anAssemblyLine, you will usually use the AssemblyLine Connector object that willgive you access to another set of methods.

The Raw Connector is fully described as Connector in the Javadocs. For moreinformation, see the Javadocs material included in the installation package(com.ibm.di.connector.Connector).

MethodsSome of the often-used methods include:

getNextEntry()Returns the next input entry.

putEntry ( entry )Add/Insert entry

modEntry ( entry, search )Modify entry identified by search with contents of entry.

deleteEntry ( entry, search )Deletes the entry identified by search.

findEntry ( search )Searches for an entry identified by search. If no entries were found a nullvalue is returned.

findEntry ( attribute, value )Performs a search using ″attribute equals value″ and returns the entryfound. If no or more than one entries were found a null value is returned.


The Entry objectThe entry object is used by AssemblyLines and EventHandlers. The entry object isa Java object that holds attributes and properties. Attributes in turn contain anynumber of values. Properties contain a single value. For more information, see theJavadocs material included in the installation package (com.ibm.di.entry.Entry).

For a complete list of available methods, including parameters and return values,see the Javadocs material included in the installation package.

Global Entry instances available in scriptingv conn - The local storage object in Connectors in an AssemblyLine. It only exists

during the Attribute Mapping phase of the Connector’s life. See “AttributeMapping” on page 44.

v work - The data container object of the AssemblyLine. It is therefore accessible inevery Connector from the AssemblyLine.

v event - The event object is the work Entry object when scripting insideEventHandlers, just like the conn object during Attribute Mapping.

v current - Available only in Connectors in Update and Delete mode. Stores theEntry that the Connector read from the data source to determine whether this isan Add or Modify operation.

v error - An Entry object is available in a Connector’s Hooks, but only in theHooks that have a name that ends with Fail. The error object holds error statusinformation in the following Attributes:

v status (java.lang.String) - ″ok″ if there is no exception thrown (in this case this isthe only error’s attribute); ″fail″ if an exception is thrown -then these attributesare also available:

v exception (java.lang.Exception) - the java.lang.Exception (or some its successorclass) object that is thrown

v class (java.lang.String) - the name of the exception class (java.lang.Exception orsome of its successors)

v message (java.lang.String) - the exception’s error messagev operation (java.lang.String) - Connector’s operation type (″addonly″,″update″, etc.)v connectorname (java.lang.String) - the name of the Connector whose Hook is

being called

See also“The Attribute object” on page 181

The FTP objectThe FTP object is available as a scriptable object. This object is useful when theFTP Client Connector does not provide the required functionality. See the fulldocumentation in the JavaDocs for com.ibm.di.protocols.FTPBean

Examplevar ftp = system.getFTP();

if ( ! ftp.connect ("ftpserver", "username","password") )

{task.logsmg ("Connect failed: " +ftp.getLastError());

Chapter 11. Objects 183

}

ftp.cd ("/home/user1");var list = ftp.dir();

while ( list.next() ){if (list.getType() == 1)task.logmsg ("Directory: " +list.getName());

elsetask.logmsg ("File: " + list.getName());

}

ftp.setBinary();ftp.get ("remotefile", "c:\\localfile");ftp.put ("c:\\localfile", "remotefile");

Main objectThe main object is the top level thread (see Interface RSInterface in the JavaDocs).This object has methods for manipulating AssemblyLine behavior. The mostcommon methods are:

void dump(entry)Dumps the contents of entry to the console

void logmsg (String msg)Writes a message to the system log file (see “IBM Directory Integratorcommand line options” on page 188 to server) as well as the console.

startAL ( name, initial-work-entry ), startAL ( name, runtime-provided-connector), startAL ( name, initial-work-entry, runtime-provided-connector ), startAL (name, java.util.Vector )

Start the AssemblyLine given by the name parameter. See also “TheAssemblyLine” on page 17.

The Search (criteria) objectThe search (criteria) object is used by AssemblyLines and Connectors to specify ageneric search criteria. See com.ibm.di.server.SearchCriteria in the JavaDocs. It isup to each Connector how to interpret and translate the search criteria into aConnector specific search. The search criteria is a very simple multi valued objectwhere each value specify an attribute, operand and a value.

OperandsThe following operands have been defined for use with the criteria objects.

= Equals

~ Contains

^ Starts with

$ Ends with

! Not equals

Examplefor ( i = 0; i < search.size(); i++ ) {var sc = search.getCriteria ( i );task.logmsg ( sc.name + sc.match + sc.value );}


The shellCommand objectThe shellCommand object contains the results from a command line execution.

On Microsoft Windows platforms, the shell command will start, but you will notbe able to get output/status from it. See com.ibm.di.function.ExecuteCommand foravailable methods.

For example:var cmd = system.shellCommand ("/bin/ls -l");if ( cmd.failed() ) {task.logmsg ( "Command failed: " + cmd.getError());} else {task.logmsg ( cmd.getOutputBuffer() );}

The status objectThe status object contains information about an AssemblyLine’s Connectors anderror codes. It is a synonym to task.getStats()

The system objectThe system object is available as a scriptable object in all scripting contexts andprovides a basic set of functions. The Java object itself is(com.ibm.di.function.UserFunctions), but linked to the Script object system (see“Accessing your own Java classes” on page 34). You can find a complete list of themethods by looking at the Javadocs.

The task objectThe task object is an instance of class that implements(com.ibm.di.server.TaskInterface) and represents the current thread of execution:v For AssemblyLines this is the AssemblyLine thread where you can access

AssemblyLine specific information and methods, see classcom.ibm.di.server.AssemblyLine.

v For EventHandler this is the EventHandler thread where you can accessEventHandler specific information and methods, see classcom.ibm.di.eventhandler.Switchboard.

Chapter 11. Objects 185

Chapter 12. Program interfaces

AssemblyLine setting tabWhen in the Admin tool, and after an AssemblyLine is opened, the Config tab letsyou configure some general settings for the AssemblyLine.

Load task parameters fromReads user defined name/value pairs from the specified file. For example,var savedValue = task.getParam("my property name");

Note that if you edit this file by hand, use only lower case letters for theparameter names.

Save task parameters toWrites user defined name/value pairs to the specified file when theAssemblyLine terminates. For example,task.setParam ("my property name", "bangalore");

Note that if you edit this file by hand, use only lower case letters for theparameter names.

Log statistics intervalCauses the AssemblyLine to issue a statement of how many entries havebeen read and processed so far. ( e.g. at every nth entry issue this logmessage ).

Max number of reads (Iterator)Causes the AssemblyLine to terminate after having processed this numberof entries. Useful when testing AssemblyLines. Entries are only countedjust before the Iterator Connector reaches the On Success hook, so anunsuccessful read will not contribute to the count. This can be useful asyou can use system.skipEntry() in the attribute map to read only the Maxnumber of reads first ’interesting’ entries.

Max number of errorsCauses the AssemblyLine to terminate after this number of errors haveoccurred.

Max duplicate entries returnedThis parameter is passed on to the Connectors in the AssemblyLine. Thisnumber rules how many entries are collected by a Connector whenmultiple entries are found. This number is relevant only for Connectorsworking in Update or Lookup mode.

Note: This value is the total number of entries returned, so limiting thisparameter to one might cause unexpected results for Delete andUpdate operations. This is due to the fact that if the Connector isunable to single out a single entry, then the results of the Delete orUpdate might result in multiple entries being deleted/updated, ornone at all (depending on the functionality of the data source). Ifyou limit the Max duplicate parameter to a value of 1 then youcannot detect these situations in your solution.

Script LanguageThe AssemblyLine’s script language. You may choose among several


languages, but you may choose only one language for all theAssemblyLine scripting, that is the code used in Prolog, Epilog, Hooks andAttribute Maps. This does not affect the language used for a scriptedConnector or a parser written in a script language.

Include All Global PrologsCheck to automatically include all scripts from the script library that hasthe same language as this AssemblyLine and also has the Auto Include flagset for it.

Include additional PrologsHere you can specify additional scripts from the script library not included(ie. scripts that do not have the auto-include flag set etc....)

Automatically map all attributesIf checked then all Connectors with empty attribute maps willautomatically map all available attributes to/from the work entry. Todefine this behavior for specific Connectors only add a single entry in theattribute map and name the attribute * (star).

Detailed LogIf checked, you will get additional log messages (debug).

Null Value BehaviorSets default Null Value Behavior for the AssemblyLine (see “Null ValueBehavior” on page 44). Defaults to Null Value Behavior for theConfiguration file. Values are:v Default Behavior tells IBM Directory Integrator to use the behavior as

described in “Preferences (Java properties)” on page 191,rsadmin.attribute.nullBehavior.

v Empty String means that the Attribute is returned with an empty stringvalue.

v Null means the Attribute is returned with no value (null value).v Delete means that the Attribute is removed during mapping.v Value lets you set a value to be returned each time this Attribute is

missing.

Null ValueEnables you to specify the value to be returned for missing Attributesduring AttributeMapping.

Note: This parameter is only valid if Null Value Behavior is set to Value.

IBM Directory Integrator command line optionsCommand line options must have their value followed immediately after theoption. Do not use a space between the option and the value.

IBM Directory Integrator Admin toolibmditk [filename]

filenameYou can have 0 or more filenames that contain legal configuration files.

IBM Directory Integrator serverThe following are command line options for the IBM Directory Integrator servertool (ibmdisrv [options]):


Example: ibmdisrv -c"C:\demos\rs.xml" -r"Access2LDAP"-l"c:\metamerge\mydemo.log"

Note: There is no space between the option letter and the value. Use quotes tosave against possible spaces or commas in the values.

-c Configuration file

-l Log file (default console output). Does very little as few messages go to theconsole. To change the logfile for most of the logging, changelog4j.properties.

-D Flag to disable startup of EventHandlers

-r List of AssemblyLine names to start. To start AssemblyLine a and b, usethe command -r a b. Other syntaxes are supported as well: -ra,b; -ra -rb.

-w If -r (or -t) is specified then this flag will cause IBM Directory Integrator towait for each AssemblyLine’s EventHandlers completion before starting thenext. If this flag is not specified then IBM Directory Integrator will start allAssemblyLines specified by the -r parameter in parallel. When the lastAssemblyLine and explicitly started EventHandler has finished, the serverstops.

Note: The server dies when it has no active threads. However, we haveexperienced that with Perl, the Perl task is counted as an activethread. Use -w to force IBM Directory Integrator to die after the lastAssemblyLine has finished.

-v Show version information and exit. This is logged in the logfile.

-P Password if configuration file is encrypted

-p Dump java properties on startup. Remember that you still have to providea configuration file, which is read before java properties are dumped.

-t List of EventHandler names to start. To start EventHandler a and b, usethe command -t a b. Other syntaxes are supported as well: -ta,b; -ta -tb.

-m Start the Administration and Monitor Console (AMC) server. Also start theMOBJ interface. See Appendix C, “Administration and Monitor Console”on page 215 for more information about AMC.

When IBM Directory Integrator terminates it returns an exit code which is one ofthe following:

0 User started IBM Directory Integrator with ″-v″ parameter (show info andexit)

1

v Could not open logfile (-l parameter)v Could not open config filev Terminated by admin request

2 Exit after auto-run. When you start IBM Directory Integrator specifying -wIBM Directory Integrator will run the AssemblyLines specified by the -rparameter and then exit.

9 License expired/invalid

Chapter 12. Program interfaces 189

Discover schemas and browsing dataA given connector’s panel always contains a Schema tab.

The Schema tab shows you a List Control where you can create the data sourceschema by hand, or have the Connector discover it for you.

The buttons at the top of this list provide you access to the following functions:

Add new attribute to the schemaAdds a new attribute to the schema.

Remove an attributeRemoves an attribute from the schema.

Connect to the data sourceConnects to the data source.

Read the next entry from the sourceThis button reads the next entry and populates the list with the attributesfound in that object.

Note: This does not erase previously listed attributes. To do this, you mustselect those attributes and click the Remove an attribute button(shown previous).

Close the connectionCloses the connection.

Query schema of the source (and of the entry currently selected)This function might not be supported by all data sources. If that happens,then the only option is to Connect and use the Next button.

In addition, you can edit directly into some of the columns of this grid list. Schemalist fields have the following meanings:

Name This is the name of the Attribute that appears in the conn object (localstorage object for the Connector’s Data Source Adaptor) when this data isread. It is also the name the Connector uses during write operations.

Java classThis is the type of Java object that IBM Directory Integrator represents thisAttribute as. This field is read-only and only informative in version 5.1.1.

Native syntaxThis column specifies the data source-specific type of this Attribute. Thisfield is read-only and only informative in version 5.1.1.

SampleHere you see an example value for this Attribute.

ExcludeIf this box is enabled, then this instructs the Connector to exclude thisAttribute from read operations (GetNext, Lookup, and so forth). Thisparameter enables you to optimize read operations from a data source byexcluding Attributes that might contain large amounts of data, or a greatnumber of values.

Note: This functionality might not be supported by all Connectors or datasources.


Input ReqdCheck this box if this Attribute is required in from the data source. If aread operation (GetNext, Lookup, and so forth) does not find thisAttribute, then it results in an error. Note that “Null Value Behavior” onpage 44 kicks in after Attribute mapping, so if a required attribute is notprovided by the raw connector, then an error is signalled and you end upin the error hook.

Note: Input Reqd is used with the input modes iterator and lookup only.

Output ReqdCheck this box if this Attribute is required for output to data sourceschema, and must be present in the conn object during a write operation. Ifnot, then this results in an error. On output, the null-value-behavior mayensure a non-null-value since the null-value-behavior is executed beforethe schema is checked.

Note: Output Reqd is used with output modes only, for example, addonly,AddOnly.

Parameter labels on the Connector/parser tabs.If you leave the cursor on the label a little while, a tooltip pops up, showing somehelp.

Green label text indicates that the value of this parameter has been inherited.When you override an inherited parameter, the text label turns black.

Blue label text indicates that the value is a parameter.

If you click on the label, you get some information about the parameter, includingthe internal name of the parameter. This can be useful when you want to setconnector parameters through scripting. Moreover, you have access to adrop-down box where you can select a parameter.

Preferences (Java properties)Your user preferences (for the GUI) are stored in the .ibmdi file that you find inyour home directory. This file is created for you the first time you start ibmditk. Itdefines the following field:

window.*The look of your dialog boxes, for example size, position, where the splitis, and so forth.

This dialog box is available through File–>Edit Preferences. It contains optionsthat will be valid for the current configuration file (some of these are “Javaproperties” on page 192). The internal name as well as some help can be found byclicking on the label.


Java propertiesThe Java Properties is a section of the configuration file where you specify a list ofproperties and their associated values. The properties are added to the Javaruntime properties so you may change/add Java specific or other thirdparty-specific properties here. Also, you will find IBM Directory Integrator-specificproperties that fine tune the way IBM Directory Integrator server and Admin toolbehaves.

These values are part of your configuration file and might be different from file tofile. You can not include these values: If you want these global for yourinstallation, you can set them in the “global.properties file” on page 55. Someproperties can also be found under File–>Edit Preferences: Click on the labels tosee their java property equivalent (these are saved in your .ibmdi file).

Some of these values need restarting of the Admin tool to take effect.

The java properties that customize the Admin tool and the server are usuallyfound in one of three places:v The .ibmdi file for GUI configuration as seen in File–>Edit Preferences.v The configuration file, under the section Java Properties (valid for the

configuration file).v The global.properties file, for installation general properties.

com.ibm.di.server.maxThreadsRunningIf this is set, it limits the number of threads that will be allowed to runsimultaneously. In order to prevent deadlocks new threads will be startedafter the max number is reached, but very slowly.

mail.smtp.hostSTRING: This should be the SMTP server to use if you use the″system.sendmail″ function.

rsadmin.attribute.nullBehaviorSTRING: If a connector does not get an attribute value from the underlyingdata source (for example no telephone number), there is ambiguity onwhat the AssemblyLine should provide. Legal values are ″Empty String″,″Null″, ″Delete″ or ″Value″. See “Null Value Behavior” on page 44 for themeaning of these values.

rsadmin.attribute.nullBehaviorValueSTRING: If rsadmin.attribute.nullBehavior is set to Value, this is the value.

rsadmin.encryptionBOOLEAN: Specify ″true″ if you want your configuration file to beencrypted. You are prompted for a password when you open/save theconfiguration file.

Please note that IBM Directory Integrator has no way of unlocking apassword protected configuration file. If you forget your password thenthe file is probably lost. The configuration file is encrypted using DES.

External PropertiesExternal Properties is a feature that enables you to store sensitive informationoutside your Config in a secure format, but still keep it configurable.


Think of External Properties as global system variables that can be usedthroughout your solution. Of course you can access External Properties from yourscripts, enabling you to make your code data-driven, changing its functionalitybased on the value of one or more of these properties. However, the most powerfuluse of External Properties is as parameter values in the configuration ofcomponents, like Connectors, Parsers and EventHandlers.

Setting Up External PropertiesThe first thing you must do is to define where your External Properties are stored,as well as whether or not you want to encrypt this information.

This is done by clicking the Edit External Properties Settings button in the toolbarat the top of the Details Pane.

Here you set the External Properties file name, which then appears in the ExternalProperties list, in the same way as any properties that you create. The specificationof the properties file becomes an External Properties called user.properties:user.properties <file path: e.g. C:\IBMDirectoryIntegrator\myProps.properties>

This item can be edited like any other by selecting the grid field and pressing F2,or simply double-clicking in the field to edit.

Managing External PropertiesAdding and removing External Properties is done using the toolbar in the title areaof the Details Pane. Of particular interest is the Save button, which commits thechanges you have made to the properties file that you specified.

Note: When you edit External Properties, this information is still stored in memoryuntil you save it to file. If you have made changes, and then start anAssemblyLine or EventHandler that uses any of these values, the changesyou have made are not available to the server. In order to make sure thatyou are testing your solution with the desired External Property values,please remember to save them periodically.

Using External PropertiesGo to the External Properties section in the main config tree.

If you take a look at the Config tab of a component and then click on a parameter,you get a Parameter Info dialog.

Here are a number of fields that you can work with:

Name This is the name of the parameter which you can refer to directly in yourscripts for configuring this component at runtime.myConnector.connector.setParam("fileAwaitDataTimeout", "3");

Is InheritedThis checkbox tells you if this parameter is being inherited from the BaseInherit parent. If you enter a value directly into the Config tab parameter,then you override the inherited value. You can reinstate inheritance of thisparameter by simply opening this dialog and checking the Is Inherited boxagain.

External PropertyHere is where you use External Properties.


Note: The External Property field is a drop-down. If you click on this fieldthen you are presented with the list of registered External Properties.If you select one of these values then IBM Directory Integrator usesthis properties value for the parameter.

Original ValueThis is the original (inherited) value of this parameter, and is displayed forreference in case you want to turn on inheritance of the parameter again.

Info This is a short description of the parameter.


Chapter 13. Examples

VBScript Connector and Microsoft Outlook Contacts ConnectorThis example shows how you can manipulate your Outlook Contacts usingVBScript. This example is also available as the IBM Directory Integrator MicrosoftOutlook Contacts Connector.

Example codeRefer to the code under the Script tab of the Microsoft Outlook Contacts Connectorthat is delivered with your IBM Directory Integrator, as this is an old example butit gives you an idea of what is in the Connector.’’ This script implements all the necessary functions for accessing’ the Contacts register in Microsoft Outlook Contacts Connector.’ Assumes that the number of entries in contact folder is constant

for the run

set ol = CreateObject ("Outlook.Application")set ns = ol.GetNameSpace ("MAPI")set contacts = ns.getDefaultFolder (10)

counter = 0

sub selectEntries()counter = 0end sub

sub getNextEntry ()’ Increase current positioncounter = counter + 1

if (counter > contacts.Items.count) then’End of itemsresult.setStatus 0result.setMessage "End of input"elseif (contacts.Items.Item(counter).Class = 40) then’ 40 is contacts itempopulateEntry entry, contacts.Items.Item(counter)else’ skipping non contact elementsgetNextEntryend ifend sub

sub modEntry ()flt = "[" & search.getFirstCriteriaName() & "] =’" & search.getFirstCriteriaValue() & "’"set item = contacts.Items.Find ( flt )if item is nothing thenresult.setStatus 2result.setMessage "Not found"exit subend if

populateItem entry, itemitem.Saveend sub

sub deleteEntry ()


flt = "[" & search.getFirstCriteriaName() & "] =’" & search.getFirstCriteriaValue() & "’"set item = contacts.Items.Find ( flt )if item is nothing thenresult.setStatus 2result.setMessage "Not found"exit subend if

item.Deleteend sub

sub findEntry ()flt = "[" & search.getFirstCriteriaName() & "] =’" & search.getFirstCriteriaValue() & "’"set item = contacts.Items.Find ( flt )if item is nothing thenresult.setStatus 2result.setMessage "Not found" + "\n --->["& flt & "]"elsepopulateEntry entry, itemend ifend sub

sub putEntry ()

set item = contacts.Items.Addif item is nothing thenresult.setStatus 2result.setMessage "Unabled to create olContacts(2) item"exit subend ifpopulateItem entry, itemitem.Saveend sub

sub populateEntry (entry, item)

entry.setAttribute "FullName", item.FullNameentry.setAttribute "Email1Address", item.Email1Addressentry.setAttribute "Categories", item.Categoriesentry.setAttribute "Birthday", item.Birthdayentry.setAttribute "LastModificationTime", item.LastModificationTime

entry.setAttribute "BusinessAddress", item.BusinessAddressentry.setAttribute "BusinessTelephoneNumber",

item.BusinessTelephoneNumberentry.setAttribute "BusinessFaxNumber", item.BusinessFaxNumber

entry.setAttribute "HomeAddress", item.HomeAddressentry.setAttribute "HomeTelephoneNumber", item.HomeTelephoneNumberentry.setAttribute "HomeFaxNumber", item.HomeFaxNumber

entry.setAttribute "MobileTelephoneNumber",item.MobileTelephoneNumber

entry.setAttribute "JobTitle", item.JobTitleend sub

sub populateItem (entry, item)item.FullName = entry.getString("FullName")item.FileAs = entry.getString("FullName")item.Email1Address = entry.getString("Email1Address")

’ item.Categories = entry.getString("Categories")’ item.Birthday = entry.getString("Birthday")

’ item.BusinessAddress = entry.getString("BusinessAddress")


’ item.BusinessTelephoneNumber =entry.getString("BusinessTelephoneNumber")

’ item.BusinessFaxNumber = entry.getString("BusinessFaxNumber")

’ item.HomeAddress = entry.getString("HomeAddress")’ item.HomeTelephoneNumber = entry.getString("HomeTelephoneNumber")’ item.HomeFaxNumber = entry.getString("HomeFaxNumber")

’ item.MobileTelephoneNumber =entry.getString("MobileTelephoneNumber")

’ item.JobTitle = entry.getString("JobTitle")end sub

See also“Script Connector” on page 128

JavaScript ConnectorThis example shows how to write a Connector using a script language. Theexample uses JavaScript and shows the objects available and how they are used.

Example code//// Place intialiazation code before function declarations.//var counter = 0;

function selectEntries(){}

function getNextEntry (){if (counter > 100) {result.setStatus (1);result.setMessage ("End of input");return;}

entry.setAttribute ("counter", counter);counter++;}

function modEntry (){}

function deleteEntry (){}

function findEntry (){}

function putEntry (){}

See also“Script Connector” on page 128

Chapter 13. Examples 197

JavaScript parserThis example shows how to write a parser using a script language. The exampleuses JavaScript and shows the objects available and how they are used.

Example code//// This is a simple parser that returns one line at a time from// the input stream.//

var counter = 0;

function writeEntry (){var names = entry.getAttributeNames();for (i = 0; i < names.length; i++) {out.write (name[i], entry.getString(name[i]));out.write (13);out.write (10);}}

function readEntry (){var str = inp.readLine();

if (str == null) {result.setStatus (0);result.setMessage ("End of input");return;}

counter++;

entry.setAttribute ("line", str);result.setStatus (1);}

See also“Script parser” on page 169

Writing a new Raw ConnectorThere are generally two ways of writing new Connectors. The first way is to writea script that implements a set of functions using your favorite scripting language.The second way is to write the Raw Connector using Java.

Script-based ConnectorRead the documentation for the “Script Connector” on page 128 and also take alook at “VBScript Connector and Microsoft Outlook Contacts Connector” onpage 195. Both will give you the necessary information to roll your own Connector.

Java-based ConnectorLearning by example is probably the best way to learn new things. Here,knowledge to the Java programming language is really useful. The source code forthe OldHTTP Client Connector is included in the examples/OldHTTPConnectordirectory. It should give you a firm understanding as to how the Java-basedConnectors are implemented. The example extends the class


com.ibm.di.connector.Connector that gives you access to many of the methods youneed (go to the JavaDocs to see these documented).

Also note that the HTTP Client Connector is the preferred Connector, we here usethe Old HTTP Client Connector because it is a better example.

Building and installing a Java-based ConnectorRemember that the IBM Directory Integrator wraps the AssemblyLine Connectoraround your Raw Connector, so you only need to write the Raw Connector.

A comment about Java librariesIf you use the same libraries as the IBM Directory Integrator (see “Distributioncomponents” on page 53), make sure that you use the same version that IBMDirectory Integrator does. If not, you can run into compatibility problems becausethe loader gets confused.

Follow these steps to get your Raw Connector built and activated. The buildinstructions assumes you have installed the Java2 SDK and that those binaries arein your PATH.1. In order to compile your code you must include ibmdisrv.jar from the IBM

Directory Integrator distribution in your classpath. Of course, you need toinclude other jars as needed, the Old HTTP Client Connector referred to aboveneeds the mailapi.jar.javac -classpath ’IBMDirectoryIntegrator/jars/miserver.jar;IBMDirectoryIntegrator/jars/mailapi.jar’ com\myname\OldHTTPClient.java

This is the Windows Command when IBM Directory Integrator was installed inthe IBM Directory Integrator Home directory. UNIX uses ’:’ instead of ’;’ asseparator.

2. Make a file named idi.inf with the following content:[connectors MyConnector]

connectorConfig {connectorType:com.myname.OldHTTPCLient

}description:My OldHTTPCLient

[end]

[form com.myname.OldHTTPCLient]title:The title

parameterlist [myparam1myparam2]

parameter {myparam1 {label:URLsyntax:stringdefault:http://localhost}

myparam2 {label:Portsyntax:droplistvalues [808080]


default:80}}[end]

The connectors section of this file tells the Admin tool that this is a connector,and also gives both the name this connector is known under in the Admin toolMyConnector, and the java class name com.myname.OldHTTPCLient.

The form section tells the Admin tool which parameters your connector needs.The parameter list section lists the order in which the parameters are presented.The parameter section contains a subsection for each parameter and has thefollowing keywords:

label The text shown in the form

defaultThe default value for the parameter

descriptionDescriptive text for the parameter. This text will appear when the userhovers over the label

syntax

string One line text

textareaMulti line text

droplistDrop-down list with values

dropeditDrop-down list with value and edit box for user defined value

booleanCheck box using ″true″ or ″false″ as value

passwordAllows a password to be input

static Text that cannot be changed

script A special function to use in the Admin tool when the user selects thisparameter. The only interesting value is selectFile, which allows theuser to browse through the filesystem and select a filepath.

scriptlabelThe label on the button which evokes the optional script

3. Add your idi.inf and class files to a jar file (myconnector.jar)jar cvf myconnector.jar idi.inf com\myname\OldHTTPCLient.class

4. Copy the jar file to a suitable directory, such as root_directory/jars/myjars . Ithas to be in a subdirectory of root_directory/jars, it should not use the systemdirectories connectors/, eventhandlers/ or parsers/.

5. Your connector is now available as MyConnector.

Copying directories with the LDAP ConnectorUsually, the best way to do this is to export using LDIF from one server, and thenimporting it to the other. However, if you want to do this using IBM DirectoryIntegrator in order to get some more control, read on.


You could do the copying by having a very simple AssemblyLine containing twoConnectors:1. An Iterator Connector (reading the source directory) using a one level scope2. An Addonly Connector (updating the target directory)

Naturally a recursion must be introduced to copy the entire tree. We will start thesame AssemblyLine over and over, but the search base would be set to whateverDN has just been inserted in the target directory:for all entries returned in current leveladd entry in target systemif (success)start same AssemblyLine with search base level set to current’s entry DN

The starting of AssemblyLines can be made parallel to make the processing faster.Of course the number of threads could explode but it is possible to control it.Because the Admin tool sets the -w parameter you will have to start IBM DirectoryIntegrator from the command line

ibmdisrv -rDumpDir -cDumpDirectory.cfg

The code customizing is done in the following:v the AddOnly Connector (on_success hook:It starts a new AssemblyLine with an

initial entry that the Prolog will pick up )v in the AssemblyLine Prolog (Before Connectors Initialized).


Chapter 14. Logging and debugging

AssemblyLine DebuggerThe AssemblyLine debugger is a simple debugger that allows you to suspendAssemblyLine processing and show values of various variables and objects in adebugger console.

The debugger is started by using the Run Debugger button in the AssemblyLinefrom the IBM Directory Integrator Admin tool.

By adding watch variables to the Watch List (use the add button), the Admin toolwill display the value of the variables at all enabled break points. You can watchvariables available within the script engine, or more generally run small scripts.Examples of variables you might want to watch is work (the work entry). A scriptcould be work.getAttribute("myItem") or task.dump(conn). This is a good way towatch the contents of internal variables and know where they are defined and not.

The Evaluate button lets you write expressions and check their value: Evaluatingwork gives you the content of the work entry, if it exists. Evaluating 1+1 gives you2. Regard the watch-list as an auto-evaluate.

Breakpoints can be set in hooks, by enabling the Debug Break check box. However,the AssemblyLine will not break on hooks without code. If a breakpoint is enabledin the Admin tool, the debug-window will show you what hook you are in whenit breaks. This is not the case for script-enabled break-points (see the following).

The calltask.debugBreak ( "message" );

forces breaks, writing out ″message″, whiletask.debugMsg ( "message" );

simply outputs a message.

These methods are only evaluated when the debug-process is run. See theJavaDocs for more debug-methods.


To access the example mentioned here, go to theroot_directory/examples/debugging directory of your IBM Directory Integratorinstallation.

Logging and debuggingIBM Directory Integrator relies on log4j as a logging engine. It is a very flexibleframework that lets you log to file, eventlog, syslog and can be tuned so it suitsmost needs.


The log scheme for the server (ibmdisrv) is described by the file log4j.properties,while the console window you get when running from the Admin tool (ibmditk) isgoverned by the parameters set in executetask.properties (see “log4j defaultparameters” on page 205).

In addition to the IBM Directory Integrator built-in logging, you can log by addingscript code in your AssemblyLine. This page describes this part of the loggingprocess.

Logging and debugging is mainly done through the Task object.

LoggingKey data is logged from the IBM Directory Integrator engine, from its components(Connectors, parsers, etc.) as well as from user’s scripts. Note that almost everyConnector has a parameter called ″Debug Mode″ - it can be used to turn on andoff the Connector’s output to the log file. Dumping to the log file is done throughthe task object. Dumping to the console (the console window associated withAssemblyLine execution) and the system log (see “IBM Directory Integratorcommand line options” on page 188) is done through the main object. Below aresome examples of what the user can dump and example code in JavaScript thatperforms these operations. All examples show how to dump to the log file usingthe logmsg method. However all you have to do in order to dump to the consolewindow is to change the task keyword to main .


To access the example mentioned here, go to the root_directory/examples/loggingdirectory of your IBM Directory Integrator installation.

Dumping the content of an Entry objecttask.dumpEntry(entry)

dumps the entry to the logfile.

Dumping the content of an Attribute

Dumping single value AttributeSuppose an attr (with name Attr1) is the single value attribute you wish to dump.You can create your own attribute and set a value to it with the following 2 linesof code:var attr = system.newAttribute("Attr1");attr.addValue("Value1");

- the dumping itself:task.logmsg("Dumping single value attribute:" + attr.getName());task.logmsg("Value = " + attr.getValue());

Dumping multiple values AttributeSuppose attr (with name Attr1) is multiple values attribute you wish to dump. Youcan create your own attribute and set some values to it with the following 3 linesof code:var attr = system.newAttribute("Attr1");attr.addValue("Value1");attr.addValue("Value2");


- the dumping itself:var values = attr.getValues();

task.logmsg ("Dumping multiple values Attribute:" + attr.getName());for (i=0; i<values.length; i++){task.logmsg("Value " + i + " —> " + values[i]);}

If you don’t know a priory whether the attribute is single or multiple values youcan use the multiple values pattern (works even when your attribute is singlevalue).

Dumping the state of a ConnectorYou can at any time, dump the state of any of the Connectors involved in yourintegration process. The following example code gives you all the informationavailable for a particular Connector - Conn. Of course, according to your needs youcan dump arbitrary subset of the Connector’s parameters listed below.var status = Conn.getStats();task.logmsg("Dumping Conn status:");

task.logmsg("Number of add operations performed: " + status.numAdd());task.logmsg("Number of delete operations performed: " +status.numDelete());task.logmsg("Number of errors: " + status.numErrors());task.logmsg("Number of get operations performed: " + status.numGet());task.logmsg("Number of entries ignored: " + status.numIgnored());task.logmsg("Number of lookup operations performed: " +status.numLookup());task.logmsg("Number of modify operations performed: " +status.numModify());task.logmsg("Number of no-change entries: " + status.numNoChange());task.logmsg("Number of entries skipped: " + status.numSkipped());

Dumping arbitrary log messagesWe won’t surprise you telling you that with the logmsg function you can log anytext you want. This means you can indicate to the log file or to the console anystate of the custom logic of your AssemblyLines.

task.logmsg(″Type here the message you want to dump″);

Debugging a Script Connector (or other object) where the taskobject is unavailable

Assuming JavaScript, the task object can be fetched by:task = java.lang.Thread.currentThread()

main can always be be accessed through:main = connector.getRSInterface()

log4j default parametersThese are some of the parameters you will find in the files log4j.properties (foribmdisrv and ibmditk) and executetask.properties (for the Execute Task windowthat you seen in the Admin tool when you run an AssemblyLine).

Full documentation can be found athttp://jakarta.apache.org/log4j/docs/manual.html. Consider this a hint-sheet.

Chapter 14. Logging and debugging 205

log4j.rootCategory= DEBUG, DefaultDEBUG is the loglevel for the named Appender (log4j term called Default).If you set this to OFF or level above INFO you will not get ouput fromyour script logmessages (see following):

log4j.appender.DefaultDefines what type of Appender the named appender Default is. It can be:v FileAppender (log to file)v ConsoleAppender (log to console)v nt.NTEventLogAppender (log to NT EventLog)v net.SyslogAppender (Unix Syslog)

log4j.appender.Default.fileDefault log file for FileAppender, relative to your installation directory(default ibmdi.log)

log4j.logger.com.ibm.di.*Log level of various IBM Directory Integrator components. Note that forexample ibmditk show the log level of the AdminTool itself (not theprocesses you are running inside it). Do not change these.

Log LevelsLog levels can be ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF. ALL logseverything, and further on the list the more messages are filtered: Nothing islogged on OFF.

Note that the IBM Directory Integrator logmsg calls log on INFO level. This meansthat setting loglevel to WARN or lower will silence your logmsg as well as allDetailed Log settings.

Creating your own log strategiesYou can use this framework to differentiate how the different AssemblyLines andEventHandler log.

The following section defines a log scheme called CONSOLE, and that can later beused by specific AssemblyLines or EventHandlers:log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppenderlog4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayoutlog4j.appender.CONSOLE.layout.ConversionPattern=%d [%t] %-5p - %m%n0

Now in order to have the AssemblyLines and EventHandler myAL and myEH,you will need the lines:log4j.logger.AssemblyLine.myAL=INFO, CONSOLElog4j.logger.EventHandler.myEH=INFO, CONSOLE

Refer to the full log4j documentation for description of the ConversionPatternparameters. Here are some parameters:

%d Date/time depending on format.

%p Priority.

%c Category.

Note: this is typically in the form Type.alName.xxx. Type can beEventHandler or AssemblyLine, alName is the name of the


AssemblyLine (or EventHandler as name by the creator), and xxx isa unique ID for the thread. %c{2} outputs alName.

%m Message.

%n Newline.

%t Threadname.

Chapter 14. Logging and debugging 207

Appendix A. FAQ IBM Directory Integrator

Questions

Writing AssemblyLinesv I need the file my AssemblyLine creates before the AssemblyLine has finished,

but it is empty or incomplete. I also need to change the output filename whilethe AssemblyLine is processing.

Limitationsv I run out of memory, but have more available. Can anything be done?v Does IBM Directory Integrator support double bytes character sets?

Answers

Writing AssemblyLines

I need the file my AssemblyLine creates before theAssemblyLine has finished, but it is empty or incomplete. I alsoneed to change the output filename while the AssemblyLine isprocessing.Files are closed only when the AssemblyLine terminates. However, you can force aConnector to close and reinitialise. The snippet of code below creates a new fileeach time it is executed. The filenames are file1.xml, file2.xml and so forth(assuming the variable iteration was initialised to 0).iteration++;// close the file associated with the Connector named xmlxml.connector.terminate();// Associate a new filename to the Connector parameter filePathxml.connector.setParam("filePath","c:/tmp/file" + iteration + ".xml");// reinitialise the Connectorxml.connector.initialize(null);

This code can be put wherever you want, even within the Connector itself.

If you have opened the AddOnly Connector in append mode, the setParam() is notnecessary, but for output mode the sequence terminate() and initialize() can makeyou lose previous work.

Limitations

I run out of memory, but have more available. Can something bedone?

Increasing the memory available to the Virtual Machine: Do the following toincrease the heap size in IBM Directory Integrator:v For Windows platforms: Edit ibmditk.bat and ibmdisrv.bat in the IBM Directory

Integrator install directory to add -Xms254000000 -Xmx1024000000 after -cp%MYCLASSPATH% in the last line of the file.

Note: Xms is the initial heap size, Xmx is the maximum heapsize.


v For Unix platform: Edit ibmditk and ibmdisrv in the IBM Directory Integratorinstall directory to add -Xms254000000 -Xmx1024000000 after -cp %MYCLASSPATH%in the last line of the file.

Note: If you use the IBM Java VM 1.3.1, it will default -set Xmx (max heap size)to half your total available memory (unless you have less than 128Mavailable).

Limiting the number of threads: When using certain EventHandlers (like TCP orHTTP), or when your AssemblyLines start firing up other AssemblyLines whichagain can start other, you might use a lot of memory. See “How to control thenumber of threads” on page 46 for more information.

Does IBM Directory Integrator support double bytes charactersets?IBM Directory Integrator is written in Java which in turn supports Unicode(double bytes) characters sets. However, external components like drivers mightnot support the set.

Scripting languages supported by WSH (Windows Scripting Host) will probablycause problems when using Unicode character sets.


Appendix B. Dictionary of terms

LDAP termsDistinguished Name (DN)

In LDAP terms the fully qualified name of an object in the directory. It isusually written in a format known as the User Friendly Name (UFN). Thename is a sequence of (RDNs) separated by a single comma(,).

Relative Distinguished Name (RDN)In LDAP terms the name of an object that is unique relative to it’s siblings.RDNs have the form <attribute name>=<attribute value>.cn=John Doe

IBM Directory Integrator termsAccumulator

A special object in the Task Call Block that lets you accumulate data from acalled AssemblyLine and return it in one chunk. See “AssemblyLineparameter passing” on page 19.

Admin tool (ibmditk or ibmditk.bat)The IBM Directory Integrator server (ibmdisrv or ibmdisrv.bat) consists ofscripts to run a Java engine on a configuration file that defines the IBMDirectory Integrator server. The configuration file is an xml-format. TheAdmin Tool is used to edit this configuration file in order to define aserver.

AL Shorthand for AssemblyLine

AssemblyLineThe basic work object within a Server (see page 213). It consist ofConnectors, Parsers and business logic. Connectors typically feed data inand out of the AssemblyLine.

AttributeContained in Entries (see page 212) and holding Values (single ormultiple). See also Task Parameters.

Attribute MappingMapping of Attributes from the data source to the AssemblyLine. To bemore precise this is mapping from the raw connector attributes to the workentry. Attribute mapping is done either in the Input Map tab or the OutputMap tab (depends of the mode of the Connector)

ComponentsThe IBM Directory Integrator consists of a kernel being the Server (seepage 213) and the (AdminTool). In addition, we talk about componentssuch as Connectors, EventHandlers and Parsers. These can, to a certainextent, be distributed and upgraded independent of the kernel.

Computed ChangesA special feature of the Update (see page213) and Connector (see page 211)mode.

ConnectorA plug-in into your data source in order to read it. Inside the


AssemblyLine we differ between the Raw Connector object (see “The RawConnector object” on page 182 ) (class name Connector) and theAssemblyLine Connector object (see “The AssemblyLine Connector object”on page 181) (class name com.ibm.di.server.AssemblyLineComponent), the

latter wrapping the former and having a different set of methods.

Connectors can work in different modes (for example, iterate, delete,update, add only, lookup and passive).

See also “Attribute Mapping” on page 44.

Delta A special term used in Iterator mode used when synchronizing a masterand a slave. See “Deltas and compute changes” on page 41 for moreinformation

Entry A term used for both the Entry object and the top level item used by theAssemblyLine (see “The AssemblyLine” on page 17) and Connectors (seeChapter 7, “Connectors” on page 59). An entry typically corresponds to arow in a database table/view, a record from a file or an object in adirectory. Entries contain Attributes which contains Values. For example, aniterator might return the next person (the Entry), having the attributes city,name and phone. The values of the three attributes are London, Holmesand 5632.

Epilog A piece of code that, if present, is run after the AssemblyLine data flowends. It typically contains saving of parameter to be used next time theAssemblyLine runs. See ″Load task parameters from,″ page 187, and ″Savetask parameters to,″ page 187. See also Prolog.

EventHandlerWill wait for a specific event, and perform an action. Usually used todecide when AssemblyLines are to be started. Will usually pass an initialwork Entry to the AssemblyLine. See ″Listener,″ page 212 for a moreprimitive version.

External PropertiesA way of externalizing certain Component parameters as filename, user,password etc. See “The configuration file” on page 47 in the technicaldocumentation. If the parameter is not to be used as Componentparameter, you probably want to use Task Parameters.

IntegratorThe name of the product. Referred to as IBM Directory Integrator. Itconsists of the Admin tool and the Server (see page 213).

IteratorA Connector in Iterator mode.

Java VMJava Virtual Machine. IBM Directory Integrator runs inside what is knownas a Java Virtual Machine. It has it’s own memory management and is inmost respects a Machine within the Machine.

Link CriteriaUsed in order to tell Update, Lookup and Delete Connectors what toaccess. Briefly speaking it links an Attribute (see page 211) from theAssemblyLine to a field (attribute, column) in the data-source.

ListenerA more primitive and more flexible way of doing what the EventHandlerdoes–waiting for an event and taking action when an event happens. LessGUI than the EventHandler.


Mode Connectors have modes: The mode describes what the Connector will beused for: Iterate, AddOnly, Lookup, Update, Delete (a Passive state isavailable as well). See “Connectors” on page 21 for more on modes.

Null Value BehaviorHow Attribute Mapping is to be done when attribute values are missing.

Prolog Code that, if present, is run before the AssemblyLine data flow starts. Codecan be run both before and after all Connectors are initialized. See alsoEpilog.

PropertiesContained in Entries (see page 212) and holding a single value. Mostlyused in Handler Action maps. See also Attribute, page 211.

Raw ConnectorThe part of the that sees the external data source. See also Chapter 7,“Connectors” on page 59.

Script ComponentSomething that looks like a Connector in the Admin tool: It can beregarded as Connector without pre-configured input/output capabilities. Itis inserted by a separate Script button in the Admin tool and should not beconfused by the (Connector).

Script ConnectorA (Script Connector) is a Connector where you have written thefunctionality yourself: It is empty in the sense that in contrary to readyrolled Connector, the Script Connector does not have the base methodsgetNextEntry, findEntry etc. implemented. Not to be confused with theScript Component.

Server (ibmdisrv or ibmdisrv.bat)The Admin tool lets you define servers. Once you have defined a server, itwill be started from the command line (see Line Options) and perform theactual work. The server might run AssemblyLines directly, but it mightalso start EventHandlers that will start AssemblyLines when needed.

State Connectors can be in one of these states:v Enabled (the normal state)v Passive (initialized) but not part of the AssemblyLine flowv Disabled (not initialized by the AssemblyLine)

Task By convention all threads (AssemblyLines, EventHandlers etc) are referredto as the ″task″ object.

Task Call BlockA java structure used to pass parameters to and from AssemblyLines. See“AssemblyLine parameter passing” on page 19.

Task ParametersParameters that will be saved and loaded from a file. Filename to be set inthe AssemblyLine Setting tab. See also External Properties.

UpdateOne of the modes. Update will perform a lookup for the object you wantto update, and if it is found it will modify the existing entry. If it does notexist it will add it. See also Computed Changes.

Value See ″Entries″, page 212 and Attribute, page 211.

Appendix B. Dictionary of terms 213

Work EntryAn instance of the Entry (see page 212) class called work. If no work Entryexists, non-Iterator Connectors will not be called: The work Entry is anobject that lets Connectors share data within an “The AssemblyLine” onpage 17. If you don’t get work from an iterator, you can create it in theProlog by using task.setWork():init_work = system.newEntry(); // Create a new Entry objectinit_work.setAttribute("uid", "cchateauvieux"); // populate ittask.setWork(init_work); // make it known as

work to the Connectors


Appendix C. Administration and Monitor Console

Administration and Monitor Console user reference

ConsiderationsThe Administration and Monitor Console (AMC) lets you monitor yourAssemblyLines by pointing a browser to a host (defaulthttp://server_ip_address:8989). IBM Directory Integrator Server are AMC enabled bythe -m switch (see ″-m″ on page 189) or the global properties amc.on and mobj.on(see ″amc.on″ on page 218).

IBM Directory Integrator Server operates with a single configuration. AllAdministration and Monitor Console users connected to an IBM DirectoryIntegrator Server at a given time work on and see one and the same configuration.That is why when a user modifies the configuration another user will work withthe updated configuration even-though she has not changed the configuration.Another consequence of ″there being only one configuration″ is that when a usersaves the configuration she might save other users’ changes to the state of theconfiguration without being aware of it. The bottom-line is that AMC does notprovide configuration isolation between users.

When you activate the IBM Directory Integrator Admin tool, the IBM DirectoryIntegrator Server itself is not started. Whenever you activate an AssemblyLine orEventHandler from the IBM Directory Integrator Admin tool, a new systemprocess is started which it runs the IBM Directory Integrator Server with theAssemblyLine or EventHandler you have chosen, for example, if you start twoAssemblyLines consecutively from the IBM Directory Integrator Admin tool, thereare two IBM Directory Integrator Servers running on your machine, onesupporting the first AssemblyLine, the second Server supporting the secondAssemblyLine.

AMC itself is a Web interface for managing a single IBM Directory IntegratorServer.

When you start AssemblyLines or EventHandlers from IBM Directory IntegratorAdmin tool, AMC is disabled for the correspondingly started IBM DirectoryIntegrator Servers. So you cannot work on the same IBM Directory IntegratorServer (and operate on the memory representation of the server’s configuration)from IBM Directory Integrator Admin tool and AMC.

AMC (and the underlying management engine called MOBJ) are enabled with the-m option when you start the IBM Directory Integrator Server (ibmdisrv) from thecommand prompt.

Note: You can change an IBM Directory Integrator configuration disk file bothfrom the IBM Directory Integrator Admin tool and from AMC. In this caseAMC and IBM Directory Integrator Admin tool have nothing in commonand they just compete to write on a single file on the disk. It is only theoperating system that guards from concurrent modification, and basicallythe one who saves last (IBM Directory Integrator Admin tool or AMC) hasits configuration state saved in the disk file.


Apply Changes approachAfter entering a new value for a setting, attribute, parameter or anything else, clickApply Changes (on the corresponding screen) in order to apply the changes to theloaded configuration on the IBM Directory Integrator server. If you don’t clickApply Changes then the value you have entered will not be applied to theconfiguration on the server, and if you later save the configuration your changeswill not be saved. That is why if you want to save your changes right after youhave entered them you have to click Apply Changes and then Save theconfiguration.

If you modify the configuration, AMC displays an asterisk (*) in front of theconfiguration name as a reminder that you have not saved your changes. Whenyou save the configuration (by clicking Save) the asterisk will disappear. Pleasenote that other users’ modifications and saves of the configuration do notshow/hide the asterisk.

Browser compatibilityAMC has been tested with Internet Explorer 6.0, Netscape 6.0 and Opera 6.0.

Note: On Opera 6.0, modify the default browser cache settings to avoid AMCmalfunction: click Preferences from the File menu, select History and Cachefrom the Network section and then select Always from the Check modified\ Documents section.

You might experience that the back button of your browser does not always work.If this is the case, the back link is generated in the AMC pages themselves.

SSL supportAMC supports SSL. See “AMC setup” on page 218 for detailed information on howto turn on and configure SSL.

When SSL is turned off, AMC is accessed from the browser at http://host:port.When SSL is turned on, AMC is accessed from the browser at https://host:port.

Some AMC functions

TCB-aware (All and AssemblyLines screens)If an AssemblyLine’s TCB defines input parameters, then AMC will show a dotted″Run...″ button in the AssemblyLine’s table row on the″Configuration\AssemblyLines″ AMC page. When you click this button a pop-upwindow will be displayed in which you will be prompted to enter values for theAssemblyLine input parameters. Then you can start the AssemblyLine by pressingthe ″Run″ button in the pop-up window. If an AssemblyLine does not have a TCB,or the AssemblyLine’s TCB defines no input parameters, then a simple ″Run″button will appear on the AssemblyLine’s table row. Pushing this button will justrun the AssemblyLine (not dealing with TCB).

Server Operations screenThe following operations are available:

Reload configurationRefreshes (reloads) the current configuration from where it was loaded.

Load Configuration from FileLoads the configuration saved in the specified file.

Note: AMC cannot be used to load encrypted configuration files.


Load Configuration from URLThis is a two-step process, carried out automatically from AMC: you haveto specify a URL and a local filename (local for the IBM DirectoryIntegrator server machine). When you click ″Load Configuration fromURL″, AMC downloads the configuration specified by the URL and savesit on the IBM Directory Integrator server machine into the local filespecified. Then AMC loads the configuration from the local file specified.

Save ConfigurationSaves the current configuration to where it was loaded from (if possible).

Save Configuration asSaves the current configuration into the specified file on the local IBMDirectory Integrator server machine.

Shutdown ServerStops the IBM Directory Integrator server. Please note that stopping theIBM Directory Integrator server also stops AMC. That is why you cannotuse AMC after shutting the IBM Directory Integrator server down, nor canyou start the IBM Directory Integrator server again from AMC.

Import screenv Configuration Path – The path to the configuration file to import from; the path

syntax depends on the configuration driver used; probably the most often usedpath will be a filename on the local IBM Directory Integrator server machine(when using old-style configurations or XML configurations).

v In each of ″AssemblyLine Name″, ″EventHandler Name″, ″Connector Name″,″Parser Name″ and ″Script Name″ text boxes you have to enter the name of thecorresponding component you want to import and then click the corresponding″Import″ button – the result is that the configuration of the specified componentis copied into the current configuration.

v Download and save Server Configuration – This feature is provided forconvenience. Pressing the ″Download & Save″ button downloads theconfiguration file specified by the URL and saves it as the specified localfilename on the IBM Directory Integrator server machine. You can then type orcopy/paste the local filename into the ″Configuration Path″ text box and importthe components you like.

Log Files Cleanup screenThe ″Log Files Cleanup″ section allows deletion of old log files created onAssemblyLines and EventHandlers runs. There are three sections on this screenallowing correspondingly:v Multiple components logs deletion – when a cleanup operation is performed

from this section log files of many AssemblyLines or/and EventHandlers will bedeleted. The scope is further specified to one of:– All AssemblyLines and EventHandlers– All AssemblyLines– All EventHandlers

v Single AssemblyLine - when a cleanup operation is performed from this sectiononly log files of the specified AssemblyLine will be deleted.

v Single EventHandler - when a cleanup operation is performed from this sectiononly log files of the specified EventHandler will be deleted.

In all of the three cases described above, log files deletion can be performed bytwo criteria:

Appendix C. Administration and Monitor Console 217

v Deletion of all log files older than a specified date – in this case all log files thatwere last modified before the specified date will be deleted

v Deletion of all log files except the latest k – in this case the user specifies aninteger k, and the cleanup will delete all log files, except those generated fromthe latest k runs of each component in the scope of the cleanup operation;specifying ″0″ will result in deleting all log files.

AMC setup

AMC propertiesAMC is configured through the global.properties file which resides in the root IBMDirectory Integrator folder. If the properties described below are not correctly set inglobal.properties, AMC will not start.

The following are the basic AMC properties stored in global.properties (anothergroup of AMC properties–those for AMC SSL configuration are also stored inglobal.properties–see page“SSL configuration” on page 219):

amc.portThe port on which AMC listens for HTTP browser requests

amc.hostThe name or IP address of the network interface, on which AMC listens forincoming HTTP requests. This can be useful on computers with multiplenetwork interfaces (IP addresses accordingly). It can also be used as asecurity measure. By setting ″amc.host=localhost″, connections from thelocal computer only are allowed. If this property is not specified (default),the IBM Directory Integrator Server machine’s IP address is retrieved andused (in the case of multiple IP addresses on one machine, only one IPaddress is chosen).

Note: To use the construct http://localhost:8989 in your browser, you mustset ″amc.localhost=localhost″. Also note that for some platforms,setting amc.host=0.0.0.0 makes AMC listen to all network interfaces,thus acting as a wildcard. However, this is platform dependent andshould must not be relied upon if you want portability.

amc.accountsFileNameThe file path of the file which stores AMC user accounts. These accountsare used for AMC’s basic HTTP authentication and user roles mechanism.

amc.xsl.pathSpecifies the path to the XSL stylesheets; usually this is the path to themanagement.jar file (AMC will expect to find its stylesheets in the xslfolder in the specified jar); another option for the amc.xsl.path is to specifythe path to a folder – in this case AMC looks for its stylesheets in thespecified folder.

amc.ssl.onSpecify ″true″ or ″false″ to correspondingly turn on / off SSL.

mobj.onSpecify true or false. Enables the JMX Manageable Object. Note that thishas some impact on performance, but enables the AMC console. (-m asswitch to the server corresponds to ″mobj.on = true″ and ″amc.on = true″)

amc.onSpecify ″true″ or ″false″. Note that mobj.on must be true for this to have


any effect. Enables AMC on the host:port specified by amc.host andamc.port. (-m as switch to the server corresponds to ″mobj.on = true″ and″amc.on = true″). If amc.on=″true″ you cannot start two parallel processes(for example, AssemblyLines and EventHandlers) from the Admin tool (thesecond server initialization logs an error message because the AMC port isalready busy).

Accounts configuration fileThis is the file specified by the amc.accountsFileName property from theglobal.properties file.

This file contains the AMC user accounts. You can manually edit this file tochange, add and remove user accounts. Each account is presented in the form:account[<num>].full_name = <user’s full name entered herewill be displayed in the browser>account[<num>].login_name = <login name for the basic authentication required>account[<num>].password = <password for the basic authentication required>account[<num>].role= <one of administrator or operator>

Users with administrator role can use each and every feature of AMC, while userswith operator roles can only view all AMC output and start/stopAssemblyLines/EventHandlers (they cannot perform ″admin″ operations like:change/save IBM Directory Integrator configuration, import components,reload/shutdown IBM Directory Integrator Server).

Here <num> represents the consecutive account number. The account numbersshould be natural numbers between 0 and 1000. Of course, neither accountnumbers, nor ″login_name″ property values should occur more than once.

AMC loads the user accounts file on start-up and stores the loaded accounts untilits termination. That is why if you modify the user accounts file you need torestart AMC before the changes can take effect.

SSL configurationWhen SSL is turned on, AMC uses the IBM Directory Integrator default SSLsettings – they are set through the javax.net.ssl.* properties in the global.propertiesfile.

Note: AMC clients are browsers and this forces some restrictions on the keystorefile. Microsoft Internet Explorer, Netscape Navigator and Mozilla do notrecognize DSA signed SSL certificates, and DSA is used by default from thekeytool utility. In order to make a successful SSL connection from InternetExplorer, Netscape or Mozzila, the certificate used by IBM DirectoryIntegrator (and from AMC) must use RSA algorithm for key pair generation.keytool generates RSA certificates when the -keyalg RSA option is specified.For example:keytool -genkey -keystore certs -keyalg RSA

Example AMC configuration in global.properties# --------------# AMC properties# --------------

# the port where AMC will listen for HTTP browser requestsamc.port=8989

Appendix C. Administration and Monitor Console 219

# the AMC host name or IP addressamc.host=220.10.3.222

# the file path of the file where AMC user accounts are storedamc.accountsFileName=amc/accounts.txt

# specifies the path to the AMC XSL stylesheets# usually this is the path to the management.jar fileamc.xsl.path=jars/management.jar

# specify true or false to correspondingly turn on/off AMC SSLamc.ssl.on=true


Appendix D. Plug-ins

Currently, IBM Directory Integrator has one plug-in, the IBM Directory IntegratorPassword Synchronizer Plug-in.

IBM Directory Integrator password synchronizer plug-inThe password synchronizer intercepts Windows NT user ID and password changerequests and propagates the changes to the multiple user ID and passwordrepositories (datasources) before the NT system changes the password.

The IBM Directroy Integrator password synchronizer changes the password of theuser ID and password entry in an LDAP server (repository/datasource). Thechanges can then be propagated to the other servers by writing an IBM DirectroyIntegrator EventHandler and IBM Directroy Integrator AssemblyLine.

This component can be used on Windows NT, Windows 2000, and Windows XPoperating systems.

Additionally, the IBM Directroy Integrator Password Synchronizer can be used toprovide global password policy enforcement, by rejecting password changes on theWindows systems if the LDAP server does not accept the new password (passwordenforcement).

Synchronizing

Synchronize from Single MachineTo synchronize passwords from a single machine to the external data sourcethrough the use of the custom written java synchronization code, simply follow theinstall instructions to install the Password Synchronizer on the Windows platform.

Synchronize from Windows NT DomainTo synchronize password changes from a Windows NT domain, install thePassword Synchronizer on the Primary Domain Controller (PDC) for the domainyou want to synchronize with. Additionally, you must install the PasswordSynchronizer on all backup domain controllers, in case the roles of the domaincontrollers change.

Synchronize from a Windows 2000 or Windows XP DomainTo synchronize password changes from a Windows 2000 or Windows XP domain,install the Password Synchronizer on all domain controllers for the domain youwant to synchronize with.

ExampleBob logs into the windows machine, presses Ctrl-Alt-Delete, and requests apassword change. That password change is handled by timpwflt.dll file, thendelegated to the associated java class file, that implementscom.ibm.bim.pwfilt.IPasswordSynchronizer, by calling the syncPassword method ofthat interface. The custom code in our case is thecom.ibm.di.plugin.idipwsync.IDIPasswordSynchronizer which sets or updates theinformation on a remote LDAP server. If the method returns true, meaning thepassword was accepted, then the password is changed on the native Windowsmachine, regardless of whether it is a standalone machine or a domain controller.


If the method returns false, meaning the password was not accepted, then thepassword change is denied, and the password is not changed on the nativeWindows machine.

Included Filestimpwflt.dll

Contains the implementation which interfaces with Windows passwordchange function.

timpwflt.jarContains the base implentation for the password synchronizer.

install3.exeThe install executable that sets up and prepares relative registry entries.

ibmjsse.jarContains the SSL support for IDIPasswordSynchronizer.

ibmjlog.jarContains the logging support for supporting code.

ibmjceprovider.jarContains the SSL support for IDIPasswordSynchronizer.

ibmjcefw.jarContains the SSL support for IDIPasswordSynchronizer.

ibmjndi.jarContains the jndi support for IDIPasswordSynchronizer.

ldap.jarContains the base ldap context support used by IDIPasswordSynchronizer.

providerutil.jarContains component directory support used by IDIPasswordSyncrhonizer.

idipwtrace.jarContains the trace support for IDIPasswordSynchronizer.

idipwsync.jarContains the IDIPassWordSynchronizer function.

ibm-diPerson_oc.ldifContains definition of ibm-diPerson object class.

Installing IBM Directory Integrator password synchronizerplug-in

Do the following to install IBM Directory Integrator password synchronizerplug-in:1. Deploy the dll and jar files.2. Run install3.3. Set up the registry.4. Enable Local Security Policy (Windows 2000 only).5. Set up the LDAP server.6. Prepare the IDIPasswordSynchronizer properties file.

Deploying the dll and jar filestimpwflt.dll

C:\winnt\system32 directory


timpwflt.jarDirectory. For example, C:\sync.

install3.exeDirectory. For example, C:\sync.

ibmjsse.jarJDK_home\jre\lib\ext

ibmjlog.jarJDK_home\jre\lib\ext

ibmjceprovider.jarJDK_home\jre\lib\ext

ibmjcefw.jarJDK_home\jre\lib\ext

ibmjndi.jarJDK_home\jre\lib\ext

ldap.jarJDK_home\jre\lib\ext

providerutil.jarJDK_home\jre\lib\ext

idipwtrace.jarJDK_home\jre\lib\ext

idipwsync.jarDirectory. For example, C:\sync.

ibm-diPerson_oc.ldifDirectory. For example, C:\sync.

Instructions for Running install3.exeThe install3.exe command has the following arguments:v The path to java.exev The classpath to synchronization jarsv Class name of the IBM Directroy Integrator synchronizer implementation

Assuming you place the following files in a directory named c:\sync:v idipwsync.props

Note: The properties file which must be on the CLASSPATH. At the point ofrunning install3.exe, the idipwsync.props file does not have to physicallyexist in the the directory yet. See “Preparing the IDIPasswordSynchronizerproperties file (idipwsync.props)” on page 225.

v idipwsync.jar (the IBM Directroy Integrator synchronizer code)v timpwflt.jarv intstall3.exe (install tool)

then the install3 command issued from the command prompt looks like thefollowing:c:\sync>install3 c:\jdk\jre\bin\java.exec:\sync;c:\sync\timpwflt.jar;c:\sync\idipwsync.jar;com.ibm.di.plugin.idipwsync.IDIPasswordSynchronizer

To summarize, using the previous command as an example:v The first argrument is the path to java.exe: c:\jdk\jre\bin\java.exe

Appendix D. Plug-ins 223

v The second argument is the CLASSPATH which includes the following threepaths:– The path of the location of the idipwsync.props file: c:\sync– The path of the location of timepwflt.jar: c:\sync\timpwflt.jar– The path of the location of the IBM Directroy Integrator Password

Synchronization jar: c:\sync\idipwsync.jarv The third argument is the the implementation class for IBM Directroy Integrator

Password Synchronizer: com.ibm.di.plugin.idipwsync.IDIPasswordSynchronizer

Setting up the registryDo the following to set up the registry:1. Run C:\winnt\system32\regedt32.2. Locate and select the pane labeled HKEY_LOCAL_MACHINE on local

machine, and select SYSTEM node.3. From the toolbar, select View–>Find key.4. Specify LSA.5. Double click Notification Packages.6. Add timpwflt on a separate line without removing any existing entries (for

example, scecli).

Enabling Local Security Policy (Windows 2000 only)If you are using Windows 2000 do the following:1. Click Control Panel–>Administrative Tools–>Local Security Policy.2. Click Account Policies–>Password Policy.3. Change Passwords must meet complexity requirements to enabled.

Setting up the LDAP server1. Add suffix

a. Using IBM Directory Server Web Admin Tool (http:/localhost/ldap), go toSettings–>Suffixes

b. In Suffix DN text entry field, add the suffix under which you store thepassword information (for example, o=ibm,c=us).

c. Click Update.d. The new suffix appears in the Current Server suffixes list with the comment

Contains no directory data.e. Click Restart the server link in the status message at the top of the screen.

2. Add the domain objecta. Using IBM Directory Management Tool, go to Start–>Programs–>IBM

Directory Server v4.1.b. Go to Directory tree–>Browse tree, select the suffix previously created in

step 1 (for example, o=ibm,c=us).c. Click the Add icon in the toolbar. The Add an LDAP entry dialog is

displayed.d. In the Entry type pull-down selection list, select Domain.e. In the Entry RDN field enter the domain name (for example, dc=carnd10)

and click OK. The Add an LDAP entry detail dialog is displayed.f. In the dc entry field repeat the previously specified domain name (for

example, carnd10), and click Add.


Note: The domain and suffix just entered must be included in theidipwsync.props file along with the other information (see “Preparingthe IDIPasswordSynchronizer properties file (idipwsync.props)” formore details).

3. Define the ibm-diPerson object. From a machine with IBM Directory ServerClient, issue the following command from the directory (C:\sync, for example):ldapmodify -c -h LDAP Hostname -D admin DN -w admin PW -f ibm-diPerson_oc.ldif

Preparing the IDIPasswordSynchronizer properties file(idipwsync.props)

Note: The properties file must be named idipwsync.props and be placed in adirectory that is in the CLASSPATH in order to be located by the programthat loads it at boot time.

Do the following to generate a partial properties file with some basic settings:c:\sync>java -cp c:\sync\idipwsync.jarcom.ibm.di.plugin.idipwsync.GenPropertiesFilefilepath ldapPassword keystorePassword

where:v filepath is the fully qualified filename (for example, c:\sync\idipwsync.props),v ldapPassword is the unencoded password for directory access (for example,

secret)v keystorePassword is the unencoded password for clientKeystore (for example,

secret)

For example,java -cp c:\sync\idipwsync.jarcom.ibm.di.plugin.idipwsync.GenPropertiesFilec:\sync\idipwsync.props secret secret"

yields the following file contents:IDIPwSynchronizer Security Settings with Encoded Passwords#Tue Jul 30 08:21:20 EDT 2002port=DiagnosticTrace=falseldapLogInUserId=ldapLogInPassword=0c0bf0e3146bkeyStoreFilePath=ErrorTrace=falseInformationTrace=falseWarningTrace=falsekeyStoreFilePassword=0c0bf0e3146bsuffix=host=logFilePath=

Note: This utility does not set all the required properties. You must edit with theinformation specific to your installation. Also, the keyStoreFilePath is thepath to a JKS file which you need to obtain or create using other utilities notincluded in this package. A keystore file is only necessary if you areenabling SSL on you Directory Server connection. This implementationassumes that a single JKS file contains both the client and the server’scertificate if Server and Client Authentication is selected on the DirectoryServer’s SSL Settings.

Appendix D. Plug-ins 225

Alternately, if you choose to manually code the properties file completely, or wishto later change either the ldapLogInPassword or keystoreFilePassword, you can use asecond utility which encodes your new password, so you can copy it into theproperties file.

To obtain an encoded version of your password issue the following command:c:\sync>java -cp c:\sync\idipwsync.jarcom.ibm.di.plugin.idipwsync.EncodePW password

where password is your ASCII password (for example, secret). For example,java -cp c:\sync\idipwsync.jar com.ibm.di.plugin.idipwsync.EncodePW secret

returns 0c0bf0e3146b.

A completed properties file for a SSL connection looks like the following:IDIPwSynchronizer Security Settings with Encoded Passwords#Tue Jul 30 08:21:20 EDT 2002port=636 DiagnosticTrace=falseldapLogInUserId=cn=rootldapLogInPassword=0c0bf0e3146bkeyStoreFilePath=c:\\sync\\keys.jksErrorTrace=trueInformationTrace=falseWarningTrace=falsekeyStoreFilePassword=0c0bf0e3146bsuffix=dc=carnd11,o=ibm,c=ushost=gbdthst1logFilePath=c:\\sync\\idipwsync.log

Note: To disable SSL, select a non-SSL port (for example, 389) and do not specify avalue for the keyStoreFilePath.

For more information, see the /plugins directory (root_directory/plugins).


Appendix E. Connector modes flowcharts

For a separate version of the Connector modes flowcharts, please go toroot_directory/docs/ConnectorModes.pdf.

The following is the legend for the components of the Connector Modesflowcharts:

v Black arrows indicate normal flow.

v Broken arrows show error/exception flow. Errors can occur both in scripted flowcomponents, as well as in IBM Directory Integrator operations.


v The Flow Endpoint symbol represents the start or end of the flow for aConnector flow diagram. The text contained in the symbol provides moreinformation about system state and behavior at this point.

v These boxes represent scripted flow components, and are used for both AttributeMaps and Hooks.

Note: If a Hook is enabled, then control is passed to the script in the Hook. If aHook is not enabled, then the flow continues past the Hook withoutexecuting the Hook.

v Some Hooks are mandatory and must be enabled, although they do not need tocontain any script. If a mandatory Hook is not enabled and the flow reaches thispoint, this is considered an error, and control defaults to error handling.

v This box represents an IBM Directory Integrator operation (these are available asfunctions in the Raw Connector object.


Note: IBM Directory Integrator operations might also result in error flows.

v Decision components represent logical branches in Connector execution,depending on state information at this point in the flow. In general, Yesbranches appear to the right of the Decision component, while No branches sendthe flow downwards. If this convention is not followed for a particular Decisioncomponent, then the branch labels appear in bold text in the flow diagram.

v The Continuation symbol indicates that the flow is continued on another pagethat is common for one or more modes. The page being referenced appears in alabel below this symbol.

Appendix E. Connector modes flowcharts 229

v This is a Continuation symbol that is used when the referenced page is still partof the same Connector mode. The page being referenced appears in a labelbelow this symbol.

AddOnly modeAvailable Objects

As always, work gives you access to the attributes that are currently in theAssemblyLine.

The information stored in the conn object is written to the data source by the Addoperation.


Call/Reply modeAvailable Objects


The information stored in the conn object is slightly different in this mode.

Note: The conn object serves two different purposes in Call/Reply mode:v Storing the call attributes/parameters defined in the Output Attribute

Map to be transmitted by the Call/Reply operation.v Receiving return attributes/parameters that will be accessed by the Input

Attribute Map after the Call/Reply operation.


Delete modeAvailable Objects


After the Build Link Criteria operation, there is a script object called searchavailable which gives you access to this information (for example, for use in theOverride Hook).

The record or entry matching the Link Criteria (which is about to be deleted) isavailable for scripting as the conn object, and Attribute Mapping is carried out toenable your AssemblyLine to use attributes from the entry which is about to bedeleted.

On Multiple EntriesIf more than one record or entry is found that matches the Link Criteria, then theOn Multiple Entries Hook must also be enabled, or this is treated as an error.

You can access the set of records or entries found by using either of these twoConnector functions:getFirstDuplicateEntry()

getNextDuplicateEntry()

Each of these functions returns an Entry object that can be used to call aConnector’s data access methods (update(), delete(), and so forth).

If you wish to proceed with the delete flow/operation, then you must set thecurrent Entry with the following Connector function:myConnector.setCurrent( myEntry )

If you do not set a current Entry, then execution will continue to On Success,bypassing the rest of the mode-specific flow.

Note: Data sources (and therefore related Connectors) behave differently whenmultiple Entries are handled. Even if you select a specific Entry as describedpreviously, it is not recommended that you continue with the delete flow, asthis can result in an error, or that the operation is performed on multipleentries.


Iterator modeAvailable Objects


The data read in by each GetNext operation is available in the conn object.

Note: If a Connector in Iterator mode detects the presence of a valid work objectat the start of its execution (for example, that there is another Iterator infront of this one in the same AssemblyLine), or that the initial work Entryhas been passed into the AssemblyLine from a calling process or system,then this Connector is not executed, and passes this Entry to the nextConnector in the AssemblyLine instead.

The following figure illustrates what happens when an Iterator reaches itsend-of-data. At this point it does not pass a work object to the next Connector,which in the case of another Iterator, signals it to begin its own iteration.


When the GetNext function detects end-of-data, flow is as follows:


Lookup modeAvailable Objects



The record or entry matching the Link Criteria (which is about to be deleted) isavailable for scripting as the conn object.


During this Hook, conn must be set to the desired Entry object by calling theConnector’s setCurrent() function:


myConnector.setCurrent( myEntry )



Each of these functions returns an Entry object that can be used in the setCurrent()call.

If setCurrent() is not called (for example, no current entry is set) then the flow ispassed on to OnSuccess, bypassing the rest of the mode-specific flow.


Update modeAvailable Objects






Each of these functions returns an Entry object that can be used to call aConnector’s data access methods (update(), delete(), and so forth).

In addition, conn can be set to the desired Entry object by calling the Connector’ssetCurrent() function:myConnector.setCurrent( myEntry )

If no Entry object is set, then execution continues to On Success, skipping the restof the mode-specific flow.

Note: Data sources (and therefore related Connectors) behave differently whenmultiple Entries are handled. Even if you set a specific Entry as describedabove, it is not recommended that you continue with the update operation,as this can result in an error, or that the operation is performed on multipleentries.


Available ObjectsAs always, work gives you access to the attributes that are currently in theAssemblyLine.


If the Update results in an Add operation, conn holds the data that is written tothe data source.


Available ObjectsAs always, work gives you access to the attributes that are currently in theAssemblyLine.


If the update results in a Modify operation, the current object gives you access tothe record/entry in the connected data source that matches the Link Criteria (forexample, is about to be modified). As in the case of an Add, the conn object holdsthe information that is to be written to the data source (in this case, by the Modifyoperation).

Note: Some data sources compute changes automatically, and if none are detected,revert with a No Changes exception. This causes flow to be directed to theOn No Changes Hook.


End-of-flow for all modesAvailable Objects



The conn and current objects are available in the OnError and OnSuccess Hooks ifthey were present previously in the flow.

End-of-flowThis flow applies to all Connectors that terminate normally (for example,terminating successfully) or due to an error. The only exception is Iterator mode,which terminates the AssemblyLine if end-of-data is reached and there are noother Iterators to pass control to.

Error Handling

Note: If On Error Hook is enabled, then control is passed to the next Connector, asif the Connector had terminated successfully. Otherwise, the AssemblyLineaborts.

If an error occurs in an OnError Hook, then the AssemblyLine also aborts.

The error object (of type Entry) is available throughout an AssemblyLine, andprovides information about an error situation through its attributes: status,exception, class, message, operation and connectorname.

The status attribute has the string value OK until an error situation arises, atwhich time it is assigned the value fail and the other attributes are added to error.


Appendix F. Notices

This information was developed for products and services offered in the U.S.A.IBM might not offer the products, services, or features discussed in this documentin other countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the information. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thisinformation at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationDepartment LZKS11400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM’s suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

Third-party component statements

Apache statementThis product includes software developed by the Apache Software Foundation(http://www.apache.org/). The Apache components include the Xerces, Xalan,XML4J, and Log4J libraries, and these are provided in object code form. This objectcode was obtained from the Apache web site and is unmodified.

Apache licenseThe Apache Software License, Version 1.1

Copyright (c) 1999-2002 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification,are permitted provided that the following conditions are met:


1. Redistributions of source code must retain the above copyright notice, this listof conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, thislist of conditions and the following disclaimer in the documentation and/orother materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, mustinclude the following acknowledgment: ″This product includes softwaredeveloped by the Apache Software Foundation (http://www.apache.org/).″Alternately, this acknowledgment may appear in the software itself, if andwherever such third-party acknowledgments normally appear.

4. The names ″Xerces″, ″Xalan″, ″log4j″, ″mx4j″ and ″Apache Software Foundation″must not be used to endorse or promote products derived from this softwarewithout prior written permission. For written permission, please [email protected].

5. Products derived from this software may not be called ″Apache″, nor may″Apache″ appear in their name, without prior written permission of the ApacheSoftware Foundation.

THIS SOFTWARE IS PROVIDED ″AS IS″ AND ANY EXPRESSED OR IMPLIEDWARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWAREFOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OFSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OFLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OFTHE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OFSUCH DAMAGE.

This software consists of voluntary contributions made by many individuals onbehalf of the Apache Software Foundation. For more information on the ApacheSoftware Foundation, please see http://www.apache.org

Rhino statementThe IBM Directory Integrator uses Rhino (JavaScript for Java) object code. Thesource code for Rhino is located at http://www.mozilla.org/rhino/download.htmland is available under the terms of the Netscape Public License 1.1(http://www.mozilla.org/MPL/NPL-1.1.html). The Rhino source code found onthe mozilla Web site was not modified in generating the object code used in IBMDirectory Integrator.

TrademarksThe following terms are trademarks of International Business MachinesCorporation in the United States, or other countries, or both:

IBM WebSphere SecureWay® AIX UpdateConnector

Lotus Notes Domino Lotus Notes

Appendix F. Notices 259

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Microsoft, Windows and Windows NT are registered trademarks of MicrosoftCorporation.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.


��

Printed in U.S.A.