Displaying a AR System form in a portlet

Required knowledge

To create a portlet to display a form view, you must be able to:

• Create a view in AR System.
• Display a view in a browser using a Mid Tier URL.
• Write a portlet in Java using the JSR 168 API. (An example portlet is included with AR System 7.0.01.)
• Deploy a portlet in your portal server and administer the portal server.

Tested platforms

The methods described in this topic are illustrated in unsupported sample portlet code that you can find in the samples/portal directory in the Mid Tier installation directory.

You can remove the sample directory content without impacting the Mid Tier functionality.

• For UNIX:

  /usr/ar/mid-tier/samples/portal

• For Windows:

  C:\Program Files\AR System\Mid-Tier\samples\portal

The sample has been verified using:

• AR System 7.0.01
• Portal servers:
  • BEA WebLogic Portal 8.1 on HP HP-UX, Linux, and Microsoft Windows Server 2003
  • IBM WebSphere Portal 5.1 on Microsoft Windows Server 2003
  • IBM WebSphere Portal 6.0 IBM AIX
  • Liferay 3.6.1 and Tomcat on IBM AIX, Linux, Microsoft Windows Server 2003, and Sun Solaris

Solution architecture

To display a form view, the AR System portlet must reference the view in the Mid Tier, so to display AR System content in a web portal, you must have:

• A browser to display the web portal.
• A portal server with a portlet container and web server to host the portal and the portlet.
• An Mid Tier to display the form view in an IFRAME element in the portlet within the portal in the browser.
• An AR System server to provide the view to the Mid Tier.
  

Components and communication

Portlet structure

Portlets are similar to servlets. The JSR 168 API is based on the servlet API and many portlet containers are extensions to servlet containers. But while a servlet produces a complete web page, a portlet produces an HTML fragment that the portal displays in a portlet window, aggregating it with other portlets.
A portlet usually has an EDIT mode. In EDIT mode, the user can set portlet preferences that can control the content and appearance of the portlet in VIEW mode. The portal can save the preferences so the user does not need to enter them for every use. A portlet can also have a HELP mode.
When you design the AR System portlet, you must decide which proprieties of the portal the user can control and which will be fixed or determined another way. For example, will the user be able to choose which AR System form, view, table, flashboard, or other data visualization field to display? If the user cannot set or change any properties, the portlet does not need an EDIT mode. You must also determine if it needs a HELP mode.
Because the Mid Tier serves the form view displayed in the portlet, to achieve basic aggregation integration, you must include a reference to the view in the portal VIEW mode HTML fragment. Do this by including an HTML IFRAME element that references the URL of the form view in its src attribute. In the simple case, the fragment can consist of only the IFRAME element. An example of an IFRAME element follows.

See Specifying-parameters-in-URLs for more information about ViewFormServlet as used in the example.

Because the view in the portlet is displayed by the Mid Tier, it might not be consistent with the portal style. You can set the appearance properties of the view to hide the web toolbar, to make the view color consistent with the portal, and to provide content for the web header and footer. You can also change the AR System style sheets in the Mid Tier to make the form view more consistent with the portal style.

Authentication solutions

Because the portal and the Mid Tier have separate authentication, AR System portlets might require the user to log in twice and log out twice. This section describes ways to handle Mid Tier login and logout.

To log in, the user must first log in to the portal and then log in to the Mid Tier. To log out, the user should log out of the portlet before logging out of the portal.

Login integration

A portlet solution can handle login to the Mid Tier in the following ways:

• Require separate logins—No integration between the portal or the portlet and the Mid Tier is required. After logging in to the portal, the user must also log in to the Mid Tier. The Mid Tier displays the login form in the servlet before it displays the referenced view.
• Allow guest users to access your AR System server—If you permit guest users, you can grant the Public group access to the form and specify the guest user authentication information in parameters to ViewFormServlet and log in the user automatically.
• Save authentication information in portlet preferences—If the portlet gets the user name and password from the user in EDIT mode and saves them in portlet preferences, the portlet can specify the user authentication information in parameters to ViewFormServlet and log in the user automatically in VIEW mode. The portlet can encrypt and decrypt the password to provide more secure storage in the portlet preferences.
• Use the same single sign on (SSO) solution—If the portal server and the AR System server use the same SSO solution for user authentication, you can configure them so that individual logins are not required.
• Customize the portal login—If you can customize your portal server, you can modify the portal login to perform the Mid Tier login before it runs any portlets. In this case, the login process on the portal server logs in to the Mid Tier instead of the portlet fragment in the portal on the browser computer. The portal login process must have access to the required authentication information.
• Use portal authentication information—You can code the portlet to log in the user automatically if:
  • You configure your portal and AR System server to use the same authentication information.
  • You can customize your portal server.
  • You create portal server interfaces that the portlet can use to get the user name and password used to log in to the portal.

For example, the Liferay portal server can be customized by changing
/portal-ejb/src/com/liferay/portal/service/impl/ UserServiceImpl.java in the Liferay 3.6.1 installation directory. Replace
if (user.getPassword().equals(encPwd)) { authResult = Authenticator.SUCCESS;

with

For the example code that gets the password from the Liferay portal, see the sample portlet code in the Mid Tier installation directory at /samples/portal/src/com/arsys/portal/LiferayARPortlet.java.

Logout integration

A user must log out of the Mid Tier to release the license. A portlet solution can handle logout from the Mid Tier in the following ways:

• Require separate logouts—No integration between the portal or the portlet and the Mid Tier is required. Include a logout button on the form view displayed in the portlet as described in Installing and Administering 

  Mid Tier

   . Users logs out of the Mid Tier using the button before they log out of the portal.

• Customize the portal logout—If you can customize your portal web page, you can change the logout behavior, so the portal logout button performs the Mid Tier logout before it performs the portal logout. This does not affect portal users who are not using your AR System portlet because the logout is ignored.
• Customize the portlet API—JSR 168 does not include a call to the portlet when the portal exits. If you can customize your portal server, you can add this capability to the API and use it in your AR System portlet to log out of the Mid Tier.

As an example of customizing the portlet API, you can customize the Liferay portal server by making the following changes:

1. Add the following method and the required import to /portal-ejb/src/ com/liferay/portal/servlet/PortletContextPool.javain the Liferay 3.6.1 installation directory:
   public static Set getAllPortletID() { return Collections.unmodifiableSet(_instance._portletContextPool.keySet());}
2. Compile /samples/portal/src/com/arsys/portal/LogoutCallback.java in the Mid Tier installation directory into the /portal-ejb/classes directory in the Liferay 3.6.1 installation directory.
3. Append com.remedy.arsys.portal.LogoutCallback to the logout.events.post property in the /portal-ejb/classes/ portal.properties file in the Liferay 3.6.1 installation directory. For example, the modified property might be:
   logout.events.post=com.liferay.portal.events.LogoutPostAction, com.liferay.portal.events.GarbageCollectorAction, com.remedy.arsys.portal.LogoutCallback

Best practices

Consider the following recommendations when you design and code the portlet. See the Form and Application Objects guide and the Installing and Administering Mid Tier  guide for more information.

Target use case

The most effective view for an AR System portlet contains only a table field or a flashboard or other data visualization field plus trim fields and active link control fields required for effective formatting and function. Avoid user input in the portlet view. For example, a flashboard that summarizes the status of interesting requests or a small table that lists relevant requests can be effective portlets.
For user interaction, provide a button or other active link control that opens a more complete view in a separate browser window, not in a portlet. The user must complete the interaction in the separate window before logging out of the Mid Tier in the portal window.

Custom view

Create a separate view for the portlet. Set the Appearance properties of the view to hide the web toolbar.

Limitations

Be aware of the following possible limitations of AR System portlets:

• Like other portlets, an AR System portlet reinitializes when the browser Refresh command is run (or the portal web page is reloaded). For example, if you type in fields in a form and refresh the portal page, your entries are lost. For portlets that display status as recommended in Target use case, this is usually not a problem.
• If a portal contains more than one AR System portlet, some portlets might not display their content the first time they appear after AR System login. To prevent this problem, use an SSO solution or customize the portal login, as described in Login integration. Otherwise, if an AR System portlet does not initially display its content, use the browser refresh function to reload the portal.
• Similarly, when the portal is open in Microsoft Internet Explorer, a change in another portlet might cause an AR System portlet to blank out its content. To display the AR System portlet, use the browser refresh function to reload the portal.