It makes sense to have solutions in which Lotus Domino and SAP Enterprise are connected and work together. When these two powerful systems are linked, it can help:

• Provide your Lotus Domino user community with easy access to data stored in SAP.
• Reduce data errors (thus increasing user satisfaction).
• Provide greater process status information, which also increases user satisfaction.
• Reduce the headcount needed to maintain your internal processes.
• Reduce associated training costs.

This article describes the powerful tools available from IBM Software Group's Lotus Enterprise Integrator (LEI) team that will allow you to realize these very worthwhile goals. We then take you through the building of a sample Employee Self Service solution using these tools. The tools that we describe include Lotus Enterprise Integrator (LEI), Domino Enterprise Connection Services, Lotus Connectors LotusScript Extension, and Lotus Connector for SAP R/3 with MTA and Workflow. Familiarity with Lotus Notes/Domino, LEI, and SAP will help you understand some of the features and concepts we discuss in this article.

Lotus Enterprise Integrator (LEI)

Getting data from point A to point B (and sometimes back again) is what Lotus Enterprise Integrator (LEI) is all about. It is built upon the Lotus Connectors, which provide access to different enterprise systems. The current list of connectors includes DB2, File, Lotus Notes, Oracle, ODBC, OLEDB, Sybase, and Text. These connectors all are part of the standard LEI product. In addition, you can purchase an SAP connector separately.

LEI provides both Data Management and Advanced Realtime activities. The Data Management activities, listed below, control what a given connector is doing at any point in time:

• Archive. Reads data from connector A, writes it to connector B, and then deletes it from connector A.
• Command. Executes operating system, database, or SQL commands.
• Direct Transfer. Reads data from connector A and writes it to connector B. This is the most widely used of all activities in LEI. It can be used for data migration, regular downloads, regular uploads, or a thousand other reasons.
• Java. Executes Java applications.
• Polling. Watches for a specified condition to be true, and when it is, triggers another activity.
• Replication. This comes in two variants: either makes connector B data look like connector A data or makes A and B data the same.
• Scripted. Executes agents without the Domino agent manager handling things. Scripts get their own process to run in, so they run faster and on your schedule, not the agent manager's schedule.

Each of these activities comes with various scheduling possibilities, many activity specific options, and the ability to launch dependent activities. Each connector can exchange data with any other connector. But the best part is this: When you use LEI activities, you fill out forms (no need to write script!) in the LEI administration database. These are standard Domino forms. In them, you pick where you are reading from or writing to, and you map the fields found in the metadata from one connection to the fields of the metadata of the other connection.

Metadata includes:

• Tables or views in a relational database management system (RDBMS). The tables may exist in the RDBMS itself, or they may be dynamically created and returned from a stored procedure.
• Domino forms in Lotus Domino.
• Tables in SAP. These are the tables used by Remote Function Calls (RFCs), Business Object Application Programmer's Interface (BAPIs), or Transactions (Batch Input Mode).

The Advanced Realtime activities, available in LEI 6 and later, are:

• Virtual Fields (formerly known in LEI 3.x as Realtime). With this activity, you can front end enterprise data in your Domino applications without having to copy the data over. The data is fetched or changed in real time. Only the keys from your enterprise data are stored in Notes documents. The cool thing here is that the user, whether human or machine, has no idea. When he opens his Notes document, it has all of its fields filled out (not just the keys). It is all done in real time!
• Virtual Documents. This is Virtual Fields taken to the next level. Now there are no more Notes documents holding key values. Everything is virtual. The views are filled out, the documents work in the views as you would expect, but nothing is really there. By adding control fields to the RDBMS tables to hold Domino-specific note information, there is no need to store anything in Lotus Domino, except the summary information displayed in a given view.
• Virtual Attachments. Attachments saved in documents being "watched" by Virtual Fields or Virtual Documents activities can now be stored in your RDBMS system, and not the Domino database. This makes them available (in read-only mode) to other RDBMS applications and keeps the NSF file from exploding in size.
• Virtual Agents. Your RDBMS stored procedures are now available to you in any place that an agent was before. They can operate on a single document or a selection of them. They will pass fields from your document to the input parameters of the stored procedures, allowing the procedures to do whatever you have designed them to do with the data.

So whether you want Data Management or Advanced Realtime activities, the Lotus Enterprise Integrator can handle many of these tasks for you. Figure 1 shows the LEI Administration database, where connections and activities are defined, and the execution of activities is controlled.

Back to top

Domino Enterprise Connection Services (DECS)

The Virtual Fields activity (formerly known as Realtime) was so wildly successful that this one feature was copied from LEI and made into its own tool called Domino Enterprise Connection Services (DECS). DECS is a standard component of the Domino Enterprise Server. DECS for Lotus Domino 6 and later is not as full-featured as the Virtual Fields activity of LEI, but it still meets many customer needs. It does not support Virtual Attachments or Integrated Credentials.

Back to top

Lotus Connectors LotusScript Extension (LCLSX)

Ideally, you would be able to handle 100 percent of your integration needs with the functionality available in an LEI form, but that isn't always the case. Many times you need business logic to interpret or modify the data after it is read from one place, but before it arrives at another. Or maybe you need to call a number of SAP BAPIs in a certain order to perform one task. For example, before you can modify HR Master Data for a given employee in SAP, you must lock the employee, and then make the change. Then you unlock the employee. You must perform these three actions on a single connection to SAP. That is more dexterity than an LEI activity offers. In an LEI activity, you can only work with a single BAPI at a time. One option (and a very good option at that) is to have the SAP ABAP people create a wrapper BAPI that does the three actions you need in one step. But, if you can't have that, you can write LotusScript to achieve your needs.

It is exactly this example that we will shortly build. We will first build it with LotusScript. Then we will build it for the case in which our ABAP people did indeed write us a nifty wrapper to do the three steps all at once for us, allowing us to show how easy it can be to use LEI. But first, let's talk about the power of the LCLSX. The LCLSX is a traditional LotusScript extension designed specifically for working with enterprise systems. The object design is best suited for use with RDBMS connectors. The SAP Connector also works with it, but sometimes the RDBMS model shows through as we will see in our example.

LCLSX has two powerful abilities not available in any other LSX:

• Connection pooling. This allows connections, which are expensive time-wise, to be pooled and reused. This can improve performance and reduce activities (such as security logging on enterprise systems) that occur for each new connection. These connections are not bound by the scope of LotusScript. They are actually maintained at the process level. As long as your Domino server process or Notes client process is running, your pool exists.
• Array Read/Array Write. LotusScript is an interpreted language, which means that it runs more slowly than a compiled program. Let's imagine that we read from a DB2 table with 100,000 records, and for each record found, we write that data to a new Notes document. Doing this before LCLSX came along required a loop that was executed 100,000 times in LotusScript. LCLSX reads (in a single LotusScript step) records 1 through 1000 from the DB2 table, and in a single step, inserts these same records into our Domino database. We read an array of records and then write the array. Our LotusScript executes its loop 100 times, instead of 100,000 times. When considering performance, that is a very big gain when your compiled programs underneath do this repetitive work.

Back to top

Lotus Connector for SAP with MTA and Workflow

Lotus Connector for SAP with MTA and Workflow are three different products bundled into one. The most important component is the Lotus Connector for SAP. This connector, when used with LEI, DECS, and the LCLSX, allows you to access RFCs, BAPIs, and Transactions available in the SAP application server. You are not restricted to a single module because of the interface that SAP provides to connect to. It is a generic road, if you will, into all modules. These RFCs and BAPIs can read to or write from SAP. Transactions write to SAP, but can return status/simple information. There are many thousands of RFCs available in SAP, and even more Transactions. From our standpoint (that of a remote access programmatic connection), there is no difference between an RFC or a BAPI. All BAPIs are RFCs.

The next component is the Domino MTA for R/3, which provides a mail connection between Lotus Domino and SAP. It provides for your standard mail needs, such as delivery confirmations, return receipts, and other bells and whistles. This product has served many customers over the years.

The final component is Domino Access to SAP Business Workflow. This is an LCLSX application built with the SAP Connector. It lets you see your SAP workitems inside of your Notes Inbox. From there, you are a click away from starting a dialog instance of the SAPGUI to process a given workitem. The logon and opening of the workitem Inbox and executing the workitem are all done with one click. After you process the workitem, you return to your Notes client. It is a simple product, but when used in conjunction with the Domino MTA for R/3 or SMTP with SAP 4.7 Enterprise, gives you a universal Inbox. That is one place to look for Notes mail, Domino workflow, SAP mail, and SAP workflow.

For more information, including demos, customer stories, and white papers, check out the Lotus Enterprise Integration home page.

Back to top

The Employee Self Service application

Let's take a look at the interface with SAP, part of the example that we mentioned previously. We will show a piece of an Employee Self Service (ESS) application that allows Domino users, whether located locally or remotely, to use a Domino application to update their personal address information. That information is not stored in Lotus Domino. It is in SAP. Our goals are:

• No SAP training for our entire Domino user community because they never directly access SAP.
• No SAP user licenses for our Domino community because they never log on to SAP.
• Reduced headcount needed in HR because these requests no longer require a call to the HR call center.

Now let's set up the application. Assuming that you're on the Domino side of this equation, step one is to tell your SAP people that you need to know where to find data and how to use the different RFCs or BAPIs that will give you what you want. It is not realistic to expect that you know these answers, or that you can figure them out yourself. Only when the Domino side works with the SAP side is such a solution possible. After talking to the SAP people, you learn the following:

• You should read table PA0006 to get setup data needed to obtain current address data and also to update address data.
• When you want to update address information, you must first call BAPI_EMPLOYEET_ENQUEUE to lock the HR record for this employee.
• To update employee address information, you must call BAPI_ADDRESSEMP_CHANGE.
• After that call, you must call BAPI_EMPLOYEET_DEQUEUE to unlock the HR record for this employee.

Step 1 is an LEI step. Using the special RFC_READ_TABLE (a very commonly used RFC in SAP), you can read the tables in SAP. Normally, RFC_READ_TABLE returns a table with all the columns that you want to fetch printed to a string. It would be your job to parse them and convert them to their original data types. Fortunately, the SAP connector will do this for you.

Start by defining a connection to SAP that will make RFC_READ_TABLE available.

Here you see all of the connection information needed to reach SAP, plus the name of the RFC that you want to access, namely RFC_READ_TABLE. You see here that PA0006 has been concatenated onto the end of RFC_READ_TABLE. This activates the feature in the SAP connector that will deliver the data in the format of table PA0006 to you, instead of the normal table DATA that RFC_READ_TABLE would deliver on its own.

Next, define a connection to your Notes database that will be your front end to your Notes user community. It could look like figure 3.

It only needs to contain your Domino server name and the database file name for this example. One of the rapid application development (RAD) options available here can be found under the Data Creation tab.

The Create Database option tells LEI to create the database for you if it doesn't exist. It won't be a pretty database (unless you define a template to use), but it will serve as the place for LEI to do future design work and to place data.

Next, you need an LEI activity. To make this example as easy as possible, use a Direct Transfer activity. In a real-world solution, you would probably opt for the Replication Activity, as it is very well suited to keeping your application stocked with SAP data over time.

This activity has SAP as its source and Lotus Notes as its target. You will read from SAP table PA0006 and write to form Employee in the Domino database. The first time that you run this, your Domino database will not exist. This means that you will have to tell the activity what the name of the Domino form should be. You will also need to fill out the Target Field(s) values yourself because they don't exist yet. You can either select automatic field mapping, which will create fields with exactly the same name as they are delivered from SAP, or you can enter field names manually.

The Select Statement field is holding a special format that only works for the SAP Connector. Details of the full "grammar" that defines what is allowed are covered in the SAP Connector documentation. Here you define an input table for RFC_READ_TABLE. The format for this is the table name, then a row number, and finally which field you want to provide an input value for. In this example, input table FIELDS is what you are writing to. Start with row 1 and write a value to field FIELDNAME. You must tell RFC_READ_TABLE which fields from table PA0006 that you want data from, and by filling out input table FIELDS, you can do this.

Under Target Data Options, select Create Target Metadata. In this example, LEI creates your Employee form for you, if it doesn't already exist. It will not be pretty, but the fields mapped in the activity will be correctly defined. This is more LEI RAD.

It is useful to understand this data that will be read in from SAP. The address parts are clear enough. It is the last three fields that need further explanation. BEGDA is Begin Date. This is the date that the address became valid. ENDDA is End Date. This is when it became/will become no longer valid. Most times, when an address is valid, SAP will hold a value of 12/31/9999 here. SUBTY is Subtype. This is a code that tells you which type of address that this is because SAP can store more than one current address for a given employee. This code means nothing to your users, so you can add a little computed field to your Domino form that turns the SAP codes into human text.

You can now go ahead and have LEI run this activity. This example enhances the Domino form a bit. A sample Notes document created from this activity would be similar to figure 6.

Field Address Type is actually computed, based on the value of SUBTY, which is hidden. Here is the formula:

@If(SUBTY="1";"Permanent Residence";"Temporary Residence")

So now you have SAP data in Lotus Domino. The goal is to let an employee modify this data, and then send those changes to SAP. To keep this example simple, assume that you have built a security schema in this Domino database, such that an employee can only edit her own address data.

One easy way to handle updates is to have a field appear in a given Notes document that can only be there if a user has edited the document via the form. For example, add field HASBEENCHANGED to your Employee form and give it a default value of 1. Whenever users edit their address documents, this field will appear. You can then, when it is time to send data to SAP, search only for documents that have the field HASBEENCHANGED with a value of 1.

Earlier, we mentioned that to be allowed to change employee address data, you must first lock the employee record, make the changes, and finally unlock the record. You need three RFCs all on the same connection to do this. Right now, that means you need a script. This example script does not account for everything that may go wrong here. It has just the minimum needed to make this example work. You can see the entire script in this sidefile.

This agent can be scheduled to run in a number of ways. You need to be sure that it runs every 60 minutes at exactly 20 minutes past the hour, so schedule it with an LEI Scripted Activity. Doing so will take the "first in first out" queue behavior of the Domino agent manager out of the picture.

We admit this was doing it the hard way. You need to write a script because you need three BAPIs called on a single connection for each address change. The easy way would have been to ask your SAP people to create a wrapper BAPI that would call all three needed BAPIs for you. This wrapper would need to have an interface that would let you send everything needed to drive all three BAPIs.

The end solution would be a wrapper with exactly the same interface as BAPI_ADDRESSEMP_CHANGE. How would it work? First, it would call BAPI_EMPLOYEET_ENQUEUE. To get the VALIDITYBEGIN date needed by this BAPI, it would just use today's date. SAP knows what today's date is, so you wouldn't have to pass that in. Next, your wrapper would call BAPI_ADDRESSEMP_CHANGE, and finally it would call BAPI_EMPLOYEET_DEQUEUE.

Call your wrapper Z_BAPI_ADDRESSEMP_CHANGE. To use this wrapper BAPI, first reuse your existing Notes connection document. However, you need a new SAP connection document to this new BAPI. It could look like figure 7.

Now all you need is a new LEI Direct Transfer Activity that uses this connection.

You can see here that you read from Notes all documents of form Employee with field HASBEENCHANGED="1". The fields in those documents are then sent to Z_BAPI_ADDRESSEMP_CHANGE.

To verify that you were successful, use the output parameter feature of the Direct Transfer activity.

Check the option "Target Metadata is Stored Procedure" and then "Accept Output Parameters into Source." The same field ERRORTEXT that you used in the script version of this example will hold text messages directly delivered from SAP if there is a problem.

To make this perfect, delete the field HASBEENCHANGED from your source documents. A good way to do this is with a script, which would be run as a Dependent Activity of this activity. This means that after this activity is done, it would launch your cleanup script. Your script could also send the employee a status email indicating success or failure and if failure, the ERRORTEXT message as well.

Back to top

Summary

In this article, we built an application that reads data out of SAP and places it into a Domino database. This database can then be used/replicated all over the world. Our Notes users can then locally change their addresses, using Lotus Notes and Domino. They need no SAP training to do this or even network connectivity to SAP. Nor do they need an SAP account. And they need no extra workstation software installed to do this. These changes then replicate back to the Domino server that LEI is watching, and the LEI activity sends the changes to SAP. After it does that, a cleanup script sends status info to the employee.

We hope that you now have some food for thought on how Lotus Domino and SAP together can be a really good combination that can save you some time and money. Many IBM and SAP customers of all sizes have benefited from these products, and the solutions cover every single module available from SAP.

One last word: we recommend checking out the developerWorks: Lotus Enterprise Integration forum. It has many questions and answers from issues encountered by the LEI user community and is a great source of information.

Resources

• See the entire script for the example used in this article in this sidefile.
  
  
• For more information about LEI, including demos, customer stories and white papers, check out the Lotus Enterprise Integration home page.
  
  
• Find out more about SAP by visiting the SAP Enterprise home page.
  
  
• See the product documentation for detailed information about how to work with the Lotus Connector for SAP.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Lotus Enterprise Integrator (LEI)
• Domino Enterprise Connection Services (DECS)
• Lotus Connectors LotusScript Extension (LCLSX)
• Lotus Connector for SAP with MTA and Workflow
• The Employee Self Service application
• Summary
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers