IBM Directory Integrator 4.7: Reference Guide

IBM Directory Integrator 4.7:Reference Guide

��

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

First Edition (August 2002)

This edition applies to version 4, release 7, 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 . . . . . . . . . . . . . . vii

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

Admin tool . . . . . . . . . . . . . . 1IBM Directory Integrator server . . . . . . . 1

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

Chapter 2. Getting Started Guide . . . . 3

Chapter 3. Supported platforms andknown issues . . . . . . . . . . . . 5

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

Starting an AssemblyLine . . . . . . . . . 8Starting from the Admin tool . . . . . . . . 8Accessing connectors inside the AssemblyLine . . 9

Connectors . . . . . . . . . . . . . . . 9How do Connectors share data? . . . . . . . 9Iterator mode. . . . . . . . . . . . . 10Multiple Iterators in an AssemblyLine . . . . 10Using the Iterator mode . . . . . . . . . 10Lookup mode . . . . . . . . . . . . 11AddOnly mode . . . . . . . . . . . . 12Update mode. . . . . . . . . . . . . 12Delete mode . . . . . . . . . . . . . 13Passive mode. . . . . . . . . . . . . 13Link criteria . . . . . . . . . . . . . 14

EventHandler . . . . . . . . . . . . . 15Starting the EventHandler . . . . . . . . 15The Event object . . . . . . . . . . . . 16Configuration and data flow. . . . . . . . 16Prolog . . . . . . . . . . . . . . . 16Actions . . . . . . . . . . . . . . . 16Attribute/property names . . . . . . . . 17Epilog . . . . . . . . . . . . . . . 17

Scripting . . . . . . . . . . . . . . . 17When is scripting needed? . . . . . . . . 17Integrating scripting into the AssemblyLine? . . 17How will scripting affect execution? . . . . . 18Control points for scripting . . . . . . . . 19Comparing JavaScript strings . . . . . . . 20Accessing your own Java classes . . . . . . 21Scripting in JavaScript . . . . . . . . . . 22Scripting in languages without new java.* . . . 22Using binary values in scripting . . . . . . 22Using date values in scripting . . . . . . . 22Using floating point values in scripting . . . . 23

Hooks . . . . . . . . . . . . . . . . 23

Enabling/disabling Hooks . . . . . . . . 24Override Hooks . . . . . . . . . . . . 24Failure Hooks . . . . . . . . . . . . 24Hooks called on other events . . . . . . . 24List of Hooks . . . . . . . . . . . . . 25

Deltas and compute changes . . . . . . . . 28Deltas . . . . . . . . . . . . . . . 28

Inheritance . . . . . . . . . . . . . . 30Attribute Mapping . . . . . . . . . . . . 30

Null Value Behavior . . . . . . . . . . 31Conn object . . . . . . . . . . . . . 31

Tasks . . . . . . . . . . . . . . . . 32How to control the number of threads . . . . 33

The configuration file . . . . . . . . . . . 33Externalizing fields like username and password 33Export, import and include . . . . . . . . 34

IBM Directory Integrator Secure Sockets LayerSupport . . . . . . . . . . . . . . . 35

Securing the connection between IBM DirectoryIntegrator and servers with SSL (IBM DirectoryIntegrator as a client) . . . . . . . . . . 35Securing the connection between client and IBMDirectory Integrator with SSL (IBM DirectoryIntegrator as a server) . . . . . . . . . . 36Replacing security from IBM JCE and JSSE toanother vender . . . . . . . . . . . . 36

Chapter 5. IBM Directory Integratorinstallation instructions . . . . . . . 39Installing on Windows platforms . . . . . . . 39Installing on Unix platforms . . . . . . . . . 39Uninstalling on Windows platforms . . . . . . 40Uninstalling on Unix platforms . . . . . . . . 40

Chapter 6. Connectors . . . . . . . . 41Connector availability and reference . . . . . . 41

Raw Connectors . . . . . . . . . . . . 41Script-based Connectors . . . . . . . . . 43Configurations . . . . . . . . . . . . 43

ADSI Connector . . . . . . . . . . . . . 43Preconditions . . . . . . . . . . . . . 43

Btree Connector . . . . . . . . . . . . . 46Configuration . . . . . . . . . . . . 46Btree object . . . . . . . . . . . . . 46Downloads . . . . . . . . . . . . . 47

Command line Connector . . . . . . . . . 47Configuration . . . . . . . . . . . . 47Downloads . . . . . . . . . . . . . 47

Direct TCP /URL scripting . . . . . . . . . 47TCP . . . . . . . . . . . . . . . . 47URL . . . . . . . . . . . . . . . . 48

EMI/UCP Connector . . . . . . . . . . . 48Configuration . . . . . . . . . . . . 48Downloads . . . . . . . . . . . . . 48See also. . . . . . . . . . . . . . . 48

© Copyright IBM Corp. 2002 iii

File system Connector . . . . . . . . . . . 48Configuration . . . . . . . . . . . . 48See also. . . . . . . . . . . . . . . 49

FTP Connector . . . . . . . . . . . . . 49Configuration . . . . . . . . . . . . 49Note. . . . . . . . . . . . . . . . 49See also. . . . . . . . . . . . . . . 49

GSM Phone Connector . . . . . . . . . . 50Configuration . . . . . . . . . . . . 50Downloads . . . . . . . . . . . . . 50

HTTP Client Connector . . . . . . . . . . 50Modes . . . . . . . . . . . . . . . 50Special attributes . . . . . . . . . . . 50Configuration . . . . . . . . . . . . 51Samples . . . . . . . . . . . . . . 52Lookup Mode . . . . . . . . . . . . 52Downloads . . . . . . . . . . . . . 52See also. . . . . . . . . . . . . . . 52

HTTP Client Connector Version 2 . . . . . . . 52Changes from earlier versions . . . . . . . 52Modes . . . . . . . . . . . . . . . 53Special attributes . . . . . . . . . . . 53Configuration . . . . . . . . . . . . 54Samples . . . . . . . . . . . . . . 54Lookup Mode . . . . . . . . . . . . 54See also. . . . . . . . . . . . . . . 55

HTTP Server Connector . . . . . . . . . . 55Configuration . . . . . . . . . . . . 55Downloads . . . . . . . . . . . . . 56See also. . . . . . . . . . . . . . . 56

HTTP Server Connector Version 2 . . . . . . . 56Configuration . . . . . . . . . . . . 56See also. . . . . . . . . . . . . . . 57

JDBC Connector . . . . . . . . . . . . . 57Configuration . . . . . . . . . . . . 57Other . . . . . . . . . . . . . . . 58Notes . . . . . . . . . . . . . . . 58See also. . . . . . . . . . . . . . . 59

ODBC–specifying database paths directly . . . . 59JMS Connector . . . . . . . . . . . . . 60

Configuration . . . . . . . . . . . . 60Specific topics . . . . . . . . . . . . 61

JNDI Connector . . . . . . . . . . . . . 61Configuration . . . . . . . . . . . . 61Downloads . . . . . . . . . . . . . 62See also. . . . . . . . . . . . . . . 62

LDAP Connector . . . . . . . . . . . . 62Configuration . . . . . . . . . . . . 62Notes . . . . . . . . . . . . . . . 64Handling memory problems in the LDAPConnector . . . . . . . . . . . . . . 64Duplicating a whole directory from a server toanother . . . . . . . . . . . . . . . 65IBM Directory Changelog Connector . . . . . 65

Lotus Notes Connector . . . . . . . . . . 66Configuration . . . . . . . . . . . . 67Downloads . . . . . . . . . . . . . 67Ports . . . . . . . . . . . . . . . 67Security . . . . . . . . . . . . . . 67

Mailbox Connector . . . . . . . . . . . . 68Configuration . . . . . . . . . . . . 68

Predefined Properties/Attributes . . . . . . 68See also. . . . . . . . . . . . . . . 69

Memory Stream Connector . . . . . . . . . 69Configuration . . . . . . . . . . . . 69

NT4 Connector . . . . . . . . . . . . . 70Preconditions . . . . . . . . . . . . . 70Character sets . . . . . . . . . . . . 73

NT4 Connector functional specifications andsoftware requirements . . . . . . . . . . . 73

Functionality . . . . . . . . . . . . . 73Business Objects . . . . . . . . . . . . 74Use cases . . . . . . . . . . . . . . 78Hardware and software configuration . . . . 84

Oracle8 JDBC Driver . . . . . . . . . . . 85Configuration . . . . . . . . . . . . 85Note. . . . . . . . . . . . . . . . 85See also. . . . . . . . . . . . . . . 86

(runtime provided) Connector . . . . . . . . 86Configuration . . . . . . . . . . . . 86Downloads . . . . . . . . . . . . . 86See also. . . . . . . . . . . . . . . 86

Script Connector. . . . . . . . . . . . . 86Predefined script objects . . . . . . . . . 87Functions . . . . . . . . . . . . . . 87Configuration . . . . . . . . . . . . 88Note. . . . . . . . . . . . . . . . 88See also. . . . . . . . . . . . . . . 88

SMPP Connector . . . . . . . . . . . . 88Configuration . . . . . . . . . . . . 88Downloads . . . . . . . . . . . . . 89See also. . . . . . . . . . . . . . . 89

SNMP Connector . . . . . . . . . . . . 89Configuration . . . . . . . . . . . . 89Notes . . . . . . . . . . . . . . . 90

TCP Connector . . . . . . . . . . . . . 90Iterator Mode. . . . . . . . . . . . . 90AddOnly Mode . . . . . . . . . . . . 91Configuration . . . . . . . . . . . . 91See also. . . . . . . . . . . . . . . 91

URL Connector . . . . . . . . . . . . . 91Configuration . . . . . . . . . . . . 91Downloads . . . . . . . . . . . . . 91See also. . . . . . . . . . . . . . . 91

Chapter 7. EventHandlers. . . . . . . 93EventHandler types . . . . . . . . . . . 93When are they started? . . . . . . . . . . 93What do they do? . . . . . . . . . . . . 93EventHandlers . . . . . . . . . . . . . 94Listeners: simple EventHandlers . . . . . . . 94Connector EventHandler . . . . . . . . . . 94

Configuration . . . . . . . . . . . . 94Objects/properties/attributes . . . . . . . 95Downloads . . . . . . . . . . . . . 95See also. . . . . . . . . . . . . . . 95

HTTP EventHandler . . . . . . . . . . . 95Example . . . . . . . . . . . . . . 95Configuration . . . . . . . . . . . . 96See also. . . . . . . . . . . . . . . 96

IBM SecureWay LDAPEventHandler . . . . . . 96Configuration . . . . . . . . . . . . 97

iv IBM Directory Integrator 4.7: Reference Guide

See also. . . . . . . . . . . . . . . 98LDAP EventHandler . . . . . . . . . . . 98

Object Added (objAdded) . . . . . . . . 99Object Rename (objRenamed) . . . . . . . 99Object Modified (objModified) . . . . . . . 99Object Removed (objRemoved) . . . . . . . 99Configuration . . . . . . . . . . . . 100Notes . . . . . . . . . . . . . . . 100See also . . . . . . . . . . . . . . 100

Mailbox EventHandler . . . . . . . . . . 100Configuration . . . . . . . . . . . . 100Objects/properties/attributes . . . . . . . 101Downloads . . . . . . . . . . . . . 101See also . . . . . . . . . . . . . . 101

TCPEventHandler . . . . . . . . . . . . 101Configuration . . . . . . . . . . . . 101Objects/properties/attributes . . . . . . . 101See also . . . . . . . . . . . . . . 102

Port listener . . . . . . . . . . . . . . 102AdminPort (simple EventHandler) . . . . . 102Generic thread (simple EventHandler) . . . . 103LDAP listener . . . . . . . . . . . . 103MailboxListener (simple EventHandler) . . . 104TCPListener (simple EventHandler) . . . . . 105Timer EventHandler . . . . . . . . . . 105

Chapter 8. Script languages . . . . . 107BeanShell. . . . . . . . . . . . . . . 107Perl . . . . . . . . . . . . . . . . 107Perl example . . . . . . . . . . . . . 108Script languages . . . . . . . . . . . . 108

BSF-based script languages . . . . . . . . 109WSH-based script languages . . . . . . . 109

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

Base parsers . . . . . . . . . . . . . 111Character set conversion . . . . . . . . . . 111

Availability . . . . . . . . . . . . . 111CSV parser . . . . . . . . . . . . . . 112

Configuration . . . . . . . . . . . . 112Notes . . . . . . . . . . . . . . . 112

DSML parser . . . . . . . . . . . . . 113Configuration . . . . . . . . . . . . 113Example . . . . . . . . . . . . . . 113References . . . . . . . . . . . . . 114See also . . . . . . . . . . . . . . 114

CDS-EDB file parser . . . . . . . . . . . 114Configuration . . . . . . . . . . . . 114Notes . . . . . . . . . . . . . . . 114

Fixed parser . . . . . . . . . . . . . . 114Configuration . . . . . . . . . . . . 114

HTTP parser. . . . . . . . . . . . . . 114Configuration . . . . . . . . . . . . 114Attributes/properties . . . . . . . . . . 115See also . . . . . . . . . . . . . . 116

LDIF parser . . . . . . . . . . . . . . 116See also . . . . . . . . . . . . . . 117

LineReader . . . . . . . . . . . . . . 117Configuration . . . . . . . . . . . . 117

Regular Expression parser . . . . . . . . . 117Functional specification . . . . . . . . . 117Source code . . . . . . . . . . . . . 118

Regular Expression parser source code . . . . . 119Script parser. . . . . . . . . . . . . . 121

Objects . . . . . . . . . . . . . . 121Functions. . . . . . . . . . . . . . 122Configuration . . . . . . . . . . . . 122Note . . . . . . . . . . . . . . . 122See also . . . . . . . . . . . . . . 122

Simple parser . . . . . . . . . . . . . 122Configuration . . . . . . . . . . . . 123

SOAP parser . . . . . . . . . . . . . 123Sample Entry . . . . . . . . . . . . 123Sample SOAP . . . . . . . . . . . . 123Configuration . . . . . . . . . . . . 123Parser-specific calls . . . . . . . . . . 124

XML parser . . . . . . . . . . . . . . 124Configuration . . . . . . . . . . . . 125Examples . . . . . . . . . . . . . . 125Notes . . . . . . . . . . . . . . . 127References . . . . . . . . . . . . . 127See also . . . . . . . . . . . . . . 127

Chapter 10. Objects. . . . . . . . . 129The AssemblyLine Connector object . . . . . . 129The Attribute object . . . . . . . . . . . 130

Methods . . . . . . . . . . . . . . 130Examples . . . . . . . . . . . . . . 131See also . . . . . . . . . . . . . . 131

The Raw Connector object . . . . . . . . . 131Methods . . . . . . . . . . . . . . 132

The Entry object . . . . . . . . . . . . 132Methods . . . . . . . . . . . . . . 132Global Entry instances available in scripting . . 133See also . . . . . . . . . . . . . . 134

The FTP object . . . . . . . . . . . . . 134Methods . . . . . . . . . . . . . . 134Example . . . . . . . . . . . . . . 134

Main object . . . . . . . . . . . . . . 135The Search criteria object . . . . . . . . . 135

Methods . . . . . . . . . . . . . . 135Operands. . . . . . . . . . . . . . 135Example . . . . . . . . . . . . . . 136

The shellCommand object . . . . . . . . . 136Methods . . . . . . . . . . . . . . 136

The status object . . . . . . . . . . . . 136Methods . . . . . . . . . . . . . . 137

The system object . . . . . . . . . . . . 137Methods . . . . . . . . . . . . . . 137

The task object . . . . . . . . . . . . . 141task–AssemblyLine . . . . . . . . . . 142task–EventHandler . . . . . . . . . . 142

Chapter 11. Program interfaces. . . . 143AssemblyLine setting tab . . . . . . . . . 143IBM Directory Integrator command line options 144

IBM Directory Integrator Admin tool . . . . 144IBM Directory Integrator server . . . . . . 144

Discover schemas and browsing data . . . . . 145

Contents v

Distribution components . . . . . . . . . 145Other files on install directory . . . . . . . 145Jar-files (jars/subdirectory) . . . . . . . . 146Java Naming and Directory Interface (JNDI) . . 146JavaMail API . . . . . . . . . . . . 146XML . . . . . . . . . . . . . . . 146Libraries (Windows) libs/ subdirectory . . . . 146Other . . . . . . . . . . . . . . . 146global.properties file . . . . . . . . . . 147

JDBC Client . . . . . . . . . . . . . . 147Parameter labels on the Connector/parser tabs. . . 148LDAP Client . . . . . . . . . . . . . 148Preferences/system properties . . . . . . . . 149System/Java properties . . . . . . . . . . 149Using external properties . . . . . . . . . 151

Chapter 12. Samples . . . . . . . . 153VBScript Connector and MSOutlook connector . . 153

Sample code. . . . . . . . . . . . . 153See also . . . . . . . . . . . . . . 155

JavaScript Connector . . . . . . . . . . . 155Sample code. . . . . . . . . . . . . 155See also . . . . . . . . . . . . . . 155

JavaScript parser . . . . . . . . . . . . 156Sample code. . . . . . . . . . . . . 156See also . . . . . . . . . . . . . . 156

Writing a new Raw Connector. . . . . . . . 156Script-based Connector . . . . . . . . . 156Java-based Connector. . . . . . . . . . 156Building and installing a Java-based Connector 157

system.parseDate (string value, string format) . . 159Example . . . . . . . . . . . . . . 159Other examples. . . . . . . . . . . . 159

Chapter 13. Logging and debugging 161AssemblyLine Debugger. . . . . . . . . . 161Logging and debugging . . . . . . . . . . 161

Dumping the content of an Entry object . . . 162Dumping the content of an Attribute . . . . 162Dumping the state of a Connector . . . . . 162Dumping arbitrary log messages . . . . . . 163

Chapter 14. Optional tasks in IBMDirectory Integrator 4.7 . . . . . . . 165Copying directories with the LDAP Connector . . 165

Chapter 15. Optimizing IBM DirectoryIntegrator 4.7 . . . . . . . . . . . 167

Chapter 16. IBM Directory Integrator4.7 — Downloads and related material 169Installation notes . . . . . . . . . . . . 169IBM Directory Integrator 4.7 . . . . . . . . 169

Download instructions . . . . . . . . . 169

Download 4.7 . . . . . . . . . . . . 169New features 4.6 . . . . . . . . . . . 169GUI improvements 4.6 . . . . . . . . . 169Bugs fixed since 4.6 beta2 . . . . . . . . 170

Fixed issues 4.6. . . . . . . . . . . . . 170Script libraries not available to Listeners . . . 170JMS 1.13 can lose queue elements whenIterating . . . . . . . . . . . . . . 170JMS MQ Series does not support topics . . . 170NT/ADSI Connector can clear passwordsduring update . . . . . . . . . . . . 171Connectors: Override Add hook defect inUpdate and AddOnly modes . . . . . . . 171HTTP EventHandler using Auth Connector . . 171XML parser limitations . . . . . . . . . 171Memory leak . . . . . . . . . . . . 171Running out of file handles. . . . . . . . 172If you use https:/ as part of the URL, theAssemblyLine will fail . . . . . . . . . 172In certain situations, the Lotus DominoConnector (and possibly some others) do notrun from the Admin Tool . . . . . . . . 1724.6 Installer fails for some systems . . . . . 172Backward compatibility . . . . . . . . . 172

Known issues 4.6 . . . . . . . . . . . . 173Delta on iterator . . . . . . . . . . . 173Memory leak . . . . . . . . . . . . 174

Chapter 17. Release Notes. . . . . . 175

Appendix A. FAQ IBM DirectoryIntegrator 4.7 . . . . . . . . . . . 177Questions . . . . . . . . . . . . . . 177

Installation and licensing . . . . . . . . 177Writing AssemblyLines . . . . . . . . . 177Security . . . . . . . . . . . . . . 177Error messages . . . . . . . . . . . . 177Limitations . . . . . . . . . . . . . 178Third party software . . . . . . . . . . 178

Answers . . . . . . . . . . . . . . . 178Installation and licensing . . . . . . . . 178Writing AssemblyLines . . . . . . . . . 179Security . . . . . . . . . . . . . . 181Error messages . . . . . . . . . . . . 182Limitations . . . . . . . . . . . . . 182Third party software . . . . . . . . . . 183

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

Appendix C. Notices . . . . . . . . 189Trademarks . . . . . . . . . . . . . . 190

vi IBM Directory Integrator 4.7: 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 %IBMDI_ROOT%/sample directory in theinstallation directories.

© Copyright IBM Corp. 2002 vii

viii IBM Directory Integrator 4.7: 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 7v “Connectors” on page 9v “Scripting” on page 17v “Hooks” on page 23v Chapter 9, “Parsers” on page 111v “EventHandler” on page 15v “Deltas and compute changes” on page 28v “Inheritance” on page 30v “Attribute Mapping” on page 30v “Tasks” on page 32v “The configuration file” on page 33v “Accessing your own Java classes” on page 21v Chapter 13, “Logging and debugging” on page 161v Appendix B, “Dictionary of terms” on page 185

Program components and interfacev “Distribution components” on page 145

Admin toolv “IBM Directory Integrator command line options” on page 144v “Preferences/system properties” on page 149v “System/Java properties” on page 149v “AssemblyLine setting tab” on page 143v “Discover schemas and browsing data” on page 145v “Parameter labels on the Connector/parser tabs.” on page 148v “JDBC Client” on page 147v “LDAP Client” on page 148

IBM Directory Integrator serverv “IBM Directory Integrator command line options” on page 144

IBM Directory Integrator componentsv Chapter 7, “EventHandlers” on page 93v “Connector availability and reference” on page 41v “Parser availability and reference” on page 111

© Copyright IBM Corp. 2002 1

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

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 130v “The AssemblyLine Connector object” on page 129v “The Raw Connector object” on page 131v “The Entry object” on page 132v “The FTP object” on page 134v “Main object” on page 135v “The shellCommand object” on page 136v “The status object” on page 136v “The system object” on page 137v “The task object” on page 141v “AssemblyLine Debugger” on page 161

2 IBM Directory Integrator 4.7: Reference Guide

Chapter 2. Getting Started Guide

IBM Directory Integrator 4.7: Getting Started Guide is a brief tutorial and introductionto IBM Directory Integrator 4.7. You need Acrobat Reader to read the IBM DirectoryIntegrator 4.7: Getting Started Guide as it is in PDF format.


Chapter 3. Supported platforms and known issues

IBM Directory Integrator 4.7 ships with IBM JRE 1.3.1.

The following are the platforms supported for IBM Directory Integrator 4.7. 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.1 or later– SuSE 7.2 or later

v Linux s/390– RedHat 7.1 or later– SuSE 7.0 or later, kernel 2.2.16


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 want tosort data. This kind of processing can be implemented using your choice of scripts,Java™ libraries and standard IBM Directory Integrator functionality (like poolingthe data to a sorted datastore, for example, ODBC Connector) and then reading itback 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.

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).v Connectors. Two or more Connectors that are plugged into your data-source (file

system, ldap, database, com-port etc.) At least 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 aurl-Connector or a file Connector), the Connector has a Parser associated with it.As for Connectors, you can write your own but a set of standard Parsers 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 Component, that just contains code.

v The workobject 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 30.

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 Activated″ 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 Activated″ 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, you must make sure there exists anEntry provided by a calling Handler or set in the Prolog. If no Working Entryexist, no Connectors are called.

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 must have at least oneConnector operating in Iterator mode. If you don’t have an iterator theAssemblyLine has no data feeding it. You can have multiple Connectors asiterators: The AssemblyLine starts with the first iterator and continue with the nextafter draining each iterator in the AssemblyLine.


Starting from an EventHandler or scriptWhen 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). Passing an initial working entry causes the AssemblyLine torun through the list of Connectors once before terminating. You can investigate theresult (which is the working entry when the AssemblyLine terminates) by usingthe (getResult()) function. See also “(runtime provided) Connector” on page 86

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

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 assembly 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. For example,the Sample1 AssemblyLine in the default configuration has two Connectors namedinput and output.

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 ODBC, 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.

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

Connectors operate in the following modes: Iterator, Lookup, AddOnly, Update, Deleteand Passive. 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.

How do Connectors share data?Connectors not in Iterator mode have their data passed through the work object. Ifno work object exist because you have no Iterator, the non-iterator Connectors arenot called. You can create your own Working Entry in the Prolog by:

Chapter 4. IBM Directory Integrator concepts 9

init_work = system.newEntry(); // Create a new Entry 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.

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 “How doConnectors share data?” on page 9) should contain at least one Connector inIterator mode. Iterators (if we call the Connectors in Iterator mode this way)supply the AssemblyLine with data. If an AssemblyLine has no Iterator it is uselessbecause its Connectors are passed nothing to process.

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 AssemblyLineIf you have more than one Connector in Iterator mode, these Connectors arestacked in the order in which they appear in the configuration and processed oneat the time. An initial work Entry is treated as coming from an invisible Iteratorprocessed 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 modeThe most common pattern for using a Connector in Iterator mode should be:1. Add a Connector in Iterator mode to your AssemblyLine.2. Choose the configure... link from IBM Directory Integrator Admin user

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

be used).4. Go to the Attributes section (tab) of the Configure Connector dialog.5. Click Connect to connect to the data source.


6. Click Query Schema (or Next if Query Schema is not supported) to retrieve anEntry’s Attributes.

7. In the ″Attribute Map″ Connector’s section push the ″Select″ button and markall 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 modeConnectors in Lookup mode are used to retrieve particular Entry’s attributes from adata source by other most often key Entry’s attributes (already retrieved fromanother data source or set by the Administrator). Lookup Connectors give thepossibility to join data from different data sources using the relations among theentities 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 user interface - each Lookup Connector has an associated Link Criteria tab.The tab defines the rule for finding relevant entries. The Link Criteria rule itself iseither a conjunction of simple conditions required for certain Entry’s attributes or amore general Connector specific mini script.

Note that the Link Criteria may identify more than one Entry (these Entries arecalled Duplicates).Lookup Connectors have an option that allows/disallowsDuplicates. You can control this option from the ″Allow Duplicates″ check-box.v If ″Allow Duplicates″ is turned off (default state) and Duplicates appear then:

– if the ″Multiple Entries Found″ Hook is not enabled, the work Entry beingprocessed is skipped (i.e. not passed to the other Connectors in theAssemblyLine) if the ″On Error″ Hook is not enabled. If the ″On Error″ Hookis enabled it should handle the situation.

– if the ″Multiple Entries Found″ Hook is enabled, the custom script placedthere should handle the situation.

v If ″Allow Duplicates″ is turned on and Duplicates appear then automatically thefirst of the Duplicates is used. If no additional processing is performed in any ofthe Hooks available, the rest of the Duplicate Entries are ignored. However theycan be handled according to user-defined logic by scripting in the ″Lookup OK″Hook. See On Success, page 27 for code example on this.

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

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

look up in).4. Go to the ″Attributes″ section (tab) of the ″Configure Connector″ dialog.5. Push the ″Connect″ button to connect to the data source.6. Push the ″Query Schema″ button (or the ″Next″ button if ″Query Schema″ is

not supported) to retrieve Entry’s Attribute.7. In the ″Attribute Map″ Connector’s section (tab) push the ″Select″ button and

mark all Attributes you need in your integration process (these include theAttributes used for looking up).

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


9.

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 modeThe most common and simple pattern for using a Connector in AddOnly modeshould be:1. Add a Connector in AddOnly mode to your AssemblyLine.2. Choose the ″configure...″ link from IBM Directory Integrator Admin user

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

source to be used).4. In the Connector’s ″Attribute Map″ section, click Select and mark all working

Attributes you need in your integration process. You can also create your ownAttributes and calculate their values through scripting.

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 LinkCriteria section in the same format as in the Lookup mode. If no such Entry isfound, a new Entry is added to the data source. If one such Entry is found, it ismodified. If more than one entry matches the Link Criteria, the ″Multiple EntriesFound″ Hook is called. Furthermore, each attribute can be tuned whether to bemodified or added, when respectively Modify or Add operation is performed.When doing a Modify operation, only those attributes that are marked as Modify,are changed in the data source. If the Entry passed from the AssemblyLine doesnot have a value for one attribute, the Null Value Behavior for that attributebecomes significant. If it is set to ″Delete″, the attribute does not exist in themodifying entry, thus the attribute cannot be changed in the data source. If it is setto ″NULL″, the attribute exists in the modifying entry, but with a null value, whichmeans 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 modeThe most common and simple pattern for using a Connector in Update modeshould be:1. Add a Connector in Update mode to your AssemblyLine.


2. Choose the ″configure...″ link from IBM Directory Integrator Admin userinterface.

3. Set values for Connector’s parameters (usually specifying the output datasource to be used).

4. Go to the ″Attributes″ section (tab) of the ″Configure Connector″ dialog.5. Push the ″Connect″ button to connect to the data source.6. Push the ″Query Schema″ button (or the ″Next″ button if ″Query Schema″ is

not supported) to retrieve Entry’s Attributes.7. In the ″Attribute Map″ Connector’s section push the ″Select″ button and mark

all Attributes you need to update in your integration process. Through the″Add″ and ″Modify″ check-boxes you can specify for each Attribute whether itshould be modified or added when respectively Modify or Add operation isperformed.

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 modeThe most common and simple pattern for using a Connector in Delete mode shouldbe:1. Add a Connector in Delete mode to your AssemblyLine.2. Choose the ″configure...″ link from IBM Directory Integrator Admin user

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

source to be used).4. In the Link Criteria tab of the Connector, add all criteria for locating the Entry to

be deleted. If exactly one Entry matches the Link Criteria, it is deleted.5. The ″Attribute Map″ section is ignored for a Connector in Delete mode.

Passive modeConnectors in Passive mode are not passed Entries during the AssemblyLineexecution. They are configured by the Administrator and initialized by theAssemblyLine, but never used in the standard AssemblyLine’s execution process.They can be invoked by script code from any of the control points for scriptingprovided by IBM Directory Integrator (see “Scripting” on page 17).

Using the Passive modeThe most common and simple pattern for using a Connector in Passive modeshould 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 131.

The instructions above assume that you only want to use the Raw Connector andParser components of the Passive mode Connector. If you also want to use theAttribute Mapping and Hooks that the Connector provides, you can do thefollowing instead:1. Add the Connector in the mode that matches the way you are going to use it.2. Specify the Attribute Mapping and the Hooks you want.3. Change the mode of the Connector to Passive. The attribute mapping is

remembered.4. You may now use the calls available to the Connector, e.g.

MyPassive.lookup(myEntry). The parameter specified is treated as the work entryby the Passive Connector.

5. Note that the local work entry reference is set to myEntry when you use thecode just above, and you need to save a reference to the original local workentry if you want to continue using it in your Hook or Script Component. TheAssemblyLine work entry reference is not changed, only the reference in thecurrent Hook or Script Component. Of course, if myEntry really is theAssemblyLine work entry, it’s content is changed as well.

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

There are to variants of Link Criteria: Simple and Advanced. Note that usually theConnector goes to the On Error Hook if more than one record match the linkcriteria.

Simple link criteriaIn the simplest case it links a value from the AssemblyLine with a value from theData-source. To be more precise it links the value of an attribute in the work entryto a 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 will 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 criteriaSometime, the Simple Link Criteria is not enough, because multiple link criteria arealways ANDed.

If you select the Advanced Link Mode check box, you are able to script your linkcriteria.

You will have to populate a text string called ret.filter that will provide the LinkCriteria or filter. However, you will have to know the syntax used by theunderlying Raw Connector: An LDAP and an SQL Connector will have differentsyntax.

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 bythe IBM 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.

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, but IBMDirectory Integrator provides some predefined functions to make life easier.

Starting the EventHandlerIn the admin-tool, under the Configuration tab, there is an EventHandler tab. If anEventHandler has the auto-start check-box set, it starts up whenever the Server isstarted with that configuration file. You can disable it by the -D switch as seenunder Line Options.

While working with the Admin-tool, you typically start the server (and thus allyour auto-started EventHandlers) simply by selecting File|Start Server . If you wantto start just one EventHandler, press the EventHandler Object tab, select theEventHandler you want to run, and press the Run Button. Some newEventHandlers even have their own Run button you can press while configuringthe EventHandler.


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” and actions. If the list of conditions is true, the actions under the OnSuccess tab is executed, otherwise the On Fail actions are executed. If theConsumeevent option is set, and actions are executed, the rest of the action map isskipped. It is also possible to temporarily Disable an action item.

ConditionsIf Match any condition is set, the list of conditions evaluates to true when at leastone condition is true, otherwise all conditions must be true for the list to evaluateto true. An empty list of conditions is true. Each condition can be a small script, ora test based on properties or attributes of the event object. See“Attribute/propertynames” on page 17

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 86. If you set the ″Wait for completion″flag, the action list waits for the AssemblyLine to finish, and sets the propertiesAssemblyLine.result, AssemblyLine.error and AssemblyLine.stats. Some of theproperties may not be set, depending on what happens in the AssemblyLine.

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” on page 17v Remove Property/Attribute - See “Attribute/property names” on page 17v 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 Adminas 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 processingwill inevitably come 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 youwill input your script as well as limit the scope of your script to cover just thatsingle goal associated with the control point.


How will 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.

The list of the global objects, see the reference for more information:v main–see “Main object” on page 135.v system–see “The system object” on page 137.v task–see “The task object” on page 141.v status–see “The status object” on page 136.v work –see ″Global Entry instances available in scripting″, page 133.v conn–see ″Global Entry instances available in scripting″, page 133.v event–see ″Global Entry instances available in scripting″, page 133.v current–see ″Global Entry instances available in scripting″, page 133.v error–see ″Global Entry instances available in scripting″, page 133.

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

By understanding the classes and interfaces exposed, you will 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 will be accessed and modified duringthe integration process. Note that each attribute value is in fact an object andbelongs to 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, ″Attributes″ 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 the


specific 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 AssemblyLineProlog Scripting here usually performs any initializing actions needed for the

participants in the AssemblyLine. There is one tab for code that is executedbefore all Connectors have been initialized, and one tab for code that isexecuted after all Connectors have been initialized, but before they are runand the real execution started. The Prolog code is executed once for eachrun of the Assembly Line. ″Prolog″ is the place to declare global variablesyou will need through the execution of the AssemblyLine (e.g., forcounters, average values, etc.)

Script ComponentYou may add Script Components to your AssemblyLine in addition toConnectors, by using the Script button under the Data Flow tab in theAssemblyLine. The Script Components is executed once for each entryprocessed by the Assembly Line, just like a Connector.

Epilog Any finalizing actions are to be coded here. The code is executed once foreach run of the AssemblyLine after all Connectors have finished theirtasks. A common pattern is to release here all resources allocated in the″Prolog″ section.

Scripting in a ConnectorAttribute Map

Custom attribute mapping is performed here. You have to select theattribute, choose the ″Advanced″ Attribute Mapping Mode and input yourscript in the edit window. Remember that after you’ve done all processingnecessary, you have to assign the result value achieved to ″ ret.value ″, i.e.″ ret.value = resultValue; ″.

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

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

Scripting in an EventHandlerReference about scripting in an EventHandler is included in Chapter 7,“EventHandlers” on page 93.

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


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 the Java Class Objects tab under the Configuration of the Admin Tool. Thisworks only if your class has a default constructor (a constructor that does not takearguments). When adding a class object, you must specify two parameters: thescript object name (the name of the scripting object which is an instance of yourjava 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.architech.function.userFunctions2 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");

Scripting in languages without new java.*When you script with a language that does not support the ’new java.*’ instruction,you can use the 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.

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.

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

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

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

3. Modify the 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.

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.

In some cases, the control flow in an AssemblyLine depends on whether aparticular Hook is enabled or not. Until version 4.6.5, a Hook would only beenabled if it contained some code, even if that code was only a comment. Fromversion 4.6.6, a Hook is enabled if it is marked as enabled, even if it contains nocode.

Override HooksFor every Connector mode (except Passive mode) there is a mode-specific OverrideHook. If this Hook is enabled, first the Before Execute Hook is called (if it isenabled), and then the Override Hook, before the flow control continues with thenext Connector in the AssemblyLine. No other Hooks are called, except FailureHooks, 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 signaled by the Connector. Forexample, an Iterator Connector has an ″On Error″ hook that can be programmed tolog or send mail about input errors, or you can modify the AssemblyLine (likeskipping the rest of the AssemblyLine).

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

Hooks called on other eventsThe following Hooks are not Failure Hooks, but still signal an event that could betaken care of:


Multiple Entries Found - Lookup ModeIf the ″Allow Duplicates″ flag is not set and there are more than onematching entry, the Connector calls this Hook if it is enabled. If the Hookis not enabled, this is treated as a failure. After this Hook is called, theLookup proceeds, using the Entry set by the myConnector.setCurrent()method. If you have neglected to call this method, the Entry used is theone returned by myConnector.getNextDuplicateEntry(). This is normally thefirst Entry found, but if you have browsed through all the Entries usingthe myConnector.getNextFindEntry() method, this will be null, causing alookup failure.

Multiple Entries Found - Update ModeWhen there are more than one matching entry, the Connector calls thisHook if it is enabled, otherwise this is treated as a failure. After this Hookis called, the Update proceeds, using the Entry set by theconnectorName.setCurrent() method. If you have neglected to call thismethod, the Entry returned by connectorName.getNextFindEntry() is used.This is normally the first Entry found, but if you have browsed through allthe Entries using the connectorName.getNextFindEntry() method, this will benull, causing an add operation to be performed.

Multiple Entries Found - Delete ModeWhen there are more than one matching entry, the Connector calls thisHook if it is enabled, otherwise this is treated as a failure. After this Hookis called, the Delete proceeds using the Entry set by themyConnector.setCurrent() Method.

Modify NoChangesCalled in some cases in a Connector in Update mode. This causes the″After Modify″ Hook to be skipped, but the ″After Update″ and ″UpdateOK″ Hooks are still called.

List of HooksThe format is:

Admin Tool NameInternal Name (Description)

These Hooks are common for all Connectors.

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 isenabled 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. SeeMultiple Entries Found - Delete Mode, page 25.)


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 is more than one matching entry, and the″Allow Duplicates″ flag is not set, the Connector calls this Hook if it isenabled, otherwise Lookup fail is called. See Multiple Entries Found -Lookup Mode, page 24.

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. If Allow Duplicatesis checked, you might want to iterate through the entries found using thegetNextDuplicateEntry() function of rscTaskComponent. An example ofhow this is used is found in the following example. Unpack the zip-fileand look at the On Success hook of the Lookup Connector where thefollowing code is found):if ( Lookup.getDuplicateEntryCount () > 1 ) {var nextEntry;while ( ( nextEntry = Lookup.getNextDuplicateEntry () ) != null ) {work.addAttributeValue ( "EMAIL_ADDR", nextEntry.getString

( "EMAIL_ADDR" ) );}}

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. See Multiple Entries Found - Update Mode, page 25.)

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

Deltas and compute changes

DeltasAttention: The Delta mechanism should be avoided if you can. Not because itdoes not work or is buggy, 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 Changes functionality of the Update connector modeinstead 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 ordeleted 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. The effect of this is that the firsttime 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.

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,Connector’s ″Configure Delta″ dialog. Note that the key Attribute must be uniquefor each Entry. This Attribute is used to retrieve the copy stored in the localdatabase, and determine this Entry’s state–unchanged, new, modified or deleted.This state is set in the work Entry, and the Entry is delivered to the otherConnectors in the AssemblyLine. You can get an Entry’s state from within yourscripts through the ″getOperation()″ Entry method (in an Output Connector youmay actually have to filter Entries according to their state and this means you haveto 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 Connector 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″. (After version 4.7, the conn.getProperty() used in after getnext hooksupplies you with an entry called delta.old which was the entry as it was beforeit 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.

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 Connector’s ″ConfigureDelta″ dialog. With this option turned on, the following processing occurs after theIterator Connector 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 in


further 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 9, inUpdate mode.

InheritanceAll Connectors have a field called inheritFrom, this field says load all params fromthat one and then apply your own. The inheritFrom is recursive (e.g. myldap couldinherit from corpldap that could inherit from metamerge.LDAP

The same goes for attribute maps and hooks in the AssemblyLine configuration:Inside the Administrator program, you will see these as choices for the Connector.

When inheriting attribute maps the Connector from which you inherit must be inthe Connector Library (a separate tab in the Administrator program). Add aConnector to the library, open it and the The Configuration tab ″Other″ lets youspecify the attribute map and hooks. Change the type field to edit the varioushooks.

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.

Attribute Mapping from an input Connector can been perceived as a form ofstandardising 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.

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 IBMDirectory 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 Connector has the jdbcExposeNullValues letting you map NULL values tomissing 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. This was theonly behavior in version 4.

Default BehaviorOn Attribute mapping level, default is Settings. For AssemblyLine Settingsthis is Settings.

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

PassiveThis depends on the methods which are called in the Connector when it isinvoked from other places in the AssemblyLine or an EventHandler.

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

The task object is the thread that executes the AssemblyLine. For each Connector inthe AssemblyLine, there is a rscTaskComponent class encapsulating eachConnector. Each Connector is automatically declared by their names (as given inthe AssemblyLine configuration). Hence, name the Connector such that they arevalid names in the selected scripting language.

See also the “Main object” on page 135 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.

There are different ways of avoiding this, one of them being to wait forAssemblyLines to finish before you start a new one using the join() call : The code:// 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 a simple ASCII file. YourAssemblyLines, Connector Libraries, preferences etc. are saved in this file.

In the simplest case, you have everything in one configuration file. However, thereare many 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 passwordIf the External Properties File is defined (you might need to restart the Admin Toolto make it active), an External Properties tab is visible in the Configuration tab.


You can define your own fields here and give them values. These values can beretrieved as drop-down values if you click on the label of a parameter field: This istypically used to exclude some secret or site specific information from youconfiguration file.

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

Export, import and includeConfiguration Files, AssemblyLines, Connectors, EventHandler etc. can be exportedin order to be reused in other configuration files. Export, Import and Include isavailable from the File Menu.

Export does not export recursively, so if you want to export an AssemblyLine youhave to export all it’s components.

Import copies the contents of the target file or URL into the active configurationfile: Later change in the target is not reflected in the configuration file.

Include makes a link to a URL or a plain file, and each time the Server or theAdmin Tool is started, it is included when the configuration file is read. Theparameter is first assumed to be an URL, and if it is illegal a filename is assumed.

Notes:

1. The Include is not done before the next time you read in the AssemblyLine.2. The configuration file’s system properties, external properties and Java

Libraries are not included.

Include has two parameters: Include First (IF) and Overwrite Current (OC).Include First means that the file is included before the master configuration is readin. This means that the master configuration file wins name conflicts. OverwriteCurrent is the opposite: The master file is read in first and might be overwritten bythe include files.

When the master configuration file is read, it always overwrites existing definedcomponents. Use IF false and OC true in order to overwrite the masterconfiguration.

The following describes the possible combination of OC/IF:

Both falseRead in all other IF files as well as the master configuration, include thisfile but skip already defined components

IF False | OC TrueRead in all other IF files as well as the master configuration, include thisfile and overwrite already defined components

IF True | OC FalseRead in this include file and then the rest of the master configuration file.Ignore elements in the master configuration that have already beendefined.


Both TrueRead in this include file first, and overwrite existing components (relevantif other configuration file have been included as well). Then read in themaster, overwriting existing components.

IBM Directory Integrator Secure Sockets Layer SupportThe IBM Directory Integrator Server 4.7 has the ability to have securecommunication with those directories supporting Secure Sockets Layer (SSL)security protocol. For SSL configuration of the IBM Directory Server, see the IBMDirectory server v5.1: Administration Guide and IBM Directory Server-Installationand Configuration Guide v5.1.

The following connectors and event handlers support SSL with the properlyconfigured IBM Directory Servers:v Connectors

– HTTPClient2– LDAP– NetscapeChangeLog– SecureWayChangeLog

v EventHandlers– HTTPEventHandler– LDAPEventHandler– SecureWayEventHandler

Securing the connection between IBM Directory Integrator andservers with SSL (IBM Directory Integrator as a client)

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 jks-type keystore file already, create a keystore file using

any key tools, such IBM GSkit or keytool from Jacarta Tomcat App server.Create a jks-type keystore file for IBM Directory Integrator.

4. Using a key tool, import the certificate to the keystore file as a root authoritycertificate if the server certificate is a self-signed certificate.

5. Edit %IBMDI_ROOT%/global.properties file for the keystore file location,keystore file password and keystore file type. In the current release, we supportjks type only.# server authenticationjavax.net.ssl.trustStore=D:\Tomcat4_0_3\clientStore.jksjavax.net.ssl.trustStorePassword=secretjavax.net.ssl.trustStoreType=jks# client authentication : for the case client authentication

is supported in the directory server.javax.net.ssl.keyStore=D:\Tomcat4_0_3\clientStore.jksjavax.net.ssl.keyStorePassword=secretjavax.net.ssl.keyStoreType=jks

6. Edit %IBMDI_ROOT%/_jvm/lib/security/java.security for the securityprovider 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 with SSL (IBM Directory Integrator as a server)

The following steps are required to enable SSL support for IBM DirectoryIntegrator as a server:1. Configure a directory 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 jks-type keystore file and a personal key already, create a

keystore file (jks-type) and a personal key using any key tools, such IBM GSkitor keytool from Jacarta Tomcat App server. Create a jks-type keystore file forIBM Directory Integrator.

4. If the certificate in the server is a self-signed certificate, export the certificate.5. Using a key tool, import the certificate to the keystore file in the client as a root

authority certificate if the IBM Directory Integrator certificate is a self-signedcertificate.

6. Edit %IBMDI_ROOT%/global.properties file for the keystore file location,keystore file password and keystore file type. In the current release, we supportjks-type only.# server authenticationjavax.net.ssl.trustStore=D:\Tomcat4_0_3\clientStore.jksjavax.net.ssl.trustStorePassword=secretjavax.net.ssl.trustStoreType=jks# client authentication : for the case client authentication

is supported in the directory server.javax.net.ssl.keyStore=D:\Tomcat4_0_3\clientStore.jksjavax.net.ssl.keyStorePassword=secretjavax.net.ssl.keyStoreType=jks

7. Edit %IBMDI_ROOT%/_jvm/lib/security/java.security for the securityprovider list.security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.crypto.provider.IBMJCA

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

Replacing security from IBM JCE and JSSE to another vender1. Download the new JCE and JSSE you want to replace the existing JCE and

JSSE. They might be in a zip file.2. Extract the zip files into a temporary folder.3. Locate the following JAR files for JSSE:

jcert.jarjnet.jarjsse.jar

Place them in the jars folder located in the directory where IBM DirectoryIntegrator 4.7 is installed.

4. Locate the following JAR files for JCE :jce1_2_2.jarlocal_policy.jarsunjce_provider.jarUS_export_policy.jar


Place them in the jars folder located in the directory where IBM DirectoryIntegrator 4.7 is installed. Please note,

Note: These jar file names are vendor-specific. Names might be slightydifferent for other vendors or versions.

5. The global.properties file needs to be changed. This file is in the installdirectory of IBM Directory Integrator 4.7. Open this file and locate these threelines:com.metamerge.sslProvider=com.sun.net.ssl.internal.ssl.Providercom.metamerge.securityProvider=com.sun.crypto.provider.SunJCEcom.metamerge.handlerPkgs=com.sun.net.ssl.internal.www.protocol

These lines are the correct lines for the JCE and JSSE for Sun. To change theselines, locate the folders where JCE and JSSE were extracted. For example, if youextracted JCE into C:\temp, then the Provider class (might be namedJSSEProvider or VendorNameJCE) is located atC:\temp\com\sun\net\ssl\internal\ssl\Provider.class. The third line,handlerPkgs, is similar except there are no classes in this path. The path endswith the folder named protocol.

6. The myclasspath variable in the files miadmin (miadmin.bat for windows) andmiserver (miserver.bat for windows) need to be changed. This enables IBMDirectory Integrator to locate the jars.a. To edit the classpath in those files, open the files. The files are in the install

directory (same as global.properties).b. Look for myclasspath= in the file. This line is where the change needs to be

made.c. Go to the end of the line, and append the location of your install directory

(this is already there for other JAR files) along with /jars/ and the name ofeach JAR file. An example of one jar file being added is"C:\Program Files\IBM\IBMDirectoryIntegrator4.7\jars\sunjce_provider.jar"

Each JAR file must be added like this.

Note: Quotes are needed on Windows platforms for spaces to be allowed inthe folder names and semi-colons to separate each JAR path. ForUnix platforms, quotes are not needed and colons are used, ratherthan semi-colons.

d. You might also want to remove the path from the previous Java securities,but this is not required for the product to work.

e. To check if you correctly followed these steps you can edit the java executecommand from javaw to java. For example, from:start _jvm\bin\javaw -cp %myclasspath% ...etc

To:_jvm\bin\java -cp %myclasspath% ...etc

These lines are found in the same file as the myclasspath= line. By changingthis command, a console appears in the background.

f. This console shows an error message such asaddProvider ’com.sun.crypto.provider.SuJCE’:java.lang.ClassNotFoundException: com.sun.crypto.provider.SunJCE.

If this does not appear, you have correctly installed other vendor Javasecurities.


v ibmjcefw.jar, ibmjceprovider.jar–IBM encryption engine.v ibmjsse.jar–IBM JSSE.


Chapter 5. IBM Directory Integrator installation instructions

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 next panel diplays the installation process of the product. During the

install process a dialog is displayed.A Java Virtual Machine (JVM) is being installed in

"NAME OF YOUR INSTALL DIRECTORY"and will overwrite the contents of this directory.Do you want to overwrite this directory?

You must click Yes to install the product.12. The product finishes installing and continues to the final panel. This is

another information panel telling you that the install completed successfully.13. 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 installedand the disk space the product requires.

10. Click Next to continue.11. The next panel diplays the installation process of the product. During the

install process a dialog is displayed.A Java Virtual Machine (JVM) is being installed in

"NAME OF YOUR INSTALL DIRECTORY"and will overwrite the contents of this directory.Do you want to overwrite this directory?

You must click Yes to install the product.12. The product finishes installing and continues to the final panel. This is

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

Uninstalling on Windows platforms1. Go to Control Panel—>Add/Remove Programs.2. Locate IBM Directory Integrator 4.7, 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.


Chapter 6. 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 therscTaskComponent in addition to the methods/properties of the Raw Connector.

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

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

ADSI Connector (AD/NT)?????

This means that for ADSI, you have to choose one of three possiblevariations for the connections, and the supported modes will depend onthe variation you choose. See “ADSI Connector” on page 43.

Btree ConnectorI A D L U

Command Line ConnectorI A

IBM Directory Changelog ConnectorI

EMI/UCP ConnectorA

Fiorano MQ (JMS)I A +

File SystemI A

FTP ConnectorI A

GSM Phone ConnectorI A D L U

HTTP Client ConnectorI A

HTTP Client2 ConnectorI A

HTTP Server ConnectorI A


HTTP Server2 ConnectorI A

IBM MQ Series (JMS)I A +

IBM Directory Changelog ConnectorI

JDBC I A D L U

JMS ConnectorI A

JNDI I A D L U

LDAP I A D L U

Lotus® Notes™

I A D L U

Mailbox ConnectorI A D

Memory Stream ConnectorI A

Netscape/iPlanet Changelog ConnectorI

NT4 I A D L U

ODBCI 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 86.

SMPP ConnectorI A

SNMP ConnectorI A L

Sonic MQ (JMS)I A +

TCP/URL 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 86.

Legend for the Supported Mode columnsv I–Iteratorv A–Add


v D–Deletev L–Lookupv U–Updatev ?–Conditionally supported, see documentationv +–Newer version supporting exists

Script-based ConnectorsFor a list of Supported Modes, see “Legend for the Supported Mode columns” onpage 42.

(Generic Connector)? ? ? ? ?

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

Microsoft® Outlook Contacts Connector)I A D L U

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

JDBC - Oracle 8 Thin Driver ConfigurationI A D L U

ODBC - Specifying database paths directlyI A D L U

ADSI ConnectorIBM Directory Integrator has no native support for the ADSI API. If you want tointegrate with ADSI you have three choices:1. Use the NT4 Connector which gives you access to the Active Directory (AD)

fields that were available in NT4/SAM2. Use the LDAP Connector, since AD can be accessed through LDAP3. Use the ADSI interface by scripting your own Connector using VB Script

The ADSIConnector 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. Full functional specification ofADSIConnector, architecture description as well as hardware and softwarerequirements can be found here.

PreconditionsIn order to successfully run ADSIConnector 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.

Chapter 6. Connectors 43

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

ConfigurationThe Connector needs the following parameters:

ComputerNameThe name of the machine (for example, ntserver01) or its IP address (forexample, 212.52.2.218) where the Connector will operate.

EntryTypeShould be set to either User (specifying that the Connector will operatewith data structured by Users) or Group (specifying that the Connectorwill operate with data structured by Groups).

UserNameIf set blank no logon on the specified machine is performed andADSIConnector will have the privileges of the process in which IBMDirectory Integrator is run. If some value is set then the Connector willattempt to logon on the ComputerName machine with this user name andthe password 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.

Constructing link criteriaOne has to construct link criteria when using the Connector in Lookup, Updateand Delete modes. ADSIConnector 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 ). Consist 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 rowsas follows (the order is vital):1. First 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 equals


v Value is set to True to indicate that the group account specified in the firstrow is global and False to indicate that the group account is local. Can alsobe configured by a template to receive True or False values indicating globalor local group accounts.

User/Group account namesOn Domain Controller Machine

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

Setting user’s passwordRemember that user’s 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’s 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

DownloadsIncluded in base product.

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


connectorTypecom.architech.connector.Btree

filePathThe file path where the Btree data is stored

keyAttributeThe attribute name giving the unique value for the entry

selectionModeSpecify 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 iteratorthe AssemblyLine will store a sequence property in the database and alsoadd a sequence number to each entry read from the source.

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


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.


connectorTypecom.architech.connector.rscCommandLine

commandLineThe command line to execute

parser The Parser responsible for interpreting/generating entries.


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

TCP// This sample 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 sample 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 );}

EMI/UCP ConnectorThe EMI/UCP Connector implements a common Short Message Service protocolfor submitting SMS messages.


connectorTypecom.architech.connector.rscCOMPort

commPortThe COM port where a modem is present (COM1,19200)

accessNumberThe telephone number to dial.

DownloadsIncluded in base product

See also“SMPP Connector” on page 88.

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 mode


connectorTypecom.architech.connector.rscFileConnector

fileMode[input | output | append]

filePathName of file to read or write

parser The name of a Parser to handle the contents of the file

fileAwaitDataTimeoutThis parameter is specified as a positive number, the Connector will wait


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

See also“URL Connector” on page 91.

FTP ConnectorThe FTP Connector is a transport Connector that requires a Parser in order tooperate. The Connector reads or writes a data stream that can either be a file or adirectory listing. Think of the FTP Connector as a remote read/write facility, notsomething you use to transfer files.

This documentation is correct for the FTP Connector that comes with IBMDirectory Integrator 4.7.


connectorTypecom.architech.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. You usually want ASCII, since you get a line at the time

NoteIterator mode supports ftpOperation get and list, Addonly supports put.

See also“The FTP object” on page 134, “URL Connector” on page 91, “HTTP ClientConnector” on page 50, “HTTP Server Connector” on page 55


GSM Phone ConnectorThe GSM phone Connector communicates with a mobile phone using extended ATcommand sets to access the mobile phone’s telephone book. The Connector hasbeen tested with Siemens S25 and Nokia 7110 but should work with GSM.05.07compatible phones.


connectorTypecom.architech.connector.SiemensS25

commPortThe serial port and baud rate where the phone is accessible (COM1,19200)

phoneBookSpecify ″SM″ for SIM Card or ″ME″ for mobile phone.


HTTP Client Connector

Note: You should use the HTTP Client Connector Version 2, as HTTP ClientConnector described below is an old version.

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

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 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 will be 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.architech.connector.HTTPConnector

url The HTTP page to request

usernameIf set the HTTP Authorization header will be set using this parameteralong with the password parameter.

passwordUsed if username is specified.


parser If specified this Parser will be used to generate the posted data for an Addoperation.

SamplesIn 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 will be 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.metamerge.com/lookup.cgiSearch Criteria:name equals johnmail equals doe.com

Resulting URL:http://www.metamerge.com/lookup.cgi?name=john&mail=doe.comThe Lookupfunction will ignore the operand. So if you specify contains instead of equals theConnector will still construct the URL as if equals where used.


See also“URL Connector” on page 91, “HTTP Server Connector” on page 55, “HTTP ClientConnector Version 2”

HTTP Client Connector Version 2The 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.

Changes from earlier versionsThe HTTP Client Version 2 uses metamerge.HTTP as internal parser if no parser isspecified. 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.

Special attributesWhen using the Connector in Iterator or Lookup mode the following set ofattributes/properties will be 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 request


name 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 Version 2 has the following parameters:

connectorTypecom.architech.connector.HTTPConnector2

url The HTTP page to request

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 will be set using this parameteralong with the password parameter.

passwordUsed if username is specified.

parser If specified, this Parser will be used to generate the http.body contentwhen sending data. The parser gets an entry with those attributes wherethe name does not begin with ″http.″ Also, this Parser (if specified) will getthe http.body for additional parsing when receiving data.

SamplesIn 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 will be 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 91, “HTTP Server Connector Version 2” on page 56,“HTTP parser” on page 114.

HTTP Server Connector

Note: You should use the HTTP Server Connector Version 2, as HTTP ServerConnector described below is an old version.

The 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 will be returned as an attribute(″postdata″) in the 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.architech.connector.rscHttpServer

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 91, “HTTP Server Connector Version 2”.

HTTP Server Connector Version 2The 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 will be returned as an attribute(″postdata″) in the returned entry.

The HTTP Server Version 2 uses metamerge.HTTP as internal parser if no parser isspecified. Version 1 had hardcoded internal java-code and is deprecated.

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.architech.connector.HTTPServer

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 91, “HTTP Client Connector Version 2” on page 52,“HTTP parser” on page 114.

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.

ConfigurationAll parameters described below give the means to configure the JDBC Connector.They are usually set through the IBM Directory Integrator Admin–either from the″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.architech.connector.rscJdbc

jdbcSourceSee documentation for your JDBC provider. It is called JDBC URL in theadministrator. See also ″jdbcSource″, page 59.

jdbcLoginThe username parameter. Only the tables available to this users will beshown.

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

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

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.

See also“Oracle8 JDBC Driver” on page 85.

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 a variety of JMS-based systems. The currentversion has been tested with SonicMQ and FioranoMQ and MQ Series. TheseJMS-based systems are very similar, with some differences in the parameters. Thecode is the same for all of them, except that they need separate initialization code.They need different libraries from the vendor.

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


connectorTypecom.architech.connector.rscJMSConnector

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.

Parser If specified, the Text message of a JMS message will be parsed using thisParser.

jms.driverSelect the JMS server type


jms.autoAcknowledgeIf true, each message is automatically acknowledged by this Connector. Iffalse, you must manually acknowledge the receipt of a JMS message.

Specific topicsHere are some files that you need to add to the IBM Directory Integrator jarsdirectory or to the classpath:

Soniq MQclient.jar

Fiorano MQfmprtl.zip (must to be added to the classpath)

IBM MQ Seriescom.ibm.mqjms.jar, com.ibm.mq.jar, jms.jar

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.architech.connector.rscJNDI

java.naming.factory.initialThe class name for the JDNI 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”.

LDAP Connector

Note: A newer version of this Connector exists.

This documentation covers the LDAP connector you will get when you downloadIBM Directory Integrator 4.7. The new version has improved functionality as wellas fixed bugs.

The 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 sample, 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.hklc.com/objectclass.html?objectclass=person) . You will there see thatyou must 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=metamerge.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.architech.connector.rscLdap

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 cause the directory server to return a specific numberof entries (called pages) instead of all entries in one chunk. Not alldirectory servers support this option.

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 64 for a full explanation. If you are using a LDAP version3 server, you should definitely use this flag as the value of an attributecannot be an empty string.


jndiExtraProviderParamsAdditional JNDI provider parameters. The format is one colon separatedname:value pair on each line.

ldapBinaryAttributesA list of attributes that are treated as binary. The format is one attributename 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 last connectorshould define the list of binary attributes for all the LDAP connectors inthis AssemblyLine if you need to change this from the default.

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 IBM


Directory 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 acouples of work around:

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 4.7” on page 177. This of course, will only work ifyour directory 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 AL would read that file. It turns out to be an effectivesolution when possible. Remember that if you are in a mode where you iteratewhole (and big) directories, you probably are able to do it as batch (as this will 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.

Duplicating a whole directory from a server to anotherUsually, the best way to do this is to export using LDIF from one server, and thenimporting it to the other. If you for some reason want to do this on-the fly, readthe following discussion.

IBM Directory Changelog ConnectorThe IBM Directory Changelog Connectors are a specialized instance of the LDAPConnector. This Connector contains logic to iterate the ChangeLog. It will returnvarious attributes, one being the changes attribute: The Connector will returnchanges as something that looks like a standard attribute, but it is in fact of theEntry 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.architech.connector.rscLdap

ldapUrlThe LDAP URL for the connection. (ldap://host:port)

ldapUsernameThe distinguished name used for authentication to the server

ldapPasswordThe credentials (password)

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 namedchangenumber=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 accrdingly.

See also“JNDI Connector” on page 61

Lotus Notes ConnectorThe Notes Connector provides access to Lotus Domino™ databases. The Connectoruses HTTP and IIOP (see “Ports” on page 67 for port number) to access theDomino server, so you must make sure these services are started and accessiblefrom the host you are running this Connector.


Provided that you use a Domino server R5, supported Notes versions are 4.5, 4.6and 5.0. Without a Domino server R5, you will not be able to access any Notesbases (neither R4 or R5) with this connector.

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 their mailboxes. This musteither be done manually or by using the ″adminp″ system tool. Users can beprovisioned in and out of Notes by applying staging databases and integratingwith adminp through Notes scripting.


connectorTypecom.architech.connector.rscNotes

dominoLoginThe username to use for authentication against the server.

dominoPasswordThe password to use.

dominoHostThe IP hostname or address to the domino server.

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.


PortsIIOP default uses port 63148, check for actual port number in Domino Administrator-> Configuration -> IIOP.

SecurityIn order to have IBM Directory Integrator access your Domino server, you mighthave to allow it through Domino Administrator -> Security -> IIOP restriction . Theuser 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 has to be configured for allowing anonymous access. Ifnot, the current version of the Connector will not to be able to connect to theDomino IIOP server.

The current Notes Connector cannot use SSL in HTTP connections to the DominoWeb Server, but this functionality should appear in newer versions.

Mailbox 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

Configurationclass com.architech.connector.Mailbox

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.

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“Mailbox EventHandler” on page 100

Memory Stream ConnectorThe Memory Stream Connector can read from or write to any stream, but is mostoften used to write into memory, where the formatted data can be retrieved later.The Connector can only operate in Iterator, AddOnly or Passive Mode. Thebehavior 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: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.

ConfigurationconnectorType

com.architech.connector.rscStreamConnector

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.

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 73 for a full functional specification of NT4Connector, architecture descriptionas 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.


ComputerNameThe name of the machine (for example, ntserver01 ) or its IP address (forexample, 212.52.2.218 ) where the Connector will operate.

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 neverexpires″.

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.


NT4 Connector functional specifications and software requirementsThe 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, Passive.

Extract user/group dataNT4 Connector reads both user and group information from the NT4 repository,including group and user metadata as well as relationship information (i.e., usersgroup and groups group membership). NT4 Connector reads both local anddomain user/group data. Data will be read from NT and organized and providedin the containers expected by the IBM Directory Integrator engine.

Add user/group dataNT4 Connector adds user information to both local machines and domaincontrollers.

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 membershipNT4 Connector modifies group membership for both local and global groups. Inline with NT security restrictions, members can be assigned 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 dataNT4 Connector modifies user and group properties on both local machines anddomain controllers. When connected to a domain controller, the connector is ableto modify the properties of both local and global groups. Modifying usermembership in groups is addressed in the previous section.


Delete user/group dataNT4 Connector can remove users from both local machines and domaincontrollers.

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

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

EntryName 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 andGroup 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 rscConnector class.

Obtain user’s data from NT databasePreconditions:

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 twostatesof 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 75.

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

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

Exceptions:



v The group name could not be found in NT database (if a search of aparticular group is performed).

Add user in NT databasePreconditions:


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


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


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


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


Start action:This use case begins when the assembly line requests that the NT4Connector modify user account information.

Actions:

1. The specified user account properties are modified. Values can be setfor all user entry’s attributes except the following attributes:v PasswordAgev PrivilegeLevelv AuthFlagsv ApplicationsParamsv LastLogon


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


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


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


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 baserscConnector class) for defining functionality of the connector in the followingmodes: Iterator, Lookup, AddOnly, Update, Delete, Passive.

Error handling: Errors that occurred during the execution of WinAPI functionswill be transformed to exceptions in the native C++ code. These exceptions arethen transformed to java exceptions and thrown through JNI in the java layer of


the connector. From the java layer of the connector they are handled by the IBMDirectory Integrator exception handling mechanism.

Hardware requirementsNT4 Connector requires the standard hardware configuration for IBM DirectoryIntegrator.

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.

Oracle8 JDBC DriverThis Connector provides access to Oracle 8 databases using Oracle’s providedJDBC driver. Please refer to your Oracle installation and documentation for a fulldescription of the driver. Using this driver with the IBM Directory Integratorserver requires the Oracle JDBC class library to be available. Make sure theClasses111.zip file (from the \Oracle\Ora8x\JDBC\lib) is in your Java class path,or copy the file to the ″lib/ext″ directory of your Java runtime directory, or copythe file to the <installdir>/jars directory.

ConfigurationIf you choose the Thin driver you do not need more than the classes111.zip fileabove. This provides a pure cross-platform Java environment with no OSdependencies. Configure an instance of the JDBC Connector with the followingvalues.

jdbcDriveroracle.jdbc.driver.OracleDriver

jdbcSourcejdbc:oracle:thin:@<host.domain>:<port>:<SID>

Substitute <host.domain> with the IP address or name for the Oracle server. Theport (usually 1521) and SID must also be configured.

NoteAn SQL DATE only contains a date, but the Oracle SQL DATE type may containboth a date and a time. If you want to store a DATE value containing both a dateand a time (different from zero), you should make sure you provide an object oftype java.sql.Timestamp, as you could with this Attribute Mapping:a = java.util.Date();ret.value = new java.sql.Timestamp (a.getTime());

metamerge.Script1 is a sample Script Connector for metamerge.Oracle8 andmetamerge.Oracle8Thin. This sample script connector is a starting point. If youopen up the connector in the Base Templates window, and press the Script tab, yousee the connector. It is just a list of mostly empty templates, so that you don’t needto write the function headings, and you spell the function names correct. The only


function that is filled in is getNextEntry, making this a connector that can operatein Iterator mode, giving a total of 101 entries, each with one attribute, calledcounter, with values from 0 to 100.

See also“JDBC Connector” on page 57.

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

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 is


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

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 132 for a description of the entry object.

The search objectGo to “The Search criteria object” on page 135 for a description of the search object.

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.architech.connector.rscScriptConnector

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!

See also“Script parser” on page 121, “JavaScript Connector” on page 155.

SMPP ConnectorThe SMPP Connector implements a common Short Message Service protocol forsubmitting SMS messages. The Connector operates in either transmitter or receivermode according to the protocol specification.

In transmitter mode the Connector will deliver SMS messages to the remote SMSservice centre using the following entry attributes:

originatorThe originator’s GSM phone number

recipientThe recipient’s GSM phone number

messageThe message to send (max 160 bytes)

report If set to ″1″ a report is requested.


connectorTypecom.architech.connector.rscEmiUcpConnector


sms.systemIDThe SystemID used in the bind request

sms.passwordThe password used in the bind request

sms.systemTypeThe system type for the local server

sms.versionThe SMSC version (1)

sms.connectormodeSpecify either transmitter or receiver. In transmitter mode the Connector willtransmit SMS messages to its peer. In receiver mode the Connector will waitfor incoming SMS messages from the peer.

sms.remoteSpecify TCP hostname/IPAddress and port number for the remote SMSC.Separate host and port with a comma as in:host.domain.com,5592

sms.src_gsm_tonSource Type of Number

sms.src_gsm_npiSource Number Plan Indicator

sms.dest_gsm_tonDestination Type of Number

sms.dest_gsm_npiDestination Number Plan Indicator


See also“EMI/UCP Connector” on page 48.

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.


connectorTypecom.architech.connector.SNMP

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.

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 in = conn.getProperty("in");var out = conn.getProperty("out");var str = in.readLine();out.write ("You said: " + str + "\r\n");out.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 48, “Direct TCP /URL scripting” on page 47,“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.


connectorTypecom.architech.connector.rscURLConnector

url The URL to open (e.g. http://host/file.csv)

parser The name of a Parser to handle the contents of the file


See also“File system Connector” on page 48, “TCP Connector” on page 90, “Direct TCP/URL scripting” on page 47.


Chapter 7. 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 typesThere are two types of EventHandlers. The first (originally called a trigger or portlistener) is an EventHandler that usually resorts to a user defined script to performspecific actions when the event occurs. With these EventHandlers you have fullcontrol but you must code your actions by hand. The second type is a higher levelhandler where you specify conditions and actions using a number of predefinedconditions and actions. The latter is much simpler to use and also provides hookswhere you can execute script code for full control.

For example, there are two versions of the Mailbox EventHandler. The simpleMailbox EventHandler calls into a script when something happens in the mailboxproviding the script access to the mailbox folder, message and some other objects.The second Mailbox EventHandler allows you to specify conditions and chooseactions using drop-down tables and forms. The latter is then easier to configuresince you really don’t have to write a single line of code to handle the event.

For simplicity we will refer to the first type as an EventHandler and the secondtype a simple EventHandler.

Note: You might infer that the simple refers to simple-to-configure. The wordsimple is instead associated with ’providing minimal or no assistance’.

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


asynchronous, 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 Mailbox EventHandler. Please consult each EventHandler’sconfiguration for more details on how they work and how to use them.

EventHandlersThese were introduced in version 4.5 and give a simple GUI requiring very little orno scripting.v Connectorv HTTPv IBM Directoryv LDAPv Mailboxv TCP Port

Listeners: simple EventHandlersListeners are simple EventHandlers that were formerly known as triggers.

These give you more flexibility than the EventHandlers, but at a cost–morescripting. The Script library is not available to these:v AdminPortv Cronjobv FTP Poller (Script example in a zip archive)v Genericv LDAPv Mailboxv Timerv TCP Port

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.architech.switchboard.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 15

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.

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 object

Chapter 7. EventHandlers 95

file = 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 mustbe 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 35.

userCommentA comment for your own use. Not used anywhere

See also“EventHandler” on page 15, “HTTP parser” on page 114

IBM SecureWay LDAPEventHandlerThe IBM SecureWay LDAPEventHandler uses LDAP unsolicited event notificationsto detect changes in an LDAP directory. In order to use the IBM SecureWayLDAPEventHandler your LDAP server must support LDAPv3 unsolicitednotification events. The only LDAP server tested with this EventHandler is theIBM Directory server but other LDAP servers may work as well.


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, ordeleted; 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 SecureWay LDAPEventHandler 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.

ConfigurationLDAP URL

The LDAP URL (ldap://hostname:port)

Login usernameThe 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.

Login passwordThe credentials (password)


ChangeLog Search baseThe search base where the changelog is kept. The standard DN for this iscn=changelog

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

Search ScopeThe scope of events which you want to be notified about. Can be one ofsubtree, level and base

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

InitialChangeNumberIf the file supplied in the ChangeNumber Filename parameter does not exist,then the EventHandler retrieves the changelog entries, starting fromInitialChangeNumber

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

For an IBM Directory installation and configuration guide please seehttp://www-3.ibm.com/software/network/directory/library/.

See also“EventHandler” on page 15, “LDAP EventHandler”

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 the version 3 search control extension. The only LDAP server tested withthis EventHandler is the Netscape/iPlanet directory server (see the “Notes” onpage 64 for more about iPlanet), 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

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.

ConfigurationSee “LDAP Connector” on page 62 for a description of the LDAP configurationparameters.

NotesiPlanet Directory 5.0 has changed the changelog to a proprietary format (seehttp://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 15, “IBM Directory Changelog Connector” on page 65

Mailbox 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.architech.switchboard.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


See also“EventHandler” on page 15

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

Configurationclass com.architech.switchboard.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)

See also“EventHandler” on page 15

Port listener

AdminPort (simple EventHandler)The AdminPort EventHandler allows remote administration of a server.

ConfigurationThe AdminPort EventHandler needs the following parameters:

passwordThe password required to access this service

tcp_portThe TCP port on which to listen for incoming connections

ExamplesIf you want to connect to this service using other tools, you should do this:1. Make an EventHandler with the metamerge.AdminPort template.2. Set a password that you can remember3. Make sure the Auto Start service is checked4. Start IBM Directory Integrator server from the File menu.5. telnet <host name> <port number>

where hostname is the host name where you are running the admin service, andportnumber is the port number you configured for the admin service

6. Type in the commands you want to give. Useful commands are:v auth <password> - This must be the first command you givev stat - Give the names of all AssemblyLines and EventHandlersv star MyAssemblyLine - Start MyAssemblyLine


v stpl MyEventHandler - Start MyEventHandlerv stop Name - Stop all AssemblyLines and EventHandlers named Namev view AL/MyAssemblyLine.log - View the log of MyAssemblyLinev view EH/MyEventHandler.log - View the log of MyEventHandlerv getc - Get the entire configuration filev putc - Use this command to change the configuration file. After this

command, follow up with the content of the entire configuration file, andthen *** on a single line to mark the end of the file. It might be easier to usethe ″File -> Upload to Server″ command of the admin tool.

v exit - This will stop the serverv quit - End this connection


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.

The following are samples for a generic thread:v metamerge.FTPPollerv metamerge.OutlookMailbox

ConfigurationThe port listener needs the following parameters:

class com.architech.trigger.rstGenericThread

scriptEngineScript language (e.g. javascript)

script The script to execute


LDAP listenerThis event handler uses the LDAP event notification mechanism to detect changesin an LDAP directory. In order to use this event handler your LDAP server mustsupport the version 3 (search) control extension.

ConfigurationSee “LDAP Connector” on page 62 for a description of the LDAP parameters.

Script LanguageThe script language used to handle events

Event HandlerSpecify script if you want the EventHandler to call functions in your scriptpage. Specify AssemblyLine if you want to start an AssemblyLine for eachevent. The event object is passed to the assembly line as an initial workentry.


LDAP ConnectorThe LDAP connector to use. This connector must be defined in yourconnector library and provides the search base and search filter for theobjects you will be notified of.

Run Assembly LineThe assembly line to start if Event Handler is Run AssemblyLine

When an event occurs and you have specified a script handler, the appropriatefunction on the script page is called with the relevant objects. Note that the objectspassed to each function depends on the event that occurred. The idleproc functionis called every 10 seconds if nothing has happened. If an error occurs thehandlError function is called. For all normal event notifications the objAdded,objRemoved, objModified and objRenamed are called.


See also“EventHandler” on page 15, “IBM Directory Changelog Connector” on page 65

MailboxListener (simple EventHandler)The MailboxListener periodically scans a POP3/IMAP mailbox for new messages.When a new message (loosely defined as an unread message) arrives, a script iscalled to handle the event.

ConfigurationThe listener needs the following parameters:

class com.architech.trigger.rstMailbox

mailServerThe hostname and optionally port for the mail service

mailUserThe username to use for authentication

mailPasswordThe password associated with mailUser

mailProtocolSpecify ″pop″ or ″imap″

mailFolderThe folder to poll (i.e. INBOX etc..)

script The script to execute for each new message

scriptEngineThe scripting language for script

Script objectsWhen your script executes you have the following objects to work with:

folder The mail folder

sessionThe mailbox session

msg The new message being handled



See also“Mailbox EventHandler” on page 100

TCPListener (simple EventHandler)The TCPListener sits idle waiting for incoming TCP connections on a specifiedTCP port. When a connection is available a script is called to handle the session.


class com.architech.trigger.rstTrigger

tcp_portThe TCP port on which to accept incoming connections

scriptEngineScript engine for script (i.e. javascript, perl etc..)

script Script to handle a TCP connection.

Script objectsWhen your script executes it has four objects available: socket, inp, out and main.See “Script parser” on page 121 for an explanation of the inp and out objects. Themain object has a function for logging messages, main.logmsg(str), and one forstarting AssemblyLines - main.startAL(alname). The socket object is the rawjava.net.Socket object. Consult the Java documentation for how to use this object.

For more information, see the Javadocs material included in the installationpackage.


Timer EventHandler

Note: In versions prior to 4.6.5, this EventHandler was called Cronjob. From 4.6.5 itis also available as Timer. There are no differences between these, but youare encouraged to use Timer as Cronjob might not be available in futurereleases.

The 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.architech.trigger.rstTimer

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


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

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


Chapter 8. Script languages

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. This isdefault rs.cfg, but you can override this with the -c switch to miadmin.

PerlIn order to get a Perl parser to work, you need a version of Perl that supportsWindows Scripting Host (WSH) engines. Only ActivePerl (that you can get for freefrom http://www.activestate.com/) has been verified. Also note that WSH onlyworks on NT/Windows 2000 platforms, so currently you cannot run a Perl parserfrom 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 Perl, so the good news is thatthe general documentation can be used. The Java object JavaObject is accessed as$JavaObject in Perl, 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 Perl 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 132)$entry->setAttribute("Multi1", "foo");

# Add an other value to it (see “The Attribute object” on page 130)$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");

Perl 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 121).sub writeEntry{

$result = $entry->getString("Line");$out->write ( $result );

}

sub readEntry{$_ = $inp->readLine();$entry->setAttribute("Line", $_);

}

Script languagesThe IBM Directory Integrator supports variety of script languages. Someinformation is found under Parsers, mostly what functions you must provide inorder to make a Parser. However, in order to use a script language, the IBMDirectory Integrator must 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 20 for moreinformation..

The included JavaScript interpreter is Rhino 1.5. Refer to the Appendix A, “FAQIBM Directory Integrator 4.7” on page 177 if you want to replace this with a newerversion.

WSH-based script languagesPerl

Visual Basic

Chapter 8. Script languages 109

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.

You can write your own parsers if needed, an example of how to do so is foundthrough the regular expression parser. From version 4.6 every parser needs a publicstring getVersion() method, and the jar file should include a metamerge.inf file withinformation about the parser. An example of a metamerge.inf file can be extractedfrom jar file of the regExp parser.

Base parsersv CSV (Comma Separated Values) Parserv DSML Parserv CDS-EDB File Parserv Fixed Parserv HTTP Parserv LDIF Parserv Line Readerv Regular Expression Parserv SOAP Parserv Script Parserv Simple Parserv XML Parser

Character set conversionJava2 uses Unicode as its internal character set. When you work with strings andcharacters in AssemblyLines and Connectors, they are always assumed to be inUnicode. Most Connectors will provide some means of character set conversion.When you read from text files on the local system, Java2 has already established adefault character set conversion which is dependent on the platform you arerunning.

However, every now and then you read/write data from/to text files in whichinformation is encoded in different character sets. The Connectors in AS thatrequire a Parser usually accept a characterSet parameter in the Parser configuration.This parameter should be set to one of the accepted conversion tables found in theJava2 runtime.

AvailabilityFor the Sun distribution of Java2 you should find a JAR archive called i18n.jar. Ifyou don’t have this jar file you must either reinstall Java or copy this jar file intothe runtime directory.

Please 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.architech.parser.rspCSVParser

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.

csvEnableQuotingThis parameter should normally be set. For versions 4.6.4 and earlier: whenthe parser output attributes contains the column separator, newline or aquote character(″), the field would be output with quotes around itwhether or not this parameter was set to true. Quotes and columnseparators inside a quoted field were preceded by a backslash ( \ ). Fromversion 4.6.5, when this parameter is set to true, the field will be outputwith quotes around it under the same conditions as in previous versions,however, quotes inside a quoted field are now doubled. Note: ifcsvEnableQuoting is set to false, the field will be output ″as is″ which maycause 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.

characterSetcharacter set conversion. This parameter is not directly available from theparser configuration, you must edit the configuration file manually to setit.

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.architech.parser.rspDSML

characterSetcharacter set conversion.

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();}

Chapter 9. Parsers 113

Referencesv DOM specificationv Apache Xercesv Apache Xalan librariesv DSML Organization

See also“XML parser” on page 124, “SOAP parser” on page 123

CDS-EDB file parserThe CDS-EDB File Parser reads and writes CDS-EDB formatted data files. ThisParser has been tested with Syntegra’s (formerly known as Control Data Systems)X.500 server.

ConfigurationNo parameters.

NotesThis parser will fail when applied to non-ASCII characters (typically nationalcharacters).

Fixed parserThe Fixed parser reads and writes fixed length records.


class com.architech.parser.rspFixed

fixedColsThis multi line parameter specifies each field name, it’s offset and length asin:field1, 1, 12field2, 13, 4field3, 17, 3

characterSetcharacter set conversion.

HTTP parserThe HTTP parser interprets a byte stream according to the HTTP specification. Thisparser is used by the HTTP Client Connector version 2 and by HTTP ServerConnector version 2.

ConfigurationThe parser has the following parameters:

parserTypecom.architech.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 22 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.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″metamerge-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 togenerate 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 Version 2” on page 52, “HTTP Server Connector Version2” on page 56

LDIF parserThe LDIF parser reads and writes LDIF style data.

It correctly parses and writes BASE64 encoded strings.

The LDIF parser tries to perform BASE64 encoding if it finds it necessary: Onesuch situation is trailing spaces after attribute values. To make sure another LDIFparser gets the space, it BASE64 encodes your attribute.

BASE64 encoding looks like garbled text if you don’t know how to decode it.


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 134 for an example of how hotto copy a binary file.

The LineReader parser is useful when reading text files only.


class com.architech.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.architech.parser.rspRegExpParser

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 root 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.3a.tar.gz

3. Extract the archive’s contents keeping path information. Copy the file″gnu-regexp-1.1.3.jar″ (placed in the ″lib″ folder) to the newly created″RegExpParser″ folder.

4. Download the Regular Expression parser jar archive (regExpParser.jar).5. Copy the file ″regExpParser.jar″ to the ″RegExpParser″ folder.


Regular Expression parser source codepackage com.architech.parser;

import com.architech.entry.Attribute;import com.architech.entry.Entry;import java.io.BufferedWriter;import java.util.StringTokenizer;import java.util.Vector;

// import clases from the "gnu.regexp" package for Regular Expressionsimport gnu.regexp.RE;import gnu.regexp.REMatch;

public class rspRegExpParser extends rspParser{

private final static String PARAM_REG_EXPR = "regularExpression";private final static String PARAM_ATTR_NAMES = "attributeNames";private final static String ATTR_NAMES_TOKEN = ";";private final static String DEFAULT_ATTR_NAME_PREFIX =

"ATTR_NAME_";private RE mRegExp;private Vector mAttributeNames;private Vector mFullAttributeNames;

// Reads Parser’s parameters and creates the regular expressionobject// and the attribute names Vectors.

public void initParser() throws Exception{

String regExpPattern = getParam(PARAM_REG_EXPR);if (regExpPattern == null) {

regExpPattern = "";}mRegExp = new RE(regExpPattern);

mAttributeNames = new Vector();String attrNames = getParam(PARAM_ATTR_NAMES);if (attrNames != null) {

StringTokenizer st = new StringTokenizer(attrNames,ATTR_NAMES_TOKEN);

while (st.hasMoreTokens()) {mAttributeNames.add(st.nextToken());

}}

mFullAttributeNames = (Vector)mAttributeNames.clone();int missingAttrNum = mRegExp.getNumSubs() -

mFullAttributeNames.size();for (int i=0; i<missingAttrNum; i++) {

mFullAttributeNames.add(DEFAULT_ATTR_NAME_PREFIX + i);}

}

// Reads a line from the input and parses it against the regularexpression// If the line matches the regular expression returns an Entryobject// populated with Attributes matching the subexpressions;otherwise -// returns an Entry object with no Attributes.

public Entry readEntry() throws Exception


{String line = getReader().readLine();if (line == null) {

return null;}

Entry entry = new Entry();if (mRegExp.isMatch(line)) {

REMatch match = mRegExp.getMatch(line);

for (int i=1; i<=mRegExp.getNumSubs(); i++) {String attrValue = match.toString(i);entry.addAttributeValue(mFullAttributeNames.

elementAt(i-1), attrValue);}

}return entry;

}

// This method actually iterates the Attributes correspondingto the// "mAttributeNames" elements and forms a single string fromtheir values.// If the resulting string matches the regular expression it iswriten on a// single line in the output; otherwise - nothing is written inthe output.

public void writeEntry(Entry entry) throws Exception{

String line = "";for (int i=0; i<mAttributeNames.size(); i++) {

Attribute attr =entry.getAttribute((String)mAttributeNames.elementAt(i));

if (attr != null) {line = line + attr.getValue();

}}

if (mRegExp.isMatch(line)) {BufferedWriter out = getWriter();out.write(line);out.newLine();

}else {

debug("Entry (" + line + ") did not match the regularexpression.");

}}

// Returns version information.

public String getVersion(){

String revision = "$Revision: 1.4 $";String date = "$Date: 2001/09/21 11:34:43 $";return revision + "\n" + date;

}

}


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 (code)

v 0 - End of Inputv 1 - Status OKv 2 - Error

setMessage (text)

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.architech.parser.rspScriptParser

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!

See also“Script Connector” on page 86, “JavaScript parser” on page 156

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.architech.parser.rspSimpleParser

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.

The samples below show an entry and a SOAP XML document as they would beread/written.

Sample Entry*** Begin Entry DumpSOAP_CALL: ’updateLDAP’mail: (’[email protected])’uid: ’johnd’*** End Entry Dump

Sample SOAP<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.architech.parser.rspSoapParser

characterSetcharacter set conversion

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 sample 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 );

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 125 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. These


functions just happen to have the same name/signature. Do not confuse thexmldom objects with the IBM Directory Integrator objects.

Configurationclass com.architech.parser.rspXml

xmlRootTagThe root tag (output)

xmlEntryTagThe entry tag for entries (output)

xmlValueTagThe value tag for entry attributes (output)

characterSetcharacter set conversion

isvalidating (4.6)If checked this parser will request a DTD/Schema validating parser

isnamespaceaware (4.6)If checked this parser will request a namespace aware parser

omitxmldeclaration (4.6)If checked, the XML declaration will be 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.

NotesIf you read big (> 4MB) or write big (>14MB) xml files, your Java VM runs out ofmemory. Refer to the Appendix A, “FAQ IBM Directory Integrator 4.7” on page 177for a solution to this.

Referencesv DOM specificationv Apache Xercesv Apache Xalan libraries

See also“SOAP parser” on page 123, “DSML parser” on page 113


Chapter 10. Objects

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 (AL) Connector as the connector object.

The AL Connector is the one calling the hook functions you define in theAssemblyLine and also the one that performs the attribute mapping. Each ALConnector in the AssemblyLine is given a name that is automatically available inyour scripts as that name. If you name a AL Connector ″ldap″ it will also be usedas the script object name. Make sure you name your Connectors in a way that iscompatible with the selected scripting language. Typically, you should avoid usingwhite-space and special characters.

The AssemblyLine Connector has methods and properties described in therscTaskComponent.

getDebug()Returns the debug flag for this Connector

setDebug ( boolean )Enables/Disables debug for this Connector

getStats()Returns the (object) for this Connector

getnext()Returns the next entry from the underlying Connector.

getNextDuplicateEntry()Returns the next duplicate entry found during a lookup or updateoperation

getDuplicateEntryCount()Returns the number of duplicate entries found during a lookup or updateoperation.

lookup (work)Performs a lookup using the configured search criteria with values fromwork entry

lookup ( attribute, value )Performs a lookup using exact matching for attribute=value

delete ( work )Performs a delete operation using configured search criteria with valuesfrom work entry

update ( work )Performs either an add or a modify using configured search criteria withvalues from work entry

trigger ( name, work, conn )Calls the hook name using work and conn.

connectorThe Connector object


The trigger function calls one of the AssemblyLine hooks defined for thisConnector using the provided conn/work. The return value is either true if thehook was executed or false if the hook is not defined or disabled. For example,suppose you have an iterating input Connector called MyConnector and wanted tolog the total number of reads performed. You could script:task.logmsg("Number of records read: " +MyConnector.getStats().numGet());

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.

MethodsaddValue ( obj )

Adds obj to attribute’s list of values

clear ()Remove all values from this attribute

contains ( obj )Returns true if this attribute contains a value equal to obj

hasValue ( obj )Returns true if this attribute holds a value equal to obj

hasValueIC ( str )Returns true if this attribute holds a string value equal to str. Comparisonis case insensitive.

getName ()Return this attribute’s name

getValue ()Returns the first value in this attribute as string (or NULL if attribute hasno values)

getValue ( int )Returns the nth value in this attribute or NULL if int is higher than thenumber of values. Values are numbered from zero and up so the first valueis getValue ( 0 ).

The object returned is of the same type as was inserted: It could forexample be a java.util.Date. getValue(0).getClass().getName() will get youthe class of the first attribute value.

getValues ()Returns an array with the values in this attribute.


setName ( str )Sets this attribute’s name

setValue ( obj )Adds value obj if attribute has no values or replaces the first value withobj.

setValue ( int, obj )Replaces the value at position int with obj.

toString ()Returns a string representation of this value on the form name:value

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 132

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 rscConnector in the Javadocs. For moreinformation, see the Javadocs material included in the installation package.

Chapter 10. Objects 131

MethodsgetNextEntry()

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.

MethodsFor a complete list of available methods, including parameters and return values,see the Javadocs material included in the installation package.The following aresome commonly used methods:

addAttributeValue (name, value)Adds a value to attribute name. If there is no attribute called name then anew attribute is created.

clone ( entry )Return a clone entry from entry

getAttribute (name)Return the attribute named name

getAttributeNames()Returns an array of attribute names in this object

getObject (name)An attribute may have more than one value. This function returns the firstvalue as an object. Some values have a string representation and othersdon’t. This function returns the value as is with no conversions.

getOp()Returns the operation code for this entry as a char.v g —-> Generic (e.g. not specified)v a —-> Addv m —-> Modifyv d —-> Delete

Only works in conjunction with Deltas.


getOperation()Returns the operation code for this entry as a string. This is useful whenprogramming in JavaScript. Possible values are ″generic″, ″add″, ″modify″and ″delete″.

Only works in conjunction with Deltas. ″Generic″ will be returned whenused outside a Delta context.

getProperty (name)Return the value for property name

getString (name)An attribute may have more than one value. This function returns the firstvalue as a string. If you use JavaScript, refer to Strings In JavaScript sinceit is not always obvious how to compare such strings.

merge (entry)Merge values from entry into this object

removeAttribute (name)Removes attribute name from this object

removeAllAttributes()Removes all attributes from this object

setAttribute (name, value)Set the attribute value for name to value.Note: Using null as value willremove the attribute, as will removeAttribute(). Clearing the attribute isdone by (getAttribute(″attributeName″)).clear()

setOp (code)Sets the operation code for this object. See getOp().

setProperty (name, value)Set the property value

size() Returns the number of attributes in this entry object

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

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 mode. Stores the Entry that theConnector read from the data source to determine whether this is an Add orModify 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 130

The FTP objectThe FTP object is available as a scriptable object. This object is useful when theFTP Connector does not provide the required functionality.

Methodsboolean connect (String host, String user, String pass)

Connect to an FTP server using the host, user and pass.

boolean close ()Close current FTP session

boolean get (String remoteFile, String localFile)Transfer remote file to local system

boolean put (String localFile, String remoteFile)Transfer local file to remote system

void setAscii ()Set ASCII mode for file transfer

void setBinary ()Set Binary mode for file transfer

boolean cd (String remoteDirectory)Change remote working directory

Object dir ()Retrieve directory listing

boolean remove (String remoteFile)Remove file from FTP server

boolean rename (String file, String newname)Rename file on FTP server

Exception getLastError ()Get the error object for the last operation

Examplevar ftp = system.getFTP();

if ( ! ftp.connect ("ftpserver", "username","password") )

{task.logsmg ("Connect failed: " +ftp.getLastError());

}

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. This object has methods for manipulatingAssemblyLine

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

Hashtable getTasks()Returns a java.util.Hashtable containing references to running threads.

The Search criteria objectThe search criteria object is used by AssemblyLines and Connectors to specify ageneric search criteria. It is up to each Connector how to interpret and translate thesearch criteria into a Connector specific search. The search criteria is a very simplemulti valued object where each value specify an attribute, operand and a value.

Methodssize () Number of criteria specifications

getCriteria ( int )Returns a criteria object at position int. The returned criteria object containsthree fields: name, match and value. The possible values for the matchoperand are listed below.

getFirstCriteriaNameReturns the attribute name for the first criteria

getFirstCriteriaValueReturns the value for the first criteria

getFirstCriteriaMatchReturns the matching operator for the first criteria

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 MS Windows platforms, the shell command will start, but you will not be ableto get output/status from it.

MethodsgetExitValue()

Returns the exit code from the command line

getOutputBuffer()Returns the output from the command line as a string

getErrorBuffer()Returns the error output from the command line as a string

getInputStream()Returns the command line’s input stream as an java.io.InputStream object.You can use this to pipe input to a command.

getError()Returns the exception if the command line failed

failed ()Returns true if the command line execution failed

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


MethodsgetError()

Returns the exception object if the AssemblyLine failed. If AssemblyLinecompleted normally this method returns NULL.

numAdd ()Number of add operations performed

numDelete()Number of delete operations performed

numErrors ()Number of errors (handled by fail hooks)

numGet()Number of get operations performed

numIgnored()Number of entries ignored (system.ignoreEntry)

numLookup()Number of successful lookup operations performed (those where the matchwas found)

numModify()Number of modify operations performed

numNoChange()Number of no-change entries (Update mode)

numSkipped()Number of entries skipped (system.skipEntry)

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.architech.function.userFunctions2), but linked to the Script object system (see“Accessing your own Java classes” on page 21). You can find a complete list of themethods by looking at the Java object, but here are some of the methods:

Methodsremove ( s1, s2 )

Remove occurrences of characters in string s1 from string s2.var str = "This string contains blanks and vowels";var rep = system.remove ( "aeiou ", str );// rep --> "Thsstrngcntnsblnksndvwls"

trim ( str )Removes leading/trailing white space from str

toInt ( str )Returns a java.lang.Integer object from the string str.

isValidInt ( str )Returns true if str can be converted to an integer

openFileForAppend ( file )Opens a file in append mode and returns a BufferedWriter object. Use thereturned object to write data to the file.


var out = system.openFileForAppend("out.txt");out.write ("Hello world!");out.newLine ();out.close ();

openFileForOutput ( file )Opens a file for output and returns a BufferedWriter object. Use thereturned object to write data to the file.var out = system.openFileForOutput("out.txt");out.write ("Hello world!");out.newLine ();out.close ();

openFileForInput ( file )Opens a file for input and returns a BufferedReader object for the file.Refer to the Java documentation for a complete description of this object.var inp = system.openFileForInput ("inp.txt");var str = inp.readLine();if ( str == null )task.logmsg ("End of file");inp.close ();

sendMail (from, recipients, subject, message, attachment)Sends an e-mail to the comma separated list of recipients in recip usingfrom as the sender address. subject and message is inserted as the subjectand main text body. attachment specifies a filename that will be attached tothe message.var errmsg = system.sendMail ("[email protected]","[email protected], [email protected]","This is the subject","Here is the text.\nLine 2","c:\\attachment.doc" );

if ( errmsg == null ) {task.logmsg ("Message sent");} else {task.logmsg ("Error: " + errmsg);

}

Make sure you have set the mail.smtp.host Java property before using thisfunction.

copyFile (fromPath, toPath, overwrite)Copies one file to another. If overwrite is false then copy will not overwritedestination file.

newAttribute (name)Creates a new (Attribute)

newEntry ()Creates a new instance of the (object )

newObject (className)Create a new instance of the Java class className.var f = system.newObject ("java.io.File");

This function is mostly for scripting engines that cannot create Java objectsdirectly. If you are using JavaScript you can create the object like this:var f = new java.io.File ();


skipEntryTells the AssemblyLine to skip the current entry and continue with thenext entry from the iterator.

ignoreEntryTells the AssemblyLine to ignore the Connector from which this function iscalled and continue with the next Connector in the AssemblyLine.Attribute mapping for this Connector is also ignored.

skipToTells the AssemblyLine to skip to the givn connector (bypassing others inthe AssemblyLine).

restartEntryTells the AssemblyLine to start over from the first Connector after thecurrent Iterator without touching the work entry.

abortAssemblyLine ( reason )Tells the AssemblyLine to abort with the message reason.

sleep ( seconds )Pause current thread for seconds seconds.

mapString ( source, set1, set2)Returns a string where all occurrences of characters in set1 have beenmapped to the corresponding character in set2.var str = system.mapString ("Testing", "et", "ET");// --> TEsTing

translateString ( str, fromCharset, toCharset)Translates a string from one character set to another. If either character setis specified as null then Unicode is assumed.var str = "Unicode String";var cp12 = system.translateString ( str, null, "Cp1252" );

toHex ( str )Returns a string where each character in str has been converted to ahexadecimal value.var str = system.toHex ("1998");// --> 31393938

parseDate ( date, format )Parses the string date according to the format given by format. Returns ajava.util.Date object on success.// July 1st 2000dt = system.parseDate ("2000.01.07", "yyyy.MM.dd");if (dt == null) {task.logmsg ("Cannot parse date");}

See formatDate for a description of the format string.

formatDate ( date, format )Formats a java.util.Date object using the provided format. Returns a stringon success. Examples:Format Pattern Result-------------- -------"yyyy.MM.dd G ’at’ hh:mm:ss z" ->> 1996.07.10 AD at 15:08:56 PDT"EEE, MMM d, ’’yy" ->> Wed, July 10, ’96"h:mm a" ->> 12:08 PM"hh ’o’’clock’ a, zzzz" ->> 12 o’clock PM, Pacific


Daylight Time"K:mm a, z" ->> 0:00 PM, PST"yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM

The letters in the format string is defined as follows:Symbol Meaning Presentation Example------ ------- ------------ -------y year (Number) 1996M month in year (Text & Number) July & 07d day in month (Number) 10E day in week (Text) Tuesdayh hour in am/pm (1~12) (Number) 12H hour in day (0~23) (Number) 0m minute in hour (Number) 30’s second in minute (Number) 55’s millisecond (Number) 978D day in year (Number) 189F day of week in month (Number) 2 (2nd Wed in July)w week in year (Number) 27W week in month (Number) 2a am/pm marker (Text) PMk hour in day (1~24) (Number) 24K hour in am/pm (0~11) (Number) 0z time zone (Text) Pacific Standard TimeG era designator (Text) AD’ escape for text (Delimiter)’’ single quote (Literal) ’

The count of pattern letters determine the format.

(Text) 4 or more pattern letters—use full form, < 4—use short or abbreviatedform if one exists.

(Number)The minimum number of digits. Shorter numbers are zero-padded to thisamount. Year is handled specially; that is, if the count of ’y’ is 2, the Yearwill be truncated to 2 digits.

(Text & Number)3 or over, use text, otherwise use number. Any characters in the patternthat are not in the ranges of [’a’..’z’] and [’A’..’Z’] will be treated as quotedtext. For instance, characters like ’:’, ’.’, ’ ’, ’#’ and ’@’ will appear in theresulting time text even they are not embraced within single quotes. Apattern containing any invalid pattern letter will result in a thrownexception during formatting or parsing. See SimpleDateFormat for moreinformation.

splitString ( str, split )Splits a string str into an array of strings.var str = system.splitString ("my name", " ");// --> ["my", "name"]

loadConnector ( name ) / getConnector ( name )Loads an instance of the Connector name, where name refers to a Connectortemplate or a Connector in the Connector library. In order to use theConnector you must also call the initialize function. Refer to the Connectorobject for more details.var ldap = system.loadConnector ("myldap");var entry = ldap.findEntry ("cn", "John Doe");if ( entry != null ) {task.logmsg ("John’s email: " + entry.getString("mail"));

}


getParser ( name )Loads an instance of the parser name, where name refers to a parsertemplate or a parser in the parser library.var ldif = system.getParser ("metamerge.LDIF");var f = new java.io.FileInputStream ("mydata.ldif");ldif.setInputStream ( f );var entry = ldif.readEntry();

task.dumpEntry ( entry );

parseObject ( parser, object )Loads an instance of the parser parser and initializes the parser with object.The object may be a string, java.io.InputStream or a java.io.Reader object.var f = new java.io.FileInputStream ("mydata.ldif");var entry = system.parseObject ( "metamerge.LDIF", f );

shellCommand ( commandLine )Executes commandLine in a shell. The returned object contains input, outputand error stream results as well as exit codes. Refer to the shellCommandobject for a complete description.var f = system.shellCommand ("/bin/ls -l /etc/passwd");task.logmsg ( f.getOutputBuffer() );

getOSName()Returns the operating system name on which IBM Directory Integrator isrunning.if ( system.getOSName().indexOf ("Windows") ) {task.logmsg ( "Running on the Windows platform" );}

getJavaProperty ( prop )Returns the Java runtime property named prop

setJavaProperty ( prop, value )Sets the Java runtime property named prop to value.system.setJavaProperty ( "mail.smtp.host", "mailserver.dot.com" );

getFTP ()Returns an FTP object.

selectSingleNode ( node, xpath )Calls the XPathAPI to find a single node matching the XPath query. Thefunction returns a Node object.

selectNodeList ( node, xpath )Calls the XPathAPI to find a list of nodes matching the XPath query. Thefunction returns a NodeList object.

selectNodeIterator ( node, xpath )Calls the XPathAPI to find a list of nodes matching the XPath query. Thefunction returns a NodeIterator object.

snmpTrap( host, port, oid, value)Refer to om.architech.function.userFunctions2.snmpTrap()

The task objectThe task object represents the current thread of execution. For AssemblyLines thisis the AssemblyLine thread where you can access AssemblyLine specificinformation. For EventHandlers a similar set of methods are available.


task–AssemblyLine

MethodsenableDebug ()

Connects this AssemblyLine to a debugger window

debugBreak ( obj )Sends obj to the debugger window and waits for a continue or stopcommand from the debugger window.

debugMsg ( obj )Sends obj to the debugger window

disableDebug ()Closes the session with the debugger window

dumpEntry ( entry )Dumps the contents of an entry object to the log file

getConfig ( p )Returns a name parameter from the AssemblyLine’s configuration.

getParam ( p )Returns a named value from the AssemblyLine’s task parameter list.

getStats ()Returns the AssemblyLine object. This object is the accumulated statisticsof all the AssemblyLine’s Connectors.

getResult()Returns the final entry for the AssemblyLine. The final entry is whatever isin the work entry by the time the AssemblyLine has completed itsbusiness.

getWork()Returns the initial entry for the AssemblyLine. The initial working entry isprovided by another task.

logmsg ( str )Writes a line (str) to the log file

setParam ( p, v )Sets a named value in the AssemblyLines task parameter list. The taskparameter list is persisted to file after the AssemblyLine completes.

setConfig ( p, v )Sets a named value in the AssemblyLine’s configuration.

setWork ( (entry) )Sets the initial work entry to entry.

task–EventHandler

MethodsdumpEntry ( entry )

Dumps the contents of an entry object to the log file

logmsg ( str )Writes a line (str) to the log file


Chapter 11. Program interfaces

AssemblyLine setting tabWhen in the admin tool, and after an AssemblyLine is opened, the settings 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 the ALterminates. 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 AL to issue a statement of how many entries have been readand processed so far. ( e.g. at every nth entry issue this log message ).

Max number of reads (Iterator)Causes the AL to terminate after having processed this number of entries.Useful when testing AssemblyLines.

Max number of errorsCauses the AL to terminate after this number of errors have occurred.

Max duplicate entries returnedThis parameter is passed on to the Connectors in the AL. This numberrules how many entries are collected by a Connector when multiple entriesare found. This number is relevant only for Connectors working in Updateor Lookup mode.

Script LanguageThe AssemblyLine’s script language. You may choose among severallanguages, 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. To


define 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. Defaults to NullValue Behavior for the Configuration file. Other values are described inAttribute Mapping.

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 toolThe following are command line options for the IBM Directory Integrator admintool (miadmin [options]):

-c Configuration file (default rs.cfg)

-e Error Log file (default console output)

-l Look & Feel ( windows | motif | metal )

IBM Directory Integrator serverThe following are command line options for the IBM Directory Integrator servertool (miserver [options]):Example: miserver -c"c:\metamerge\demos\rs.cfg" -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 (default rs.cfg)

-l Log file (default console output)

-D Flag to disable startup of EventHandlers

-r Comma separated list of AssemblyLine names to start.

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

Notes:

1. You do not want this flag with -t if you start several EventHandlers:Only one will be active at a time.

2. The server dies when it has no active threads. However, we haveexperienced that with Perl, the Perl task is counted as an active thread.Use -w to force IBM Directory Integrator to die after the lastAssemblyLine has finished.

-v Show version information and exit.

-P Password if configuration file is encrypted

-p Dump java properties on startup


-t Comma separated list of EventHandlers to start. The -w flag has the sameeffect on EventHandlers as on AssemblyLines.

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

Discover schemas and browsing dataThe configuration tab of the Connectors always contain an Attribute tab. This canbe used to discover the Attributes the configured Connector can access.

It is also a way of telling the Admin Tool what attributes are available from theConnector: You will later be able to push the Select button under the Attribute Maptab and just map the Raw Connector attributes into the work entry. See “AttributeMapping” on page 30.

Query Schema is only supported by certain Connectors: Data Sources like LDAPand SQL typically have a schema.

Data Browsing can be done by most Connectors. The exceptions are:v File Connectors in output mode (which will destroy your file as it tries to

recreate it)v Connectors that will wait for data after the last entry has been found:

Depending on your timeout, you will never manage to browse past the ’end’ ofthe data. Such an example is the Netscape Changelog Connector.

When you say Connect, certain datasources (like MS Access) might lock thedata-source for you. You should therefore be careful to close the connection afterhaving browsed data or queried a schema.

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 and parsers are found in separate subdirectories andnot described here.

Other files on install directorymiloader.jar

Makes sure jar-files in jars/ subdirectory are loaded by miadmin andmiserver

Chapter 11. Program interfaces 145

rs.cfg Sample configuration file

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

log.txt Install log file.

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

XMLxalan.jar, 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.

Otherv ncso.jar - Domino 5 client library.v comm.jar - Serial port driver.v [email protected], [email protected], [email protected] - Used by

SNMPConnector and system.snmpTrap(). Code from Tivoli/IBM


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

JDBC ClientThe IBM Directory Integrator supplies you with a simple JDBC browser, it isavailable under Tools|JDBC Browser. The browser supplies you with a superset ofthe functionality you get when you configure a Connector itself with the Attributetab (Configure | Attributes).

In order to use it you need to have a configured JDBC Connector in yourConnector Library: It should have all the information needed to connect to thedata-source you are interested in.

The Browser will let you open the Connector: A dialogue box letting you selectyour Connector will show up.

The following buttons enable a rudimentary browsing:

Open Let’s you select your JDBC data-source by choosing a correctly configuredConnector from the Connector Library.

Tables Queries the JDBC source for the available tables. Will usually be done foryou when you select the Connector (See Open).

ColumnsSelect one of the Tables/Views and press Columns to query the TableDefinition. It will show you the available columns as well as their type.


Clear Clears the output window

ExecuteExecutes an SQL statement. The statement is typed in the SQL Statementsub window. The results of the execution is not shown directly: You willhave to use the Next button for that.

Execute can be used to actually change the data.

Next Returns next entry that has previously been Executed. This typically letsyou browse through a returned dataset, one record at the time.

Parameter labels on the Connector/parser tabs.If you leave the cursor on the label a little while, a tooltip pops up, showing somehelp.

Red label text indicates that the value of this parameter has been inherited. Whenyou 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.

LDAP ClientThe IBM Directory Integrator supplies you with a simple LDAP browser, it isavailable under Tools|LDAP Browser. The browser let you look and modify datain your LDAP directory, so it is a little more than a plain browser.

In order to use it you need to have a configured LDAP Connector in yourConnector Library: It should have all the information needed to connect to thedata-source you are interested in.

The Browser will let you open the Connector: A dialogue box letting you selectyour Connector will show up.

Be warned that this page is not an LDAP tutorial. Knowing LDAP helps a lotwhen trying to use the Browser functionality.

The following buttons enable a rudimentary browsing:

Open Let’s you select your LDAP data-source by choosing a correctly configuredConnector from the Connector Library.

Base Search base for your Query. Is typically on the form o=Airius.com. oin thisexample is one of the Attributes you will see under Attributes.

Filter Filter restricts the search from Base. Is typically in the form cn=G*.

Returns entries that start with a G.

Show The attribute value to display in the left-hand pane (after a Find is done).

Max returnMaximum number of entries returned by the server.


Find Queries the LDAP server and displays the entries that matches the searchcriteria.

New Lets you create new Object Classes.

Add Adds the entry typed in the right hand side of the screen to the directory.

ModifyModifies the highlighted entry to include the changes made to the righthand side of the screen.

Delete Deletes the highlighted entry from the directory.

Object classesReturns the list of Object Classes known to the server.

AttributesReturns the list of Attributes known to the server.

Server infoAssorted information about the Server.

Preferences/system propertiesThis window is available through View | Preferences. It contains following optionsthat will be valid for the current configuration file (some of these are “System/Javaproperties”). The internal name as well as some help can be found by clicking onthe label. If more information is needed, it might be found by following the linksbelow.v Null Value Behavior.v Null Value.v Log Rotation Count.v SMTP Server.v Web browser.v Title Color.v Editor Font.v Editor Font Size.v Encrypt Config File.v Java Command.v Look and Feel.v Reuse Command Window.v Show Toolbar.v Keystore.

System/Java propertiesThe System/Java Properties is a page where you specify a list of properties andtheir associated values. The properties are added to the Java runtime properties soyou may change/add Java specific or other third party-specific properties here.Also, you will find IBM Directory Integrator-specific properties that fine tune theway IBM Directory Integrator server and Admin Tool behaves.

These values are part of your configuration file and might be different from file tofile.


Some of these values need restarting of the Admin tool to take effect. Since someof these values can be set through the menu, you should set the values there.

com.architech.certificatesFileThe X.509 Sun Keystore file to be used

com.architech.rotatelogsNUMBER: Specifies how many AssemblyLine log files to save. Each savedlog file is suffixed by a ″.x″ where x is a number.

external.propertiesSTRING: File that shows where the properties are placed. This is mostuseful in order to isolate site specific parameters on an external file.

external.properties.encryptedShould the file named in external.properties be encrypted? This encryptionis not really secure, so if you care about security, you will probably want toencrypt this file yourself and decrypt it before running IBM DirectoryIntegrator.

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. See “System/Java properties” onpage 149.

rsadmin.attribute.nullBehaviorValueSTRING: If rsadmin.attribute.nullBehavior is set to Value, this is the value.

rsadmin.browserSTRING: Specify the web browser you prefer when viewing AssemblyLinereports. Use ″{0}″ as the place holder for the AssemblyLine report HTMLfile. (e.g. explorer {0}).

rsadmin.color.titleSTRING: Color of the title bar in the Admin Tool.

rsadmin.editor.fontSTRING: Font for the editor (used to write scripts in hooks)

rsadmin.editor.fontsizeNUMBER: Fontsize

rsadmin.enableformsFor internal use only

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.

rsadmin.guiFor internal use only

rsadmin.javacmdUsed to overwrite the default Java (VM) command


rsadmin.javacmd.reuseBOOLEAN: True if the Admin tool is to reuse the javacmd window. Falseif you want command windows all over the place.

rsadmin.lookAndFeelLook and feel value from View|Look and Feel

rsadmin.toolbarBOOLEAN: Hide or shows buttons in the Admin Tool.

rsadmin.treeventhandlerFor internal use only

Using external propertiesIn order to externalize certain configuration parameters like filenames etc. , do thefollowing: (We will here assume that you want to externalize the filenamec:\foo.xml, give it a symbolic name key FileName and store this in an external filec:\myProperties.txt)

1. Go to the External Property tab in the main configuration tab2. Push the Add button. If you had no External Property file, you will be

prompted for it’s filename (c:\myProperties.txt). This filename is stored in theconfiguration file you are inn, so all your AssemblyLines will have access to theparameters.

3. Register a property key and it’s value (FileName and c:\foo.xml )4. You should now have an External Property tab with Filename and c:\foo.xml

showing as key and value5. Go to the configuration screen for the component where you want to use

FileName,typically in an AssemblyLine.6. Since you are interested in the File Path parameter of a file Connector: Click the

File Path label (not textbox!)7. A box shows up with a User Property drop-down: Select FileName.

The NT4 Connector example contains an example where a username and passwordis shared between 5 configuration files and 10 Connectors.


Chapter 12. Samples

VBScript Connector and MSOutlook connectorThis example shows how you can manipulate your Outlook Contacts usingVBScript. This example is also available as the IBM Directory IntegratorMSOutlook connector.

Sample code’’ This script implements all the necessary functions for accessing’ the Contacts register in MSOutlook.’ 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 then


result.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 86

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.

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

Chapter 12. Samples 155

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.

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

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 Connector and also take a look at the sampleConnector. Both will give you the necessary information to roll your ownConnector.

Java-based ConnectorLearning by example is probably the best way to learn new things. The sourcecode for the Client Connector is freely available for download and should give youa firm understanding as to how the Java-based Connectors are implemented. Note:from version 4.6 you need to implement a public String getVersion() method.


Also note that the HTTP Client2 Connector is the preferred Connector, we here usethe HTTP Client Connector because it is a better example.

Building and installing a Java-based ConnectorRemember that the IBM Directory Integrator will wrap the AssemblyLineConnector around your Raw Connector, so you only need to write the RawConnector.

A comment about Java librariesIf you use the same libraries as the IBM Directory Integrator does (see“Distribution components” on page 145) you should make sure that you use thesame version as IBM Directory Integrator does. If not, you can run intocompatibility problems because the 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 miserver.jar from the IBMDirectory Integrator distribution in your classpath. Of course, you need to includeother jars as needed, the HTTP Client Connector referred to above needs themailapi.jar.javac -classpath ’IBMDirectoryIntegrator/jars/miserver.jar;IBMDirectoryIntegrator/jars/mailapi.jar’ com\myname\httpconnector.java

This is the Windows Command when IBM Directory Integrator was installed in themetamergeHome directory. UNIX uses ’:’ instead of ’;’ as separator.

2. Make a file named metamerge.inf with the following content:[connectors MyConnector]

connectorConfig {connectorType:com.myname.HTTPConnector

}description:My HTTPConnector

[end]

[form com.myname.HTTPConnector]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, andalso gives both the name this connector is known under in the Admin ToolMyConnector, and the java class name com.myname.HTTPConnector.

The form section tells the Admin Tool which parameters your connector needs. Theparameter list section lists the order in which the parameters are presented. Theparameter section contains a subsection for each parameter and has the followingkeywords:

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 the user tobrowse through the filesystem and select a filepath.

scriptlabelThe label on the button which evokes the optional script

3. Add your metamerge.inf and class files to a jar file ( myconnector.jar )jar cvfM myconnector.jar metamerge.inf com\myname\HTTPConnector.class

4. Copy the jar file to a suitable directory, such as metamerge/jars/myjars . It hasto be in a subdirectory of metamerge/jars, it should not use the system directoriesconnectors/, eventhandlers/ or parsers/.

5. Your connector is now available as MyConnector.


system.parseDate (string value, string format)This function returns a Date object (java.util.Date) representing the string formatteddate given by the value parameter. The format parameter specifies the date/timeformat the value is given in. If the function fails then a NULL value is returned.

Example// July 1st 2000dt = system.parseDate ("2000.01.07", "yyyy.MM.dd");if (dt == null) {task.logmsg ("Cannot parse date");

}

Other examplesFormat Pattern Result-------------- -------"yyyy.MM.dd G ’at’ hh:mm:ss z" ->> 1996.07.10 AD at 15:08:56 PDT"EEE, MMM d, ’’yy" ->> Wed, July 10, ’96"h:mm a" ->> 12:08 PM"hh ’o’’clock’ a, zzzz" ->> 12 o’clock PM, Pacific

Daylight Time"K:mm a, z" ->> 0:00 PM, PST"yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM

The format string can take a number of parameters:Symbol Meaning Presentation Example------ ------- ------------ -------G era designator (Text) ADy year (Number) 1996M month in year (Text & Number)

July & 07d day in month (Number) 10h hour in am/pm (1~12) (Number) 12H hour in day (0~23) (Number) 0m minute in hour (Number) 30’s second in minute (Number) 55’s millisecond (Number) 978E day in week (Text) TuesdayD day in year (Number) 189F day of week in month (Number) 2 (2nd Wed

in July)w week in year (Number) 27W week in month (Number) 2a am/pm marker (Text) PMk hour in day (1~24) (Number) 24K hour in am/pm (0~11) (Number) 0z time zone (Text) Pacific

Standard Time’ escape for text (Delimiter)’’ single quote (Literal) ’


Chapter 13. 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 AssemblyLine.

By adding watch variables, the Admin Tool will display the value of the variablesat all break points. Examples of variables you might want to watch is work (thework entry) or work.getAttribute(″Item″) (just the attribute Item). This is a great wayto watch the contents of internal variables and know where they are defined andnot.

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.

Breakpoints can be set in hooks, by enabling the Debug Break check box. However,the AssemblyLine will not break on hooks without code.

Also, the calltask.debugMsg ( "message" )

writes ″message″ to the debug console and forces a break (only when debugging).

Logging and debuggingLogging and debugging is mainly done through the Task object. A log file willshow up in the same directory as your configuration file, subdirectory log/AL/ forAssemblyLines and log/EH/ for EventHandlers. Each run will create a new logfile bearing the name of your AssemblyLines or EventHandler and a run number.The run number will continue until the Rotate Log parameter is reached at whichpoint logs are rotated.

Logging Key data is logged from the IBM Directory Integrator engine, from itscomponents (Connectors, parsers, etc.) as well as from user’s scripts. Note thatalmost every Connector has a parameter called ″Debug Mode″ - it can be used toturn on and off the Connector’s output to the log file. Dumping to the log file isdone through the task object. Dumping to the console (the console windowassociated with AssemblyLine execution) and the system log (see “IBM DirectoryIntegrator command line options” on page 144) is done through the main object.Below are some examples of what the user can dump and sample code inJavaScript that performs these operations. All examples show how to dump to thelog file using the logmsg method. However all you have to do in order to dump tothe console window is to change the task keyword to main .


Dumping the content of an Entry objecttask.dumpEntry(entry)

/ ″ main.dump(entry) ″ will dump the entry to the console /

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 sample 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″);

Chapter 13. Logging and debugging 163

Chapter 14. Optional tasks in IBM Directory Integrator 4.7

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 AL with search base level set to current’s entry DN

The starting of ALs can be made parallel to make the processing faster. Of coursethe number of threads could explode but it is possible to control it. Because theAdmin Tool sets the -w parameter you will have to start IBM Directory Integratorfrom the command line

miserver -rDumpDir -cDumpDirectory.cfg

The code customizing is done in the following:v the AddOnly Connector (on_success hook:It starts a new AL with an initial entry

that the Prolog will pick up )v in the AssemblyLine Prolog (Before Connectors Initialized).


Chapter 15. Optimizing IBM Directory Integrator 4.7

As we get experience with sub optimal ways of using the IBM Directory Integrator,this page will contain tips on what to do/not to do.


Chapter 16. IBM Directory Integrator 4.7 — Downloads andrelated material

Installation notesFor a list of important files included in an IBM Directory Integrator installation, see

IBM Directory Integrator 4.7

Download instructionsIf you don’t install 4.7 on a fresh directory (for example, over a patched version of4.6), you might experience that the installer doesn’t want to replace some of yourchanged (patched) files.

Download 4.7If you are running on a Unix system where it is impossible to use the Installerbecause of the GUI, refer to the Appendix A, “FAQ IBM Directory Integrator 4.7”on page 177 on this topic.

New features 4.6v New scheme for handling missing values: Set default behavior if the Connector

or the AssemblyLine have missing attributes.v Improved Debug Functionality: Works for EventHandlers. Lets you watch

variables and evaluate expressions. Advanced Link Criteria possible (scriptable)v Jar File Splitting. Connectors, EventHandlers and parsers are now stored in

separate files. This makes it much easier to add new ones outside a main release(as well as easier to fix bugs), and simplifies the way you write your ownConnector.

v Possibility to extract parts of the configuration files (such as passwords) in anExternal Parameter File. Possibility to Include URLs into configuration files.

v Log-files are handled slightly different: EventHandler and AssemblyLine logs goto different directories.

v When running AssemblyLines from the Admin Tool, you can reuse the Javacommand window if you want to

v A trivial parser has been added: LineReader reads a line (and from 4.6.3 it canalso write a single line)

GUI improvements 4.6v Keyboard shortcuts added to some of the menu itemsv Open/Save/New can be removed to save spacev Hooks are displayed differently: They now show the call order betterv When doing a Configure|Connector, all connector attributes will be selected for

you and made available to the AssemblyLinev When selecting Attributes for the work entry, you have the option to select all or

none


Bugs fixed since 4.6 beta2Older bugs are described under beta2v XML parser did not output strings of length 1v Errors counted twice in main error counterv NT4 Connector did not always support international charactersv Error Object would only exist in some of the failure hooksv It was possible to get access to some passwords in clear-text even if the

configuration file was encrypted.v The Before/After SelectEntries were listed as common hooksv If connector throws exception, Connector Stats would be emptyv Logs for EventHandler and logs for AssemblyLines would show up in different

placesv JDBC connector : Syntax error in SELECT clause when table name contains a

spacev The Before/After SelectEntries were listed as common hooksv Script Component could destroy the work entryv Script Component was executed on initializationv Encrypted configuration files would create temporary versions that were not

encrypted

Fixed issues 4.6

Script libraries not available to ListenersListeners, or simple EventHandlers do not have access to your Script Libraries.

Work around:v Copy/Paste your scriptv Contact [email protected] to get a set of new jar-files that fixes Timer

and GenericThread listeners.

This bug is fixed in the next release, and will probably trigger a 4.7 release.

Logged in 4.6.7, present since 4.6, fixed in 4.7

JMS 1.13 can lose queue elements when IteratingIf you have an Iterator with a timeout, and the Timeout is reached (queue emptyfor more than the timeout value), then entries might get lost. You will lose thequeue items if they are put in the queue after the timeout, but before theConnector has been properly closed.

Logged 2002-3-1 for ETA JMS version 1.13. This bug does not apply to JMSversions delivered with IBM Directory Integrator 4.6 since it uses functionality newin 1.13.

There is no work-around for this bug but it will only show up if you use thetimeout feature of JMS.

JMS MQ Series does not support topicsWhen using IBM-MQ JMS you will get a null pointer exception when trying toconnect.


Logged in version 4.6.2

This issue is fixed by the new version of the Connector 1.13 but a fix for the JMSConnector enclosed with the 4.6 release (JMS 1.12) is available.

NT/ADSI Connector can clear passwords during updateAny update operation that has not mapped the Password Attribute, will result inclearing the Password.

Logged in version 4.6.6.

Connectors: Override Add hook defect in Update and AddOnlymodes

The work object is not available in the Override Add Hook

Fix: This will be fixed in 4.6.6. If this bug hits you, download miserver.jar and putit in the jars/ directory.

Fixed in 4.6.6, Logged in version 4.6.5, present since 4.6.3

HTTP EventHandler using Auth ConnectorAn updated version of the HTTP EventHandler should have been included withversion 4.6.3: If you use the Auth Connector with the HTTP EventHandler, youwill get a java.lang.AbstractMethodError.

If you suspect this, go to the EventHandler templates and check the version ofmetamerge.HTTPEventHandler: Revision 1.3 of the HTTPEventHandler has thisproblem.

Fix: Replace HTTPEventHandler.jar in the jars/eventhandlers directory with the newHTTPEventHandler.jar

Fixed in 4.6.6, Logged in version 4.6.5, present since 4.6.3

XML parser limitationsThe XML parser can have problems reading files larger that 4MB and writing fileslarger than 14MB.

This is caused by Java not getting access to enough memory. See the Appendix A,“FAQ IBM Directory Integrator 4.7” on page 177 for a reply to this.


Memory leakEach time an AssemblyLine is started, around 30k memory is ’lost’. This istypically something that causes problems when you have a configuration file withan EventHandler starting AssemblyLines over and over.

Logged in 4.6.4, reduced in 4.6.5 to 2.5k

Chapter 16. IBM Directory Integrator 4.7 — Downloads and related material 171

Running out of file handlesThe log file is not closed properly after terminating an AssemblyLine. This cancause you to run out of file handles if you start the AssemblyLine many times, forexample, from an EventHandler.

Work around: Close down and restart the MISERVER when you are getting low onfile handles. Fixed in 4.6.5.

If you use https:/ as part of the URL, the AssemblyLine willfail

This is due to an internal parser not being loaded. The error message you will getis:

ERROR> AssemblyLine xxx failed because unknown protocol: https

The situation will only occur when using the Run button in the admin-tool, not ifyou run your AssemblyLine from command-line or EventHandler.

Temporary fix / work around1. In the Admin Tool, select View|Preferences.

2. In the Java Command box, type miserver (you might need to prefix this withthe path of the miserver application)


In certain situations, the Lotus Domino Connector (andpossibly some others) do not run from the Admin Tool

The Lotus Domino Connector will in this situation give you a connection error.You will know that you have encountered this issue if1. You are able to Connect button on the Configuration|Attributes tab of the

Connector.2. The AssemblyLine can be run through the miserver command

This is due to an internal parser not being loaded.

Temporary fix / work around1. In the Admin Tool, select View|Preferences.

2. In the Java Command box, type miserver (you might need to prefix this withthe path of the miserver application)


4.6 Installer fails for some systemsThis is true for Solaris 2.6, Windows ME, TurboLinux, MacOS X.

The problem is traced back to the software building our Installer, expect a fix to bereleased by the end of October.


Backward compatibilityIf you use code that supplies an entry to be treated as the work-entry, it might fail.


This issue is related to expert usage of IBM Directory Integrator. If the followinginformation makes no sense to you, you can ignore this item altogether.

Some methods, like rscTaskComponent.add (usually called byconnectorName.add() ) have an Entry object as a parameter. That parameter willusually be the work entry, in which case there are no problems. However, if youhave created your own temporary Entry object and want the AL to treat it as thework entry, you could submit the temporary Entry object as a parameter. This hasstopped working, as the global work entry will always be used.

Work aroundUsing the work object for passing the Entry values will get around this problem.This issue still is a bug, and a patch will restore the backward compatibility.

ExampleWe here assume that you have a connector called myConnector in AddOnly mode.tempWork.addAttributeValue( "name", "John Doe");myConnector.add( tempWork );

This code will currently fail, whilework.addAttributeValue( "name", "John Doe");myConnector.add( work );

will perform correctly supposing that the other attributes of work does not create aproblem.

Logged in version 4.6.2, fixed in 4.6.3

Known issues 4.6You will here find a description of major, unfixed problems. Newest issues areadded at the top. When work arounds are available they will be published here, aswill early version of bug-fixes.

Delta on iteratorThe Delta configuration only works for the ″first″ component. The ″first″component is the first component added to the AssemblyLine in the currentsession, that is still not removed.

This annoying bug is fixed in the next Major release.

Work around:v Move the Iterator you want to configure to the top of the AssemblyLine by

selecting and using the Up arrowv Save your configuration filev Restart the Admin Tool (the Iterator will now become the ’first’ known

Connector to the Admin tool as it reads the configuration file)v Configure the Delta of the Iteratorv Move the Iterator back where it should be using the Down arrow

Logged in 4.6.7, present at least since 4.6.

Chapter 16. IBM Directory Integrator 4.7 — Downloads and related material 173

Memory leakEach time an AssemblyLine is started, around 2.5k memory is ’lost’. This istypically something that causes problems when you have a configuration file withan EventHandler starting AssemblyLines over and over.

In addition, if you run the AssemblyLines from the Admin tool, the log-windowwill use a lot of memory. You may want to close the log-window to free thismemory.

Work arounds

1. Close down and restart the MISERVER when you are getting low on memory.2. If you have installed 4.7, you can replace the JavaScript engine as described in

the Appendix A, “FAQ IBM Directory Integrator 4.7” on page 177. A side effectis that this will give you the Bean Scripting Framework (BSF) 2.2 which permitsus to free the memory. Note that even though we know of few problems withthis solution (see the Appendix A, “FAQ IBM Directory Integrator 4.7” onpage 177), BSF2.2 will be not be the official library before the next majorrelease.

Logged in version 4.6.4, present since the beginning


Chapter 17. Release Notes

The following are new or changed functionality of IBM Directory Integrator forthis release:v New global.properties file.v Changes due to use of Install Shield.v Security Framework changes.v New default JVM.v Naming of the product.v New licensing changes.v URL Connector/HTTP Switchboard is changed.v Admin tool could not access encrypted external properties in 4.6.8.v Including config-files into each others could cause IBM Directory Integrator to

detect an non-existing loop.


Appendix A. FAQ IBM Directory Integrator 4.7

Questions

Installation and licensingv My license is about to expire. What do I do?v I have a Unix system without X-Windows. How do I install Metamerge

Integrator?v I have installed a new version, service pack or Connector version, but I just see

the old functionality.v Can I install different versions of Integrator on the same computer?

Writing AssemblyLinesv I need the file my AssemblyLine creates before the AssemblyLine has finished,

but it is empty or incomplete.v I need to change the output filename while the AssemblyLine is processing.v I need to pass the input/output file names (or other Connector parameters) to

an AssemblyLine I start from an EventHandler.v When creating XML files from an LDAP directory or LDIF file, the

AssemblyLine fails.v When I compare JavaScript strings, I get inequality despite the fact that the

strings are equal.v Can I use Bean Shell with with Metamerge Integrator?v How do I start the Metamerge Integrator from a trigger in my database?v I have an AssemblyLine with an iterator in it, but some of the entries are

skipped. Why is that?v I have a new version of a script connector (or parser) in the base template

library, but my AssemblyLine seems to use an old one?v I have written my own Connector, and it used to work. When I recompile it

now, why has it stopped working?v I want to copy a whole LDAP directory to another. How do it do that?v I need to debug a Script Connector (or other object) where the task object is

unavailable. How to I access task.debugMsg () and other log-functionality?

Securityv I need support for 128 bits RC4 bulk encryption over SSL. Why is it not

supported?v I need Third Party SSL Socket Factories. Are those supported?v How do I use certificates from Trusted Third Parts?

Error messagesv ERROR> AssemblyLine x failed because No criteria can be built from input (no

link criteria specified)


Limitationsv I run out of memory, but have more available. Can anything be done?v Does Integrator support double bytes character sets?

Third party softwarev What version of JavaScript is included and can I replace it with a newer one?v Can I use Java 1.4 with Integrator 4.6?

Answers

Installation and licensing

My license is about to expire. What do I do?Contact your sales representative. He will send you a new license file (aslicense.jar).You will need to replace your old license file with this one on all computers whereyou are running IBM Directory Integrator.

The location of the old file is dependent on what version of IBM DirectoryIntegrator you are running:v Version from 4.6beta (June 2001): jars/ subdirectory of the directory where you

installed IBM Directory Integratorv Version 4.5.3 and before (June 2001): lib/ext subdirectory of the Java runtime

library you are using with IBM Directory Integrator. Version before 4.5.3 includeall versions of ArchiTech server (as the product was called prior to 2001).

I have a Unix system without X-Windows. How do I install IBMDirectory Integrator?We will here assume that setting the DISPLAY variable does not help you: Thetarget system could for example be on a protected net that cannot see your XServer.

You will of course not be able to run the Admin Tool, as it has a GUI, but you canstill run the IBM Directory Integrator server. What you have to do is:1. Install on a Unix machine where you have access to an X server. Install to a

directory called IBMDirectory

2. Create an archive (i.e tar or zip) with all the files installed in IBMDirectory

3. Copy the archive to the target machine an extract the IBMDirectory directory

I have installed a new version, service pack or Connectorversion, but I just see the old functionality.Make sure that all your old jar-files in the jars directory and subdirectories arerenamed to an extension different than .jar . For example, if you have a newjdbc.jar, make sure it either replaces the old one, or that you rename the old tojdbc.jar.old. This is because the jar-file loader will pick up any jar-files it finds. Sorenaming a file is not enough: For the loader to miss it it cannot have the extension.jar.

If you do a full install, make sure you install on a fresh directory and copy yourlicence file (aslicense.jar) from/to the jars/ directory.


Can I install different versions of IBM Directory Integrator on thesame computer?Yes. Just make sure you don’t install them on the same or overlapping directories.Also remember that, under Windows, your shortcuts/program menu will onlypoint to one specific instance of miadmin.exe or miserver.exe

Writing AssemblyLines

I need the file my AssemblyLine creates before theAssemblyLine has finished, but it is empty or incomplete.

I need 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 reinitialize. The snippet of code below will create a new fileeach time it is executed: The filenames will be file1.xml, file2.xml etc. (assuming thevariable iteration was initialized 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!connector.terminate() is not as dangerous as it sounds.

If you have opened the AddOnly Connector in append mode, the setParam() is notnecessary, but for output mode the sequence terminate() and initialize() would makeyou loose previous work.

I need to pass the input/output file names (or other Connectorparameters) to an AssemblyLine I start from an EventHandler.On 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 AL 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 10 for further discussion)

Appendix A. FAQ IBM Directory Integrator 4.7 179

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)

When creating XML files from an LDAP directory or LDIF file, theAssemblyLine 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");

When I compare JavaScript strings, I get inequality despite thefact that the strings are equal.JavaScript has two kind of strings: String literals like ″test″, and the string Objectyou will get as a result of new String(); Usually string literals are used, but whenyou use methods like work.getString(″a″) it will return a string Object. This topic istreated in depth (here).

Can I use Bean Shell with with IBM Directory Integrator?We have tested it briefly, but not certified it.

How do I start the IBM Directory Integrator from a trigger in mydatabase?There are many ways to do that.v A simple way is to have the trigger update a dedicated table with the data you

want sent to the AssemblyLine. You would then start an AssemblyLine every 5minutes (for example, by using the Timer EventHandler), iterating through thetable and removing entries as they are processed.

v If the AssemblyLine runs on a different machine, you could make the triggergenerate small files containing the relevant data and reachable by FTP. The FTPPoller could then look for files and process them, making sure they are removedafter being processed.

Discussion: Writing to a TCP port and using the TCP Port EventHandler seemsnice, but should be avoided if you are concerned with data being lost: You (or thetrigger) will have no simple way of knowing what data have and have not beenprocessed. The same can be said for a solution involving the HTTPClient.

However, if you have access to JMS Message Bus technology, the trigger cansimply drop the data to be processed on the bus.

I have an AssemblyLine with an iterator in it, but some of theentries are skipped. Why?If you have a Lookup Connectors after your Iterator, the Connector might fail dueto no or multiple entries found (see “Failure Hooks” on page 24) . The failingLookup Connector will cause the AssemblyLine to skip the entry and tell theIterator to move on with the next entry.

However, if the On Error hook of the Lookup Connector is enabled (see “Hooks”on page 23) , the AssemblyLine will think the error is taken care of and proceed.


Of course, you should put code there to check whether the error was serious orjust acceptable (for example no entries returned). Checking the content of yourattributes is one way, using the rscTaskComponent method getDuplicateEntryCount() is another. See “Hooks” on page 23 for more on this

I have a new version of a script connector (or parser) in the basetemplate library, but my AssemblyLine seems to use an old one.Why?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.

If your script connector was inserted in the configuration file using an Admin toolwith version number 4.6 beta or lower, you will have the content of the scriptcopied into your configuration file regardless of whether you have changed it ornot. Removing the old script Connector from the AssemblyLine and re-introducingit will get you around this, but remember to copy over code from your hooks!

I have written my own Connector, and it used to work. When Irecompile it now, it has stopped working. Why?First of all, from version 4.6, a new public String getVersion() method is mandatory(so you can keep track of the version of your Connector).

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

I want to copy a whole LDAP directory to another. How do I dothat?See “Copying directories with the LDAP Connector” on page 165. An example isprovided as well.

I need to debug a Script Connector (or other object) where thetask object is unavailable. How to I access task.debugMsg () andother log-functionality?Assuming JavaScript, the task object can be fetched by:task = java.lang.Thread.currentThread()

main can always be be accessed through:main = connector.getRSInterface()

Security

I need support for 128 bits RC4 bulk encryption over SSL. Whyis it not supported?IBM Directory Integrator supports SSL through (JSSE). The version delivered withIBM Directory Integrator 4.6 only supports 40 bits RC4 encryption. A newerversion (1.0.3) supporting 128 bits RC4 is available and can be downloaded fromhttp://java.sun.com/products/jsse/index-103.html. Refer to the download link tosee what other cryptographic suites are supported by 1.0.3 (RSA, DES, Triple DES,Diffie-Hellman, DSA)


I need Third Party SSL Socket Factories. Are those supported?This is a matter of what version of (JSSE) you have. Due to export restrictions, onlythe Global version of JSSE is delivered with IBM Directory Integrator. If you residein the USA or Canada, refer to (JSSE home page) to download a more powerfulversion.

Error messages

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.

Limitations

I run out of memory, but have more available. Can something bedone?

Increasing the memory available to the Virtual Machine: Some components,such as the XML parser, will use a lot of memory, and the Java VM default onlyhas 64 MB available.

Notes

v Your OS might limit how much memory it lets you get. Under Unix, try ulimit -ato see how much you can have. Under NT, remember that the OS keeps somememory to itself (128MB+) so even if your server contains 256MB you mightonly get access to 100MB or less.

v If your memory problems occurred while using and LDAP iterator, check outthe LDAP documentation for more tips

v A memory leak is known, see “Known issues 4.6” on page 173 for more on this.

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

Third party software

What version of JavaScript is included and can I replace it with anewer one?We are currently using Rhino version 1.4R3 from Mozilla. A newer version (1.5 R2)is available and can be downloaded. We know of few problems with this version,but you replace the Rhino/BSF engines at your own risk.

For description of changes between Rhino 1.4R3 and 1.5R2, seehttp://www.mozilla.org/rhino/download.html

Here are the instructions you need to upgrade:1. Download bsf2-2.zip and extract it into your IBM Directory Integrator directory.2. Remove ″jstools.jar″ and ″bsfengines.jar″ from the ″jars″ directory. You should

then be up and running with the BSF2.2(http://oss.software.ibm.com/developerworks/projects/bsf ) and Rhino 1.5R2 (http://www.mozilla.org/rhino/ ) versions.

Note the following improvements:1. Line numbers are supplied when script errors are found2. try/catch construction available within JavaScript3. Inherited static methods would not work. For example, task.sleep() is now

available. With earlier versions of BSF, you had to write java.lang.Thread.sleep()to get access to task.sleep()

Sometime, at places where objects (in particular work) are null, IBM DirectoryIntegrator might behave differently (it might in fact abort because work isundefined). You will experience this if you have code using work before Connectorinitialization and in similar cases of ’early’ work use where work is not defined.


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

The IBM Directory Integrator server consists of a Java engine running aconfiguration file that defines the server. The configuration file is a text-file,easily editable using a graphical user interface called the Administrator orthe Admin-tool. The admin-tool is installed with the product.

AL Shorthand for AssemblyLine

AssemblyLineThe basic work object within a Server (see page 187). It consist ofConnectors, Parsers and business logic. Connectors typically feed data inand out of the AssemblyLine.

AttributeContained in Entries (see page 186) 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.

ComponentsThe IBM Directory Integrator consists of a kernel being the Server (seepage 187) and the (Admin-Tool). 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 page187) and Connector (see page 185)mode.

ConnectorA plugin into your data source in order to read it. Inside the AssemblyLinewe differ between the Raw Connector object (see “The Raw Connectorobject” on page 131 ) (class name rscConnector) and the AssemblyLineConnector object (see “The AssemblyLine Connector object” on page 129)(class name rscTaskComponent), the latter wrapping the former andhaving 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 30.

Delta A special term used in Iterator mode used when synchronizing a masterand a slave. See “Deltas and compute changes” on page 28 for moreinformation

Entry A term used for both the Entry object and the top level item used by theAssemblyLine (see “The AssemblyLine” on page 7) and Connectors (seeChapter 6, “Connectors” on page 41). 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 143, and ″Savetask parameters to,″ page 143. 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 186 for a moreprimitive version.

External PropertiesA way of externalizing certain Component parameters as filename, user,password etc. See “The configuration file” on page 33 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. Sometime referred to as IBM Directory Integratoror the Integrator. It consists of the Admin tool and the Server (see page187).

Link CriteriaUsed in order to tell Update, Lookup and Delete Connectors what toaccess. Briefly speaking it links an Attribute (see page 185) 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 mode isavailable as well). See “Connectors” on page 9 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 186) and holding a single value. Mostlyused in Handler Action maps. See also Attribute, page 185.

Raw ConnectorThe part of the that sees the external data source. See also Chapter 6,“Connectors” on page 41.

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 notbe confused 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 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.

Task By convention all threads (AssemblyLines, EventHandlers etc) are referredto as the ″task″ object.

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 186 and Attribute, page 185.

Work EntryAn instance of the Entry (see page 186) 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 7. 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 B. Dictionary of terms 187

Appendix C. 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.

TrademarksThe following terms are trademarks of International Business MachinesCorporation in the United States, or other countries, or both:

IBM

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Windows and Windows NT are registered trademarks of Microsoft Corporation.

UNIX is a registered trademark of The Open Group in the United States and othercountries.


This product includes software developed by the Apache Software Foundation(http://www.apache.org/).

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

Other company, product, and service names may be trademarks or service marksof others.

Appendix C. Notices 191

��

Printed in U.S.A.

IBM Directory Integrator 4.7: Reference Guide

Documents

Transcript of IBM Directory Integrator 4.7: Reference Guide