Overview of the Lotus Notes Adapter

About the Lotus Notes Adapter

IBM webMethods Adapter for Lotus Notes is an add-on to IBM webMethods Integration Server that enables you to exchange data with Lotus Domino Servers. Using Adapter for Lotus Notes, IBM webMethods Integration Server developers can create and run services that execute transactions to retrieve data from, and insert and update data in, Domino Servers. For example, you can use Adapter for Lotus Notes to retrieve a document from the Domino Server based on data from another system connected to Integration Server.

Lotus Notes applications may also act as clients to Integration Server. A code sample for setting up this functionality is provided.

Architecture and Components

Adapter for Lotus Notes provides a set of user interfaces, services, and templates that enable you to create integrations with Lotus Notes systems. The adapter is provided as a single package that must be installed on Integration Server. For detailed installation instructions, see Installing the Adapter. For software requirements, see IBM webMethods Adapters System Requirements.

The following diagram shows at a high level how Adapter for Lotus Notes components interface with a Domino Server using the Lotus Domino Toolkit for Java/CORBA to access remote Domino objects.

IBM webMethods Integration Server . Adapter for Lotus Notes is installed and runs on Integration Server.
WmART Package. The WmART package provides a common framework for webMethods 6 and later adapters to use Integration Server functionality, making Integration Server the run-time environment for Adapter for Lotus Notes. The WmART package is installed with Integration Server.
Adapter for Lotus Notes. Adapter for Lotus Notes is delivered as a single package called WmLotusNotesAdapter. The adapter provides Integration Server Administrator user interfaces that enable you to configure and manage adapter connections, and user interfaces in IBM webMethods Designer that enable you to configure and manage adapter services. Adapter for Lotus Notes installation includes a single template from which you can create all Adapter for Lotus Notes services.
Adapter Connection Template. Adapter for Lotus Notes connections enable you to create adapter services. You must configure an adapter connection before you can create adapter services. The adapter provides a template for adapter connections in the Integration Server Administrator. For a detailed description of adapter connections, see Adapter Connections.
Adapter Service Template. Adapter for Lotus Notes provides an adapter service template that enables Integration Server to communicate with Domino Servers. Adapter for Lotus Notes’s adapter service template is available in Designer. Services created from this template allow you to manipulate Domino objects based on available methods in the IBM Lotus Domino Toolkit for Java/CORBA. For more information about adapter services and using the adapter service template, see Adapter Services.
Lotus Domino Toolkit for Java/CORBA. Adapter for Lotus Notes communicates with the Domino Server using the Lotus Domino Toolkit for Java/CORBA (NCSO.jar or NCSOW.jar). The remote Domino object classes in the NCSO.jar and NCSOW.jar files use CORBA to access the Domino Server over a TCP/IP network. Remote access consists of two parts:
- Adapter for Lotus Notes receives the Domino Server's initial object as an IOR (Interoperable Object Reference) via the HTTP protocol.
- Adapter for Lotus Notes receives additional objects and makes method calls over IIOP.
  For more information about the Lotus Domino Toolkit for Java/CORBA and the NCSO.jar or NCSOW.jar files that the adapter requires, see IBM webMethods Adapters System Requirements and IBM's Java Access to Domino Objects - IBM Redbook Library Part 1. This information is also available in the documentation for the Lotus Domino Toolkit for Java/CORBA and on the IBM Lotus web site.

For a detailed description of the run-time data flow for Adapter for Lotus Notes services, see Adapter Service Run-Time Processing.

The following diagram illustrates a typical business-process integration at run time involving Adapter for Lotus Notes and the Domino Server.

Package Management

Adapter for Lotus Notes is provided as a package called WmLotusNotesAdapter that you manage like any package on Integration Server. There are several considerations regarding how you set up and effectively manage your packages on Integration Server, such as those described in the following list.

Create user-defined packages for your connections, and adapter services. See Package Management for details.
Understand how package dependencies work so you make the best decisions regarding how you manage your adapter services. See Package Dependency Requirements and Guidelines for details.
Control which development groups have access to which adapter services. See Group Access Control for details.
Understand how clustering, an advanced feature of Integration Server, works to effectively manage your adapter services. See Adapter for Lotus Notes in a Clustered Environment for details.
Enable and disable packages. See Enabling Packages and Disabling Packages for details.
Load, reload, and unload packages. See Loading, Reloading, and Unloading Packages.

Adapter Connections

Adapter for Lotus Notes uses an adapter connection to create a Lotus Domino session object (lotus.domino.Session). A session object is required before doing any work with a Domino Server. Adapter for Lotus Notes provides one connection type, Lotus Notes Connection. A connection for Adapter for Lotus Notes is a placeholder for connection information: user, password, host, and an HTTP/HTTPS option. More than one session object can be created with an adapter connection.

A connection does not automatically start or maintain connections to a Domino Server; it only creates session objects to a Domino Server. And because adapter connections do not store session objects created to a Domino Server, there is no connection pooling support.

Integration developers using Adapter for Lotus Notes may need to create session objects for many users, sometimes hundreds. Creating an adapter connection for each of these users is a significant administrative effort. Developers can create session objects by configuring an adapter service to use a certain adapter connection and optionally override the user and password in the connection. That is, the credentials stored in the connection are the default values when no credentials are specified when the connection creates a session object. This enables one connection to create session objects for more than one user. For more information about creating Domino session objects, see the Lotus Domino Toolkit for Java/CORBA documentation. There is no transactional support for an adapter connection because the Lotus Domino Toolkit for Java/CORBA does not provide it.

Integration developers are responsible for recycling any Domino objects (especially session objects) they create locally to free local and remote resources. The adapter provides two utility services, wm.ln.utils.garbage:recycle and wm.ln.authentication:logout, for this purpose. For more information about these services, see Freeing Resources After Processing.

You configure connections using the Integration Server Administrator. You must have Integration Server Administrator privileges to access the Adapter for Lotus Notes's administrative screens.

For instructions for configuring, viewing, editing, enabling, and disabling Adapter for Lotus Notes connections, see Adapter Connections. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.

For a list of tasks that you must do before you can create your connections, see Before Configuring or Managing Adapter Connections.

Built-In Services For Connections

Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.

The built-in service pub.art.service:setAdapterServiceNodeConnection enables you to change the connection associated with an adapter service. For information, see Changing the Connection Associated With an Adapter Service at Design Time.

For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Changing the Connection Associated With an Adapter Service at Design Time

Integration Server provides a built-in service that you can use at design time to change the connection associated with an adapter service. This built-in service, named setAdapterServiceNodeConnection, is provided in the WmART package's pub.art.service folder. Using this service, you can change the specific connection associated with an adapter service at design time so that you do not need to create and maintain multiple adapter services.

Note: These built-in services can be run at design time only; do not use them within an Integration Server flow or Java service. You must run this service directly from Designer by selecting and running the service.

For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Other built-in services enable you to control connections; for more information, see Built-In Services For Connections.

Changing the Connection Associated with an Adapter Service at Run Time

Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar backend resources.

For example, a service can be defined to use a default connection that interacts with your company's North American Lotus Domino server. However, at run time you can override the default connection and instead use another connection to interact with the company's European Lotus Domino server.

For more information about overriding a service's default connection at runtime, see Dynamically Changing a Service's Connection at Run Time.

Adapter Services

Adapter services allow you to connect to, and initiate operations on, a Domino Server. Adapter services are based on a template provided with Adapter for Lotus Notes. With Adapter for Lotus Notes, an adapter service wraps a method you select from the adapter service template. These methods belong to the Java lotus.domino classes supplied by the Lotus Domino Toolkit for Java/CORBA, and are used to remotely execute methods on Domino objects. Adapter for Lotus Notes supports a subset of the classes in the toolkit. The methods in the template are defined in an XML data file. For information about managing the XML data file, see Editing the XML Data File.

Adapter for Lotus Notes provides adapter services that have been pre-configured to call each of the supported methods in the Java lotus.domino classes. These adapter services use a preconfigured adapter connection that serves as a placeholder for connection information. Also provided with Adapter for Lotus Notes are built-in flow and Java services that wrap one or more of the adapter services. Integration developers use the flow and Java services in their integrations instead of calling the adapter services directly.

For information about the adapter services and how they are provided in Designer, see Built-In Services Reference. For information about the classes and methods provided in lotus.domino package, see the Lotus Domino Toolkit for Java/CORBA documentation.

Note: A samples package is available that contains adapter services that show how to work with the Domino objects. You can use the samples as "working examples" from which you can build and test your own integrations.

Using the Adapter Service Template

You use Designer to configure an adapter service. For more information, see the IBM webMethods Service Development Help for your release.

Configuring a new adapter service from the adapter service template is straightforward. Using Designer, you assign the service a default adapter connection, select the adapter service template, select the class and method to execute on the Domino Server, and specify how the adapter is to generate the input and output signatures.

Note: There can be more than one method in the class with the same name. The adapter distinguishes them by appending the method signatures to the method name.

Configure at least one adapter service that executes the createSession method in the lotus.domino.Session class, which creates the connection object for the Domino Server. Then configure additional adapter services as needed to perform specific Domino operations. There is no requirement to associate the same connection to adapter services after a session object has been created.

After you configure an adapter service, you can incorporate it into a flow service or Java service to interact with a Lotus Notes system. For example, you can create a flow service that creates an e-mail and sends it using the Lotus Notes system.

Important: All services must first invoke an adapter service that specifies the lotus.domino.Session class and createSession method to create the connection object for the Domino Server. For information about creating this adapter service, see Example Lotus Notes Operation.

Adapter for Lotus Notes provides the following adapter service template:

Adapter Service Template	Description
Domino Operation	Provides classes and methods for Domino objects. See Configuring Lotus Domino Operation Services for instructions.

The input and output signatures for the adapter service are shown in the service template, and are generated as Java data primitives when you create the service. However, you can force the signatures to be generated using Strings by specifying the Primitive option.

When you run the adapter service, specify the correct, valid inputs. For information about the inputs, see the Lotus Domino Toolkit for Java/CORBA documentation. Note that in the toolkit documentation, "" is referred to as "null". Adapter for Lotus Notes converts nulls to "".

Freeing Resources After Processing

To free local and remote resources created by the services, call the wm.ln.utils.garbage:recycle and/or wm.ln.authentication:logout utility service in each flow or Java service. For example, within a flow you create a session object, send an email, call recycle, then send a newsletter, then call logout.

The wm.ln.utils.garbage:recycle service recycles all Domino objects at the root level of the pipeline, including session objects if they exist. Session objects are recycled last. Use the recycle service between processing steps if you have more work to do and want to reuse the same session object. Do leave the session object at the root level of the pipeline or else it will be recycled. For more information, see wm.ln.utils.garbage:recycle.
The wm.ln.authentication:logout service checks to see if there is a session object at the root level of pipeline. The logout service requires that there be a session object in the pipeline, and if there is, it scans the pipeline, and then call the recycle service to recycle all other objects, and then recycles the session object. If there is no session object, the logout service fails. Always use the logout service as the last step in a flow or Java service to ensure that all objects are recycled. For information about the input and output parameters, see wm.ln.authentication:logout.

Adapter Service Run-Time Processing

The following diagram illustrates how Adapter for Lotus Notes processes adapter services at run time.

Step	Description
1	An Integration Server client, typically using a flow or Java service, invokes a Adapter for Lotus Notes service on the IBM webMethods Integration Server to perform an operation on a Domino Server. You configured the adapter service earlier using Designer.
2	The adapter service uses the methods and classes in the Lotus Domino Toolkit for Java/CORBA to perform the necessary operations.
3	If the operation is successful, the adapter service returns the output from the operation, if applicable. If the operation is unsuccessful, the adapter service returns an error. For more information about how the adapter handles exceptions, see Built-In Services Reference.

Lotus Notes-to-webMethods Communications

For Lotus Notes-to-webMethods (outbound) communications, you must write a shared agent in Java or LotusScript that invokes a service on the specified IBM webMethods Integration Server. For more information, see Lotus Notes-to-webMethods Communications.

Lotus Notes-to-webMethods Run-Time Processing

Integration Server processes service requests from an agent running on a Domino Server. You must understand how agents run on a Domino server. For more information about using webMethods clients, see the IBM webMethods Service Development Help for your release.

Adapter for Lotus Notes processes Lotus Notes-to-webMethods transactions at run time as follows:

Step	Description
1	Data inside the Lotus Notes system is added, deleted, or modified, or another type of event occurs that triggers the shared agent for Lotus Notes-to-webMethods communications.
2	The shared agent connects to Integration Server.
3	One or more services execute based on the data sent by the shared agent.
4	Integration Server synchronously returns the result to the shared agent.

Using Version Control Systems to Manage Adapter Elements

The adapter supports the Version Control System (VCS) Integration feature provided by Designer. When you enable the feature in Integration Server, you can check adapter packages or elements into and out of your version control system from Designer. For more information about the VCS Integration feature, see the Configuring the VCS Integration Feature.

Beginning with Integration Server 8.2 SP3, the adapter supports the local service development feature in Designer. This feature extends the functionality of the VCS Integration feature to check package elements and their supporting files into and out of a VCS directly from Designer. For more information about local service development and how it compares to the VCS Integration feature, see the IBM webMethods Service Development Help.

Optimize Infrastructure Data Collector Support for IBM webMethods Adapter for Lotus Notes

Optimize Infrastructure Data Collector monitors the system and operational data associated with webMethods run-time components such as Integration Servers, Broker Servers, Brokers, and adapters, and reports the status of these components on Optimize for Infrastructure or other external tools. When you start monitoring an Integration Server, Infrastructure Data Collector automatically starts monitoring all ART-based adapters that are installed on Integration Server.

For information about monitored key performance indicators (KPIs) collected for the monitored adapter components, see the IBM webMethods Optimize User’s Guide and Administering IBM webMethods Optimize for your release.

Viewing the Adapter's Update Level

You can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the adapter's About page in the Integration Server Administrator.

Controlling Pagination

About this task

When using the adapter on Integration Server 8.0 and later, you can control the number of items that are displayed on the adapter Connections screen and Notifications screen. By default, 10 items are displayed per page. Click Next and Previous to move through the pages, or click a page number to go directly to a page.

To change the number of items displayed per page, set the watt.art.page.size property and specify a different number of items.

To set the number of items per page

Procedure

From Integration Server Administrator, click Settings > Extended.
Click Edit Extended Settings. In the Extended Settings editor, add or update the watt.art.page.size property to specify the preferred number of items to display per page. For example, to display 50 items per page, specify:
```
watt.art.page.size=50
```
Click Save Changes. The property appears in the Extended Settings list.
For more information about working with extended configuration settings, see the IBM webMethods Integration Server Administrator’s Guide for your release.