In this article, you learn about a new Web service called the Free Time Web service in IBM Lotus Domino V7. You see how this service is implemented in Lotus Domino and how Lotus Domino and Java developers can use it to get information about the calendar availability of both people and resources.

The new Free Time Web service consists of two parts: a Lotus Domino V7 server task called WSCONN and a Lotus Domino V7 database containing the Web service. You can download the task program and the database from IBM Passport Advantage. When searching in IBM Passport Advantage, search on either part number C8525NA or on the text string "Free Time Web Service." A database with the Web service only is available from the Download section of this article.

The WSCONN server task

The WSCONN server task is responsible for making a Web service request to the Free Time Web service on another Lotus Domino V7 server. When an IBM Lotus Notes client searches for people's or resources' calendar availability, the Lotus Domino V7 server performs a free-time lookup for those meeting attendees. If an attendee whose name is an Internet email address is in the same Lotus Domino domain as the server, the server obtains the attendee's free-time information from the Free Time database (busytime.nsf). If the attendee isn't in the local Lotus Domino Directory, the server sends a Web service request to another Lotus Domino V7 server using WSCONN as a gateway. WSCONN makes a request to the Web service using a URL defined in the Notes.ini variable WSCALCONN_URL. The URL, which points to a remote Lotus Domino V7 server, looks like this: http://host/busytimews.nsf/busytimelookup?OpenWebService.

You can load the WSCONN task from the Lotus Domino server console using the command LOAD WSCONN. To automatically run the WSCONN task at server startup, add WSCONN to the Notes.ini variable ServerTasks.

NOTE: For this remote search functionality to work, you must use a person name formatted as an Internet email address. If your organization has several Lotus Domino domains, you can easily test this functionality. In the other domain’s Lotus Domino Directory, copy a person's email address to the clipboard. Then, open your calendar and paste the email address into the Invitees field of a new calendar reservation. Click Scheduler to see the calendar availability of the people you've invited. The email address entry is populated with that person's calendar bookings, as shown in figure 1, thanks to a Web service lookup that the Lotus Domino V7 server performed.

Here, you can see the result of a Web service lookup in the standard Lotus Notes mail database. A Lotus Notes user has created a new meeting invitation for two people. The first person is Mary Poppins; the other is Peter Pan. Mary Poppins is a Lotus Notes user in the same domain as the mail file's owner, and her name appears in abbreviated Lotus Notes format. Peter Pan's calendar resides on a remote server and is not directly accessible to the current user. Peter Pan's name is entered as an Internet email address, which tells the server to use the WSCONN task to get the calendar availability information from a remote server through a Web service call. In the visual scheduler, both people's calendar availability is displayed, and the user who created the invitation sees no difference between results from a native Lotus Notes free-time lookup and a Web service lookup.

It is possible in the WSCALCONN_URL variable to specify a URL pointing to any Web host; theoretically, it should be possible to make a free-time request to a non-Lotus Domino V7 server, such as Apache Tomcat, IBM WebSphere Application Server, and Microsoft Internet Information Services. That server can find calendar information in its own calendar application and format the response according to the data types that the Lotus Domino server expects. In this way, it is possible to integrate live calendar lookupsseamlessly between two completely different systems.

Back to top

The busytimews.nsf database

Another part of the Free Time Web service is the Lotus Domino database busytimews.nsf. The database contains no documents, and the only design element in the database is a Web service called BusyTimeLookup. The LotusScript source code of the Web service isn't hidden, and you can examine how it works. You can also create a copy of this Web service and modify it according to your needs. (Later in this article, you see how to create a simplified version of the service.) The Web service itself doesn't depend on the WSCONN task; you can make a call to the Web service from a consumer client without having the WSCONN task running.

Because the Web service resides inside a regular Lotus Domino database, usual Lotus Domino access control list (ACL) security applies for access to the Web service. To limit access to the Web service, you can modify the ACL of the busytimews.nsf database to disallow access to Default and Anonymous users and grant Reader-level access to people who are allowed to use the Web service. To let another Lotus Domino V7 server access the Web service through the WSCONN task, create a new Web user and assign that user an HTTP password. Then, you can put those login credentials into the WSCALCONN_URL variable in the Notes.ini file:

WSCALCONN_URL=
http://username:password@host/busytimews.nsf/busytimelookup?OpenWebService

You can add another level of security by using Secure Sockets Layer (SSL) to encrypt the communication between the server and the client.

To obtain the Web Services Description Language (WSDL) definition of the Free Time Web service, use the URL http://host/busytimews.nsf/busytimelookup?WSDL. (We use this WSDL URL in the Java and Microsoft SOAP -- MSSOAP -- consumer client examples.)

Another database containing a similar Free Time Web service is cppfbws.nsf; you can use this database instead of busytimews.nsf to provide free time lookup to Lotus Notes and Web clients. The difference between the two databases is that the data structure returned by the Web service in cppfbws.nsf is slightly different from that returned by the Web service in busytimews.nsf. The design of the cppfbws.nsf database and the source code of the Web service are hidden. If you want to use this database instead of busytimews.nsf, change the WSCALCONN_URL variable in Notes.ini file to the following:

WSCALCONN_URL= http://host/cppfbws.nsf/busytimelookup?OpenWebService

Back to top

Accessing the Free Time Web service

The LotusScript code of the Web service is rather simple. When the Web service receives a request, it uses the FreeTimeSearch function to obtain the busy periods for the requested names within the specified time. You can use the same function to determine the availability of rooms and resources as well.

You can access the Free Time Web service using different kinds of Web service consumer clients, such as Apache Axis, Microsoft .NET, and MSSOAP. These service consumer clients must have support for complex data types for sending and receiving data. For the consumer client example in this article, we use the Axis Java classes, which are included with Lotus Domino V7 and Lotus Notes V7. To make the creation of required Java classes as easy as possible, we use an open source Lotus Domino-based tool called Stubby, which was created by Julian Robichaux and is available for download from the OpenNTF Web site.

Many older Web service consumer clients can have problems parsing the complex data types returned as a result of a call to the Free Time Web service. Because the source code of the Web service is open, you can modify the Web service's LotusScript code to accept and return simple data types, such as text strings. This makes the Web service easily accessible from basically all consumer clients, especially from those that make dynamically created calls using WSDL.

Let's get into the examples of a Java agent and a LotusScript agent, respectively, that are programmed to access the Free Time Web service.

Calling the Web service from a Java agent

With the help of the Stubby database, you can quickly create stub files containing all the functionality required to call a particular Web service. All you need to know is the location of the Web service's WSDL file; Stubby does the rest automatically. The tool generates Java files, class files, and a JAR file. You can then detach the generated JAR file to your local hard disk and import it into your Java agent with the help of the Edit Project button in the agent’s design panel. You don't need to import any other libraries into the Java agent to enable the agent to call the specified Web service. If you need more information about the methods, parameters, and data types of the Web service, you can find it in the generated Java source files.

Stubby also has support for authentication using either user name/password or single sign-on (SSO) tokens. A solution for accessing SSL-protected URLs is also available. Using SSL greatly improves the security of the Web service because it encrypts the incoming requests and outgoing responses, rendering them unreadable for observers who might have gained access to monitor network traffic between the client and the Web server. The encryption also protects your login credentials, which are passed as a part of the request.

After including BusytimeService.jar in the Java agent, you can write code to call the LOOKUP method of the Web service. The parameter you send to the Web service is a complex data type called REQUESTSTRUCTURE, which consists of several arrays. The returned data type is called RESPONSESTRUCTURE, which contains nested arrays.

You can also place the same Java code in a Java script library design element and use it from a LotusScript agent through LotusScript to Java (LS2J). Listing 1 shows the agent source code.

import lotus.domino.*;
import DefaultNamespace.*;
public class JavaAgent extends AgentBase {
 public void NotesMain() {
  try {
   String[] attendees = new String[2];
   String[] requestors = new String[1];
   String[] details = new String[1];
	
   attendees[0]="Peter Pan"; //name of the first person
   attendees[1]="Mary Poppins"; //name of the second person		
   requestors[0]="";   //Web service does not require this parameter
   details[0]="";   //Web service does not require this parameter

   BusytimeServiceLocator locator = new BusytimeServiceLocator();
   Busytime service = locator.getDomino();

   DefaultNamespace.REQUESTSTRUCTURE REQUEST=new DefaultNamespace.REQUESTSTRUCTURE();
   REQUEST.setATTENDEES(attendees);
   REQUEST.setDETAILS(details);
   REQUEST.setREQUESTORS(requestors);
   REQUEST.setSTART("2007-02-26 01:01");  //Start time for search
   REQUEST.setEND("2007-02-26 22:01");   //End time for search
			
   DefaultNamespace.RESPONSESTRUCTURE respstr=service.LOOKUP(REQUEST);

   DefaultNamespace.RESPONSE[] resp=respstr.getATTENDEES();
   for(int x=0;x<resp.length;x++){
    System.out.println("\nPerson: "+resp[x].getATTENDEE());
    DefaultNamespace.INTERVAL[] interval=resp[x].getBUSY();
    System.out.println("Found busy periods: "+String.valueOf(interval.length));
    for(int i=0;i<interval.length;i++){
     System.out.println("-----------------------------------");
     System.out.println("**** Busy interval "+String.valueOf(i+1)+" ****");
     System.out.println("Start: "+interval[i].getSTART());
     System.out.println("End: "+interval[i].getEND());
    }
   }			
  } catch(Exception e) {
    e.printStackTrace();
  }
 }
}

Figure 2 shows the output from the Java agent.

In the agent’s output, you see booked calendar times and times when the person is not available, which are determined by the person’s calendar scheduling preferences.

If you look at the agent code, you see that the data received from the call is nested in several levels of arrays. RESPONSESTRUCTURE contains an array of RESPONSE type, which you access through the getATTENDEES() function. Each RESPONSE contains the name of a person, accessible through the getATTENDEE() function, and an array of time intervals, accessible through the getBUSY() function. Each INTERVAL contains a start time and an end time, which you access using the getSTART() and getEND() functions. The INTERVAL data type contains the DETAIL data type, which is currently not used but is planned to have information about location, room, subject, and chairperson. As long as you know what the structure of the returned data types looks like, enumerating them is typically easy.

Making modifications to the Web service

Now, let's look at how you can modify the Web service to work with an MSSOAP client. You can call the MSSOAP consumer object from LotusScript code; the call is executed quickly, which makes it a good choice for using it from a Lotus Notes client.

The modified Web service accepts three parameters:

• Name of the person
• Start of the time period
• End of the time period

Calling this Web service results in a single string in which the values are separated by semicolons. In the LotusScript consumer agent, you can easily convert this semicolon-separated string into an array by applying the Split() function to the string.

The difference between this modified Web service and the original Web service is that this one returns time periods during which the person is available for bookings; the original Web service returns times during which the person is not available for bookings. Another difference is that the original Web service converts the time to the GMT date format, while the modified Web service keeps the time in the same time zone format in which the user created it.

Listing 2 shows the code for the simplified Web service.

Class busytime
Function lookup(attendeename As String, PeriodStartTime As String, 
PeriodEndTime As String) As String
 On Error Resume Next 'required to handle non-existing names
 Dim session As New NotesSession
 Dim timewindow As NotesDateRange
 Dim startDateTime As New NotesDateTime(PeriodStartTime)
 Dim endDateTime As New NotesDateTime(PeriodEndTime)
 Dim busyTime As Variant
 		
 Set timewindow = session.CreateDateRange()
 Set  timewindow.StartDateTime = startDateTime
 Set  timewindow.EndDateTime = endDateTime
 busyTime = session.FreeTimeSearch ( timewindow, 5, attendeename, False)
 If (busyTime(0) Is Nothing) Then
  tmp="No Match Found"
 Else
  Forall x In busyTime 'loop through all free time periods
   tmp=tmp+ x.Text+";" 'concatenate times into a single string
  End Forall
 End If
 lookup=tmp
End Function
End Class

The code of this Web service is obviously much shorter than the original, but it provides basically the same functionality.

Calling the modified Web service from LotusScript using MSSOAP

With simple data types, it's easy to access the Web service and pass parameters to it. The modified Web service accepts three string parameters and returns a text string. You split the returned string into an array using semicolons as separators between the time periods, as shown in Listing 3.

Sub Initialize
 Dim intervals As Variant

'Specify the location of the service's WSDL file
sWSDL = "http://host/busytimews.nsf/BusyTimeLookupSimple?wsdl"

'Create a new MSSOAP client object 
Set Client =CreateObject("MSSOAP.SoapClient")

'Initialize connection to the WSDL file and get WSDL structure
Call Client.mssoapinit (sWSDL)

'Call Lookup function provided by the Web service 
wsresult = Client.lookup("Peter Pan", "2007-02-26 00:01", "2007-02-26 23:59")

'Split the semicolon-concatenated string to get all individual values	
intervals = Split(wsresult, ";")

Forall v In intervals 'loop through results
 If v<>"" Then
  cnt=cnt+1
  tmp=tmp+ "Busy Period "+Cstr(cnt)+": "+v+Chr(10)
 End If
End Forall

Messagebox tmp, MB_OK, "Result"
End Sub

Figure 3 shows the output from the agent.

With just 13 lines of LotusScript code, you've created a consumer client for your Web service. You can also use the Stubby database to generate stub files and call this modified Web service from Java agents.

Back to top

Conclusion

You can integrate calendar availability for people and resources into Lotus Domino V7 and other software with the help of Web services. And when required, you can modify the Web service to avoid complex data types. By taking advantage of the automated generation of required Java files in Stubby and other tools (such as WSDL2Java), you can save several hours of your valuable time.

Back to top

Download

Information about download methods

Resources

Learn

• Read "Consuming Web services from a Lotus Domino Java agent" (developerWorks, August 2006) for more information about creating Web services consumers.
  
  
• See "Writing complex Web services" (developerWorks, November 2006) for information about advanced Lotus Domino Web services techniques.
  
  
• Read "Lotus Notes/Domino V7 Web Services" (developerWorks, September 2004) for information about Web services design elements.
  
  
• Read the developerWorks Lotus article, "Practical Web services in IBM Lotus Domino 7: What are Web services and why are they important?".
  
  
• Read the developerWorks Lotus article, "Practical Web services in IBM Lotus Domino 7: Writing and testing simple Web services".
  
  
• Read the developerWorks Lotus article, "Practical Web services in IBM Lotus Domino 7: Writing complex Web services".
  
  

Get products and technologies

• Download the trial version of the IBM Lotus Notes client software.
  
  
• Download the Stubby database.
  
  
• Download a free trial version of IBM Lotus Domino V7.
  
  
• Download the Free Time Web service database from Passport Advantage.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The WSCONN server task
• The busytimews.nsf database
• Accessing the Free Time Web service
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Notes and Domino Administrator
• Demo: Lotus Notes 8 composite applications
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Notes and Domino Administrator

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers