Integrating IBM Lotus Forms with IBM Lotus Domino

IBM® Lotus® Forms and IBM Lotus Domino® servers complement each other. Integrating these two products can yield a varied list of features for better application architecture. This article explains the various ways that you can integrate Lotus Forms with Lotus Domino and details the benefits that this integration brings.

Josephine E. Justin, Senior IT Specialist, IBM

Josephine E. Justin is working with IBM India Software Labs as a Senior IT Specialist. She has been working in the industry for more than eight years and was involved in projects for major clients all around the world. Her skills and interests include WebSphere Portal Server, Web content management systems, WebSphere Portlet Factory, WebSphere Dashboard Framework, Lotus Quickr, Lotus Forms, Lotus Mashups, and Java Platform, Enterprise Edition development. You can reach Josephine at jojustin@in.ibm.com



Abhishek Jain (abhi.jain@in.ibm.com), Technical Consultant, IBM

Abhishek Jain has worked with IBM India Software Labs since 2004 and has been in the industry for more then seven years. He is currently working as a Technical Consultant with IBM Lotus Lab Services and has skills in various Lotus technologies, namely Lotus Domino, Lotus Sametime, Lotus Quickr, and Lotus Connections. He has considerable experience with Lotus and Java and Java Platform, Enterprise Edition technologies and is certified in both of them. You can reach Abhishek at abhi.jain@in.ibm.com.



Rajaguru Balagurusamy (rajaguru.rajam@in.ibm.com), IT Specialist, IBM

Rajaguru Balagurusamy is an IT Specialist with IBM India Software Labs. He specializes in IBM WebSphere Portal, IBM Lotus Forms, IBM WebSphere Portlet Factory, and Java Platform, Enterprise Edition. Rajaguru is certified in IBM WebSphere Portal Development. You can reach Rajaguru at rajaguru.rajam@in.ibm.com.



Vinodh R. Mahendrakumar (vinmahen@in.ibm.com), IT Specialist, IBM

Vinodh Mahendrakumar is currently working as an IT Specialist for IBM Lotus and has been working with the Services team of IBM, at the India Software Labs. He has been involved in developing WebSphere Portal, IBM Lotus Quickr (Java Platform, Enterprise Edition), and Lotus Web Content Management sites. You can reach Vinodh at vinmahen@in.ibm.com.



29 June 2009 (First published 16 June 2009)

Also available in Chinese Russian Spanish

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

Lotus Domino and Lotus Forms integrate seamlessly to provide a varied list of features, particularly in providing replication and offline capabilities. This integration provides a solution that can be deployed in a distributed environment.

This article details different integration layers and the benefits of integration. This article also shows how integration can be achieved and explains a sample procurement process. This solution involves the deployment of Lotus Domino 8.0.2 and Lotus Forms Server 3.5.


Overview of Lotus Forms and Lotus Domino integration

Integrating Lotus Forms and Lotus Domino can be done at various levels of the application. The options available for this integration include the following:

  • User interface (UI) level integration. UI integration can be done through the browser or the Lotus Forms Viewer. Users can access a form using the Lotus Forms Viewer as a standalone client or as a plug-in through a Web browser. Users can also access a form without any additional client software through a Web browser by relying on the Lotus WebForm server.
  • Data level integration. Data integration can be done using a Lotus Domino agent or a servlet or a portlet. This integration can be done using the Lotus Forms API and the Lotus Domino API. It can also be done by directly consuming Domino XML (DXL) or by using the XForms model instance. Web service integration provides an excellent way of integrating these two products.
  • Process level integration. Lotus Domino helps in defining workflow, which can be utilized by Lotus Forms through Web service calls.

Figure 1 provides an overview of the different integration options between Lotus Forms and Lotus Domino.

Figure 1. Integration architecture
Integration architecture

Integration scenario

This section describes the sample procurement scenario covered in this article.

This system comprises logically independent approval and procurement cycles for business needs, segregated on the basis of approval rights, authorization, and budget. Two levels of organizational hierarchy are covered in this sample. LevelOne is the lower level, and LevelTwo is the upper level.

The actors involved are these:

  • Initiator. Specific role defined at LevelOne to create requests.
  • L1Approver1. First approver at LevelOne.
  • L1Approver2. Second approver at LevelOne.
  • L1 Approver3. Third approver at LevelOne.
  • L1Approver4. Fourth approver at LevelOne (special approver).
  • L1Approver5. Fifth approver at LevelOne.
  • L2Approver1. First approver at LevelTwo.
  • L2Approver2. Second approver at LevelTwo.
  • L2Approver3. Third approver at LevelTwo.
  • L2Approver4. Fourth approver at LevelTwo (special approver).
  • L2Approver5. Fifth approver at LevelTwo.

Figure 2 illustrates the process workflow.

Figure 2. Workflow
Workflow

Setting up the environments

This section explains the development and server environments used to develop and deploy the procurement process.

Table 1 lists the server-side components used in this integration.

Table 1. Server components
Component / server namePurpose
Lotus Domino 8.0.2This component is used for authentication, authorization, form storage. and workflow.
Lotus Forms Server 3.5WebForm server component of Lotus Forms Server is used to provide zero-footprint display of the e-form to the browser. The Lotus Forms Server API component provides a set of APIs to process the form values including signature validation.
IBM WebSphere® Application Server 6.1This component is used as a base for the Lotus Forms Server installation.
Certificate serverThis component is an optional setup if distribution of digital certificates is required.

Table 2 lists the development tools used in this integration.

Table 2. Development tools
Component namePurpose
Lotus Domino administratorUsed to administer and configure Lotus Domino.
IBM Lotus Domino DesignerUsed to develop the Lotus Domino application.
Lotus Forms DesignerUsed to design e-forms.
IBM Rational® Application Developer Used to develop e-forms-based Web applications using the Lotus Forms API.

Table 3 lists the client components used in this integration.

Table 3. Client tools
Component namePurpose
IBM Lotus Notes®Used for database management.
Lotus Forms ViewerUsed to view e-forms.
Web browserUsed to view zero-footprint e-forms and the procurement application.

Setting up the server components

Follow these steps to install Lotus Domino and Lotus Forms Server components:

  1. Install Lotus Domino Enterprise Server 8.0.2 on server node 1.

    Refer to the installation steps.

  2. Install WebSphere Application Server V 6.1 on server node 2. This installation is the base for the Lotus Forms Server components.

    Refer to the installation steps.

  3. Install the Lotus Forms API on the server node 2.

    Refer to the installation steps.

  4. Install Lotus WebForm server on the server node 2.

    Refer to the installation steps.

Follow these steps to create a WebSphere LTPA token:

  1. On the WebSphere Application Server, start the administrative console and log in.
  2. Select Security - Secure administration, applications, and infrastructure.
  3. Select the Authentication mechanisms and expiration option as shown in figure 3.

    Figure 3. Choosing the authentication mechanism
    Choosing the authentication mechanism
  4. In the Cross-cell single sign-on section, enter a password in the Password field and enter the path and file name in the Key File Name field.

    NOTE: Make note of the password; you need it during the next single sign-on (SSO) task when the LTPA key is imported into the Lotus Domino server.

  5. Click the Export Keys button. A success message for file saving displays.
  6. Log out from the administrative console. Copy the key file to a location that is accessible to the Lotus Domino server.

To import the WebSphere LTPA token into Lotus Domino, follow these steps:

  1. On the Lotus Domino server, start the Lotus Domino administration client, and open the Domino Directory (names.nsf) database.
  2. Change to the Clusters - Servers view.
  3. Click Web, and then select the option Create Web SSO Configuration.
  4. Type the domain suffix in the DNS Domain field. This suffix should match the domain name that you entered in the WebSphere Application Server.

    NOTE: The domain suffix is the end of domain name, including the period. For example, the domain suffix of region.country.com is .com.

  5. Add the Lotus Domino hierarchical names of the Lotus Domino servers that will participate in the SSO domain in the Domino Server Names field. See figure 4.

    NOTE: There is no need to enter the name of the WebSphere Application Server.

    Figure 4. DNS Domain and Domino Server Names fields
    DNS Domain and Domino Server Names fields
  6. Click Keys, and then select the Import WebSphere LTPA keys option. Click OK.
  7. Enter the path and name of LTPA key file, and then click OK.
  8. Enter the password for the LTPA key, and then click OK.
  9. A message displays that states that the key import is successful as shown in figure 5. Click OK.

    Figure 5. Successfully imported LTPA configurations
    Successfully imported LTPA configurations
  10. Click the Save button and then the Close button.

Digital certificate server setup

The digital certificate server can be set up to circulate digital certificates to users. Refer to http://www.ibm.com/developerworks/lotus/library/forms-signatures/ for setting up the digital certificate servers.


Development environment setup

The steps outlined in this section help you set up the development environment of Lotus Domino and Lotus Forms applications. The project interchange files are provided in the Download section of this article.

To set up the Lotus Domino development environment, follow these steps:

  1. Copy the NSF files from the Download section to the data folder of your Lotus Domino server.
  2. Sign the databases using the ID of the Lotus Domino administrator.
  3. Update the access control list (ACL) of the database DomForInt.nsf to prevent Anonymous access and to grant appropriate roles to the users.
  4. Assign the Admin role to the Lotus Domino administrator to cover all the administration tasks, and assign the Initiator role to any users or groups that initiate the request.
  5. The login page shown in the section that follows, comes from the Web configuration database domcfg.nsf, which is included in the Download section. If you already have this database configured on your server, the application uses the login page of your environment.
  6. Enter the URL http://<server name>/domforint.nsf to access the application UI and to log in using the administrator ID.

The Forms link in the left panel, shown in figure 6, enables the administrator to upload the forms template.

Figure 6. Forms template upload
Forms template upload

The Notifications link enables the administrator to upload notifications that are displayed on the home page of all users.

By selecting the Profiles option, the administrator can define the workflow as shown in figure 7.

Figure 7. Profiles page
Profiles page

The Configuration section, shown in figure 8, allows the administrator to control the Lotus Forms application servlet URL.

Figure 8. Application Configuration section
Application Configuration section

Rational Application Developer is used to develop the Lotus Forms servlet application. Follow these steps to set up the development environment, using the WAR file provided in the Download section of this article.

  1. Import the WAR file into the Rational Application Developer workspace. If the workspace is not created already, create a new workspace.
  2. Select File - Import.
  3. In the Import window that displays, select Web, and then select WAR file.
  4. Click Next to launch the WAR Import wizard.
  5. Click Browse to select the WAR file to import.
  6. After you have selected the file, click Open.
  7. Click Next to launch the WAR Import: Web Libraries wizard.
  8. Click Finish to import the WAR file.
  9. After the file is imported and expanded, Rational Application Developer Enterprise Explorer displays the servlet named FormViewServlet and the JSP files, hidden.jsp and thank.jsp, used in this sample as shown in figure 9.

    Figure 9. Rational Application Developer Enterprise Explorer
    Rational Application Developer Enterprise Explorer
  10. To set the Lotus Domino Web service URL in the servlet according to your environment, change the webserviceURL string in the FormViewServlet.java file appropriately.
  11. To set the translator URL when using a zero-footprint solution, change the value of the init parameter translatorLocation appropriately.

Application details

The application architecture shown in figure 10 provides a zero-footprint view of Lotus Forms using the WebForm server (translator) component. This architecture enables the browser to view the high-fidelity form by converting the Extensible Forms Definition Language (XFDL) into XHTML.

Figure 10. Application architecture
Application architecture

Procurement workflow is defined in Lotus Domino. As Lotus Domino provides the user interface in this sample, it also has the procurement application to list the form templates available and to approve or disapprove the procurement workflow. Lotus Domino also exposes a Web service for the forms application to store the submitted e-form into Lotus Domino.

The Lotus Forms API is used to process the form values and validate the signatures. It can also create the barcode and update the form with the barcode appropriately. Prepopulation of the form is done by updating the XML model instance in the form using the Lotus Forms API.

User authentication and authorization are taken care by Lotus Domino. Single sign-on is set up between Lotus Domino and WebSphere Application Server. Lotus Forms provides the ability to integrate digital signatures with forms and the feature to verify signatures in the submitted forms.

Authenticating the user

The procurement process initiator of the organization logs in to the application using the Lotus Domino application UI as shown in figure 11. Authentication and authorization are handled by Lotus Domino.

Figure 11. Lotus Domino login page
Lotus Domino login page

Once the initiator is logged in, the user sees the home page, and the right panel displays the pending approvals. If the user is an initiator, then the Forms link in the left panel can be clicked to view the templates available to create a new request as shown in figure 12..

Figure 12. Authenticated pages
Authenticated pages

Loading the form

Lotus Domino retrieves the form template and passes it to Lotus Forms servlet, which loads the form to the user.

The link displayed in the UI calls the (PopulateCost) agent in the database, which constructs the initial list of approvers and then dynamically constructs a document using the (f_TemplateAgent) form in the database. This form, in turn, calls another agent (LoadForm), which constructs the form.

The form retrieved is displayed as part of the Lotus Domino UI by the Lotus Forms servlet.

Figure 13 shows the display of the form in a browser.

Figure 13. Form loading
Form loading

The form is loaded by the Lotus Forms servlet application through the FormNodeP object available with the Lotus Forms API. Listing 1 shows the code used to load the form to the browser.

Listing 1. Form display
OutputStream responseOS1 = response.getOutputStream();	
theForm.writeForm(responseOS1, null, 0);

Prepopulation of forms happens through the XForms instances. The code snippet shown in listing 2 loads the form fields with instance values.

Listing 2. XForms instance display
<xforms:select1 ref="instance('INSTANCE')/formdata/cost" selection="open">
   <xforms:label></xforms:label>
   <xforms:itemset nodeset="instance('INSTANCE')/populationdata/cost">
     <xforms:label ref="@name"></xforms:label>
     <xforms:value ref="@name"></xforms:value>
   </xforms:itemset>
   <xforms:setvalue ref="instance('INSTANCE')/formdata/preapprover" 
   ev:event="xforms-value-changed"></xforms:setvalue>
</xforms:select1>

The form is loaded with the instances of the cost and approver list, so that the user can select the approver from a list, in this procurement process. See the cost field shown in figure 14.

Figure 14. Prepopulate the Form - Cost Field
Prepopulate the Form - Cost Field

After the user selects the cost, the next level of appropriate preapprovers is displayed. See figure 15.

Figure 15. Building form field relations - approvers
Building form field relations - approvers

For approvers, a similar procedure is used to load the submitted form.

Validating the form fields

You can validate the form fields at both the client side and server side as in any Web application. Form fields are validated using the XFDL or XForms elements at the client side. Automatic generation of values is also done using compute statements in the e-form. The code shown in listing 3 provides a sample compute statement provided as part of the form inclued in the Download section. This snippet computes the height of a field based on the value of another field.

Listing 3. XFDL compute
<box sid="BOX1">
    <itemlocation>
      <x>167</x>
      <y>329</y>
      <width>498</width>
      <height compute="'50' + ('25' * (incrlbl.value))">124</height>
    </itemlocation>
    <bgcolor>#DFDFD5</bgcolor>
</box>

Server-side validation of the form values is performed in a similar fashion to any other Web application. To retrieve the form fields at the server side, you can use the Lotus Forms APIs. The code snippet in listing 4 shows how the Lotus Forms API could be initiated.

Listing 4. Forms API initialization
try
{
	WSProperties wsProps = new WSProperties(getClass());
	DTK.initializeWithLocale("Webform Server", wsProps.getCoreVersionText(), 
	wsProps.getAPIVersionText(), null);
	DTK.setHardGCFlag(false);
}
catch (UWIException e)
{
	throw new ServletException(e.getMessage());
}

After it is initiated, the Lotus Forms API can be used to retrieve form fields for validation at the server side or for any other processing. The code snippet in listing 5 displays the use of the Lotus Forms API to retrieve form fields from the XFDL form.

Listing 5. Retrieve form field value
String costValue = theForm.getLiteralByRefEx(null, 
"PAGE1.costlist.value", 0, null, null);
String preappValue = theForm.getLiteralByRefEx(null, 
"PAGE1.preapproverlist.value", 0, null, null);
String hiddenValue = theForm.getLiteralByRefEx(null, 
"PAGE1.hidden.value", 0, null, null);

Similarly, listing 6 sets the value of an XFDL form field.

Listing 6. Set form field value
theForm.setLiteralByRefEx(null, "PAGE1.casenofield1.value", 0, null, null, case1);
theForm.setLiteralByRefEx(null, "PAGE1.casenofield.value", 0, null, null, case1);

Submitting the form

After the form is loaded, the initiator or approver modifies the values of the form and submits the form. Submission of the form points to the Lotus Forms servlet application running in WebSphere Application Server V6.1. The submission URL for the submit button is provided as part of the <url> tag.

Listing 7. Submit URL
<<button sid="next1">
         <itemlocation>
            <within>TOOLBAR</within>
            <x>474</x>
            <y>34</y>
            <width>55</width>
         </itemlocation>
         <fontinfo>
            <fontname>Arial</fontname>
            <size>7</size>
            <effect>bold</effect>
         </fontinfo>
         <bgcolor>#0000FF</bgcolor>
         <fontcolor>#FFFFFF</fontcolor>
         <url compute="global.global.custom:url"></url>

The URL property of the Submit button points to the global URL property for this e-form. The global custom URL property is defined at the beginning of the e-form as shown in listing 8.

Listing 8. Global URL
<custom:url xfdl:compute="">FormViewServlet?action=submit</custom:url>
<saveformat>application/vnd.xfdl</saveformat>

Initiating and processing the procurement workflow

After the form is submitted by the initiator, a success message is displayed to the initiator for the submission of the form. The Lotus Forms servlet application processes the values of the e-form and then submits the e-form as a document to the Lotus Domino Server using a Web service. The code snippet in the Lotus Forms servlet application, shown in listing 9, calls the Lotus Domino Web service.

Listing 9. Web service call
try{
	String endpoint = webserviceURL;
	Service service = new Service();
	Call call = (Call) service.createCall();
	//call.setOperationName(new QName(endpoint, "initialize"));
	call.setOperationName(new QName(endpoint, "putForm"));
	call.setTargetEndpointAddress(new java.net.URL(endpoint));
	call.setUsername("domino admin");
	call.setPassword("password");
	String ret = (String) call.invoke(new Object[] { formid,updatedXFDL });
}
catch(Exception e){
e.printStackTrace();
}

After the Web service is called, the Lotus Domino server stores the form and initiates the procurement process. The workflow is controlled by a scheduled agent, ProcessEFormRequest. This agent allows the approver to see the procurement case for the approval as shown in figure 16.

Figure 16. Approver’s activities view
Approver’s activities view

Barcode generation

Barcodes, a machine-readable representation of data, are used for quality assurance, batch separation, and error reduction. There are two-dimensional and three-dimensional barcode readers available.

Barcode generation APIs can be used to generate barcodes with the data provided. These APIs generate the barcodes as images. These barcode images can be loaded into Lotus Forms XFDL using Lotus Forms extensions as JAR files or using the server-side APIs. Figure 17 displays the form showing the embedded barcode.

Figure 17. Barcode generation
Barcode generation

This form can be printed to read the barcode, and it can generate the coded data into other systems for data processing.

Attachments to the form

Procurement process-related documents can be attached to the form. For this step, the form uses XForms standard-based instances to upload, extract, and delete the attachments. Figure 18 shows the form with the document attached.

Figure 18. Form attachments
Form attachments

Signature verification

Verification of the signature is a key in any signature-based form implementation. Verification of the signature indicates the validity of the signature. This verification can be performed by calling the FormNode.verifyAllSignatures() method to verify all the signatures of the form. The FormNode.getSignatureVerificationStatus() method can also be performed to check the verification status of a particular node.


Advantages of the integration

This integration takes advantage of both Lotus Domino and Lotus Forms technologies. These two technologies complement each other.

These features specifically are provided by Lotus Domino for our scenario:

  • Replication feature to enable the distributed application deployment, which can provide high availability and high performance
  • Form management for form storage and retrieval
  • Authentication and authorization of the application
  • Workflow capability that helps in easily defining the business process

These features specifically are provided by Lotus Forms:

  • High-fidelity forms to replicate paper-based forms
  • Overlapping digital signatures
  • Standard (XForms)-based forms display and data processing
  • Forms extension to support iKey-based digital signatures

These features are provided by the integration of Lotus Domino and Lotus Forms:

  • Offline capability
  • Sharing of form attachments with other systems through the use of Web services
  • Email functionality for forms to be sent as attachments in email

Conclusion

This article explains how the integration of Lotus Domino and Lotus Forms can benefit Web applications. This integration can be extended to portlet applications and can provide the facility to utilize the best features from both Lotus Domino and Lotus Forms servers.


Acknowledgments

The team would like to acknowledge Gopi Srinivasan, Technical Sales Manager and Pawan Rawal, Technical Sales Specialist for their valuable inputs.


Download

DescriptionNameSize
Code sampleAttachments.zip8.45MB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=397571
ArticleTitle=Integrating IBM Lotus Forms with IBM Lotus Domino
publish-date=06292009