IBM Application Portlet Builder

 

+
Search Tips   |   Advanced Search

 

---

Contents

1. Set up the Application Portlet Builder
   • Client Requirements
   • Server Requirements

2. Configuration
   • Configure for Domino
   • Configure for JDBC
   • WAS configuration for a database provider
   • WAS configuration for a data source

3. Builder Example

---

Overview

The IBM Application Portlet Builder functionality enables users to create portlets that can access and manipulate data in an enterprise application, without requiring programming knowledge of the system. By selecting business objects available from the enterprise application, users can specify which data fields should be displayed in a portlet. When the portlet is created, the portlet can be made available to portal end users.

Application Portlet Builder is a general term that actually refers to two portlet builders which are portlets themselves: a JDBC Portlet Builder and a Domino Portlet Builder. In the actual product user interface these builders are respectively referred to as JDBC Business Object Builder and Portlet Builder for Domino.

These portlets are not supported as remote WSRP services.

 

---

Set up the Application Portlet Builder

 

Client requirements

The portlets built with the Application Portlet Builder support browsers and devices capable of rendering HTML markup. The following table provides detailed information.

Minimum requirements for HTML
Markup level	HTML 4.01 Transitional
Java applet	None
JavaScript	1.3
<iframe>	Domino only
Style sheets	Portal styles only
Software	This portlet has been tested on the following browsers: Internet Explorer V6.0 Netscape V7.0
Accessibility	Yes

Single sign-on is supported through the WebSphere Portal Credential Vault. A user's credentials are stored in a slot assigned to each portlet. Initially, a separate slot is created for each portlet. However, a portlet's configuration mode can be used to set the name of a specific slot. If the same slot is used for all portlets that connect to the same application, a user's credentials need only be entered once.

 

 

Server requirements

The Application Portlet Builder supports the following enterprise applications:

• JDBC connection to Cloudscape, Oracle and DB2 via a WebSphere data source
• Domino Server v.5 and later

To enable remote database communication, for Oracle the TNS Listener must be running. For DB2, the DB2 Configuration Assistant must be used to set up a local alias to the remote database.

The Application Portlet Builder does not support the following databases:

• SQL Server
• DB2 390

 

---

Configure for Domino:

1. In your Domino server under...

   Server Document | Internet Protocols | HTTP

   ... set Allow HTTP clients to browse databases to Yes.

2. Start your Domino server and remember the port number.

3. Start HTTP service on your Domino server by typing load http in the Domino server console window. Wait until this loads.

4. Start DIIOP service on your Domino server by typing load diiop in the Domino server console window. Wait until this loads.

5. Ensure that single sign on (SSO) is configured correctly if it is enabled.

6. If you are running a supported Domino v5 server, ensure that the security on your Domino server is configured to allow you to run restricted and unrestricted Java. In your Domino server, under...

   Server Document | Security | Run restricted Java/javascript/COM

   ...and...

   Server Document | Security | Run unrestricted Java/javascript/COM

   ...your user name should appear in both of the lists.

7. If Domino server and WebSphere are installed on the same machine, change the Domino server's http port number so it does not conflict with the http server in WebSphere. Remember this port number.

   The Portlet Builder for Domino is located under...

   My Portal | My Work | Developers Area | Lotus Domino Builder

   You will be prompted for the following information while creating each portlet.

   Parameter	Value
   Domino Server Name:	Name of the Domino Server that you are using.
   Port Number:	Port number of the Domino Server that you are using.
   Domino Database Name	Name of the Domino Database that you are using.
   Domino User ID	User ID
   Password	Password

 

---

Configure for JDBC:

 

 

WebSphere Application Server Configuration for a Database Provider

1. Start the Administrator's Console.

2. In the left hand panel expand Resources.

3. Select JDBC Providers.

4. In the right hand panel specify the cell or node scope by browsing or entering it in the input field. Click Apply.

5. Click New to create a JDBC Provider

6. Using the drop down list, select the appropriate provider and click on the Apply button. Use the appropriate configuration information listed below for your provider:

   • DB2
     • Select DB2 JDBC Provider.
     • Set property Classpath to the location of db2java.zip

   • Oracle
     • Select Oracle JDBC Thin Driver
     • Set property Classpath to the location of ojdbc14.jar

   • Cloudscape

   • • Select Cloudscape JDBC Provider.5.0
     • Set property Classpath to the location of db2j.jar. The default location is WAS_HOME /lib.

7. Save your changes to the Master Configuration.

 

 

 

WebSphere Application Server Configuration for a Data Source

Complete the following steps to create a connection to the backend through a database data source

1. Start the Administrator's Console.
2. In the left hand panel expand Resources.
3. Select JDBC Providers.
4. In the right hand panel specify the cell or node scope by browsing or entering it in the input field. Click Apply.
5. Select the appropriate JDBC provider.
6. Select Data Sources in the Additional Properties table for the provider.
7. Click on the New button to create a Data Source.
8. Enter a value for the property Name.
9. Enter a value for property JNDI Name.
10. Click Apply.
11. Use the following to configure the appropriate provider:

12. • DB2
      1. Select Custom Properties under the Additional Properties table.
      2. Enter the database name for property databaseName. Click OK.
      3. Enter the DB2 server port number for property portNumber. The default is 50000. Click OK
      4. Save your changes to the master configuration.

    • Oracle
      1. Select J2C Authentication Data Entries under the Related Information table.
      2. Click on the New button.
      3. Enter a value for the property Alias.
      4. Enter the database user ID for property User ID.
      5. Enter the database password for property Password.
      6. Click OK.
      7. Save your changes to the master configuration.
      8. Navigate back to your data source in the Administrator's Console.
      9. Select the Authentication Alias you just created for both Container and Component using the drop down list.
      10. Click Apply.
      11. Select Custom Properties under the Additional Properties table.
      12. Enter the database name for property databaseName.
      13. Enter the Oracle URL for property URL. The format is jdbc:oracle:thin:@myServer:1521:myDatabase, where myServer is the server name, 1521 is the port it uses for communication, and myDatabase is the database name.
      14. Save your data source configuration.

    • Cloudscape
      1. Select Custom Properties under the Additional Properties table.
      2. Enter the database name for property databaseName. For example, WAS_HOME/bin/DefaultDB.
      3. Enter the value for the property Connection Attributes.
      4. If your Cloudscape database needs to be upgraded, enter upgrade=true to permit the upgrade. In this case you will not be able to get a schema list from the database when using the Application Portlet Builder. The SystemErr.log will have an exception and indicate upgrade=true needs to be set for this database.

Notes:

1. After creating the appropriate provider and data source, it will be necessary to stop and restart both the WebSphere Application Server and the WebSphere Portal appserver.

2. The JDBC Builder is located under...

   My Portal | My Work | Developers Area | JDBC Builder

3. For remote DB2 databases, the database connection needs to be set up using the DB2 Client Configuration Assistant. The database alias name entered here is the database name used for the data source. Note that "Test Connection" might fail because there is no awareness of the remote user ID and password. This authentication is handled when configuring the portlet and Application Portlet Builder.

4. For Cloudscape, only one open connection is permitted on a database at a time. If you successfully test the connection using the test connection button on the Cloudscape data source, you might need to restart the server.

5. If you are using Cloudscape viewer and you upgrade you might no longer be permitted to view this database. This is because the viewer tool says the tool needs an upgrade to view the upgraded database.

6. This portlet uses the WebSphere JDBC data source so it can take advantage of connection pooling. consider how many portlets you run versus the size of your connection pool, since each portlet uses a connection. The connection is used and then released. If you run a large number of these portlets, you might need to increase the size of your connection pool.

7. The JDBC portlet will not allow you to update or delete records for tables that do not have primary keys. When you attempt to delete or update records for a table that does not have primary keys, you see the following message:

Fatal error occurred in BusinessObject Framework. Please see log for details.

In the log you will see one of the following messages along with a stack trace:

• Update is not supported for tables that have no primary keys.
• Delete is not supported for tables that have no primary keys.

 

---

Builder Example

 

 

Scenario

The HR manager would like to create a portlet that would access the HR system database. In this lab, the HR will use WPAI Portlet Builder (JDBC) to create a Portlet to access the HR database. The HR manager is not a Portlet Developer and needs a way to create a Portlet without using a development environment. WPAI would provide that capabilities to the HR Manager.

 

 

Create the DERF_CMN Database.

1. cp derf_cmn.zip to...

   \cloudscape\databases\

2. Unzip derf_cmn.zip

   cd \cloudscape\databases
   unzip derf_cmn.zip

 

 

Create JDBC data source for DERF Employee DB

The JDBC portlet builder of WebSphere Portal Application Integrator allows a Business Power user (not a Java Programmer) to build application portlets that can Create, Review, Update and Delete records (rows) in any relational database that can be accessed as a data source from WAS.

First, we need to create a new JDBC data resource for the Derf Employee database.

1. From the Programs menu or from a command line, start server1 and WebSphere_Portal server.

2. Open the WAS Admin console.

   http://portal.ibm.com:9090/admin/

3. Logon as wpsadmin, however you can use any ID that you like.

4. Expand Resources and Click on JDBC Providers.

5. Click on New to create a new JDBC provider.

6. Select Cloudscape JDBC Provider from the list.

7. Click on Apply.

8. Take all defaults but replace the classpath for the ${CLOUDSCAPE_JDBC_DIVER_PATH}/db2j.jar to:C:/WebSphere/PortalServer/shared/app/cloudscape/db2j.jar. (see following screenshot). Be sure to change the back slashes (\) to forward slashes (/).

9. Click Apply.

10. Scroll down to the bottom of this page and select Data Sources.

11. Click on New to create a new datasource.

12. Complete the new datasource form. Make sure you note the JNDI Name. This will be used to link the datasource to the JDBC Builder later on.

    Name:	derf_db
    JNDI Name:	jdbc/derf_db

    Note that names are case sensitive. You can leave the other entries as they are. Now change the database name to derf_cmn. Scroll down the page and select Custom Properties. Select databaseName. Change Value to C:/cloudscape/databases/derf_cmn Click Apply Make sure you save your changes. Do the following: Click on Save. Click on Save again.

13. Test the connection.
    • Drill down to your your new datasource.
    • ResourcesJDBC ProvidersCloudscape JDBC ProviderData Sources.
    • Select the derf_db database. Click on Test Connection .

    If the connection works, youll see a message Data Source is used by the application to access the data from the database. A data source is created under a JDBC provider which provides the specific JDBC driver implementation class.

14. Cycle the system
    • Start Programs | IBM WebSphere | Portal Server v5.1 | Stop the Server.
    • Start Programs | IBM WebSphere Application Server v5.1 | Stop the Server.
    • Start Programs | IBM WebSphere Portal Server v5.1 | Start the Server.

    You do not need to restart WebSphere Application Server (server1). It is only needed to access the WAS Admin Console again.

    You are now ready to use the WPAI JDBC Builder with this datasource.

 

 

Using the WPAI JDBC Portlet Builder to create a portlet.

1. Logon on to the portal as wpsadmin/wpsadmin.

2. Navigate to My PortalMy WorkDevelopers AreaJDBC Builder

3. Before you can use the JDBC Portlet Builder, configure it.
   • Click on the Configure (wrench) icon in the upper right of the portlet title bar.

   • For the JNDI Name for the Datasource, use the name you entered when you created the Datasource jdbc/derf_db. Remember its case sensitive.

   • Enter wpsadmin/wpsadmin as the userid and password and click OK

4. The following is the initial screen of the JDBC Builder portlet. If you had already created portlets, they would be listed here.

5. We havent built any portlets yet so click on *New Portlet.

6. Fill in the form as follows:

   Portlet Name:	Employee Comp
   JNDI Name for Datasource:	jdbc/derf_db
   Authentication Options:	Use this user ID and password
   Slot name	derf_slot

   This will create a slot in the Credential vault called derf_slot and the user will be prompted for userid and password when first attempting to access the database.

   Note that you come back to this screen to create a second portlet, you could use the same credential vault slot. In that case, click the use an existing credential vault slot and select derf_slot from the list.

7. The template should be Business Object Struts Template.

   

8. Click Next.

9. Now we need to create a business object for the data we want to access from our datasource. Click *New business object.

   

   APP should be selected from the dropdown list. Then you can search for the tables associated with that Schema.

   Leave the % in the Table Name text box to search for all tables.

   Click on Get List

   If the drop down list is empty, something is wrong. The mistake is usually that the datasource was set up incorrectly or you used an invalid userid and password for the when you configured the JDBC Portlet Builder portlet. If you look at the WebSphere Portal error log, you probably get an indication of the problem. To correct the user id and password (remember, the password for wpsadmin is wpsadmin) be able to edit the Portlet Builder portlet to change the userid and password.

   If its a problem with the datasource, go back to the WAS console and check your entries. Remember, the database name is...

   C:/cloudscape/databases/derf_cmn

   ...and remember to use the correct JNDI name (jdbc/derf_db).

10. Select the EMPLOYEE_DETAILS table and it will appear in the Table Name text box.

11. Click OK.

12. First we have to give this new business object a name. Use Derf Employees as the Business object name.

13. Select the Search automatically heck box as well as the Search, Update, Create and Delete check boxes. This will allow us to be able to Create, Retrieve, Update and Delete records in the Derf Employee database.

14. Click Next.

    We are now presented with a list of all of the fields of the Business object. We can select which fields are displayed, which fields can be changed and which are searchable. We can change the field display name if we want to. We can also indicate which fields we want to be People Aware. If we select the Edit icon on the left, we can set more details of a particular field, including Click to Action support.

    We only want to see a few fields. Check FULLNAME, DEPT, JOB, and EMPLOYEEID fields.

    Note that all fields are selected by default.

15. Select the Edit (pencil) icon next to DEPT.

16. Click the + sign next to Click-to-Action

17. In the Type field put dept

18. In the Namespace field put deptid.

19. Make sure the value equals DEPT

20. Click OK

21. Click Next.

22. We can use this screen to change the display order of the fields. Arrange them using the screen shot below by using the up and down arrows

    Note that PERMANENTRECORDNOTES and SALARY are on the following page and were selected automatically. If you did not want them to show up, you can delete them now (by Clicking on the minus sign) or click on Back and remove the Check boxes on the second page.

23. Click Finish when done.

24. We have now completed the creation on our Derf Employees business object. Note that we can come back and change the definition at any time using this same tool.

25. Click OK to complete the portlet. Note: this will take a few minutes to build the porltet.

 

 

Run the new JDBC portlet

1. Click on Edit Page in the Top-Right-Hand corner

2. Select , Click on Add portlets to add our new portlet.

3. Enter Employee (remember our portlet is called Employee Comp) in the Search field and Click Search.

4. Select our new Employee Comp portlet and Click OK.

5. Click on Done to complete the process.

6. Your Page should now look like the picture below.

   

    

    

   Create Department Portlet supporting Click-to-Action

   1. Click on *New Portlet in the JDBC Business Object Builder portlet.

   2. Fill in the form as follows:

      Portlet Name:	Department
      JNDI Name for Datasource:	leave as jdbc/derf_db
      Authentication Options:	Select Use Existing Vault Slot and select derf_slot.