TIBCO ActiveMatrix Adapter for LDAP Configuration and Deployment. Software Release 6.0 August 2010

Transcription

1 TIBCO ActiveMatrix Adapter for LDAP Configuration and Deployment Software Release 6.0 August 2010

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN TIBCO ACTIVEMATRIX ADAPTER FOR LDAP CONFIGURATION AND DEPLOYMENT). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIB, TIBCO, TIBCO Software, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO Rendezvous, TIBCO ActiveMatrix Administrator, TIBCO Designer, TIBCO Hawk, and TIBCO Enterprise Message Service are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 iii Contents Figures vii Tables ix Preface xi Related Documentation xii TIBCO Product Documentation xii Other TIBCO Product Documentation xii Typographical Conventions xiv How to Contact TIBCO Customer Support xvii Chapter 1 Preparing LDAP Server Interfaces Overview Preparing the LDAP Server for Use with the Adapter Enabling SSL on the LDAP Servers Chapter 2 Getting Started Prerequisites Scenario Overview Connections to LDAP Permissions to Access Repository Server Other Examples Creating the Project Configuring the Adapter Configuring the Publication Service Configuring the Subscription Service Configuring the Request-Response Service Converting the Project to a Repository File Deploying the Project and Start the Adapter Chapter 3 Adapter Instance Options Overview Configuration Tasks

4 iv Contents Configuring the SSL Environment Converting Certificates to Use SSL at Design Time Using SSL with the Adapter Adapter Instance Fields Configuration Tab Design-time Connection Tab Run-time Connection Tab General Tab Multithreading Tab Logging Tab Startup Tab Monitoring Tab Adapter Services Publication Service Fields Configuration Tab Transport Tab Schema View Tab Schema Tab Subscription Service Fields Configuration Tab Transport Tab Schema View Tab Schema Tab Request-Response Service Fields Configuration Tab Transport Tab Schema View Tab Schema Tab Supported LDAP Operations and Message Structure Chapter 4 Deploying and Starting the Adapter Using TIBCO Administrator Creating an EAR File in TIBCO Designer Deploying the Project Starting or Stopping the Adapter Monitoring the Adapter Chapter 5 Advanced Topics Using the Adapter with a Revision Control System Defining a TIBCO Hawk Session Using Global Variables Changing Global Variable Values at Runtime

5 Contents v Predefined Global Variables Setting Encoding Options LDAP Server Synchronization Password Synchronization between Sun Directory Server and Microsoft Active Directory Server Configuring the Repository for Binary Attribute Support Message Acknowledgement Message Acknowledgement by the Request-Response Service Message Acknowledgement by the Subscription Service Publishing Messages Configuring Timers for Publication Services Publishing Messages in Sequence Publishing Duplicate Events Publishing Deleted Entries in the Microsoft Active Directory Server Updating Entries in the LDAP Server Adding a User Account with a Password into Microsoft Active Directory Server Changing the LDAP Server Connection Parameters Migration Chapter 6 Monitoring the Adapter Using TIBCO Hawk Overview Starting TIBCO Hawk Software The Auto-Discovery Process Invoking Microagent Methods Available Microagents activatetracerole() deactivatetracerole() getadapterserviceinformation() getcomponents() getconfig() getconfigproperties() gethostinformation() getrvconfig() getstatus() gettracesinks() getversion() _onunsolictedmsg() preregisterlistener() reviewledger() settracesinks() stopapplicationinstance() unregisterlistener()

6 vi Contents getactivitystatistics() getactivitystatisticsbyoperation() getactivitystatisticsbyservice getconnectionstatistics() getpollinginterval() getqueuestatistics() getthreadstatistics() resetactivitystatistics() resetconnectionstatistics() resetthreadstatistics() setpollinginterval() Appendix A Trace Messages Overview Trace Message Fields Status Messages Appendix B Additional LDAP Directory Server Settings Setting Default Naming Context in ADAM Configuring Global Catalog Server Index

7 vii Figures Figure 1 Launch TIBCO Designer Figure 2 TIBCO Designer Panel Figure 3 Configuration Tab of Adapter Figure 4 Design-time Connection Tab of Adapter Figure 5 Logging Tab of Adapter Figure 6 Transport Tab of Publication Service Figure 7 Schema View Tab of Publication Service Figure 8 Transport Tab of Subscription Service Figure 9 Schema View Tab of Subscription Service Figure 10 Transport Tab of Request-Response Service Figure 11 Schema View Tab of Request-Response Service Figure 12 Lengthy Schema Name Figure 13 Schema Files Created Figure 14 Warning: Add File to RCS Figure 15 Monitoring Tab when defining a Hawk Session Figure 16 DefaultHawkSession Icon Figure 17 HawkSession Defined Figure 18 Hawk Enterprise Monitor Figure 19 Microagents, Methods and Arguments Dialog Figure 20 Displaying a Method Figure 21 Invocation Results Dialog Figure 22 Add/Remove Snap-in Figure 23 Add Standalone Snap-in Figure 24 Schema Management Console Figure 25 Expanded Schema Management Console Figure 26 subclassof Properties Figure 27 systemauxiliaryclass Properties

8 viii Figures

9 ix Tables Table 1 General Typographical Conventions xiv Table 2 Syntax Typographical Conventions xv Table 3 Field Description of Configuration Tab Table 4 Field Description of Design-time Connection Tab Table 5 Field Description of Run-time Connection Tab Table 6 Field Description of General Tab Table 7 Field Description of Multithreading Tab Table 8 Field Description of Logging Tab Table 9 Field Description of Startup Tab Table 10 Field Description of Monitoring Tab Table 11 Field Description of Configuration Tab Table 12 Field Description of Transport Tab Table 13 Field Description of Schema View Tab Table 14 Field Description of Schema Tab Table 15 Field Description of Configuration Tab Table 16 Field Description of Transport Tab Table 17 Field Description of Schema View Tab Table 18 Field Description of Schema Tab Table 19 Field Description of Configuration Tab Table 20 Field Description of Transport Tab Table 21 Field Description of Schema View Tab Table 22 Field Description of Schema Tab Table 23 Predefined Global Variables Table 24 Microagent Methods Table 25 Tracing Fields

10 x Tables

11 xi Preface TIBCO ActiveMatrix Adapter for LDAP is a bidirectional gateway between applications configured for the TIBCO environment and an LDAP server. Topics Related Documentation, page xii Typographical Conventions, page xiv How to Contact TIBCO Customer Support, page xvii

12 xii Preface Related Documentation This section lists documentation resources you may find useful. TIBCO Product Documentation The following documents form the TIBCO ActiveMatrix Adapter for LDAP documentation set: TIBCO ActiveMatrix Adapter Concepts Read this manual to gain an understanding of adapters in general that you can apply to the various tasks you may undertake. This manual explains concepts relating to the adapter and the application with which it interacts. Installation, configuration, and deployment information is included in this manual. TIBCO ActiveMatrix Adapter for LDAP Examples This manual provides hands-on examples that demonstrate the use of the adapter. TIBCO ActiveMatrix Adapter for LDAP Release Notes Read this document for information about new features, deprecated features, and open and closed issues. README for TIBCO ActiveMatrix Adapter for LDAP Read this document to get information on the current release version, and see a summary of software and hardware requirements for installing and running the adapter. Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products. Note that only books that relate to adapters are listed. Each of the books is available from the doc directory in the product s installation area. TIBCO ActiveEnterprise TIBCO Designer TIBCO Administrator TIBCO ActiveMatrix BusinessWorks TIBCO Rendezvous TIBCO Enterprise Message Service TIBCO Hawk

13 Related Documentation xiii TIBCO Adapter SDK TIBCO Runtime Agent

14 xiv Preface Typographical Conventions The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention TIBCO_HOME ENV_HOME Use Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco. Other TIBCO products are installed into an installation environment. Incompatible products and multiple instances of the same product are installed into different installation environments. The directory into which such products are installed is referenced in documentation as ENV_HOME. The value of ENV_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco. code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process. bold code font Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable disable] italic font Italic font is used in the following ways: To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts. To introduce new terms. For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName

15 Typographical Conventions xv Table 1 General Typographical Conventions (Cont d) Convention Key combinations Use Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q. The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken. Table 2 Syntax Typographical Conventions Convention Use [ ] An optional item in a command or code syntax. For example: MyCommand [optional_parameter] required_parameter A logical OR that separates multiple items of which only one may be chosen. For example, you can select only one of the following parameters: MyCommand para1 param2 param3

16 xvi Preface Table 2 Syntax Typographical Conventions (Cont d) Convention Use { } A logical group of items in a command. Other syntax notations may appear within each logical group. For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4. MyCommand {param1 param2} {param3 param4} In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4: MyCommand {param1 param2} {param3 param4} In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4. MyCommand param1 [param2] {param3 param4}

17 How to Contact TIBCO Customer Support xvii How to Contact TIBCO Customer Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows. For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a username and password. If you do not have a username, you can request one.

18 xviii Preface

19 1 Chapter 1 Preparing LDAP Server Interfaces This chapter explains how to configure the LDAP server to interoperate with the adapter. Topics Overview, page 2 Preparing the LDAP Server for Use with the Adapter, page 3

20 2 Chapter 1 Preparing LDAP Server Interfaces Overview Before configuring the adapter, you must prepare the LDAP Server applications interfaces so that the adapter can interoperate with it.

21 Preparing the LDAP Server for Use with the Adapter 3 Preparing the LDAP Server for Use with the Adapter Configuring the LDAP Server involves the following task: Enabling SSL on the LDAP Servers Enabling SSL on the LDAP Servers SSL (Secure Sockets Layer) is a network protocol that allows authentication and encryption of data. SSL provides a secure connection between a client and a server. Based on the SSL configurations of the client and the server, various levels of privacy are established. Understanding the basic operation of SSL will help you to correctly configure the required level of privacy for the client as well as the application data. SSL supports, but does not require, server authentication (the client authenticates the server), client authentication (the server authenticates the client), and mutual authentication. SSL uses public key cryptography. One, or both the communicating applications has a public-private key pair; these keys are symmetric; data encrypted with the public key can be decrypted with the private key, and vice versa. To use SSL on all supported directory servers, the server's key pair must be pre generated and configured in the server.

22 4 Chapter 1 Preparing LDAP Server Interfaces

23 5 Chapter 2 Getting Started This chapter presents examples that demonstrate key adapter features. Work through these examples to get a hands-on understanding of how the adapter works. Topics Prerequisites, page 6 Creating the Project, page 7 Configuring the Adapter, page 9 Configuring the Publication Service, page 12 Configuring the Subscription Service, page 14 Configuring the Request-Response Service, page 17 Converting the Project to a Repository File, page 20 Deploying the Project and Start the Adapter, page 21

24 6 Chapter 2 Getting Started Prerequisites Before starting the configuration exercise, make sure that all required software has been installed and is operating correctly. For a list of required software, see the installation instructions in TIBCO ActiveMatrix Adapter for LDAP Installation. You should know how to drag and drop icons in TIBCO Designer and be familiar with saving projects. If you are not familiar with these topics, refer to the TIBCO Designer User s Guide, which is available by clicking Help -> Designer Help in TIBCO Designer. Scenario Overview The exercises in this chapter are designed to help you become familiar with basic adapter configuration. Running through these exercises will familiarize you with the different LDAP operations that a service supports. Connections to LDAP Make sure that the adapter is connected to the LDAP Server. See Chapter 1, Preparing LDAP Server Interfaces, on page 1 for details. Permissions to Access Repository Server If your site is using TIBCO ActiveMatrix Administrator to set access control to the repository server, you must have the account name and password that is used by the adapter to log onto the server. Other Examples TIBCO ActiveMatrix BusinessWorks examples are available in the TIBCO_HOME\adapter\adldap\version_num\examples directory. For more information, see the TIBCO ActiveMatrix Adapter for LDAP Examples.

25 Creating the Project 7 Creating the Project The TIBCO Designer GUI is used to configure adapter instances. When starting TIBCO Designer, you must create or select a project. A project contains the configuration files that define options used by a runtime adapter. After a project is configured, it is converted to a repository file and available for use by the runtime adapter. To create a project: 1. Start TIBCO Designer by executing the following command, depending on your operating system. On Microsoft Windows, select: Start -> Programs -> TIBCO -> TIBCO Designer 5.6- > Designer 5.6 On UNIX, from a command window change directory to the install-path/tibco/designer/5.6/bin directory and type./designer 2. In the TIBCO Designer dialog, click New empty project. Figure 1 Launch TIBCO Designer 3. In the Save Project dialog, select Multi-File Project (if it is not selected) and click the Browse button for the Project Directory field. Navigate to the C:\tibco\adapter\adldap\version_num\examples folder and click the Create New Folder icon. Name the new directory LDAPConfig and click OK. 4. In the Save Project dialog, click OK. The project will be saved in the LDAPConfig directory.

26 8 Chapter 2 Getting Started The next diagram shows the TIBCO Designer GUI with the LDAPConfig project defined. Figure 2 TIBCO Designer Panel Project panel Design panel Configuration panel Palette panel

27 Configuring the Adapter 9 Configuring the Adapter An adapter instance can contain publication services, subscription services, or request-response services. Options for logging, design-time connection, startup, and monitoring are set on the adapter instance. In this exercise, default values are used for all these options except design-time connection configuration. To configure the adapter instance: 1. Drag the LDAP Adapter Configuration icon from the palette panel to the design panel. This creates an adapter named by default, LDAPAdapterConfiguration. The name can be changed, but in this exercise, names assigned by TIBCO Designer will be used. Figure 3 Configuration Tab of Adapter 2. Click the Design-time Connection tab to specify the LDAP Server access details and select the Sun Directory Server in the Server Type drop-down. The values specified in the Design-time Connection tab must be the same as the real LDAP server information.

28 10 Chapter 2 Getting Started a. Specify the machine name in the Server Name field. b. Specify the port number in the LDAP Port field. c. Specify the user name in the User DN field. TIBCO Designer uses this user name to access the Sun Directory Server. d. Specify the password in the Password field. TIBCO Designer uses this password to access the Sun Directory Server. e. Click Test Connection to verify that the values you entered are correct for your setup. Figure 4 Design-time Connection Tab of Adapter 3. Click the Logging tab to identify the file log options. In the next diagram, Information, Warning and Error messages are specified to be logged to the log file and standard input. The Log File field lists the global variables that are used to define the log file path and name. The DirTrace and Deployment variables are set using global variables. You can click the Global Variable tab to display the variables in the project panel. The default settings will be used in this example. The InstanceId variable need not be set. The variable automatically substitutes the adapter name at runtime.

29 Configuring the Adapter 11 Figure 5 Logging Tab of Adapter 4. Select Project > Save to save the project information.

30 12 Chapter 2 Getting Started Configuring the Publication Service This section explains how to configure an adapter with a publication service that publishes a message from the specified LDAP Directory. The steps are: Configure the Publication Service Configure the Transport Information Configure the Schema Definitions Task A Configure the Publication Service 1. In the project panel, expand the LDAP Adapter Configuration node, then highlight the Adapter Services folder to access the LDAP Publication Service icon. 2. Drag the LDAP Publication Service icon from the palette panel to the design panel. 3. In the Configuration tab, specify the Service Name that this service should use, and select JMS in the Transport drop-down. Task B Configure the Transport Information 1. Click the Transport tab and enter ldapexample.pub in the Destination field. 2. Select Topic in the Connection Factory Type drop-down. Click Apply. Figure 6 Transport Tab of Publication Service

31 Configuring the Publication Service 13 Task C Configure the Schema Definitions 1. Click the Schema View tab and in the Base DN field, you can either specifiy directly the Base DN or you can click Browse DIT to select the proper Base DN. Make sure that this Base DN is identical to the real LDAP connection information. For instance, o=myorg0,c=i0,dc=mydomain,dc=portal,dc=com, LDAP_SERVER_BASE_DN. 2. Click OK. 3. Check the box Sample Entry in the Select Object Classes From field. 4. Click Browse DIT in the Sample Entry field. 5. Navigate to the proper place in the Select Sample Entry for Schema dialog box. For example, ou=myorgou0, o=myorg1, c=i0, dc=mydomain,dc=portal,dc=com 6. Click OK. 7. Click Apply in the Schema View tab. Figure 7 Schema View Tab of Publication Service 8. Select Project -> Save to save the project information.

32 14 Chapter 2 Getting Started Configuring the Subscription Service This section explains how to configure an adapter with a subscription service that subscribes to a message from the JMS Transport. You must use the project created in the previous exercise. The steps in this exercise are: Configure the Subscription Service Configure the Transport Information Configure the Schema Definitions Task A Configure the Subscription Service 1. In the project panel, expand the LDAP Adapter Configuration node, then highlight the Adapter Services folder to access the LDAP Subscription Service icon. 2. Drag the LDAP Subscription Service icon from the palette panel to the design panel. 3. In the Configuration tab, specify the Service Name that this service should use, and select JMS in the Transport drop-down. Task B Configure the Transport Information 1. Click the Transport tab and enter ldapexample.sub in the Destination field. 2. Select Topic in the Connection Factory Type drop-down. Click Apply.

33 Configuring the Subscription Service 15 Figure 8 Transport Tab of Subscription Service Task C Configure the Schema Definitions 1. Click the Schema View tab and in the Base DN field, you can either specify directly the Base DN or you can click Browse DIT to select the proper Base DN. Make sure that this Base DN is identical to the real LDAP connection information. For instance, o=myorg0,c=i0,dc=mydomain,dc=portal,dc=com, LDAP_SERVER_BASE_DN. 2. Click OK. 3. Check the box Sample Entry in the Select Object Classes From field. 4. Click Browse DIT in the Sample Entry field. 5. Navigate to the proper place in the Select Sample Entry for Schema dialog box. For example, ou=myorgou0, o=myorg0, c=i0, dc=mydomain,dc=portal,dc=com. 6. Click OK. 7. Click Apply in the Schema View tab. 8. Select Project -> Save to save the project information.

34 16 Chapter 2 Getting Started Figure 9 Schema View Tab of Subscription Service

35 Configuring the Request-Response Service 17 Configuring the Request-Response Service This section explains how to configure a request-response service to receive a request, execute the search criteria and publish the search results on JMS transport. You must use the project created in the previous exercise. The steps in this exercise are: Configure the Request-Response Service Configure the Transport Information Configure the Schema Definitions Task A Configure the Request-Response Service 1. In the project panel, expand the LDAP Adapter Configuration node, then highlight the Adapter Services folder to access the LDAP Request-Response Service icon. 2. Drag the LDAP Request-Response Service icon from the palette panel to the design panel. 3. In the Configuration tab, specify the Service Name that this service should use, and select JMS in the Transport drop-down. Task B Configure the Transport Information 1. Click the Transport tab and enter ldapexample.rpc in the Destination field. 2. Select Topic in the Connection Factory Type drop-down. Click Apply.

36 18 Chapter 2 Getting Started Figure 10 Transport Tab of Request-Response Service Task C Configure the Schema Definitions 1. Click the Schema View tab and in the Base DN field, you can either specify directly the Base DN or you can click Browse DIT to select the proper Base DN. Make sure that this Base DN is identical to the real LDAP connection information. For instance, o=myorg0,c=i0,dc=mydomain,dc=portal,dc=com, LDAP_SERVER_BASE_DN. 2. Click OK. 3. Check the box Sample Entry in the Select Object Classes From field. 4. Click Browse DIT in the Sample Entry field. 5. Navigate to the proper place in the Select Sample Entry for Schema dialog box. For example, ou=myorgou0, o=myorg0, c=i0, dc=mydomain,dc=portal,dc=com. 6. Click OK. 7. Click Apply in the Schema View tab. 8. Select Project -> Save to save the project information.

37 Configuring the Request-Response Service 19 Figure 11 Schema View Tab of Request-Response Service

38 20 Chapter 2 Getting Started Converting the Project to a Repository File The project must be exported to the DAT (repository) format for use by the adapter. To export the project to a local repository: 1. Select Project -> Export Full Project. 2. In the Export Project dialog box, specify the project name and the directory to save to. Click OK. It is recommended that you save the project as example.dat, as the exercises in this chapter use example.dat as the project name.

39 Deploying the Project and Start the Adapter 21 Deploying the Project and Start the Adapter Before starting the adapter, you must create a properties file for the adapter. Task A Deploy the Adapter To create a properties file for the adapter: 1. Change directory to the adapter bin directory: cd C:\tibco\adapter\adldap\version_num\bin 2. Copy adldap.tra to a new text file named example.tra. 3. Using a text editor, open the example.tra file and change the following properties. Change: #TIBCO.repourl repourl to: TIBCO.repourl C:/tibco/adapter/adldap/version_num/examples/example.dat Change: #TIBCO.configurl configurl to: TIBCO.configurl adldap/ldapadapterconfiguration Change: application.args adldap -system:propfile C:/tibco/adapter/adldap/version_num/bin/adldap.tra to: application.args adldap-system:propfile C:/TIBCO/adapter/adldap/version_num/bin/example.tra Task B Start the Adapter Open a command window. 1. Start the JMS Server by executing the following command: On Microsoft Windows, select Start -> Programs -> TIBCO -> TIBCO Enterprise Message Service -> Start EMS Server. On Unix, from a command window change directory to the install-path/tibco/jms/bin directory and type./tibjmsd 2. In the second command window change directory to the install-path/tibco/adapter/adldap/version_num/bin directory. 3. Start the adapter: adldap --run --propfile example.tra

40 22 Chapter 2 Getting Started

41 23 Chapter 3 Adapter Instance Options This chapter explains how to create an adapter instance and assign it services by configuring standard settings. All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the runtime adapter. Topics Overview, page 24 Configuring the SSL Environment, page 25 Adapter Instance Fields, page 28 Adapter Services, page 41 Publication Service Fields, page 42 Subscription Service Fields, page 52 Request-Response Service Fields, page 61 Supported LDAP Operations and Message Structure, page 71

42 24 Chapter 3 Adapter Instance Options Overview You can configure adapter instances and add and configure adapter services using TIBCO Designer. Configuration Tasks Use the following sequence to create and configure an adapter service. 1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer User s Guide for details on multi-file projects. 2. Drag the LDAP Adapter Configuration icon from the palette panel to the design panel. This creates an adapter named, by default, LDAPAdapterConfiguration. 3. Define the adapter instance by assigning a new name and optionally change logging options. See Logging Tab on page 38 for details. 4. Specify the LDAP Design Time Connection and test the connection. 5. Add a service to the adapter instance by dragging the service icon from the palette panel and dropping it in the design panel. 6. Define the configuration, transport, and schema options for the service. 7. To select a Base DN for a service, in the Schema View tab, click the Browse DIT button. The Directory Information Tree is displayed in a dialog. Specify the Maximum Number of Entries and then select an LDAP entry for the service from the DIT. You can also browse the DIT to specify a sample entry for the schema. This generates the class reference needed for the service. Repeat step 2 through step 7 for each adapter service that you want to configure. Set the combination of options required for your service. See the Configuration Tab on page 29 for details. 8. Export the project as a local repository and exit TIBCO Designer. After configuring the adapter, you must create the runtime adapter properties file and add the project name and adapter instance name.

43 Configuring the SSL Environment 25 Configuring the SSL Environment Configuring the SSL environment involves the following tasks: Converting Certificates to Use SSL at Design Time You will need to obtain the following from your LDAP server administrator: 1. The CA (Certificate Authority) certificate that signed the LDAP server certificate. 2. To use External (client certificate based) authentication, the certificate and private key of the LDAP user that the adapter will authenticate to the LDAP server as a PKCS12 file. Use the administration tools of the LDAP server to export the LDAP user s certificate and private key. The samples assume that the PKCS12 file is called userident.p12. The PKCS12 file is encrypted with a password and you will need that as well. To use SSL for the design-time connection, the certificates and keys must be imported into a keystore as described in Converting Certificates to Use SSL at Design Time. Converting Certificates to Use SSL at Design Time To use SSL for the design-time connection to the LDAP server, the CA certificate must be imported into a keystore. Use the Java utility keytool for this. The command for using this utility is: TIBCO_HOME\jre\1.6.0\bin\keytool -import -v -alias alias -file cert_file -keystore keystore To import the CA certificate from the cacert.der file into the keystore file, TIBCO_HOME\jre\1.6.0\lib\security\keystore with the alias CAcert, run the following command: TIBCO_HOME\jre\1.6.0\bin\keytool -import -v -alias CAcert -file cacert.der -keystore TIBCO_HOME\jre\1.6.0\lib\security\cace rts You will be prompted to choose a password. You require this password to import additional certificates into the keystore. Select yes when the keytool prompts you to trust the imported certificate. To use SSL at design time with anonymous or simple authentication: In the Design-time Connection tab, specify the following values. For details, see Design-time Connection Tab on page 30.

44 26 Chapter 3 Adapter Instance Options Specify the LDAP server (Hostname or IP address). Specify the port number in the LDAP Port field. Select the Use SSL check box. In the Trusted Certificate Authorities field, specify the path to the Java keystore you created earlier. In the example above, the keystore file is in the TIBCO_HOME\jre\1.6.0\lib\security\cacerts folder. Specify the authentication mode to be Simple or Anonymous. If you select Simple authentication, the User DN and Password are mandatory. Click Test Connection to make sure that the design-time adapter can connect to the LDAP server using SSL with the specified parameters. To use SSL at design time with external authentication: 1. In the Design-time Connection tab, specify the following values. For details, see Design-time Connection Tab on page 30. Enter the LDAP Server (Hostname or IP address). Specify the port number in the LDAP Port field. Select the Use SSL check box. In the Trusted Certificate Authorities field, specify the path to the Java keystore you created earlier. In the example above, the keystore file is TIBCO_HOME\jre\1.6.0\lib\security\cacerts. 2. Select External for the Authentication mode. 3. In the Client Identity field, specify the full path to the PKCS12 file that has the LDAP user s certificate and key. 4. In the Identity Password field, provide the password to the PKCS12 file. 5. Click Test Connection to make sure that the design-time adapter can connect to the LDAP server using SSL with the specified parameters. Using SSL with the Adapter To use the SSL protocol with the adapter: 1. Configure SSL support in the LDAP server. For further information, see Preparing the LDAP Server for Use with the Adapter on page Get the LDAP server's certificate and the certificate (chain) of the CA that issued the LDAP server's certificate.

45 Configuring the SSL Environment Create certificate stores containing the certificates. For the design-time and runtime connection, use the Java keytool to create a keystore. For details, refer to Converting Certificates to Use SSL at Design Time on page 25. If you are using Active Directory as the LDAP server and setting up a publication service, you must also import the certificate to the systems certificate store on the Microsoft Windows machine that will run the adapter. 4. Configure the SSL parameters on the Design-time Connection tab. Refer to Design-time Connection Tab on page Configure the SSL parameters on the Run-time Connection tab. Refer to Run-time Connection Tab on page 33. You can configure SSL separately for the design-time and runtime connections.

46 28 Chapter 3 Adapter Instance Options Adapter Instance Fields The following tabs can be used to define an adapter instance: Configuration Tab, page 29 Design-time Connection Tab, page 30 Run-time Connection Tab, page 33 General Tab, page 36 Multithreading Tab, page 37 Logging Tab, page 38 Startup Tab, page 39 Monitoring Tab, page 39

47 Adapter Instance Fields 29 Configuration Tab This tab contains the fields below: Table 3 Field Description of Configuration Tab Field Instance Name Description Version Message Filter Description Use the default name or replace it with a name of your choice. An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name. An instance name cannot use global variables. An instance name must be unique with respect to other adapter instances for the same adapter in the project. The same instance name can be used to name an adapter instance for a different adapter in the same project. For example, an R/3 adapter instance named TEST and a Siebel adapter instance named TEST can coexist in the same project. Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique. When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance to which they belong. Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated next time you rename the adapter instance. Provide information about the adapter instance that you want stored in the project. The field is optional. The version string indicates the ActiveEnterprise (AE) format in which the adapter instance is saved. An adapter instance can be saved in AE Version 4.0 or AE Version 5.1, AE Version 5.2 and AE Version 5.3 format. When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to AE Version 5.3. To change versions, click the Change Version button. Specify a message filter, if you have configured a message filter resource for use with the adapter. The filter allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Filters can be written using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer s Guide for information about writing a message filter.

48 30 Chapter 3 Adapter Instance Options Table 3 Field Description of Configuration Tab (Cont d) Field Shall All Tabs Description Select this box to display additional tabs for configuring advanced options. Design-time Connection Tab Many of the following fields make use of global variables. Click the Global Variables tab in the project panel to enter a value for a global variable. Table 4 Field Description of Design-time Connection Tab Field Server Type Server Name Description Specify the type of server. This is the name of the LDAP server that the adapter will connect to. You can choose Microsoft Active Directory Server/ADAM, IBM Directory Server, Sun Directory Server, Novell edirectory, or Oracle Internet Directory, and Others. Others is a new feature in 6.0.0, but only limited testing has been conducted, thus Others is not officially supported. Specify the name of the machine where the LDAP server is installed. If an existing dat file is opened and the machine name is changed, then the following message displays: You have already configured adapter instances and services for a particular LDAP server. The change that you are attempting will be valid only if the new server has identical directory information tree and schemas. Please confirm this and that you do wish to proceed with this change. Click Yes to effect the changes to the machine name. Click No to revert to the previous value.

49 Adapter Instance Fields 31 Table 4 Field Description of Design-time Connection Tab (Cont d) Field Use SSL LDAP Port Authentication Mode User DN Description Select this check box to specify whether the SSL protocol should be used. By default, this check box is not selected. In TIBCO ActiveMatrix Adapter for LDAP 6.0.0, the projects using SSL (irrespective of simple or external) that were created in cannot be started. In such a case, users need to reconfigure the SSL configuration in the Run-time Connection tab before running the project. Three parameters, in 5.4.0, under Run-time Connection tab Converted Certificates and Keys Directory, Client Certificate Name, and Client Key Password have been respectively replaced by Trusted Certificate Authorities, Client Identity and Identity Password in As a result, users need to set these three new parameters to values that are identical to the values of the same parameters under Design-time Connection tab. Specify the number of the port that the adapter is configured to listen to. The default port number for LDAP servers is 389. The default SSL port number is 636. The mode of authentication used for connecting to the LDAP server. Currently, the following are supported: Simple If you select the Simple authentication mode, you must specify the user name and password required to log on to the LDAP server. Click Test Connection. If the entries are accurate, the adapter will connect to the server. Anonymous If you select the Anonymous authentication mode, you do not need to specify the user name and password. You will be logged on to the LDAP server automatically. Click Test Connection. If the configuration is accurate, the adapter will connect to the server. External This field is only available if you select the Use SSL check box. If you select the External authentication mode, you must ensure that the User DN and Password fields are empty. In the Client Identity field, provide the path to the userident.p12 file. Also, enter the password for the.p12 file in the Identity Password field. Click Test Connection. If the entries are accurate, the adapter will connect to the server. Specify the user name that will be used to log on to the LDAP server. You must specify the DN used to bind to the LDAP server. For example, cn=administrator,cn=users,dc=adsldap.

50 32 Chapter 3 Adapter Instance Options Table 4 Field Description of Design-time Connection Tab (Cont d) Field Password Remember Password Use Design-time Connection for Run-time Trusted Certificate Authorities Client Identity Identity Password Verify Server Certificate Common Name Test Connection Description Specify the password that will be used to log on to the LDAP server at design time. When the Server Type is IBM Directory Server, and if SSL external mode is used, correct User DN and Password must be entered. If SSL external mode is used, but the Server Type is not IBM Directory Server, User DN and Password fields are disabled. If this check box is not selected, the password must be entered each time the project is opened. If it is selected, the password will be stored in the project repository. This password is for the design-time connection only. The password for the runtime connection is stored in the adldap.tra file, either in clear text or in obfuscated format. Select this check box to use the design-time connection information for the runtime adapter. This is the file that contains the list of trusted certificates and specifies which Certificate Authorities should be trusted as issuers of the LDAP server certificate. The file is created using keytool. This field supports the use of global variables You must specify the complete path of the client.pfx or.p12 file. This field supports the use of global variables This is the password that is used to decrypt the private key of the client. This field supports the use of global variables The design-time connection does not support this option. Click to test the validity of the connection information that you specified for the adapter instance.

51 Adapter Instance Fields 33 Run-time Connection Tab This tab contains the fields below: Table 5 Field Description of Run-time Connection Tab Field Server Type Server Name Use SSL LDAP Port Description Specify the type of server. This is the name of the LDAP server that the adapter will be connecting to. You can choose Microsoft Active Directory Server/ADAM, IBM Directory Server, Sun Directory Server, Novell edirectory, or Oracle Internet Directory, and Others. Others is a new feature in 6.0.0, but only limited testing has been conducted, thus Others is not officially supported. Specify the name of the machine where the LDAP server is installed. Select this check box to specify whether the SSL protocol should be used. By default, this check box is not selected. In TIBCO ActiveMatrix Adapter for LDAP 6.0.0, the projects using SSL (irrespective of simple or external) that were created in cannot be started. In such a case, users need to reconfigure the SSL configuration in the Run-time Connection tab before running the project. Three parameters, in 5.4.0, under Run-time Connection tab Converted Certificates and Keys Directory, Client Certificate Name, and Client Key Password have been respectively replaced by Trusted Certificate Authorities, Client Identity and Identity Password in As a result, users need to set these three new parameters to values that are identical to the values of the same parameters under Design-time Connection tab. Specify the number of the port that the adapter is configured to listen to. The default port number for LDAP servers is 389. The default SSL port number is 636.

52 34 Chapter 3 Adapter Instance Options Table 5 Field Description of Run-time Connection Tab Field Authentication Mode User DN Password Description The mode of authentication used for connecting to the LDAP server. Currently, the following are supported: Simple If you select the Simple authentication mode, you must specify the user name and password required to log on to the LDAP server. Click Test Connection. If the entries are accurate, the adapter will connect to the server. Anonymous If you select the Anonymous authentication mode, you do not need to specify the user name and password. You will be logged on to the LDAP server automatically. Click Test Connection. If the configuration is accurate, the adapter will connect to the server. External This field is only available if you select the Use SSL check box. If you select the External authentication mode, you must ensure that the User DN and Password fields are empty. In the Client Identity field, provide the path to the userident.p12 file. Also, enter the password for the.p12 file in the Identity Password field. Click Test Connection. If the entries are accurate, the adapter will connect to the server. Specify the user name that will be used to log on to the LDAP server. You must specify the DN used to bind to the LDAP server. For example, cn=administrator,cn=users,dc=adsldap. Specify the password that the adapter must use at run time. The password is encrypted and stored in the project file. If you select the Use Design-time Connection for Run-time check box under the Design-time Connection tab, the adapter uses the design-time password at run time too. To maintain backward compatibility, if the runtime password is not specified or if the field is empty in the project file, the adapter uses the password from the.tra file. This field is mandatory. The adapter handles the password at design time and run time as follows: In the release and later, you can enter the runtime password in the Password field under the Run-time Connection tab. The adapter looks for the runtime password in the project file. In the release, you cannot specify a runtime password through TIBCO Designer. However, if you select both the Remember Password and Use Design-time Connection for Run-time check boxes, the adapter first looks for the password in the project file. If there is no specified password, the adapter uses the password specified in the.tra file.

53 Adapter Instance Fields 35 Table 5 Field Description of Run-time Connection Tab Field Trusted Certificate Authorities Client Identity Identity Password Verify Server Certificate Common Name Maximum Number of Reconnect Attempts Number of Reconnect Attempts Before Suspending Impacted Service(s) Interval between Reconnect Attempts (milliseconds) Description This is the file that contains the list of trusted certificates and specifies which Certificate Authorities should be trusted as issuers of the LDAP server certificate. The file is created using keytool. This field supports the use of global variables You must specify the complete path of the client.pfx or.p12 file. This field supports the use of global variables This is the password that is used to decrypt the private key of the client. This field supports the use of global variables. The runtime connection does not support this option. Specify the total number of reconnection attempts to make before the runtime adapter or adapter service is stopped. A value of -1 means reconnection attempts will continue indefinitely. You cannot specify a value of zero. Specify the number of reconnection attempts to make before suspending the adapter services. Specify the time interval in milliseconds, between each reconnection attempt.

54 36 Chapter 3 Adapter Instance Options Table 5 Field Description of Run-time Connection Tab Field Adapter Termination Criteria (after max number of reconnect attempts) Description The adapter provides the following choices: When All Services Are Suspended To stop the adapter when a service is suspended. Therefore, only the adapter service that cannot reconnect is stopped. Other adapter services that are connected continue to function normally. When Any Service is Suspended To stop the adapter if any one service is unable to re-establish a connection after the specified number of reconnection attempts. However, since the adapter currently supports only a single connection to a LDAP server, either choice results in the same behavior. The adapter stops after the maximum number of reconnection attempts. General Tab This tab contains the fields below: Table 6 Field Description of General Tab Field Termination Subject or Topic Adapter Encoding Description A message sent on the termination subject (if TIBCO Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter. In most cases, you should use the default value. See TIBCO Rendezvous Concepts for information about specifying subject names. See the TIBCO Enterprise Message Service User s Guide for information about publishing on a topic. This field has been disabled and is no longer available for use.

55 Adapter Instance Fields 37 Multithreading Tab It is possible to run the adapter in the multithreaded mode for improved throughput and performance. You can specify the number of concurrent dispatcher threads that are to be operated for a given session. Table 7 Field Description of Multithreading Tab Session Name Number of Threads Shows the TIBCO-enabled application session that has been created by TIBCO Designer. A termination service must use a different session from the session that is configured because if all threads are waiting for a connection, there will be no thread available to process the termination request. Setting a session for the termination service that is different from the configured session ensures that the request is processed immediately. Specifies the number of dispatch threads to be started for this session. It is recommended that you set the threading after configuring all the services. Setting the threads after configuring the services will allow you to inspect all the different sessions and choose the appropriate thread counts.

56 38 Chapter 3 Adapter Instance Options Logging Tab This tab contains the fields below: Table 8 Field Description of Logging Tab Field Use Advanced Logging Description When Use Advanced Logging is not selected (the default), you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected. When Use Advanced Logging is selected, you have complete control on selecting the destinations and associating desired roles with each of the destinations. To create and configure the sinks, select the log sinks folder under the Advanced folder in the project panel. To create sinks, drag and drop the Generic log sink icon from the palette panel into the design panel. From the configuration panel, select the sink type. The following are the sink types available: File Hawk Network STDIO When File and STDIO sinks are created from the Generic log sink, they offer further configuration options. For the File sink, the file limit, file count, and the option to append or overwrite can be specified. When created by default, this is set to bytes, 3 and Append Mode respectively. For the STDIO sink, the option to write to stdout or stderr can be selected. When created by default, stdout is selected. The Hawk sink uses the hawk session, created and used by the adapter for monitoring purposes, to send tracing messages to the TIBCO Hawk monitor or Display. For details on Hawk sessions, see Using Global Variables on page 90. The configuration for the Hawk sink involves specifying the MicroAgent Name that must be specified in the configuration panel. The Network sink is used to publish tracing messages on TIBCO Rendezvous. The configuration for the network sink involves specifying the session, and the subject on which the trace messages needs to be published. For all the sinks, optionally the name and description for the sink can be provided.

57 Adapter Instance Fields 39 Table 8 Field Description of Logging Tab (Cont d) Field Log to Standard I/O Log File Log Info/Debug/ Warning/Erro r Messages Description (STDIO Sink) When selected, trace messages are displayed in the command prompt window where the adapter is started. When not selected, trace messages do not display in the window. Specify the name of the log file (log sink) to which trace messages are written. Global variables can be used to specify the location of the log file. See Using Global Variables on page 90 for more information. The roles available are Info, Debug, Warning, and Error messages. The trace message generated depends on the roles selected. Turning on the roles can affect the performance of the adapter. Therefore, it is recommended that you turn on the required roles only. Trace messages of the selected level(s) will be collected in the named log sink. You can configure what levels of trace messages you want logged, and where trace messages are sent. There are three types of logs (log sinks) that you can configure to hold trace messages, corresponding to three levels (roles) of trace messages, Information, Warning and Error. A fourth level of trace messages, Debug, is reserved and should not be enabled unless requested by the TIBCO Product Support Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter. Startup Tab This tab contains the fields below: Table 9 Field Description of Startup Tab Show Startup Banner Metadata Search URL Select this option to show the startup banner. The startup banner displays the runtime adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started. This field has been disabled and is no longer available for use. Monitoring Tab Many of the following fields make use of global variables. Click the Global Variables tab in the project panel to enter a value for a global variable.

58 40 Chapter 3 Adapter Instance Options Table 10 Field Description of Monitoring Tab Field Enable Standard Microagent Standard Microagent Name Enable Class Microagent Class Microagent Name Class Microagent Timeout Standard Microagent Timeout Default Microagent Session Description Allows you to turn on or off the standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the standard microagent on or off. This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used. The InstanceId variable need not be set because it is automatically set at run time by the runtime adapter. Allows you to turn on or off the instance or class specific standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the class microagent on or off. This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used. Specifies the amount of time the Hawk Agent should wait for HMA method invocations to complete before timing them out. The default is milliseconds. Normally there is no need to change this value, however, on machines under extreme stress where method invocations are timing out, this new option allows the timeout value to be increased. See above, Class Microagent Timeout. This field is predefined and cannot be changed. It specifies the name of the TIBCO Rendezvous session that will be used by the standard, class, and custom microagents. The session name and the corresponding session is automatically generated by TIBCO Designer. Do not change the session name or the session. However, you can modify the session parameters if required. Navigate to the Sessions folder under the Advanced folder to modify the session parameters. Make sure you have set the correct parameter value for the global variables that correspond to the TIBCO Hawk configuration. If the session parameters are not set properly, the microagents will not display in the TIBCO Hawk Display.

59 Adapter Services 41 Adapter Services After configuring an adapter instance, select one or multiple adapter services for the instance. The following sections describe the services and fields that are available to the adapter. Publication Service Fields on page 42 Subscription Service Fields on page 52 Request-Response Service Fields on page 61

60 42 Chapter 3 Adapter Instance Options Publication Service Fields The following tabs are available: Configuration Tab on page 42 Transport Tab on page 43 Schema View Tab on page 48 Schema Tab on page 51 The publication service supports the following LDAP operations: INSERT, UPDATE, DELETE and MODIFY DN. Changes made through the INSERT, UPDATE, DELETE and MODIFY DN operations on the LDAP server are picked up by the adapter and published. Configuration Tab This tab contains the fields below: Table 11 Field Description of Configuration Tab Field Name Description Description You can use the default name or replace it with a name of your choice. A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name. A service name cannot use global variables. Provide information about the service that you want stored in the project. The field is optional.

61 Publication Service Fields 43 Table 11 Field Description of Configuration Tab (Cont d) Field Transport Type Description Select the transport to be used by the runtime adapter, JMS or TIBCO Rendezvous. After selecting the transport, the transport-specific configuration fields display. The transport can be configured to use a trusted store and identity resource for SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field that provides a dialog for SSL configuration. To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and select the Use SSL check box. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help. Transport Tab This tab contains the fields below: Table 12 Field Description of Transport Tab Field Message Subject Description This field displays only if TIBCO Rendezvous is selected in the Transport Type drop-down list (under the Configuration tab). By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.

62 44 Chapter 3 Adapter Instance Options Table 12 Field Description of Transport Tab (Cont d) Field Destination Description This field displays only if JMS is selected in the Transport Type drop-down list (under the Configuration tab). By default a service uses a dynamic destination that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name, and the service name. If you use this default dynamic destination, make sure the values for Domain and Deployment are not empty. You can override the default dynamic destination by specifying the static destination in this field. The static destination must be defined on the JMS server before it can be used by the runtime adapter. See the TIBCO Enterprise Message Service User s Guide for information about destinations. Reply Message Subject Reply Destination Quality of Service This field is not applicable to TIBCO ActiveMatrix Adapter for LDAP. This field is not applicable to TIBCO ActiveMatrix Adapter for LDAP. If TIBCO Rendezvous is selected as the transport type, select: Certified Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires. This is often called certified message delivery. If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger. Reliable Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated.

63 Publication Service Fields 45 Table 12 Field Description of Transport Tab (Cont d) Field Wire Format Connection Factory Type Description Services must use the same wire format to exchange data. ActiveEnterprise Message (TIBCO Rendezvous only) Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter SDK set of data types. This format allows ActiveEnterprise components to perform extra validation on messages sent or received. See the TIBCO Adapter SDK Programmer s Guide for details about the control information generated and sent with ActiveEnterprise messages. XML Message (TIBCO Rendezvous and JMS) The XML Message wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the ActiveEnterprise schema. Topic (JMS only) A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe. Queue (JMS only) A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.

64 46 Chapter 3 Adapter Instance Options Table 12 Field Description of Transport Tab (Cont d) Field Description Delivery Mode Persistent (JMS only) In general, a message marked persistent will be available to a JMS client even if the JMS server goes down. Non-Persistent (JMS only) A message marked non-persistent will not be available to a JMS client if the JMS server goes down. Messages sent with the persistent delivery mode are always written to persistent storage, except when they are published to a topic that has no durable subscribers. When a topic has no durable subscribers, there are no subscribers that need messages resent in the event of a server failure. Therefore, messages do not need to be saved, and performance is improved because disk I/O is not required. Session Reference Endpoint Reference Every adapter can have one or more sessions configured for it. Sessions encapsulate stateful connections to TIBCO Rendezvous and other messaging sources. The session object shown in this field is initially supplied by the adapter, depending on the Quality of Service selected. You can change the session by browsing for it in the project panel. You can drag a different endpoint, browse for another endpoint resource, go to the referenced endpoint to edit its properties or delete the endpoint. Endpoint reference objects are explained in the TIBCO Designer Palette Reference.

65 Publication Service Fields 47 The semantics for these fields are more complex than the explanation given here. See the TIBCO Enterprise Message Service User s Guide for more information. Typically, a publication service will publish INSERT, UPDATE, DELETE, and MODIFY DN operations. For the publication service on the Active Directory server, a MODIFY DN operation on any monitored entry is published as UPDATE and not as MODIFY DN. The adapter supports persistent publisher services. Therefore, the adapter will be able to publish changes that occurred on the LDAP server even when the adapter was not running. However, if the adapter is not running when the changes take place on the LDAP server, only INSERT and UPDATE operations will be published. MODIFY DN operations will be published as UPDATE while DELETE operations (for Sun Directory Server and edirectory) will not be published at all. This is because the deleted entries no longer exist on the LDAP server and information on deleted entries is also no longer available. For Active Directory, the DELETE operation will be published (whether or not the adapter is running when the delete happens on the server), but Active Directory moves the deleted entry to a Deleted Objects subtree, retaining only its RDN (Relative Distinguished Name), if there is no conflict with other deleted items. The DN of the entry itself is lost. The object GUID (a unique GUID) for the object is retained and may be used to retrieve the object from a parallel store, if it exists. When the adapter publishes a deleted object, it uses the new DN, not the original DN of the entry. So, for example, the DN may look like: DN = CN=Aparna DEL:aec6dadb-244d-4fd0-a058-4c6e7ef18a09,CN=Deleted Objects,DC=adsldap Since the information on the original DN and attribute values are not available on the Active Directory server, the adapter cannot publish those details; only the DN as used in the deleted objects container is available.

66 48 Chapter 3 Adapter Instance Options Schema View Tab This tab contains the fields below: Table 13 Field Description of Schema View Tab Field Base DN Select Object Classes From Sample Entry Description Displays the selected Base DN (Distinguished Name) of a specified node. To display the Base DN, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. When the length of an object class name that is fetched from the Base DN field exceeds 128 characters, the ActiveEnterprise schema created with this name affects the runtime functionality. When you click Apply, a dialog box (Figure 12 on page 51) is displayed that prompts you to enter a shorter name that can be stored in the schema. The name you enter must be unique and less than 128 characters. If the service has been configured with a long schema name, the dialog box will not display if a service has already been configured for the same object class. There are two methods you can use to select an object class: Sample Entry You can specify a sample entry so that the object class for that entry is populated in the Objectclasses field. LDAP Schema You can specify an object class by selecting it from the ldap schema on the ldap server. This field is available only if you select the Sample Entry option for the Select Object Classes From field. In your LDAP server, you can specify an entry from the schema you will use for this service. The service will only handle entries with identical object classes. To specify a sample entry for the schema, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. This generates the class reference needed for the service, in the Objectclasses field.

67 Publication Service Fields 49 Table 13 Field Description of Schema View Tab (Cont d) Field LDAP Schema Classes Description This field is available only if you select the LDAP Schema option for the Select Object Classes From field. To select the LDAP schema classes for the service, you can browse the LDAP schema by clicking the Browse Schema button and selecting the object classes from the Available Objectclasses list. This generates the class reference needed for the service, in the Objectclasses field. Maximum Number Of Entries Click Browse DIT for the Base DN or Sample Entry fields to access the Maximum Number of Entries field. This field is available in the Select Base DN and Select Sample Entry for Schema dialog boxes. Specify the maximum number of entries that you want to restrict the service to. The DIT expands only if the number of entries is equal to, or less than the value you specify. You cannot specify a value greater than as the maximum number of entries. If you need to select a node within a subtree that has more than entries, you must specify the DN, in the DN (Base DN/Sample Entry) box. You may come across the following exceptions The size of the result exceeds server specific limit and The Number of Descendants for this Node are more than the requested number. Additionally, if you are using the Sun Directory Server, you may come across the exception The adminstrative limit on the maximum number of entries to return was exceeded. To proceed, you will need to log on to the server and change the value for the search size limit: For the Sun Directory Server, click the Configuration tab. Select Database Settings and click the LDBM Plugin Settings tab. Change the value of the Look-through limit entry. While you are in the Configuration tab, select the root of the tree, and click the Performance tab. Change the value for the Size Limit entry too. For further details, see the documentation shipped with the server you are using. Objectclasses Displays the object class of the entry specified in the Base DN, or Sample Entry fields, if these have been specified. Otherwise, the value from the LDAP Schema Classes field is displayed. You cannot edit this field.

68 50 Chapter 3 Adapter Instance Options Table 13 Field Description of Schema View Tab (Cont d) Field Handle Any Subset of Configured Object Classes Filter Description This field is available if a composite object class is displayed in the Objectclass field. Although the adapter is configured for a composite object class, all combinations of the object class are supported. Therefore, if you select the check box, changes made to any attribute of an entry belonging to any subset of the configured object class will be published by the service. This field is not visible when the adapter instance is configured for the Microsoft Active Directory server. You can specify a filter option in this field. The adapter supports LDAP V3 filters. Only entries that conform to the specified filter will be published. The conditions used to specify a filter should be syntactically accurate. If the filter specified has an incorrect syntax, the following message is displayed: Syntax of the filter is not valid. Please ensure that you enter a valid LDAP filter. If the filter syntax is correct but no entries match the filter specifications, the following warning is displayed: No results are found on the LDAP server with the given filter. Please ensure that filter is semantically correct. This may mean that at the time of configuration, no entries may match the filter, but the entries may be present at runtime.

69 Publication Service Fields 51 Figure 12 Lengthy Schema Name Schema Tab This tab contains the fields below: Table 14 Field Description of Schema Tab Field Class Reference Description Displays the reference to the ActiveEnterprise schema that corresponds to the object class that was configured under the Schema View tab.

70 52 Chapter 3 Adapter Instance Options Subscription Service Fields The following tabs are available: Configuration Tab on page 52 Transport Tab on page 54 Schema View Tab on page 57 Schema Tab on page 60 Configuration Tab This tab contains the fields below: Table 15 Field Description of Configuration Tab Field Name Description Transport Type Description You can use the default name or replace it with a name of your choice. A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name. A service name cannot use global variables. Provide information about the service that you want stored in the project. The field is optional. Select the transport to be used by the runtime adapter, JMS or TIBCO Rendezvous. After selecting the transport, the transport-specific configuration fields display. The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field that uses a dialog to perform SSL configuration. To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

71 Subscription Service Fields 53 Table 15 Field Description of Configuration Tab (Cont d) Field LDAP Operations Update Only if Different Chase Referrals Description Specify the operations that this service supports. At least one operation must be selected. Select: Insert To add an entry. Update To update an existing entry. Delete To remove an entry. Upsert To update an entry if it already exists. If the entry does not exist, running this operation will insert it. Modify DN To move an entry from one location to another by changing the RDN (Relative Distinguished Name). Validate Object To validate the object class of a requested entry against the configured object class for all operations. The adapter has additional support for synchronization of entries between two LDAP servers through a configuration option in the subscription service. This option prevents infinite loops for server synchronization scenarios. To determine the scenarios in which this option should be selected, refer to LDAP Server Synchronization on page 95. Select this check box to specify that if a referral is encountered during an operation, the referral should be followed. When you browse the DIT tree, the adapter palette will not follow a referral and only entries on the configured server will be displayed. The referring server returns an LDAP URL in the following format: ({ldap ldaps}://host[:port]/dn). Depending on the URL used, the following referral chasing scenarios are possible: If the URL is ldaps://, then referral chasing uses SSL. If the URL is ldap://, then referral chasing does not use SSL. If the bind to the original server is SSL-EXTERNAL and the referral URL is ldap://, then the bind to referred server will be anonymous. Referrals are not supported for the publication service. Chasing referrals for a selected operation will work only if the authentication information used for connecting to the servers is identical for all servers.

72 54 Chapter 3 Adapter Instance Options Table 15 Field Description of Configuration Tab (Cont d) Field Referral Hop Count Description This field specifies the number of servers that must be followed if a referral is encountered. If there are more referral servers than the number specified in this field, these servers will not be in the purview of the specified operation. This field is available only if you select the Chase Referrals check box. Transport Tab This tab contains the fields below: Table 16 Field Description of Transport Tab Field Message Subject Description This field displays only if TIBCO Rendezvous is selected in the Transport Type drop-down list (under the Configuration tab). By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names. Destination This field displays only if JMS is selected in the Transport Type drop-down list (under the Configuration tab). By default a service uses a dynamic destination that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name, and the service name. If you use this default dynamic destination, make sure the values for Domain and Deployment are not empty. You can override the default dynamic destination by specifying the static destination in this field. The static destination must be defined on the JMS server before it can be used by the runtime adapter. See the TIBCO Enterprise Message Service User s Guide for information about destinations.

73 Subscription Service Fields 55 Table 16 Field Description of Transport Tab (Cont d) Field Quality of Service Description If TIBCO Rendezvous is selected as the transport type, select: Certified Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires. This is often called certified message delivery. If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger. Distributed Queue Distributed queue includes a group of cooperating transport objects, each in a separate process. Each transport object is called a member. To balance the transmission load among servers, the adapter can use distributed queues for one-of-n delivery of messages to a group of servers. Each member of a distributed queue listens for the same subject using the TIBCO Rendezvous Distributed Queue listener objects. Even though many members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts. Load balancing for the processing of TIBCO Rendezvous certified messages is supported by using distributed queuing. The messages from TIBCO Rendezvous are distributed equally among all instances that belong to the same group. This distributes the message load over several adapter instances. However, the order in which messages are sent to the application is not guaranteed. Reliable Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated.

74 56 Chapter 3 Adapter Instance Options Table 16 Field Description of Transport Tab (Cont d) Field Wire Format Connection Factory Type Delivery Mode Description Services must use the same wire format to exchange data. ActiveEnterprise Message (TIBCO Rendezvous only) Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter SDK set of data types. This format allows ActiveEnterprise components to perform extra validation on messages sent or received. See the TIBCO Adapter SDK Programmer s Guide for details about the control information generated and sent with ActiveEnterprise messages. XML Message (TIBCO Rendezvous and JMS) The XML Message wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the ActiveEnterprise schema. Topic (JMS only) A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe. Queue (JMS only) A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point. For a subscription service, a message is marked as durable or non durable. This field is available only if JMS transport is selected. Durable If a subscription service is marked durable, it indicates that messages need to be resent on the configured topic or queue, if the JMS server goes down. Non-Durable If a subscription service is marked non-durable, it indicates that messages will not be resent on the configured topic or queue, if the JMS server goes down.

75 Subscription Service Fields 57 Table 16 Field Description of Transport Tab (Cont d) Field Session Reference Endpoint Reference Description Every adapter can have one or more sessions configured for it. Sessions encapsulate stateful connections to TIBCO Rendezvous and other messaging sources. The session object shown in this field is initially supplied by the adapter, depending on the Quality of Service selected. You can change the session by browsing for it in the project panel. You can drag a different endpoint, browse for another endpoint resource, go to the referenced endpoint to edit its properties or delete the endpoint. Endpoint reference objects are explained in the TIBCO Designer Palette Reference. The semantics for these fields are somewhat more complex than the explanation given here. See the TIBCO Enterprise Message Service User s Guide for more information. Schema View Tab This tab contains the fields below: Table 17 Field Description of Schema View Tab Field Base DN Description Displays the selected Base DN (Distinguished Name) of a specified node. To display the Base DN, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. When the length of an object class name that is fetched from the Base DN field exceeds 128 characters, the ActiveEnterprise schema created with this name affects the runtime functionality. When you click Apply, a dialog box (Figure 12 on page 51) is displayed that prompts you to enter a shorter name that can be stored in the schema. The name you enter must be unique and less than 128 characters. If the service has been configured with a long schema name, the dialog box will not display if a service has already been configured for the same object class and has a shorter name.

76 58 Chapter 3 Adapter Instance Options Table 17 Field Description of Schema View Tab (Cont d) Field Select Object Classes From Sample Entry LDAP Schema Classes Description There are two methods you can use to select an object class: Sample Entry You can specify a sample entry so that the object class for that entry is populated in the Objectclasses field. LDAP Schema You can specify an object class by selecting it from the ldap schema on the ldap server. This field is available only if you select the Sample Entry option for the Select Object Classes From field. In your LDAP server, you can specify an entry from the schema you will use for this service. The service will only handle entries with identical object classes. To specify a sample entry for the schema, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. This generates the class reference needed for the service, in the Objectclasses field. This field is available only if you select the LDAP Schema option for the Select Object Classes From field. To select the LDAP schema classes for the service, you can browse the LDAP schema by clicking the Browse Schema button and selecting the object classes from the Available Objectclasses list. This generates the class reference needed for the service, in the Objectclasses field.

77 Subscription Service Fields 59 Table 17 Field Description of Schema View Tab (Cont d) Field Maximum Number Of Entries Description Click Browse DIT for the Base DN or Sample Entry fields to access the Maximum Number of Entries field. This field is available in the Select Base DN and Select Sample Entry for Schema dialog boxes. Specify the maximum number of entries that you want to restrict the service to. The DIT expands only if the number of entries is equal to, or less than the value you specify. You cannot specify a value greater than as the maximum number of entries. If you need to select a node within a subtree that has more than entries, you must specify the DN, in the DN (Base DN/Sample Entry) box. You may come across the following exceptions The size of the result exceeds server specific limit and The Number of Descendants for this Node are more than the requested number. Additionally, if you are using the Sun Directory Server, you may come across the exception The adminstrative limit on the maximum number of entries to return was exceeded. To proceed, you will need to log on to the server and change the value for the search size limit: For the Sun Directory Server, click the Configuration tab. Select Database Settings and click the LDBM Plugin Settings tab. Change the value of the Look-through limit entry. While you are in the Configuration tab, select the root of the tree, and click the Performance tab. Change the value for the Size Limit entry too. For further details, see the documentation shipped with the server you are using. Objectclasses Handle Any Subset of Configured Object Classes Displays the object class of the entry specified in the Base DN, or Sample Entry fields, if these have been specified. Otherwise, the value from the LDAP Schema Classes field is displayed. You cannot edit this field. This field is available if the object class displayed in the Objectclass field is a composite object class. If you select the check box, changes made to any element of the composite object class will be used by the subscription service.

78 60 Chapter 3 Adapter Instance Options Schema Tab This tab contains the fields below: Table 18 Field Description of Schema Tab Field Class Reference Description Displays the reference to the ActiveEnterprise schema that corresponds to the object class that was configured under the Schema View tab.

79 Request-Response Service Fields 61 Request-Response Service Fields The following tabs are available: Configuration Tab on page 61 Transport Tab on page 63 Schema View Tab on page 67 Schema Tab on page 69 Configuration Tab This tab contains the fields below: Table 19 Field Description of Configuration Tab Field Name Description Transport Type Description You can use the default name or replace it with a name of your choice. A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name. A service name cannot use global variables. Provide information about the service that you want stored in the project. The field is optional. Select the transport to be used by the runtime adapter, JMS or TIBCO Rendezvous. After selecting the transport, the transport-specific configuration fields display. The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field that uses a dialog to perform SSL configuration. To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

80 62 Chapter 3 Adapter Instance Options Table 19 Field Description of Configuration Tab (Cont d) Field LDAP Operations Description Specify the operations that this service supports. At least one operation must be selected. Select: Insert To add an entry. Update To update an existing entry. Delete To remove an entry. Upsert To update an entry if it already exists. If the entry does not exist, running this operation will insert it. Modify DN To move an entry from one location to another by changing the RDN. Validate Object To validate the object class of a requested entry against the configured object class for all operations. Lookup To find an entry. Authenticate To validate a user DN with a specific password. Search To find entries that match a search criteria. The search filter defines criteria that an entry must match to be returned from a search. The basic component of a search filter is an attribute value assertion of the form: attribute operator value For example: ( (sn=smith)(sn=miller)) matches entries with the surname Smith or the surname Miller. TIBCO ActiveMatrix Adapter for LDAP supports standard LDAP search. Therefore, if your search filter is LDAP compatible, the adapter will be able to successfully execute the action. For more details on search filters and their syntax, see the following RFC at If you select this field, the Limit Search Results field is displayed. Limit Search Results If you select this check box, the Enter the Number of Entries field is displayed. Enter the Number of Entries Specify the number of entries that the adapter should search. The default is Extended Search If you select this check box, the adapter returns all the entries found in the search without checking for the configured objectclasses that the entry belongs to.

81 Request-Response Service Fields 63 Table 19 Field Description of Configuration Tab (Cont d) Field Chase Referrals Referral Hop Count Description Select this check box to specify that if a referral is encountered during an operation, the referral should be followed. When you browse the DIT tree, the adapter palette will not follow a referral and only entries on the configured server will be displayed. The referring server returns an LDAP URL in the following format: ({ldap ldaps}://host[:port]/dn). Depending on the URL used, the following referral chasing scenarios are possible: If the URL is ldaps://, then referral chasing uses SSL. If the URL is ldap://, then referral chasing does not use SSL. If the bind to the original server is SSL-EXTERNAL and the referral URL is ldap://, then the bind to referred server will be anonymous. Referrals are not supported for the publication service. Chasing referrals for a selected operation will work only if the authentication information used for connecting to the servers is identical for all servers. This field specifies the number of servers that must be followed if a referral is encountered. If there are more referral servers than the number specified in this field, these servers will not be in the purview of the specified operation. This field is available only if you select the Chase Referrals check box. Transport Tab This tab contains the fields below: Table 20 Field Description of Transport Tab Field Message Subject Description This field displays only if TIBCO Rendezvous is selected in the Transport Type drop-down list (under the Configuration tab). By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.

82 64 Chapter 3 Adapter Instance Options Table 20 Field Description of Transport Tab (Cont d) (Cont d) Field Destination Description This field displays only if JMS is selected in the Transport Type drop-down list (under the Configuration tab). By default a service uses a dynamic destination that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name, and the service name. If you use this default dynamic destination, make sure the values for Domain and Deployment are not empty. You can override the default dynamic destination by specifying the static destination in this field. The static destination must be defined on the JMS server before it can be used by the runtime adapter. See the TIBCO Enterprise Message Service User s Guide for information about destinations.

83 Request-Response Service Fields 65 Table 20 Field Description of Transport Tab (Cont d) (Cont d) Field Quality of Service Description If TIBCO Rendezvous is selected as the transport type, select: Certified Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires. This is often called certified message delivery. If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger. Distributed Queue Distributed queue includes a group of cooperating transport objects, each in a separate process. Each transport object is called a member. To balance the transmission load among servers, the adapter can use distributed queues for one-of-n delivery of messages to a group of servers. Each member of a distributed queue listens for the same subject using the TIBCO Rendezvous Distributed Queue listener objects. Even though many members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts. Load balancing for the processing of TIBCO Rendezvous certified messages is supported by using distributed queuing. The messages from TIBCO Rendezvous are distributed equally among all instances that belong to the same group. This distributes the message load over several adapter instances. However, the order in which messages are sent to the application is not guaranteed. Reliable Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated.

84 66 Chapter 3 Adapter Instance Options Table 20 Field Description of Transport Tab (Cont d) (Cont d) Field Wire Format Connection Factory Type Delivery Mode Description Services must use the same wire format to exchange data. ActiveEnterprise Message (TIBCO Rendezvous only) Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter SDK set of data types. This format allows ActiveEnterprise components to perform extra validation on messages sent or received. See the TIBCO Adapter SDK Programmer s Guide for details about the control information generated and sent with ActiveEnterprise messages. XML Message (TIBCO Rendezvous and JMS) The XML Message wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the ActiveEnterprise schema. Topic (JMS only) A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe. Queue (JMS only) A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point. For a request-response service, a message is marked as durable or non durable. This field is available only if JMS transport is selected. Durable If a request-response service is marked durable, it indicates that messages need to be resent on the configured topic or queue, if the JMS server goes down. Non-Durable If a request-response service is marked non-durable, it indicates that messages will not be resent on the configured topic or queue, if the JMS server goes down.

85 Request-Response Service Fields 67 Table 20 Field Description of Transport Tab (Cont d) (Cont d) Field Session Reference Endpoint Reference Description Every adapter can have one or more sessions configured for it. Sessions encapsulate stateful connections to TIBCO Rendezvous and other messaging sources. The session object shown in this field is initially supplied by the adapter, depending on the Quality of Service selected. You can change the session by browsing for it in the project panel. You can drag a different endpoint, browse for another endpoint resource, go to the referenced endpoint to edit its properties or delete the endpoint. Endpoint reference objects are explained in the TIBCO Designer Palette Reference. The semantics for these fields are more complex than the explanation given here. See the TIBCO Enterprise Message Service User s Guide for more information. Schema View Tab This tab contains the fields below: Table 21 Field Description of Schema View Tab Field Base DN Select Object Classes From Description Displays the selected Base DN (Distinguished Name) of a specified node. To display the Base DN, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. When the length of an object class name that is fetched from the Base DN field exceeds 128 characters, the ActiveEnterprise schema created with this name affects the runtime functionality. When you click Apply, a dialog box (Figure 12 on page 51) is displayed that prompts you to enter a shorter name that can be stored in the schema. The name you enter must be unique and less than 128 characters. If the service has been configured with a long schema name, the dialog box will not display if a service has already been configured for the same object class. There are two methods you can use to select an object class: Sample Entry You can specify a sample entry so that the object class for that entry is populated in the Objectclasses field. LDAP Schema You can specify an object class by selecting it from the ldap schema on the ldap server.

86 68 Chapter 3 Adapter Instance Options Table 21 Field Description of Schema View Tab (Cont d) Field Sample Entry LDAP Schema Classes Description This field is available only if you select the Sample Entry option for the Select Object Classes From field. In your LDAP server, you can specify an entry from the schema you will use for this service. The service will only handle entries with identical object classes. To specify a sample entry for the schema, you can browse the Directory Information Tree by clicking the Browse DIT button and then selecting the required node from the DIT. This generates the class reference needed for the service, in the Objectclasses field. This field is available only if you select the LDAP Schema option for the Select Object Classes From field. To select the LDAP schema classes for the service, you can browse the LDAP schema by clicking the Browse Schema button and selecting the object classes from the Available Objectclasses list. This generates the class reference needed for the service, in the Objectclasses field.

87 Request-Response Service Fields 69 Table 21 Field Description of Schema View Tab (Cont d) Field Maximum Number Of Entries Description Click Browse DIT for the Base DN or Sample Entry fields to access the Maximum Number of Entries field. This field is available in the Select Base DN and Select Sample Entry for Schema dialog boxes. Specify the maximum number of entries that you want to restrict the service to. The DIT expands only if the number of entries is equal to, or less than the value you specify. You cannot specify a value greater than as the maximum number of entries. If you need to select a node within a subtree that has more than entries, you must specify the DN, in the DN (Base DN/Sample Entry) box. You may come across the following exceptions The size of the result exceeds server specific limit and The Number of Descendants for this Node are more than the requested number. Additionally, if you are using the Sun Directory Server, you may come across the exception The adminstrative limit on the maximum number of entries to return was exceeded. To proceed, you will need to log on to the server and change the value for the search size limit: For the Sun Directory Server, click the Configuration tab. Select Database Settings and click the LDBM Plugin Settings tab. Change the value of the Look-through limit entry. While you are in the Configuration tab, select the root of the tree, and click the Performance tab. Change the value for the Size Limit entry too. For further details, see the documentation shipped with the server you are using. Objectclasses Handle Any Subset of Configured Object Classes Displays the object class of the entry specified in the Base DN, or Sample Entry fields, if these have been specified. Otherwise, the value from the LDAP Schema Classes field is displayed. You cannot edit this field. This field is available if the object class displayed in the Objectclass field is a composite object class. If you select the check box, changes made to any element of the composite object class will be used by the subscription service. Schema Tab This tab contains the fields below:

88 70 Chapter 3 Adapter Instance Options Table 22 Field Description of Schema Tab Field Class Reference Description Displays the reference to the ActiveEnterprise schema that corresponds to the object class that was configured under the Schema View tab.

89 Supported LDAP Operations and Message Structure 71 Supported LDAP Operations and Message Structure TIBCO ActiveMatrix Adapter for LDAP supports the following: INSERT Operation DELETE Operation UPDATE Operation MODIFY DN Operation UPSERT Operation LOOKUP Operation SEARCH Operation AUTHENTICATE Operation These operations are done in the context of the wire schema and the native schema. Native schema contains the attribute names (field names) of any object class that is configured for the service. Each attribute is a multi-value sequence of strings. For example, if the object class is inetorgperson the native schema is: inetorgperson { sn cn telephonenumber { }... } Wire schema contains the native schema as well as the Opcode, DN, NewDN, Objectclass, SearchCondition, and Attributes. For example: inetorgperson { Opcode DN NewDN ObjectClass Searchcondition Attributes

90 72 Chapter 3 Adapter Instance Options } { } sn cn telephonenumber... Details about an LDAP operation is specified using a wire schema. For each operation: The specified entry must be within the subtree for the adapter service that you specify during configuration. The object class must match the object class of the adapter service. If either of these two conditions is not met, the operation will fail. You can specify the Opcode acronym for the operation to work. For example, if you specify AT for the INSERT operation, the adapter will use only the first character of the acronym. The same concept is applicable to all Opcodes. For Opcodes that have a two-letter acronym, the adapter will use the first two characters and ignore all subsequent characters. However, if the first letter of an acronym is not valid, the adapter will display an error. INSERT Operation The INSERT operation uses the LDAP_ADD or A operation codes and will add an entry to the LDAP server. For an INSERT operation using the LDAP_ADD operation code, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_ADD" DN = "uid=xyz,ou=people,o=abc.com" inetorgperson { sn = "abc" cn = "def" telephonenumber = "123233" objectclass="inetorgperson" } } The details specified in the native schema will be added for the entry specified in the DN field.

91 Supported LDAP Operations and Message Structure 73 DELETE Operation The DELETE operation uses the LDAP_DELETE or D operation codes, and will delete an entry from the LDAP server. For a DELETE operation using the LDAP_DELETE Opcode, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_DELETE" DN = "uid=xyz,ou=people,o=abc.com" } For a DELETE operation, the native schema is not required. UPDATE Operation The UPDATE operation uses the LDAP_MODIFY or M operation codes, and will modify the entry on the LDAP server by overwriting the existing attribute values in the entry. The UPDATE operation can be specified as: Opcode = LDAP_MODIFY Opcode = LDAP_MOD_REPLACE or MR Opcode = LDAP_MOD_ADD or MA Opcode = LDAP_MOD_DELETE or MD LDAP_MOD_REPLACE or MR will overwrite the existing attribute values with the new attribute values specified. LDAP_MOD_ADD or MA will add the new attribute values to the old entry only if the original entry does not contain the attribute values being added. LDAP_MOD_DELETE or MD will delete the specified attribute values from an entry. For the UPDATE operation using the LDAP_MODIFY Opcode, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_MODIFY" DN = "uid=xyz,ou=people,o=abc.com" inetorgperson { sn = "abc1" cn = "def1" telephonenumber = " "

92 74 Chapter 3 Adapter Instance Options } } MODIFY DN Operation The MODIFY DN operation replaces the RDN (Relative Distinguished Name) of an entry specified in the DN field with the RDN specified in the NewDN field. This operation uses the LDAP_MODIFYKEY or MK operation codes. For example, for the MODIFY DN operation using the LDAP_MODIFYKEY Opcode, the inbound message appears in the following format: inetorgperson { Opcode = "LDAP_MODIFYKEY" DN = "uid=xyz,ou=people,o=abc.com" NewDN="uid=ijk" } UPSERT Operation The UPSERT operation is an INSERT or an UPDATE operation. If the entry does not exist, it will be added. If the entry exists, it will be modified. This operation uses the LDAP_UPSERT or U operation codes. For the UPSERT operation using the LDAP_UPSERT Opcode, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_UPSERT" DN = "uid=xyz,ou=people,o=abc.com" inetorgperson { sn = "abc" cn = "def" telephonenumber = "123233" objectclass="inetorgperson" } } LOOKUP Operation This operation is available with the request-response service. The LOOKUP operation uses the LDAP_LOOKUP or L operation codes. For the LOOKUP operation using the LDAP_LOOKUP operation code, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_LOOKUP" DN = "uid=xyz,ou=people,o=abc.com"

93 Supported LDAP Operations and Message Structure 75 } For the LOOKUP operation, native schema is not required as you are merely checking if the entry exists or not. SEARCH Operation This operation is available with the request-response service. The SEARCH operation can be specified as: Opcode = LDAP_SEARCH or SS Opcode = LDAP_SEARCH_BASE or SB Opcode = LDAP_SEARCH_ONELEVEL or SO Opcode = LDAP_SEARCH_SUBTREE LDAP_SEARCH_BASE helps you to search for an entry using a search condition, LDAP_SEARCH_ONELEVEL helps you to search one level below the base using a search condition, not including the base, and LDAP_SEARCH_SUBTREE lets you search the entire subtree. LDAP_SEARCH and LDAP_SEARCH_SUBTREE are the same. For details on search filters and their syntax, see the following RFC at For the SEARCH operation, the inbound message will be in the following format: inetorgperson { Opcode = "LDAP_SEARCH" DN = "ou=people,o=abc.com" SearchCondition = "mail=someone@somewhere.com" } OR inetorgperson { Opcode = "LDAP_SEARCH" DN = "ou=people,o=abc.com" SearchCondition = "mail=someone@somewhere.com" Attributes = { telephonenumber MobileNumber } } In the first search condition, all entries that match the search criteria are returned with all the details of each entry, including the DN.

94 76 Chapter 3 Adapter Instance Options In the second search condition, only the details specified as the Attributes (telephonenumber and MobileNumber) are returned along with the DN. The outbound message will be in the following format: inetorgperson { { DN = "uid=abc,ou=people,o=abc.com" inetorgperson { } } inetorgperson { DN = "uid=xyz,ou=people,o=abc.com" inetorgperson { } }... } When you perform a search, a number of entries may be retrieved. Therefore, the outbound message will be a sequence of wireschema that has details about each entry specified in the native schema. Each entry is identified by its DN, mentioned in the wireschema. However, you can also set an attribute filter. The adapter search operation can fetch attributes that are a subset of the attributes of the configured object class and this can be specified in the Attributes attribute of the request-response Server service schema. The filter should be specified as a sequence. AUTHENTICATE Operation This operation is available only for the request-response service. The AUTHENTICATE operation uses the LDAP_VALIDATE_USR or V operation codes. For the AUTHENTICATE operation using the LDAP_VALIDATE_USR operation code, the inbound message will be in the following format:

95 Supported LDAP Operations and Message Structure 77 inetorgperson { Opcode = "LDAP_VALIDATE_USR" DN = "uid=xyz,ou=people,o=abc.com" Password = "secret" } For the AUTHENTICATE operation, there is no native schema as you are merely checking if the entry can be authenticated or not.

96 78 Chapter 3 Adapter Instance Options

97 79 Chapter 4 Deploying and Starting the Adapter Using TIBCO Administrator This chapter provides an overview about deploying, starting, stopping, and monitoring adapter services using the TIBCO Administrator web interface. Topics Creating an EAR File in TIBCO Designer, page 80 Deploying the Project, page 81 Starting or Stopping the Adapter, page 82 Monitoring the Adapter, page 83

98 80 Chapter 4 Deploying and Starting the Adapter Using TIBCO Administrator Creating an EAR File in TIBCO Designer Generate an Enterprise Archive file (EAR) that contains information about the adapter services to deploy. The EAR file contains information on what you wish to deploy. This could be one or more adapter services, one or more TIBCO BusinessWorks process engines, or both. Building an archive creates the EAR file, which you can then deploy from TIBCO Administrator. If you make changes to the business processes or adapter services included in the archive, you need to rebuild the archive. Saving the project does not affect the archive. In TIBCO Designer, follow these steps to create an EAR: 1. Configure the adapter services. 2. Drag and drop the Enterprise Archive resource from the palette panel to the design panel. 3. Select the Enterprise Archive. Drag and drop the Process Archive resource from the Process palette panel to the design panel. If there are any processes in your project, configure them using the Browse Resources button. 4. If there are any configured adapter services in your project, an Adapter Archive resource becomes available in the Adapter Resources palette panel. Drag the Adapter Archive into the design panel and specify information in the Configuration tab, then click Apply. 5. Go to the Enterprise Archive and click Build Archive to create the EAR file. See Also See the TIBCO Designer User s Guide for more information about this procedure. The guide is available from the TIBCO Designer Help menu.

99 Deploying the Project 81 Deploying the Project Before deploying a project, the machine on which the adapter is installed must be part of a TIBCO administration domain. After you have installed the TIBCO Administration Server, any machine on which you install TIBCO Runtime Agent (required by an adapter) is automatically added to the administration domain. The TIBCO software installed on the machine is then visible and accessible via the TIBCO Administrator GUI. When you deploy a project, startup scripts and other information about the different components are sent to the machines to which the components were assigned. The project data store and TIBCO Administration Server are updated with the deployed components. To deploy a project: 1. Start TIBCO Administrator and import the EAR file into TIBCO Administrator Enterprise Edition. 2. Assign adapter archives to adapters installed in the administration domain and likewise assign process archives to process engines. 3. Specify startup options for each adapter service. Password Handling At design time, the adapter uses a password to connect to the backend application and fetch metadata. At runtime, the adapter uses a password to connect to the back-end application and interoperate with it. When deploying the adapter, check that the password has been specified in the adldap.adldappassword property. See Also See the TIBCO Administrator User s Guide for an introduction to the TIBCO administration domain and detailed information about the above steps.

100 82 Chapter 4 Deploying and Starting the Adapter Using TIBCO Administrator Starting or Stopping the Adapter The TIBCO Administrator Application Management module allows you to start, and stop deployed applications. To start an adapter service from the module: 1. In the Administrator GUI left pane, expand Application Management -> Application-Name -> Service Instances. 2. In the Service Instances panel, select the check box next to the adapter service. 3. Click the Start Selected button. The status changes from Stopped to Starting up to Started. 4. To stop the adapter service, select it, and then click the Stop Selected button. See Also See the TIBCO Administrator User s Guide for more information.

101 Monitoring the Adapter 83 Monitoring the Adapter TIBCO Administrator offers a number of monitoring options. Specify alerts and TIBCO Hawk rulebases for each machine in the domain. Specify alerts and Hawk rulebases for each adapter service. View the log for each adapter service. See Also See the TIBCO Administrator User s Guide for information about configuring the above monitoring options.

102 84 Chapter 4 Deploying and Starting the Adapter Using TIBCO Administrator

103 85 Chapter 5 Advanced Topics This chapter explains advanced topics. The advanced features help you to use the adapter with a revision control system, define a TIBCO Hawk session to monitor the adapter, use variable substitution to override global variables that are predefined in the project, set encoding options before running the adapter so that it can handle files that use different encodings, synchronize LDAP servers, configure the repository for binary attribute support, acknowledge and publish messages, add a user with a password to Active Directory. Finally, some migration issues are presented. Topics Using the Adapter with a Revision Control System, page 86 Defining a TIBCO Hawk Session, page 88 Using Global Variables, page 90 Setting Encoding Options, page 94 LDAP Server Synchronization, page 95 Configuring the Repository for Binary Attribute Support, page 96 Message Acknowledgement, page 97 Publishing Messages, page 99 Updating Entries in the LDAP Server, page 102 Adding a User Account with a Password into Microsoft Active Directory Server, page 103 Changing the LDAP Server Connection Parameters, page 104 Migration, page 105

104 86 Chapter 5 Advanced Topics Using the Adapter with a Revision Control System TIBCO Designer supports revision control systems such as MicroSoft Visual SourceSafe and Perforce. If you are using a revision control system, you must manually add some configured resources to the revision control system and check in the resources when completing the instance configuration. As part of service configuration, the adapter creates schema files in root/aeschemas/ae. For example, if you configure a service in an adapter configuration Instance1, the following files are created: Project_root/AESchemas/ae/Instance1.aeschema The AESchemas/ae folder initially contains basedocument.aeschema, which is a TIBCO-defined schema. The following figure shows the schema files that are created when you save the configuration. Figure 13 Schema Files Created

105 Using the Adapter with a Revision Control System 87 When the project is saved and a revision control system has been specified, the adapter displays a warning that additional files were created and should be added to the revision control system. This warning appears only when the files are created for the first time. The warning displays a Go To Resource button that helps in navigating to the resource. Use the Multi-User -> Add Resources to RCS menu command to add these files to the revision control system. The following figure shows a warning that may be displayed: Figure 14 Warning: Add File to RCS For information about how to use the Multi-User feature in TIBCO Designer, refer to the TIBCO Designer User s Guide.

106 88 Chapter 5 Advanced Topics Defining a TIBCO Hawk Session To use TIBCO Hawk to monitor the adapter you must first define a TIBCO Rendezvous session on which TIBCO Hawk messages will be sent and received. Use the following steps to create the session. 1. In the project tree panel, click the LDAP Adapter Configuration icon defined for your adapter instance. 2. Click the Monitoring tab. 3. The Default MicroAgent Session contains the name of the Hawk session: DefaultHawkSession. Use default settings for the other fields. The next diagram shows the definition for a Monitoring tab. Figure 15 Monitoring Tab when defining a Hawk Session 4. Open the Advanced folder for the adapter instance. Double-click the Sessions folder. 5. Double-click the DefaultHawkSession Icon.

107 Defining a TIBCO Hawk Session 89 Figure 16 DefaultHawkSession Icon. 6. In Service, type 7474 (the default used by TIBCO Hawk) or modify the global variable by clicking the Global Variables tab. 7. In Daemon, type tcp:7474 (the default used by TIBCO Hawk) or modify the global variable by clicking the Global Variables tab. 8. If you choose to change the defaults, click Apply and save the project. Figure 17 HawkSession Defined

108 90 Chapter 5 Advanced Topics Using Global Variables The variable substitution mechanism can override global variables predefined in the project in a restricted manner. Predefined variables can be viewed and set in TIBCO Designer. Variables are specified as %%VARNAME%% and cannot contain any white space. Variable substitution allows you to accomplish the following: Substitute string variables specified in the project at startup time. Locally define the value for a variable for a specific project. The local value takes precedence over any global value. Specify the value for a variable in a properties file. This overrides the project repository and values set in code, but not variables set on the command line. Enforce the pre-defined variables listed in Predefined Global Variables on page 92. Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance. Specifying Variables Using TIBCO Designer Global variables provide an easy way to set defaults for use throughout your project. There are several ways in which they can be used: Define a variable using TIBCO Designer, then override the value for individual applications at deployment time using TIBCO Administrator. You can also override values for predefined variables, unless the GUI does not allow you to make them settable later. Predefine a variable using TIBCO Designer, then override the value for individual services (for example, publication service or TIBCO BusinessWorks process) at deployment time using TIBCO Administrator. The values you specify are then used at runtime. You can also override values for predefined variables, unless the GUI does not allow you to make them settable later. For example, you could assign the value 7474 to the predefined global variable RvDaemon. You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line. To use global variables in your project, follow these steps: 1. In the project panel, select the Global Variables tab.

109 Using Global Variables 91 The project panel is updated to display all currently defined global variables. You now have these choices: To assign or change a variable value, select that region and triple-click the variable. The variable expands so you can change either the variable name or the variable value. Press Enter when you re done. To add a new global variable group, click the leftmost icon at the bottom of the dialog box. Specify the name of the group, then press Enter. With the group icon selected, you can click the abc icon to add variables to the group. To add a global variable, click the abc icon. A new global variable item is added to the bottom of the list. Supply the variable name and, optionally, the value. Press Enter when you re done. The global variable is now displayed in the global variables list. 2. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by %% on both sides. When the project is deployed and the configured components are run, all occurrences of the global variable name are replaced with the global variable value (unless it was overridden in a way that had higher precedence). A number of global variables are predefined. See Predefined Global Variables on page 92 for information. You may add definitions of any variables you need, to the predefined variables. Changing Global Variable Values at Runtime You can change the value of a global variable when you deploy your project in TIBCO Administrator. See the section on modifying runtime variables in the TIBCO Administrator User s Guide for more information on using TIBCO Administrator. You can also specify values for global variables when starting a process engine on the command line. To do this, specify the following as a command line argument when starting the process engine: -tibco.clientvar.variablepathandname value where variablepathandname is the name of the variable you wish to set, including the path to the variable if it is contained in a folder. value is the value you wish to set the variable to. For example, if you have a global variable named item1 contained in a folder named mygroup and you wish to set its value to 500, add the following argument to the command line when starting the process engine: -tibco.clientvar.mygroup/item1 500

110 92 Chapter 5 Advanced Topics Predefined Global Variables The next table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter instance is configured. Table 23 Predefined Global Variables Variable Deployment DirLedger DirTrace Domain HawkEnabled JmsProviderUrl JmsSslProvider Url RemoteRvDaemon RvDaemon Description Defaults to the TIBCO Designer project name. This value can be any string value. This global variable is used by the system to partially define the subject name defined for a service. Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory. Specifies the path name for logging the file used by the adapter. The default is the root installation directory. The default value for file-based local projects is MyDomain. The value for server-based projects is the domain to which the project was saved. Indicates whether TIBCO Hawk is used to monitor the adapter. True indicates that a Hawk microagent is defined for the adapter. False indicates the microagent is not to be used. Specifies where the JMS server is located. Setting this value mostly makes sense in the early stages of a project, when only one JMS server is used. Specifies where the JMS server, running in the SSL mode, is located. Setting this value mostly makes sense in the early stages of a project, when only one JMS server is used. TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator Server Configuration Guide for details about setting up a domain using rvrd. TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is 7500.

111 Using Global Variables 93 Table 23 Predefined Global Variables Variable RvNetwork RvService RvaHost RvaPort TIBHawkDaemon TIBHawkNetwork TIBHawkService Description TIBCO Rendezvous network. This variable need only be set on computers with more than one network interface. If specified, the TIBCO Rendezvous daemon uses that network for all outbound messages. In most cases, you can leave the default. TIBCO Rendezvous service. The TIBCO Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service. A transport can communicate only on the same service with other transports. Unless you are using a non-default TIBCO Rendezvous configuration, you should leave the default (7500). Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant if you are using the TIBCO Rendezvous Agent (rva) instead of the TIBCO Rendezvous daemon, and if you have configured a non-default setup. See TIBCO Rendezvous Administration for details about specifying the rva parameters. TCP port where the TIBCO Rendezvous agent (rva) listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters. Defaults to TIBCO Rendezvous daemon used in the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter. TIBCO Rendezvous network used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter. TIBCO Rendezvous service used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

112 94 Chapter 5 Advanced Topics Setting Encoding Options Complete the following steps prior to running the adapter so it can handle files in different encodings. 1. Configure inter-communication encoding. The wire format encoding used for communication between adapters and TIBCO applications is determined by the encoding property set in the project. The adapter configuration can be saved in a project: At design time or running as a legacy project using a local repository. Deployed to a TIBCO Administrator Domain. If the adapter configuration is saved to a project in an Administration server domain, TIBCO messaging encoding is determined by the repo.encoding property in the server's tibcoadmin.tra file. Each adapter or TIBCO-enabled application that uses the Administration server for storing and retrieving configuration data from a project uses this encoding setting when communicating. This assures that all components (including adapters and other TIBCO-enabled applications) that use the same repository also use the same encoding value to communicate. The repo.encoding property value can be ISO (the default) or UTF8. If English or other Latin-1 language data is transmitted between adapters, ISO should be used. Otherwise, use UTF8. If an adapter instance is saved in a local project, the TIBCO messaging encoding is determined by the encoding property of the local project file. To communicate with other adapters using the same encoding, all adapters and applications must have their local project file encoding property set to be identical. The encoding value is set on the root project folder, in the Save Project dialog box, TIBCO Messaging Encoding field. The default value is ISO The encoding property set in the project file is superseded by the server's encoding property. The encoding property discussed above is the encoding used by the communication between adapters and applications, not the encoding used for the persistent storage of the project files. Project files are always saved using UTF8.

113 LDAP Server Synchronization 95 LDAP Server Synchronization To synchronize two LDAP servers, you need to set up two adapter instances: one instance for each server. Each adapter instance should contain a publication and a subscription service. The publication and subscription services must be configured to the same destination or subject to enable them to exchange data between the two servers. The following two situations are possible: The two LDAP servers that you are trying to synchronize have changes happening on separate directory information trees. This situation does not require special configuration. You can configure an adapter instance for use with both synchronized and non-synchronized LDAP servers using identical methods. The two LDAP servers have changes occurring on the same or overlapping directory information trees. If the adapter services in the adapter instances use two different object classes, no special configuration is required. However, if the adapter services use the same object class, you must select the Update Only if Different check box on the Configuration tab of the subscription service. Selecting this check box enables the adapter subscription service to look up the server and decide whether an update is required. For more information on configuring synchronized LDAP servers, see Configuration Tab on page 52. Password Synchronization between Sun Directory Server and Microsoft Active Directory Server The LDAP servers use the one-way hash function when storing passwords. Therefore, you cannot use the adapter to synchronize passwords and the system cannot retrieve the original passwords. Since the Sun Directory Server and Microsoft Active Directory Server use different algorithms to store the passwords, copying the password as opaque data is not available as an option. If you store the passwords in clear text on both the Sun Directory Server and Active Directory servers, you can copy the password from one server to another. However, this is not a real-world use scenario.

114 96 Chapter 5 Advanced Topics Configuring the Repository for Binary Attribute Support The adapter provides support for binary attributes to enable you to work with images, audio files, and so on using the adapter. At design time, do the following before starting the adapter: 1. After you have configured the adapter services, navigate to the Project_Root_ folder/aeschemas/ae/scalar/ae/sequences folder. 2. Drag and drop a Generic Sequence icon into the Sequences folder and enter the name as sequence[binary]. 3. Select Binary as the element type and click Apply. 4. Navigate to the Project_Root_folder/AESchemas/ae/adapter/ldap/LDAP server type/ldap server machine/native/classes/required schema directory to set the type as binary for the required attributes. This contains the schema that was created. The required schema is the schema that must be modified and can be an object class name such as inetorgperson, user, organization, and so on. The LDAP server type and LDAP server machine values are the values that you specified in the Server Type and Server Name fields under the Design-Time Connection tab while configuring the adapter instance. 5. Expand the schema and identify the attributes that need to be modified for the binary type. For each attribute, click Browse in the Sequence field and select the sequence[binary] that was created in step Click Apply. 7. Save the project.

115 Message Acknowledgement 97 Message Acknowledgement The following adapter services acknowledge messages: request-response service subscription service Message Acknowledgement by the Request-Response Service The following scenarios are applicable for message acknowledgement by the request-response service: LDAP Server is Not Running LDAP Server does Not Respond in Time LDAP Server Returns an LDAP Error Code LDAP Server Returns a Success Code with Data LDAP Server is Not Running If the LDAP server is not running, the adapter verifies that the message was received by the LDAP server and informs you that the server is unavailable. The adapter then tries to reconnect to the LDAP server. You can configure the number of retries that must be attempted and the interval between each retry in the adapter s properties file. If the adapter is not able to reconnect to the LDAP server, it will stop attempting to reconnect after the maximum number of retries has been reached. LDAP Server does Not Respond in Time In this scenario, a connection timeout results. The adapter returns a timeout message. The adapter then tries to reestablish a connection with the server. LDAP Server Returns an LDAP Error Code If the LDAP server returns an LDAP error code because an error has occurred, the adapter returns a message that contains this code.

116 98 Chapter 5 Advanced Topics LDAP Server Returns a Success Code with Data If the operation is completed successfully, the LDAP server returns a success code with the processed data. The adapter then sends a response message that contains the success code and the data received from the LDAP server. Message Acknowledgement by the Subscription Service The following scenarios are applicable for message acknowledgement by the subscription service: LDAP Server is Not Running LDAP Server is Running, but the API Fails LDAP Server is Running and the API Succeeds LDAP Server is Not Running In this scenario, the adapter attempts to reconnect to the server immediately. The adapter does not confirm that the messages were received, nor does the adapter inform you that the LDAP server is not running. You can configure the number of retries that must be attempted and the interval between each retry in the adapter s properties file. If the adapter is not able to reconnect to the LDAP server, it will stop attempting to reconnect after the maximum number of retries has been reached. LDAP Server is Running, but the API Fails In this scenario, an error message is returned by the API. This message can be viewed on the console as well as in the log file. LDAP Server is Running and the API Succeeds In this scenario, if you have configured the logging roles, the success code can be viewed in the log messages.

117 Publishing Messages 99 Publishing Messages This section explains the following: Configuring Timers for Publication Services Publishing Messages in Sequence Publishing Duplicate Events Publishing Deleted Entries in the Microsoft Active Directory Server Configuring Timers for Publication Services You can configure the polling interval for the publication service. To do so, in TIBCO Designer, navigate to the AdapterInstanceName -> Advanced -> Timers folder, and select the timer that was created when you added a publication service. On the Configuration tab, specify the polling interval in the Interval (milliseconds) text box. This will determine the interval at which the service will poll the LDAP server. For more details on configuring timers, see the TIBCO Designer Palette Reference. Publishing Messages in Sequence You can use the adapter s publication service to publish messages in sequence. The publication service of the adapter can behave in one of the following ways: If the adapter is running, all changes that are being made will be published in sequence. If the adapter is not running and if n number of changes have been made on a particular entry, when the adapter is started, the publication service will publish only the most recent change. Publishing Duplicate Events During publishing of messages, the server first returns the entries that match the search criteria of the adapter. However, unlike in an ordinary search, the server keeps the search active until you disconnect from the server. If an entry is changed and the changed data matches the search criteria, the server will publish the modified entry. Therefore, if an entry is changed twice, and both changes match the search criteria when the adapter is running, the LDAP server will publish both changes.

118 100 Chapter 5 Advanced Topics For entries that are changed when the adapter is not running, the adapter does not fetch all the changes that were made. It only retrieves messages that match the search criteria that were modified after the adapter stopped, that is, after the timestamp of the last modification that was received by the adapter when it was running. Therefore, the adapter cannot publish duplicate changes, if the changes were made when the adapter was not running. Publishing Deleted Entries in the Microsoft Active Directory Server Entries deleted from a Microsoft Active Directory Server are published with a different DN and without applying the configured filter, if any. When you delete entries on the Microsoft Active Directory Server, it moves the entries to a Deleted Objects subtree, retaining only its DN and object class, if there is no conflict with other deleted items. When the adapter publishes a deleted object, it uses the new DN, not the original DN of the entry. For example: DN = CN=Aparna DEL:aec6dadb-244d-4fd0-a058-4c6e7ef18a09,CN=Deleted Objects,DC=adsldap Since the information about the original DN and attribute values are not available on the Microsoft Active Directory Server, the adapter cannot publish those details; only the DN used in the deleted objects container is available. Therefore, the adapter will publish all deleted entries belonging to the object class irrespective of whether it is a part of the Base DN you selected during configuration. Additionally, if you configure a publication service with a filter (for example, attribute1 = abc), the adapter cannot search for attribute1 as it no longer exists. Therefore, the adapter will ignore the filter for publishing deleted entries, for Microsoft Active Directory Server. In order to publish the deleted entries in Active Directory Server, the "User DN" provided in the LDAP Adapter instance should be a part of the server's "Domain Admin" group by default. In other words, the "User DN" should have Administrator rights to publish deleted entries. This is because deleted objects are stored in the Deleted Objects container. By default, only the System account and members of the Administrators group can view the contents of this container. However, for a non-admin user to publish the deleted entries, it is required to modify the permissions on the deleted objects container. Please refer to the article in the below link which describes how to modify the permissions on the deleted objects container:

119 Publishing Messages 101 TIBCO recommends that you do not process DELETE operations published by a publication service configured for the Microsoft Active Directory Server. Further technical details are available at

120 102 Chapter 5 Advanced Topics Updating Entries in the LDAP Server For subscription and request-response services, executing the DELETE, MODIFY, and MODIFYKEY operations on a node results in the adapter trying to validate the object class of the node. To do this, the adapter performs a SEARCH operation to retrieve the details of that node. This affects the performance of the adapter.

121 Adding a User Account with a Password into Microsoft Active Directory Server 103 Adding a User Account with a Password into Microsoft Active Directory Server To add a user account with a password into Microsoft Active Directory Server, you must make the following configuration changes: 1. Configure the adapter instance to use an SSL connection at run time. To do this, configure the SSL parameters in the Run-time Connection tab of the adapter instance. For details on configuring SSL, see Configuring the SSL Environment on page Set the unicodepwd attribute type in the user schema to binary. For details on setting binary attributes, see Configuring the Repository for Binary Attribute Support on page 96. In the request data that is to be sent to the adapter, the actual password must be enclosed in double quotes. Supply the binary encoded value of the password, including the double quotes, to the unicodepwd attribute.

122 104 Chapter 5 Advanced Topics Changing the LDAP Server Connection Parameters In the 5.x version of the adapter, the Run-time Connection tab was introduced. Consequently, although you can continue to use the same connection parameters for the LDAP server at design-time and runtime, you also have the option to specify different design-time and runtime connection parameters. This ensures that you can migrate from one LDAP server to another by specifying different server details in the Design-time Connection and the Run-time Connection tabs. Since the schemas are generated at design time using the server details specified in the Design-time Connection tab, the references are not broken if you change the server details in the Run-time Connection tab. However, for the adapter to work, the schemas on both the servers must be identical. Additionally, you can specify the global variables for the server details in the Run-time Connection tab, and provide the values at runtime, using the adapter s properties file. This allows you to migrate the project from one LDAP server to another without modifying the project file. You only need to modify the adapter s properties file (.tra). To specify global variables for runtime connection parameters: 1. Open the project file in TIBCO Designer and select the adapter configuration you want to modify. 2. Click the Design-time Connection tab and clear the Use Design-time Connection For Run-time check box. 3. Click the Run-time Connection tab and specify global variables for the server details. You can provide the values for these global variables at runtime, using the adapter s properties file. For details on how to configure an LDAP server and specify global variables, see the TIBCO ActiveMatrix Adapter for LDAP Examples. This ensures that schema references are not broken when the runtime connection parameters of the LDAP server are changed.

123 Migration 105 Migration You may wish to use TIBCO ActiveMatrix Adapter for LDAP to start projects created in However, for the projects using SSL (irrespective of simple or external) that were created in 5.4.0, they cannot be started. In such cases, users need to reconfigure the SSL configuration in the Run-time Connection tab before running the project. Three parameters, in 5.4.0, under Run-time Connection tab Converted Certificates and Keys Directory, Client Certificate Name, and Client Key Password have been respectively replaced by Trusted Certificate Authorities, Client Identity and Identity Password in As a result, users need to set these three new parameters to values that are identical to the values of the same parameters under Design-time Connection tab. For projects not using SSL created in 5.4.0, they can be started normally by version of adapter for LDAP.

124 106 Chapter 5 Advanced Topics

125 107 Chapter 6 Monitoring the Adapter Using TIBCO Hawk This chapter explains how to use TIBCO Hawk microagents to monitor and manage the adapter. Topics Overview, page 108 Starting TIBCO Hawk Software, page 109 The Auto-Discovery Process, page 110 Invoking Microagent Methods, page 111 Available Microagents, page 114

126 108 Chapter 6 Monitoring the Adapter Using TIBCO Hawk Overview TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all distributed applications and systems. System administrators can use it to monitor adapters in a wide area network of any size. TIBCO Hawk can be configured to monitor system and adapter parameters and to take actions when predefined conditions occur. These actions include: sending alarms that are graphically displayed in the TIBCO Hawk display, sending , paging, running executables, or modifying the behavior of a managed adapter. Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability from the TIBCO Rendezvous features of publish/subscribe, subject name addressing, interest-based routing, and reliable multicast. TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured with rules that instruct them on everything from what and how to monitor to what actions to take when problems are discovered. Thus the workload is fully distributed throughout the enterprise. Every agent is autonomous in that it does not depend on other components to perform its functions. The TIBCO Hawk Enterprise Monitor consists of these components: Display GUI front end that displays alarms and provides editors to create rule bases, create tests, view messages, and invoke microagents to request information or initiate an action. Agents Intelligent processes that perform monitoring and take actions as defined in rules. Rulebases Rules that are loaded by agents to determine agent behavior. Application Management Interface (AMI) Manages network applications via TIBCO Rendezvous and supports communication between a network application and monitoring TIBCO Hawk agents, including the ability to examine application variables, invoke methods, and monitor system performance. Microagents Feed information back to TIBCO Hawk and expose action methods to rulebases. For more information, see the TIBCO Hawk documentation.

127 Starting TIBCO Hawk Software 109 Starting TIBCO Hawk Software The TIBCO Hawk agent can be configured to start automatically during the system boot cycle. See the TIBCO Hawk Installation and Configuration guide for information about starting TIBCO Hawk. The TIBCO Hawk Administrator s Guide explains how to start the TIBCO Hawk Display. The guides are included in your TIBCO Hawk software installation area.

128 110 Chapter 6 Monitoring the Adapter Using TIBCO Hawk The Auto-Discovery Process After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk Agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets. At first, the Agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents: Figure 18 Hawk Enterprise Monitor Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right. Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see your TIBCO Hawk Administrator s Guide.

129 Invoking Microagent Methods 111 Invoking Microagent Methods A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you install and start the adapter, its microagents are dynamically added to the local agent. To invoke a microagent method: 1. Start TIBCO Hawk Display, then right-click on the agent icon and select Get Microagents. If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access. The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent. Figure 19 Microagents, Methods and Arguments Dialog This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes. 2. Click a microagent name, such as Self, to display a list of associated methods and text descriptions in the panels below. 3. Click the name of the method to invoke, such as getcomponentinfo.

130 112 Chapter 6 Monitoring the Adapter Using TIBCO Hawk Figure 20 Displaying a Method If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel. 4. Specify any arguments for the method invocation. 5. Verify that the Invoke radio button is selected. 6. Click the Invoke button to invoke the selected method. The Invocation Results dialog displays the results returned by the method. Figure 21 Invocation Results Dialog 7. Click Done to close the dialog.

131 Invoking Microagent Methods 113 These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rule bases, see your TIBCO Hawk Administrator s Guide.

132 114 Chapter 6 Monitoring the Adapter Using TIBCO Hawk Available Microagents Each adapter has three microagents, a standard TIBCO Hawk microagent named COM.TIBCO.ADAPTER.xyz where xyz is the adapter configuration name, a custom microagent, and a class microagent (for PAM compliance). The microagents provide: Business level statistics statistics that report the progress of the adapter as it interacts with the vendor application. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database. Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment. Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter. An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is running. It does not make a permanent change of the setting in either the repository or the.tra file. By default, all three microagents are available at run time. You can disallow adding custom methods to the standard microagent when deploying the adapter by changing the addcustomhawkmethodstoclassmagent property value in the adapter s property file. The following table lists each method available for the adapter and page on which the method is explained. Table 24 Microagent Methods Method Description Page Standard Methods activatetracerole() deactivatetracerole() Activates a mapping of a role to a sink at run time. Deactivates a mapping of a roles to sinks at run time

133 Available Microagents 115 Table 24 Microagent Methods (Cont d) Method (Cont d) Description (Cont d) Page getadapterserviceinfo rmation() Returns information about the services implemented by this adapter. 119 getcomponents() getconfig() getconfigproperties() gethostinformation() getrvconfig() getstatus() gettracesinks() getversion() _onunsolictedmsg() Returns information about the publisher, subscriber and IODescriptor. Returns basic configuration information. More specific information is accessed by the more specific methods. Returns all attributes and elements for the given repository object. Returns standard and extended application information. Returns information about all TIBCO Rendezvous sessions defined. Returns general status information, such as the number of TIBCO Rendezvous messages received and published, the number of errors since the last call, the PID of the application, and more. Returns information about sinks to which traces currently go. Returns the configuration ID, application name, version, and date for this adapter instance. Displays alert messages sent to the current adapter preregisterlistener() Preregisters an anticipated listener. 129 reviewledger() settracesinks() Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter. Adds a role or changes the file limit of a previously specified sink

134 116 Chapter 6 Monitoring the Adapter Using TIBCO Hawk Table 24 Microagent Methods (Cont d) Method (Cont d) Description (Cont d) Page stopapplicationinstan ce() Stops the running adapter instance. 133 unregisterlistener() Custom Methods getactivitystatistics () getactivitystatistics ByOperation() getactivitystatistics ByService getconnectionstatisti cs() getpollinginterval() getqueuestatistics() getthreadstatistics() resetactivitystatisti cs() resetconnectionstatis tics() resetthreadstatistics () setpollinginterval() Unregisters a currently preregistered listener. Returns the total number of objects processed for all the schemas. Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation. Returns information about the services implemented by this adapter. Returns the state and statistics for all the current connections used by the adapter. Returns the current polling interval setting. Returns the current count of elements in any internal queue used by the adapter. Returns the operation counts of the current threads Resets all the counts for the activity statistics. Resets all the counts for the connection statistics. Resets all the counts for the thread statistics. Sets the polling interval for the publication service

135 activatetracerole() 117 activatetracerole() Activates a mapping of a role to a sink at run time. This replaces the now-deprecated settracesink() TIBCO Hawk method. Input Parameters Type Description Role Name string Name of the role to activate. Sink Name string Name of the sink for which to activate the role.

136 118 Chapter 6 Monitoring the Adapter Using TIBCO Hawk deactivatetracerole() Deactivates a mapping of a roles to sinks at run time. Input Parameters Type Description Role Name string Name of the role to activate. Sink Name string Name of the sink for which to activate the role.

137 getadapterserviceinformation() 119 getadapterserviceinformation() Returns information about the services implemented by this adapter. Input Parameter Type Description Service Name string Name of the service from which to get information. Default is ALL. Returns Type Description Line integer Sequential row number. Service Name string Name of the service as defined at design time. Endpoint Name string Name of the endpoint used for this service. Type string Type of the endpoint, for example, publisher or subscriber. Quality of Service string Quality of service for the endpoint. For example RVCM or JMS Persistent. Subject string Subject defined for this endpoint. Class string Class associated with the endpoint. Number of Messages integer Number of messages processed for this endpoint.

138 120 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getcomponents() Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers. Input Parameters Type Description Component Name string Name of the component. If no value is enter, all components display. Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The default value is All. Returns Type Description Instance ID string Name of this adapter instance as defined at design time. Adapter Name string Name of the adapter. Component Name string Name of the component. Component Type string The name of the TIBCO Adapter SDK class for this component, such as Publisher, Subscriber, or IODescriptorSource. For more information about the class, see your TIBCO Adapter SDK documentation. Session Name string Name of the session. Description string Information about this component, for example, time interval, signal type, and validating the publisher or subscriber.

139 getconfig() 121 getconfig() Retrieves generic configuration information. More specific configuration information is accessed through separate methods. Returns Type Description Instance ID string Configuration ID of this adapter. Adapter Name string Name of the adapter. Repository Connection Configuration URL string string URL of the repository used for adapter instance. Location of the adapter project; either a file name or configuration URL. Command string Command line arguments used to start the adapter.

140 122 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getconfigproperties() Returns all attributes and elements for the given repository object. Input Parameter Type Description Property string Name of the property for which elements (tags) and attributes are desired. For example, agentone/startup. If no value is given, all properties are returned. Returns Type Description Element Name string Repository directory for the property. Attribute Name string Name of the repository object attribute. Attribute Value string Value of the repository object attribute. Line integer Line number in which this property is defined in the project file.

141 gethostinformation() 123 gethostinformation() Return standard and extended application information set. It returns the following information. Returns Type Description Name string Name of the property. Value string Value of the property.

142 124 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getrvconfig() Returns information about the TIBCO Rendezvous session defined by this adapter. Information about all currently defined sessions is returned if no sessionname is provided. Input Parameter Type Description Session Name string Name of the TIBCO Rendezvous session for which configuration is required. If not given, information about all sessions is returned. The default is all. Returns Type Description Instance ID string Configuration ID of this adapter. Adapter Name string Name of the adapter. Session Name string Name of the session. Service string Service parameter for this session. Daemon string Daemon parameter for this session. Network string Network parameter for this session. Synchronous? boolean Returns 1 if this is a synchronous session, 0 otherwise. Session Type string Type of session; one of M_RV, M_RVCM, or M_RVCMQ. Certified Name string Name of this certified session. Ledger File string Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions. CM Timeout string Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

143 getstatus() 125 getstatus() Retrieves basic status information about the adapter. This information is fairly limited; for more detail, additional methods are provided (getconfig() on page 75 and getrvconfig() on page 77. Returns Type Description Instance ID string Configuration ID for this adapter instance. Adapter Name string Name of the adapter. Uptime integer Number of seconds since startup. Messages Received integer Number of TIBCO Rendezvous messages received. Messages Sent integer Number of TIBCO Rendezvous messages published. New Errors integer Number of errors since the last call to this method. Total Errors integer Total number of errors since startup. Process ID integer Process ID of the application. Host string Name of host machine on which this adapter is running.

144 126 Chapter 6 Monitoring the Adapter Using TIBCO Hawk gettracesinks() Returns information about sinks to which traces currently go. Input Parameters Type Description Sink Name string Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all. Role Name string Name of the role for which you need information for the specified sink or sinks. Default is all. Returns Type Description Instance ID string Name of this adapter instance as a string. Adapter Name string Name of the application for this sink. Sink Name string Name of the sink Sink Type string Type of this sink. One of filesink, rvsink, hawksink, stderrsink. Roles string Roles this sink supports, as a string. For example warning, error, debug.

145 getversion() 127 getversion() Retrieves version information for the current application. Two lines may be returned, one for the TIBCO Adapter SDK, one for the adapter. Returns Instance ID Adapter Name Description Configuration ID as a string, for example SDK. Name of the adapter as a string, for example agentone. Version Version number as a string, for example 5.1.

146 128 Chapter 6 Monitoring the Adapter Using TIBCO Hawk _onunsolictedmsg() Displays all alert messages sent from the adapter or an error if not successful.

147 preregisterlistener() 129 preregisterlistener() Preregister an anticipated subscription service. Some sending applications can anticipate requests for certified delivery even before the listening applications start running. In such situations, the publication service can preregister subscription services, so TIBCO Rendezvous software begins storing outbound messages in the publication service ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified deliver. Input Parameters Type Description Session Name string Name of the session that anticipates the listener. Publisher Name string Name of the component for which the listener should be preregistered. Listener Session Name string Name of the subscription service to preregister. Returns OK if the subscription service was preregistered successfully, false otherwise.

148 130 Chapter 6 Monitoring the Adapter Using TIBCO Hawk reviewledger() Returns information retrieved from the ledger file of a TIBCO Rendezvous certified messaging session. Before invoking this method, ensure that the certified messaging publisher adapter has established a certified delivery agreement with its subscriber agents. Input Parameters Type Description Session Name string Name of the TIBCO Rendezvous session for which ledger information is desired (default is all). Subject string Name of the subject for which ledger information is desired. Returns Type Description Session Name string Name of the TIBCO Rendezvous CM session to which this information applies. Subject string Subject name for this session. Last Sent Message integer Sequence number of the most recently sent message with this subject name. Total Messages string Total number of pending messages with this subject name. Total Size integer Total storage (in bytes) occupied by all pending messages with this subject name. If the ledger contains ten messages with this subject name, then this field sums the storage space over all of them. Listener Session Name string Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session.

149 reviewledger() 131 Returns (Cont d) Type Description Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery. Line integer Row number in ledger file. Unacknowledged Messages integer Number of RVCM messages pending for this listener. The value is computed by subtracting the last sent sequence number from the last acknowledged sequence number.

150 132 Chapter 6 Monitoring the Adapter Using TIBCO Hawk settracesinks() Adds a role or changes the file limit of a previously specified sink. Input Parameters Type Description Sink Name string Name of the sink for which you want to add a role or change the file limit. Role Name string Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all. File Size integer Maximum file size for this sink. This parameter is ignored if the sink specified by sinkname is not a file sink. Returns OK if successful or an error if not successful.

151 stopapplicationinstance() 133 stopapplicationinstance() Stops the specified adapter by calling the internal stop() method. This method returns OK if successful or an error if not successful.

152 134 Chapter 6 Monitoring the Adapter Using TIBCO Hawk unregisterlistener() Unregister a currently preregistered subscription service. Input Parameters Type Description Session Name string Name of the session that anticipates the subscription service. Publisher Name string Name of the publication service to which the subscription service is preregistered. Listener Session Name string Name of the subscription service to unregister. This method returns true if the subscription service was unregistered successfully, false otherwise.

153 getactivitystatistics() 135 getactivitystatistics() Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects. Input Parameter Type Description GetSubTotalBy string Indicates how to group the subtotals, by Service or Operation. Returns Type Description Name string Service name or All Services which represents the final tally of all the services Total integer Total number of objects processed including both success and failures. Success integer Total number of objects successfully processed. Failure integer Total number of objects that caused an error during processing. MeasurementIn terval integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started.

154 136 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getactivitystatisticsbyoperation() Returns statistics about one operation. Input Parameter Type Description Operation string Name of the operation. Returns Type Description Operation string Name of the operation. Service Name string Name of the service. Total integer Total number of objects processed, both success and failures. Success integer Total number of objects successfully processed. Failure integer Total number of objects that caused an error during processing. MeasurementIn terval integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started. LineIndex string Concatenated string of Service Name and Operation separated by a comma.

155 getactivitystatisticsbyservice 137 getactivitystatisticsbyservice Returns statistics about the data handled by a given adapter service or all adapter services since the time the adapter was started. Input parameter Type Description Service Name string Name of service to get the statistics for. If no service name is given, performance statistics for all services is returned. Returns Type Description Service Name string Service name Schema Name string Name of top level schema processed by this service. Operation string Type of operation this service provides. Total integer Total number of objects processed, both success and failures. Success integer Total number of objects successfully processed. Failure integer Total number of objects that caused an error during processing. MeasurementIn terval integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started. LineIndex string Concatenated string of Service Name and Operation separated by a comma.

156 138 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getconnectionstatistics() Returns the state and statistics for all the current connections used by the adapter. Returns Type Description Connection ID string Unique identification of a particular connection. Connection Type string Type or key that will match this connection to a thread or queue. State string Current state: CONNECTED or DISCONNECTED. NumRetries integer Total number of times this connection had to be reestablished. TotalNumOperat ions CurrentNumOpe rations NumLostConnec tions MeasurementInte rval integer integer integer integer Total number of operations processed by this connection since the adapter started. Total number of operations processed by this connection since the last reconnection. Total amount of time that this connection has been lost. Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started.

157 getpollinginterval() 139 getpollinginterval() Returns the current polling interval setting. Returns Type Description PollingInterval integer Polling interval in milliseconds.

158 140 Chapter 6 Monitoring the Adapter Using TIBCO Hawk getqueuestatistics() Return the current count of elements in any internal queue used by the adapter. This includes the TIBCO Rendezvous event queues automatically spawned by TIBCO Rendezvous for each adapter. Returns Type Description QueueID string Unique identification of a particular queue. QueueType string Type or key that will match this queue to a thread or connection. QueueCount integer Current number of elements in the queue. MaxQueueSize integer Maximum number of elements in the queue. MeasurementInte rval integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started.

159 getthreadstatistics() 141 getthreadstatistics() Return the operation counts of the current threads. Returns Type Description ThreadID string Unique identification of a particular thread. ThreadType string Type that tells what part of the adapter this thread belongs. Valid types include "Publisher", "Subscriber", "RPC", or "Connection". TaskType string One-word description of the tasks this thread processes. TaskCount integer Number of tasks processed by this thread. MeasurementInterv al integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started.

160 142 Chapter 6 Monitoring the Adapter Using TIBCO Hawk resetactivitystatistics() Resets all the counts for the activity statistics.

161 resetconnectionstatistics() 143 resetconnectionstatistics() Resets all the counts for the connection statistics.

162 144 Chapter 6 Monitoring the Adapter Using TIBCO Hawk resetthreadstatistics() Resets all the counts for the thread statistics.

163 setpollinginterval() 145 setpollinginterval() Set the polling interval for the publication service. Input Parameter Type Description PollingInterval integer Polling interval in milliseconds. ServiceName string Name of service where the polling interval is set.

164 146 Chapter 6 Monitoring the Adapter Using TIBCO Hawk

165 147 Appendix A Trace Messages This appendix explains the trace messages that are logged to a location specified at configuration time. Topics Overview, page 148 Trace Message Fields, page 150 Status Messages, page 152

166 148 Appendix A Trace Messages Overview Trace messages provide information about adapter activities. The messages are logged to the console where the runtime adapter was started and to a log file. Trace messages can also be redirected to the TIBCO Hawk Display application, or sent to other applications using the TIBCO Rendezvous transport. Each trace message can include the following fields: <Timestamp> <Adapter Identifier> <Role> <Category> <Status Code> <Tracking Identifier> The above fields are explained in Trace Message Fields on page 150. The following diagram shows an example trace message and calls out the fields. Timestamp 2003 Jul 09 10:58:54:984 GMT +5 Adapter Identifier Role Category ldap.ldapadapterconfiguration Info [Adapter] Status Code AELDAP Publisher LDAPPublicationService publishing Tracking Identifier tracking=#kj2--7--dkic3uxu-/gpzzw6e-zzw# Example Trace Messages The following trace messages were written during a session where TIBCO ActiveMatrix Adapter for LDAP published a message that used the UPDATE operation, and then processed the message. The first message indicates that TIBCO ActiveMatrix Adapter for LDAP has started. The timestamp indicates when the adapter started, and the role indicates that the trace message is informational, which means the activity is normal for the adapter. The category is identified, and the corresponding status code is displayed. The status code indicates that the adapter started successfully Jul 09 10:58:54:984 GMT +5 ldap.ldapadapterconfiguration Info [Adapter] Adapter ldap started successfully The next set of trace messages indicates the publication service of the adapter publishing a message that uses the UPDATE operation. The #Kj2--7--Dkic3UxU-/gPzzw6E-zzw# tracking identifier included in the trace message uniquely identifies the message. The adapter provided the identifier Jul 09 10:58:54:984 GMT +5 ldap.ldapadapterconfiguration Info [Adapter]

167 Overview 149 AELDAP Publisher LDAPPublicationService publishing tracking=#kj2--7--dkic3uxu-/gpzzw6e-zzw# 2003 Jul 09 10:58:55:015 GMT +5 ldap.ldapadapterconfiguration Info [Adapter] AELDAP Adapter publishing : Publisher : LDAPPublicationService publishing. Opcode = LDAP_MODIFY DN = uid=pop,ou=unit5,o=benchmark,dc=us.tibco.com The final trace message indicates the subscription service has received the message, and acknowledges that the UPDATE operation is complete with the following message Jul 09 10:58:55:031 GMT +5 ldap.ldapadapterconfiguration Info [Adapter] AELDAP Service LDAPSubscriptionService invoked tracking=#0va--9--dkic3k-w-/gqzzw6e-zzw# 2003 Jul 09 10:58:55:031 GMT +5 ldap.ldapadapterconfiguration Info [Adapter] AELDAP Service: LDAPSubscriptionService Operation: LDAP_MODIFY DN: uid=pop,ou=unit5,o=benchmark,dc=us.tibco.com

168 150 Appendix A Trace Messages Trace Message Fields Each trace message includes the following fields: Table 25 Tracing Fields Field Name Description Timestamp Timestamp of occurrence. For example, 2003 Jul 09 10:58:54:984 GMT +5. Adapter Identifier Role Name of the adapter that wrote the trace message. This is a combination of the adapter acronym and adapter configuration name. For example, the application identifier, LDAP.publisher1 identifies a TIBCO ActiveMatrix Adapter for LDAP service named publisher1. A role can be: Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with Info indicates that a significant processing step was reached and has been logged for tracking or auditing purposes. Only info messages preceding a tracking identifier are considered significant steps. Warn. An abnormal condition was found. Processing will continue, but special attention from an administrator is recommended. Error. An unrecoverable error occurred. Depending on the error severity, the adapter may continue with the next operation or may stop altogether. Debug. A developer-defined tracing message. In normal operating conditions, debug messages should not display. When configuring the adapter you define what roles should or should not be logged. For example, you may decide not to log Info roles to increase performance.

169 Trace Message Fields 151 Table 25 Tracing Fields Field Name Category Status Code Tracking Identifier Description One of the following: Adapter. The adapter is processing an event. Application. The adapter is interacting with the LDAP server. Configuration. The adapter is reading configuration information. Database. The adapter is interacting with a database. Metadata. The adapter is retrieving metadata from the LDAP server. Palette. The adapter is interacting with the palette. Publisher Service. The publication service is reporting this trace message. Request-Response Server. The request-response service is reporting this trace message. Shutdown. The adapter is shutting down. Startup. The adapter is starting. Subscription Service. The subscription service is reporting this trace message. System. This category is not linked to a specific event process. The trace message may be related to a Microsoft Windows service related messages, memory allocation, file system error, and so on. TibRvComm. The adapter is communicating with TIBCO Rendezvous. XML. The adapter is parsing XML documents. Unique code for the message and description. Status codes are identified by a unique number and description. If a trace message includes an error or warn role, the status code documentation includes a resolution. See Status Messages on page 152 for details. A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a message s beginning to its completion as it is exchanged by TIBCO applications. If the adapter is the termination point of the message, the tracking identifier is not displayed in the trace message. You cannot modify the tracking identifier format or configure what information is displayed.

170 152 Appendix A Trace Messages Status Messages. Message Role Category Resolution AELDAP Cannot connect to the LDAP server. errorrole Adapter Verify connection parameters in the Connection Tab for the adapter instance configuration. AELDAP Unable to open the audit log file for reading. errorrole Adapter Ensure that the path for the audit log file is correct as displayed in the Connection Tab during adapter instance configuration. AELDAP Service <service name> invoked. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Publisher <service name> publishing. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Unable to initialize the timer. errorrole Adapter Internal error occurred. The repository created through the adapter palette is possibly corrupted. Please reconfigure the adapter. AELDAP Unable to fetch the schema for the LDAP server <server name>. errorrole Adapter The adapter was unable to do a schema query against the LDAP server. Verify that the LDAP server is up and that connection parameters specified in the Connection Tab during configuration are correct.

171 Status Messages 153 Message Role Category Resolution AELDAP An internal error occurred on the LDAP Server: <server name>. errorrole Adapter This may be due to a error in configuring the adapter in TIBCO Designer. Please verify your adapter and service configuration. AELDAP Adapter publishing: <message>. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Error occurred while creating persistent search control: <error description>. errorrole Adapter This may be due to a error while configuring the adapter in TIBCO Designer. Please verify your adapter and service configuration. AELDAP Operation <operation name> is not supported for the service: <service name>. errorrole Adapter The LDAP operation is not supported by the service. Please check your adapter service configuration in TIBCO Designer. AELDAP <DN> is not a valid DN for the service: <service name>. errorrole Adapter The DN of the specified entry is not within the scope of the DIT selected for this service. AELDAP RPC Service: <service name> sending the reply back. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Service: <service name> Operation: <operation name> DN: <DN> <DN>. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Trying to reestablish connection with the LDAP server. warnrole Adapter The connection with the LDAP server was lost, possibly due to the server going down. The adapter will attempt to reconnect to the server.

172 154 Appendix A Trace Messages Message Role Category Resolution AELDAP Unable to reestablish connection with LDAP server in service <service name> while executing operation <operation name> with DN as <DN>. errorrole Adapter The adapter attempted to reconnect to the LDAP server after a connection went down; however this reconnect attempt was unsuccessful. The adapter will now stop. Please check your LDAP server. AELDAP Service <service name> attempted operation <operation name> on DN <DN> resulted in error: <error description>. errorrole Adapter The error string in the message describes the cause of the problem. This is an error returned from the LDAP server. AELDAP Cannot run the service <service name> on non windows platform against Active Directory server. errorrole Adapter An adapter instance working against Active Directory must be run only on Microsoft Windows. An attempt was made to start the adapter on a non-microsoft Windows platform. Please run the adapter on Microsoft Windows. AELDAP Unable to reestablish connection with LDAP server in service <service name>. errorrole Adapter The adapter attempted to reconnect to the LDAP server after a connection went down; however this reconnect attempt was unsuccessful. The adapter will now stop. Please check your LDAP server. AELDAP The logfile <logfile name> could not be opened. The adapter will not publish any changes which occurred before the adapter was started. This is normal if you are starting the adapter for the first time. warnrole Adapter If you are not starting the adapter for the first time, check if the file exists. If it does not, check on file space and on write permissions for the adapter to create the file.

173 Status Messages 155 Message Role Category Resolution AELDAP The logfile <logfile name> could not be read. The adapter will not publish any changes which occurred before the adapter was started. errorrole Adapter Files cannot be created and/or read. Contact your system administrator. AELDAP The logfile <logfile name> could not be written to. errorrole Adapter Files cannot be created and/or read. Contact your system administrator. AELDAP This version of TIBCO ActiveMatrix Adapter for LDAP is not compatible with the specified repository. Please install and use a newer version of the adapter. errorrole Configuration Install the latest version of the adapter. AELDAP Warning: Opening a repository corresponding to an older LDAP Adapter version. It is recommended (but not necessary) that you open the repository in the current TIBCO ActiveMatrix Adapter for LDAP palette, update all services and save the repository. warnrole Configuration Use the current palette to open the repository, update all services and save the repository. AELDAP Startup Error. Unable to create a connection with the target application using connection parameters [Host = <host name>, Port = <port>, User DN = <user DN>, Password = ******]. Target application error is <error description>. errorrole Adapter Check connection parameters provided at configuration time. Also check if the LDAP server is running. AELDAP Startup Error. Received target application error with the target application LDAP. The connection <user DN>, Password = ***** and the Connection pool size is <connection pool size>. errorrole Adapter Check connection parameters provided at configuration time. Also check if the LDAP server is running.

174 156 Appendix A Trace Messages Message Role Category Resolution AELDAP Reconnect attempt <attempt number>. inforole Adapter Indicates normal adapter operation. No action necessary. Connections to the LDAP server have been broken and a reconnect is being attempted. AELDAP Reconnect succeeded on attempt <attempt number at which reconnection was successful>. inforole Adapter Indicates normal adapter operation. No action necessary. Reconnects were attempted and succeeded in current attempt. AELDAP Reconnect failed on attempt <attempt number> - will retry in <time> milliseconds warnrole Adapter The reconnect failed, but the adapter will try again after the specified time interval. AELDAP Connection reestablished for publisher - message may be a duplicate of a previously published message. warnrole Adapter The connection was reestablished. However, the message may be a duplicate of a previously published message. AELDAP The request received could not be processed due to connection errors. Error reply sent back. errorrole Adapter Due to connection errors, the request could not be processed. If configured, reconnection attempts have been started to the target LDAP server. AELDAP Adapter stopping due to persistent connection errors. Please check LDAP Server and restart adapter. inforole Adapter Connection could not be established after the configured number of reconnects. The adapter will stop execution.

175 Status Messages 157 Message Role Category Resolution AELDAP Subscription services suspended due to reconnect failure. inforole Adapter Connection could not be re-established; as configured, subscriber services are now suspended and will be automatically revived once the connection is back up. AELDAP Connection reestablished; suspended subscriber services if any, reactivated. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Operation did not succeed due to connection error in service <service name>. The operation will be reattempted. inforole Adapter An operation such as Add, Delete, Modify could not be performed by a subscriber service due to connection errors. Will be reattempted once the connection is back up. AELDAP Subscription error. Subscription service <service name> listening on subject <subject name> failed due to target application invocation error <error description>. Target application is LDAP. The target application specific commands and parameters are <parameters>.the bad message is = <error message> and is logged for future reference. errorrole Adapter The target application invocation error is from the LDAP server. Please contact your LDAP server administrator for information on the cause of the error.

176 158 Appendix A Trace Messages Message Role Category Resolution AELDAP Request-Response error. Request-Response service <service name> listening on subject <subject name> failed due to target application invocation error <error description>. Target application is 'LDAP' and the inbound event is <inbound event>. The target application specific commands and parameters are <target application commands and parameters>. errorrole Adapter This error occurs when the request-response service sends a request from TIBCO IntegrationManager that has inaccurate or incomplete data. The LDAP Server cannot complete the specified operation using this data. Make sure that you send accurate and complete data to the LDAP server so that the operation can be successfully completed. AELDAP No object class specified for the service: <service name>. errorrole Configuration Specify an object class in the adapter configuration. AELDAP Service <service name> attempted operation <operation name> on DN <DN> resulted in error: Invalid object class. errorrole Adapter Check if the LDAP server entry that is being acted on belongs to the object class configured for the adapter service. AELDAP Service <service name> attempted operation <operation name> on DN <DN> resulted in error: Unable to find the specified entry. errorrole Adapter Check if the entry exists on the LDAP server. AELDAP Service <service name> attempted operation <operation name> on DN <DN> resulted in error: Modify not performed since the server has identical data. warnrole Adapter For server synchronization through the Update Only If Different option, a modify request was ignored since incoming data is the same as data on the LDAP server.

177 Status Messages 159 Message Role Category Resolution AELDAP Startup Error. Unable to create an SSL connection with the target application using connection parameters [Host = <host name>, Port = <port>]. ldapssl_init() failed. errorrole Adapter Check your LDAP server connection parameters provided at configuration time. AELDAP Startup Error. Unable to set automatic reconnectionoption on the SSL connection. Non-fatal error. Continuing. Connection parameters [Host = <host name>, Port = <port>, User DN = <user DN>]. warnrole Adapter Setting reconnect option through ldap_set_option() has failed. Contact your LDAP administrator. AELDAP Startup Error. Unable to enable client EXTERNAL authentication using parameters [Client certificate and key nickname =<certificate and key nickname>, Key password = ******]. Target application error is: <error description>. warnrole Adapter Make sure that the right client certificate is imported into the converted certificates and keys directory and the client key password is correct. AELDAP Startup Error. Unable to initialize client library for SSL using parameters [Client certificate and key directory = <client certificate and key directory>, Server authentication = <authentication>]. Target application error is: <error description>. errorrole Adapter Check certificates and key directory as well as connection parameters. AELDAP Startup Error. Unable to bind to target LDAP server on SSL channel using parameters [Host = <host name>, Port = <port>, Client authentication mechanism = <authentication mechanism>, User DN = <user DN>]. Target application error is: <error description>. errorrole Adapter Check your LDAP server connection parameters.

178 160 Appendix A Trace Messages Message Role Category Resolution AELDAP Failed to connect to the server. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to get the DnsHostName. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to open the Root DSE on an Active Directory Server using parameters [ADsPath = <path>, User DN = <user DN>, Use SSL = <SSL used>]. Target application error code is: <error code>. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to open the DC Service on an Active Directory Server using parameters [ADsPath = <path>, User DN = <user DN>, Use SSL = <SSL used>]. Target application error code is: <error code>. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to open the IDirectorySearch on an Active Directory Server using parameters [ADsPath = <path>, User DN = <user DN>, Use SSL = <SSL used>]. Target application error code is: <error code>. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to open the IDirectorySearch with fast bind option on an Active Directory Server using parameters [ADsPath = <path>, User DN = <user DN>, Use SSL = <SSL used>]. Target application error code is: <error code>. errorrole Adapter Check your connection parameters and contact your Active Directory administrator. AELDAP Failed to open an object on an Active Directory Server using parameters [ADsPath = <path>, User DN = <user DN>, Use SSL = <SSL used>]. Target application error code is: <error code>. errorrole Adapter Check your connection parameters and contact your Active Directory administrator.

179 Status Messages 161 Message Role Category Resolution AELDAP Publisher <service name> on subject <subject name> did not find any entries to publish. inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Startup Error. Unable to create a Custom Hawk Micro Agent Named <microagent name> used for %2. errorrole Adapter This occurs only if there is a problem with the adapter configuration. Please verify your configuration through the LDAP palette, save and restart the adapter. AELDAP Startup Error. SDK Exception <error description> occurred while creating a shutdown listener with parameters <parameters>, <parameters>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>. errorrole Adapter This occurs only if there is a problem with the adapter configuration. Please verify your configuration through the LDAP palette, save and restart the adapter. AELDAP Startup Error. The command line parameters <parameters> have not been specified properly errorrole Adapter Check the specified command line parameter used while starting the adapter. Also, verify that information in the.tra file is correct. AELDAP Configuration Error. <error description>. errorrole Configuration Check the error message for details on the configuration error and fix those. AELDAP Task raised exception. <error description>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

180 162 Appendix A Trace Messages Message Role Category Resolution AELDAP Unable get connection object. <description> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Unable to release connection object. <description>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Subscription error. Subscription service <service name> listening on <subject name> received an unexpected event of type = <event type received>, Expects event <event type expected>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>. errorrole Adapter Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to Subscription Service Fields on page 52 for details on the configuration of subscription service. AELDAP Subscription error. Subscription service <service name> failed to deserialize the event received on subject <subject name> and SDK exception thrown is <error description>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>. errorrole Adapter Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to Subscription Service Fields on page 52 for details on the configuration of subscription service.

181 Status Messages 163 Message Role Category Resolution AELDAP Subscription error. Subscription service <service name> listening on subject <subject name> received inbound event with null data. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>. errorrole Adapter Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to Subscription Service Fields on page 52 for details on the configuration of subscription service. AELDAP Subscription error. Subscription service <service name> listening on subject <subject name>, could not could not find the tracking data. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>. errorrole Adapter Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to Subscription Service Fields on page 52 for details on the configuration of subscription service. AELDAP Subscription error. Subscription service <service name> listening on subject <subject name> received error <error description> in SDK message level UserExit <user exit parameter>. errorrole Adapter Make sure the UserExit parameters are valid and the user exit is invokable from SDK.

182 164 Appendix A Trace Messages Message Role Category Resolution AELDAP Publication error. Publication service <service name> publishing on subject <subject name> encountered error <error description> while trying to connect to target application <application name>. Connection parameters are <connection parameters>, the connection timeout is <connection timeout> milliseconds, and the number of retry efforts is <number of retry attempts>. Polling timeout is <polling timeout> milliseconds. errorrole Adapter Check the target application and make sure it is up and running. Check the connection parameters for right syntax and values. Please refer to Creating the Project on page 7 for details on how to specify connection parameters AELDAP Publication error. Publication service <service name> with publication subject <subject name> received error while sending event over the wire. The Publish endpoint details are <endpoint details>. errorrole Adapter Please check your configuration file to verify that the publisher service is configured correctly. AELDAP Publication error. Publication service <service name> with publication subject <subject name> received error <error description> in the SDK message level UserExit. The User exit names are <user exit name> and the User exit parameters are <user exit parameters>. errorrole Adapter Make sure the UserExit parameters are valid and the user exit is invokable from SDK. AELDAP Publication error. Publication service <service name> with publication subject <subject name> encountered error <error description> while trying to create publish event with schema <schema>. The Target application details are <application details>. errorrole Adapter Make sure the UserExit parameters are valid and the user exit is invokable from SDK. AELDAP Advisory warning message for %1 warnrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

183 Status Messages 165 Message Role Category Resolution AELDAP Error occurred while trying to publish. The exception is: <error description>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Request-Response error. Request-Response service <service name> listening on subject <subject name> received a time out error. Time out period in configuration file is <time> milli seconds. errorrole Adapter Increase the timeout value for the request-response service. AELDAP AppManager already initialized. setmappproperties() ignored. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Invalid service type. Service <service name> contains invalid value for the attribute 'type'. errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Failed to find component <component name> in repository. errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Service contains incorrect endpoint type. <service name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

184 166 Appendix A Trace Messages Message Role Category Resolution AELDAP Agent's publisher service not found. <agent name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Agent contains incorrect publisher service type. <agent name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Class inheritance error. <class name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Feature not implemented. <feature name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Connection Manager initialization failed. <name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Agent termination failed. <agent name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

185 Status Messages 167 Message Role Category Resolution AELDAP <information message> inforole Adapter Indicates normal adapter operation. No action necessary. AELDAP Application Manager initialization error. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP <error description> errorrole Adapter The connection with the LDAP Server cannot be established. Make sure that the LDAP server is running. AELDAP Operation contains invalid parameter type. <operation name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Transaction failed: <error description> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Reply operation failed for server service <service name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Unable to create Hawk service: <service name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

186 168 Appendix A Trace Messages Message Role Category Resolution AELDAP Operation contains incorrect number of parameters. <operation name> errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Remote operation invocation failed for service <service name>. errorrole TibRvComm The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Invalid operation name. Service <service name> contains a operation name that is not supported in the associated class. errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP No operation match. Operation name specified for Service <service name> does not match any of the operations in the associated class. errorrole Configuration The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Unable to deserialize reply message for publisher reply service: <service name>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Invalid event received by publisherreplyservice <service name>. errorrole TibRvComm The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

187 Status Messages 169 Message Role Category Resolution AELDAP Unable to deserialize incoming message for subscriber service: <service name>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Unable to get the MPublisher associated with the data event for subscriber reply service <service name>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Publisher reply service unable to send reply. <service name>. errorrole TibRvComm The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Unable to execute task <task name>. errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Task returned incorrect MInstance. <task name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette. AELDAP Task execution error. <task name> errorrole Adapter The adapter configuration does not seem to have been saved correctly. Please review, edit and save the configuration correctly from the palette.

188 170 Appendix A Trace Messages Message Role Category Resolution AELDAP Startup Warning. Connection pool size <current connection pool size> is smaller than desired pool size <required connection pool size>. The connection parameters are [Host = <host name>, Port = <port>, User DN = <user DN>, Password = ******, SSL = <SSL>. warnrole Adapter AELDAP This field is mandatory errorrole Palette Error message for the null field. This field is mandatory. AELDAP The port number must be greater than or equal to 0, and less than or equal to errorrole Palette Error message if the port number is beyond the standard range. AELDAP This is not a valid value. errorrole Palette Error message if the value entered in No. Of Threads field is invalid. AELDAP Invalid subject. errorrole Palette Error message if an invalid subject is entered in the Termination Subject or Topic field. AELDAP You must select at least one LDAP action. errorrole Palette Error message for the LDAP actions. AELDAP The specified LDAP server type does not match with the actual LDAP server type you are trying to connect to. Please select the correct server type. errorrole Palette Error message while connecting to the LDAP server, if it is different from the specified server in the Server Type field. AELDAP Connection could not be established with the LDAP server, so currently the Schema View tab will not be available.please ensure that valid parameters have been specified in the Design-time Connection tab. warnrole Palette Warning message when the Schema View tab of a service could not be shown.

189 Status Messages 171 Message Role Category Resolution AELDAP No X509TrustManager implementation available. Please check your SSL connection information and certificate keystore. errorrole Palette While establishing the SSL connection, an error occurs if the selected file for the Trusted Certificate Authorities field is not a valid keystore. Check that the CA certificate is present in the trusted store and that the keystore exists. AELDAP Couldn't find trusted certificate. Please check your SSL connection information and certificate keystore. errorrole Palette While establishing the SSL connection, an error occurs if the CA certificate is not present in the selected trusted store or if the entered keystore doesn't exist. Check that the CA certificate is present in the trusted store and that the keystore exists. AELDAP Please wait... inforole Palette Indicates normal adapter operation. No action necessary. AELDAP Invalid number. errorrole Palette Make sure that the number field does not contain a hyphen (-) character. AELDAP This DN does not exist. errorrole Palette Check that the DN specified exists on the LDAP server. AELDAP Connecting to the LDAP server... inforole Palette Indicates normal adapter operation. No action necessary. AELDAP At least one service already exists with the previous server data.make sure that no service exists before attempting to configure the new server. errorrole Palette Delete any services already configured if these correspond to a different server.

190 172 Appendix A Trace Messages Message Role Category Resolution AELDAP You have already configured adapter instances and services for a particular LDAP server. The change that you are attempting will be valid only if the new server has identical directory information tree and schemas. Please confirm this and that you do wish to proceed with this change. warnrole Palette Warning message for server name change. AELDAP The selected resource cannot be moved. warnrole Palette Warning message while moving the service or instance. AELDAP Fetching schema... inforole Palette Message while fetching the schema. AELDAP Fetching descendants... inforole Palette Message while fetching the descendants. AELDAP This field supports only integer values. errorrole Palette Error message if non-integer values are entered in the Maximum Number Of Entries field of the Schema View tab. AELDAP The maximum value for this field should not exceed errorrole Palette Error message if the number of maximum entries is specified as greater than in the Schema tab. AELDAP The specified DN and sample schema entry values together do not form a valid DN. Please enter correct values. errorrole Palette Error message if the number of maximum number of entries is specified as greater than 10,000 in the Schema tab. AELDAP The number of search entries must be greater than or equal to 1 and less than or equal to errorrole Palette Error message if the specified number of search entries is less than 1 or greater than 1000.

191 Status Messages 173 Message Role Category Resolution AELDAP The maximum number of retries cannot have a zero value. errorrole Palette Make sure that you have not entered zero in the Maximum Number of Reconnect Attempts field. You can enter -1 or a positive integer that is greater than zero in the Maximum Number of Reconnect Attempts field. AELDAP The maximum number of retries must be greater than or equal to -1, and less than or equal to 65535, excluding zero. errorrole Palette Make sure that the value entered in the Maximum Number of Reconnect Attempts field, is not out of range. AELDAP The maximum number of retries should be greater than or equal to number of retries before suspend. errorrole Palette Make sure that the value entered in the Maximum Number of Reconnect Attempts field is not less than the value entered in the Number of Reconnect Attempts Before Suspending Impacted Service(s) field. AELDAP The number of retries before suspend must be greater than or equal to 1, and less than or equal to errorrole Palette Make sure that the value entered in the Number of Reconnect Attempts Before Suspending Impacted Service(s) field is not out of range. AELDAP The sleep between retries must be greater than or equal to 100, and less than or equal to errorrole Palette Make sure that the value entered in the Interval Between Reconnect Attempts (milliseconds) field is not out of range.

192 174 Appendix A Trace Messages Message Role Category Resolution AELDAP Could not fetch schema due to insufficient access privilege. Please change the authentication details in the Design-time Connection tab as necessary. errorrole Palette Make sure that the schema in the Class Reference field of the Schema View tab, for a given DN and Sample Entry for Schema, is populated. AELDAP Adapter Service names must only have alphanumeric characters. Please type in a valid name. errorrole Palette Make sure that the name of the service does not consist of non-alphanumeric characters.

193 Additional LDAP Directory Server Settings 175 Appendix B Additional LDAP Directory Server Settings This appendix explains each of the additional LDAP directory server settings you can make during design-time. Topics Setting Default Naming Context in ADAM, page 176 Configuring Global Catalog Server, page 177

194 176 Appendix B Additional LDAP Directory Server Settings Setting Default Naming Context in ADAM The naming context container of ADAM provides you information about objects deleted from LDAP server. You can specify a default naming context. The following information provides information on how to set default naming context in ADAM. By default, an ADAM instance does not provide a default naming context. You can, however, configure ADAM to provide a default naming context as follows: 1. In ADAM ADSI Edit, expand the My Connection tree as follows: a. Expand the CN=NTDS Settings, CN=ServerName$InstanceName, CN=Servers, CN=Default-First-Site-Name, CN=Sites, CN=Configuration, CN={GUID}. 2. Right-click on the CN=NTDS Settings node. The CN=NTDS Settings Properties dialog appears. 3. Select the attribute msds-defaultnamingcontext. 4. Click the Edit button. 5. Type the value with the base DN to be used in the naming context, for example: o=tibco,c=us 6. Click OK twice. 7. Restart your ADAM instance so the new default naming context will take effect.

195 Configuring Global Catalog Server 177 Configuring Global Catalog Server To configure Global Catalog Server on Active Directory server, a few schema attributes viz. InvocationID, subclassof and systemauxiliaryclass, need to be set using a custom console that contains the Schema snap-in. If you are working on a new Active Directory setup, please note that this snap-in is part of the administrative tools but is not registered by default. In case the snap-in is not registered, the following steps would register the Schema snap-in: open a command console and navigate to C:\Windows\System32 and run regsvr32 schmmgmt.dll In order to make Schema management easier, create a custom Schema console for the registered Snap-in by following the steps below: From the Run window, type mmc and click OK. This opens an empty MMC console From the CONSOLE menu, select FILE -> ADD/REMOVE SNAP-IN. The Add/Remove Snap-in window opens

196 178 Appendix B Additional LDAP Directory Server Settings Figure 22 Add/Remove Snap-in Click Add. The Add Standalone Snap-in window opens Figure 23 Add Standalone Snap-in

197 Configuring Global Catalog Server 179 Double-click Active Directory Schema and then click Close Click OK to save the change and return to the MMC window. The Active Directory Schema tree will appear under the Console Root folder Save the file with a name like Schema.msc. The system will put the file in your personal profile. Save it to the \Windows\System32 folder if you want other administrators to use it. Set the attribute values by following the steps below From the Run window, type Schema.msc and click OK to open the Schema management console. Figure 24 Schema Management Console Expand the Active Directory Schema node in the tree view to see the list of class objects and attributes. Right click on the attribute invocationid and select Properties.