- How this Article is Organized
- Background
- Obtaining the Required Patches
- Sun ONE Portal Server and Lotus iNotes Integration Recipe
- About the Author
- Acknowledgements
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Sun ONE Portal Server and Lotus iNotes Integration Recipe
Ingredients
Client Browser
This recipe was tested using Internet Explorer 5.5SP2 + December 2002 Security update. Other Internet Explorer 5.5 and 6.0 versions should work as well, but they must be tested thoroughly as a part of the integration process.
Notes Server
The Notes server version used for this recipe is:
<!-- Domino Release 5.0.12 (Solaris Sparc) -->
This is the latest release of Domino available at the time of writing. You can find the server version information by viewing the document head of any iNotes page.
Notes Client
The Notes client version (iNotes) used for this recipe is:
<!-- $HaikuForm - 567 -->
The client version information is also available from the document source and is mostly useful for support tickets that might need to be opened with IBM.
Portal Server
Required Versions:
Sun ONE Portal Server 6.0 + SRA + 6.0SRAExchangeFixes
Sun ONE Portal Server 6.1 + SRA
New iNotes-specific ruleset (inotes_ruleset.xml)
NOTE
Earlier versions of Portal 3.0, such as SP5, may work using this recipe as a guideline, but this document focuses only on Portal 6 releases.
Advantages
The native user interface can be used to access Notes from inside or outside the corporate network.
No client configuration is required.
The Notes server does not have to reside in the DMZ.
Encryption/Decryption is performed using Secure Sockets Layer (SSL).
The integration can be used in conjunction with Lotus Notes portlets developed for Portal 6.
The integration takes advantage of new 6.0 architecture where the ruleset can be associated with a particular Gateway which might be used to access the Exchange server.
Disadvantages
A Notes.ini entry must be added to prevent portal session loss when iNotes users log out.
You cannot use an out-of-box default ruleset.
XML rewriting for the Gateway instance must be disabled to access iNotes.
Known Problems With iNotes Integration
Currently, there are no known problems.
What
The following tasks provide an overview of what is involved in this recipe:
"Create a New Ruleset for the Portal Desktop" on page 5
"Create New Rewriter Ruleset for iNotes" on page 7
"Associate New Rulesets with an Appropriate Gateway Instance" on page 9
"Create a Proxies for Domains and Subdomains Entry for iNotes Server" on page 10
"Install the Portal 6 Patch Containing Exchange-Related Fixes" on page 10
"Enable Rewriting of Cascading Style Sheet (CSS) Content" on page 11
"Disable Rewriting of XML Content" on page 11
"Modify the notes.ini Start File" on page 12
"Modify Portlet URLs (if applicable)" on page 12
"Restart the Portal Components" on page 12
How
Create a New Ruleset for the Portal Desktop
From the Administration console, select View: Service Management.
Select the Rewriter link under the Portal Server Configuration section of the left view pane.
Under the Rules section, select New.
In the text field, change the RuleSet ID attribute value to desktop_ruleset:
Create a ruleset that will account for the Portal Desktop contents which you have deployed.
Select Save.
<RuleSet id="desktop_ruleset">
The contents may include URLScraped content if the ruleset is shared, the Bookmark provider, the Netlet provider, and so forth.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE RuleSet SYSTEM "jar://rewriter.jar/resources/RuleSet.dtd"> <RuleSet type="GROUPED" id="desktop_ruleset"> <HTMLRules type="GROUPED" id="idshtmlrules"> <Applet source="*/NetMailServlet" code="NetMail.class" param="*URL" valuePatterns="" /> <Applet source="*/NetFileApplet" code="rp.class" param="*URL" valuePatterns="" /> <Applet source="*/NetletConfig" code="SServer.class" param="configURL" valuePatterns="" /> <Attribute name="action" tag="*" valuePatterns="" /> <Attribute name="background" tag="*" valuePatterns="" /> <Attribute name="codebase" tag="*" valuePatterns="" /> <Attribute name="href" tag="*" valuePatterns="" /> <Attribute name="src" tag="*" valuePatterns="" /> <Attribute name="value" tag="*" valuePatterns="" /> <Attribute name="url" tag="*" valuePatterns="" /> <Attribute name="archive" tag="*" valuePatterns="" /> <Attribute name="style" tag="*" valuePatterns="" /> <JSToken>on*</JSToken> </HTMLRules> <JSRules type="GROUPED" id="idsjsrules"> <Variable type="URL">location.href</Variable> <Variable type="URL">parent.location</Variable> <Variable type="URL">self.location</Variable> <Variable type="EXPRESSION">window.location</Variable> <Variable type="EXPRESSION">location</Variable> <Variable type="EXPRESSION">surf_form_URL</Variable> <Variable type="SYSTEM">window.location.pathname</Variable> <Function type="EXPRESSION" name="*findWindow" paramPatterns="y" /> <Function type="URL" name="openSavedBookmarkURL" paramPatterns="y" /> <Function type="URL" name="openURL" paramPatterns="y" /> <Function type="URL" name="openAppURL" paramPatterns="y" /> <Function type="URL" name="openNewWindow" paramPatterns="y" /> <Function type="URL" name="parent.openNewWindow" paramPatterns="y" /> <Function type="URL" name="window.open" paramPatterns="y" /> <Function type="URL" name="netletConfigOpen" paramPatterns="y,y" /> <Function type="URL" name="netletWinOpen" paramPatterns="y" /> <Function type="DHTML" name="document.write" paramPatterns="y" /> <Function type="DHTML" name="document.writeln" paramPatterns="y" /> </JSRules> </RuleSet>
Create New Rewriter Ruleset for iNotes
From the Administration console select View: Service Management.
Select the Rewriter link under the Portal Server Configuration section of the left view pane.
Under the Rules section, select New.
In the text field, change the RuleSet ID attribute value to inotes_ruleset:
Create a bare-bones ruleset which looks something like the following:
Select Save.
<RuleSet id="inotes_ruleset">
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE RuleSet SYSTEM "jar://rewriter.jar/resources/RuleSet.dtd"> <RuleSet id="inotes_ruleset"> <!-- Rules for Rewriting HTML Source --> <HTMLRules> <!-- Rules for Rewriting HTML Attributes --> <Attribute name="action" /> <Attribute name="background" /> <Attribute name="codebase" /> <Attribute name="code" /> <Attribute name="href" /> <Attribute name="src" /> <Attribute name="lowsrc" /> <Attribute name="style" /> <Attribute name="content" tag="meta" /> <!-- Rules for Rewriting HTML Attributes containing Java Script --> <JSToken>on*</JSToken> </HTMLRules> <!-- Rules for Rewriting JavaScript Source --> <JSRules> <!-- Rules for Rewriting JavaScript variables in URLs --> <!-- <Variable type="URL"> LayoutOption3 </Variable> --> <Variable type="URL"> imgsrc </Variable> <Variable type="URL"> *location.href </Variable> <Variable type="URL"> parent.location </Variable> <Variable type="URL"> self.location </Variable> <Variable type="URL"> location.replace </Variable> <Variable type="EXPRESSION"> src </Variable> <!-- Rules for Rewriting JavaScript Function Parameters --> <Function type="EXPRESSION" name="window.open" paramPatterns="y"/> <Function type="DHTML" name="document.write" paramPatterns="y"/> <Function type="DHTML" name="document.writeln" paramPatterns="y"/> </JSRules> </RuleSet>
Associate New Rulesets with an Appropriate Gateway Instance
From the Administration console, select View: Service Management.
Under the SRAP Configuration section of the left view pane, select the link next to Gateway.
Select the Edit link next to the Gateway instance which will be used to connect to the Notes server.
Under the domain-based rulesets, perform one of the following actions according to you iNotes and portal domain setup:
Create an entry for the fully qualified iNotes server.
Create an entry for the iNotes server's DNS domain.
Create an entry with a superset of the inotes_ruleset and the desktop_ruleset.
Select Add.
Also under the domain-based rulesets section, change the portal server node's domain ruleset from default, or gateway_default_ruleset to desktop_ruleset.
Select Add.
Select the previous rule entry for the portal server node's domain.
Select Remove.
Select Save.
This is the easiest and most manageable approach. The entry would look something like inotes.int.sun.com|inotes_ruleset where inotes is the hostname of the Notes server, and int.sun.com is the internal domain where the Notes server resides.
This is useful if the Notes server is in a separate subdomain from the portal server node, so that the ruleset for the portal desktop, URLScraper, and Bookmark provider, and do on, can be kept separate from the ruleset used for iNotes. The entry might look something like:
int.sun.com|inotes_ruleset
This option may be required if the portal and iNotes servers are deployed on the same physical domain and host, because a URL cannot yet be associated with a specific ruleset. To prevent unwanted rules from being applied to iNotes, or to prevent the Portal Desktop from not being rewritten correctly, a dedicated Gateway instance might need to be used solely for users wishing access to iNotes. The entry might look something like:
sun.com|sunwide_ruleset
Create a Proxies for Domains and Subdomains Entry for iNotes Server
NOTE
This step is only necessary if the Notes server is on a different DNS subdomain from the portal server node.
From the Administration console, select View: Service Management.
Under the SRAP Configuration section of the left view pane, select the link next to Gateway.
Select the Edit link next to the Gateway instance which will be used to connect to the Notes server.
Add the DNS domain of the Notes server to the Proxies for Domains and Subdomains section.
Select Add.
Select Save.
Install the Portal 6 Patch Containing Exchange-Related Fixes
NOTE
This patch installation is only required for Portal 6 versions earlier than 6.1.
The patch you need for this recipe is called 6.0SRAExchangeFixes (patch ID 115156-01).
If you have added or changed files in the Portal web-apps directory, back it up in case the changes are overwritten or lost when the service is redeployed.
Uncompress and untar the patch contents.
Install the patch using the Solaris patchadd command, first on the profile and platform nodes, and then on the Gateway node.
# cp install_dir/SUNWps/web_apps \ install_dir/SUNWps/web_apps_pre6.0SRAExchangeFixes
# gunzip 6.0SRAExchangeFixes.tar.gz # tar -xvf 6.0SRAExchangeFixes.tar
# patchadd 115156-01 Checking installed patches... Executing prepatch script... Verifying sufficient filesystem capacity (dry run method)... Installing patch packages... Patch number 115156-01 has been successfully installed. See /var/sadm/patch/115156-01/log for details Executing postpatch script... Checking for previous patch revisions... Restarting SunONE Portal Server Gateway w/ original settings. stopping gateway ... done. starting gateway ... done. Gateway restarted. Please wait a moment before connecting to it. Postpatch processing complete. Patch packages installed: SUNWpsgw SUNWpsrw
Enable Rewriting of Cascading Style Sheet (CSS) Content
From the Administration console, select View: Service Management.
Under the SRAP Configuration section, select the link next to Gateway.
Select the Edit link next to the appropriate Gateway instance.
Add CSS=text/css to the Mime mappings section.
Select Add.
Select Save.
Disable Rewriting of XML Content
From the Administration console, select View: Service Management.
Under the SRAP Configuration section, select the link next to Gateway.
Select the Edit link next to the appropriate Gateway instance.
Select the XML=text/xml entry from the Mime mappings section.
Select Remove.
Select Save.
Modify the notes.ini Start File
Backup your existing notes.ini file.
Add the following line to the notes.ini file:
Restart the Notes server.
iNotes_WA_SkipEndIESession=1
Modify Portlet URLs (if applicable)
Modify the creation scripts to the iNotes equivalent URLs.
For example, to create a new task, the default URL which loads the webmail templates instead of the iNotes templates is:
http://notes.int.sun.com/mail/uid.nsf/Task?OpenForm&ui=webmail
The links need to be changed at the provider's source level, so this may require professional services intervention if you do not have the provider source. One example of how this link would correctly load in iNotes is to change it instead to:
http://notes.int.sun.com/mail/uid.nsf/($ToDo)/$new/?EditDocument&Form=h_PageUI&PresetFields=h_EditAction;h_New,s_NotesForm;Task
Restart the Portal Components
Restart the portal nodes by issuing the /etc/init.d/amserver startall command.
Restart the Gateway nodes by issuing the /etc/init.d/gatweway start command.
Restart the specific Gateway instance used for iNotes access by issuing the /etc/init.d/gateway -n profile_name start command.
Why
Do I Need to Create a New Rewriter Ruleset for the Portal Desktop?
Maintaining a separate ruleset for the Desktop is useful for isolating only those rules that are absolutely necessary for the out-of-box Portal providers to work. The custom ruleset for the Desktop will also be less generalized than either of the default rulesets, which means there is less of a chance of things being rewritten improperly.
One entry which is specifically added to the Portal Desktop ruleset is:
<Function type="EXPRESSION" name="*findWindow" paramPatterns="y" />
This ensures that a link added to the Bookmark Provider to launch iNotes will launch with the rewritten URL. Depending on other rules, the link may appear to be rewritten by checking the browser status when performing a mouseover. This is a bit misleading in this case because the HREF attribute value will be rewritten, but the JavaScript_ onHandler will actually load the appropriate URL.
For example:
<A HREF="https://gw.sun.com/http://notes.int.sun.com/mil/uid.nsf" target="iNotes" onClick="javascript:Bookmark_findWindow('http://notes.int.sun.com/mail/uid.nsf'); return false;">iNotes</A>
The rule is wildcarded because each bookmark channel that is defined for the container will have its own findWindow function. The alternative would be to change the window.open function rule from a URL type to an expression type so that the bookmark URL passed to the findWindow function would be rewritten at runtime when the window was opened.
<Function type="EXPRESSION" name="window.open" paramPatterns="y" />
This would correctly rewrite the URL reference in the following function body:
function Bookmark_findWindow( url ){
Å@counter++;
Å@var urlWin;
Å@var windowID = "";
Å@var windowOption = "all_new";
Å@if( windowOption == "all_new" ){
Å@Å@windowID = "Webtop_url_number"+counter;
Å@Å@urlWin = window.open( url, windowID );
Å@Å@urlWin.focus();
Å@}
.
.
.
If the link is not rewritten by one of the methods recommended above, the browser attempts to initiate a direct connection to the Notes server, which will most likely fail if the user is on the outside of the firewall.
Do I Need to Create a New Rewriter Ruleset for iNotes?
By creating a separate ruleset specifically for iNotes-related integration, the ruleset can be maintained and modified independently of other default rulesets. This prevents rule trumping, and extends the ability to create a specific Gateway node that Notes users log in to in order to access iNotes. The overzealous default rulesets provided out-of-box with Portal 6 will break most of the menu functionality, including the Save, Save & Close, and Edit functions.
An additional entry was added:
<Variable type="EXPRESSION"> src </Variable>
This rewrites the dynamically created IFRAME source URL for the Web Page Panel type to work. This addition is necessary because of the arbitrary variable name used for the layout panel, and the fact that the value specified for the web page panel doesn't get rewritten correctly because of the encoded colon after the protocol identifier as shown:
var LayoutOption3 = 'http%3A//stocks.int.sun.com/channels/stocks_channel.html';
The layout variables are loaded into an array, and the dynamically created IFRAME src is set in the following SCRIPT block:
<script> function np(index){if (theWelcomeFrameset.frames[index].mL().readyState !=
"complete"){setTimeout('np(' + index + ')', 3000);
return;}theWelcomeFrameset.frames[index].lj(true);}function
nq(index){theWelcomeFrameset.frames[index].lj(false);
document.body.onclick =function(){theWelcomeFrameset.lj(true);};var
s="setTimeout('np(" + index + ")'," + 3000 + ")"; haiku.LB.add(s);}if
(h_ClientBrowser.isIE5()){nq(ht); var
mg=theForm.document.createElement("IFRAME"); with(mg){id=ld();
src=LayoutOption[ht];style.display="none";}document.write(mg.outerHTM
L);}else{var s="<layer>nyi - " + LayoutOption[ht] +
"<\/layer>";document.write(s);}</script>
The layout page to set the web page panel type looks something like FIGURE 1.
)
FIGURE 1 Layout
Configuration Page
The IFRAME for the third panel, when loaded properly through the rewriter, ends up looking something like FIGURE 2.
)
FIGURE 2
Example of an IFRAME
If the src assignment is not rewritten correctly, and the IFRAME is attempted to be downloaded, the browser alerts the user about mixed secure and insecure content on the page. Selecting No to "load the page content anyway?" displays a NavigationCancelled error in the IFRAME, and answering Yes displays an IE 404 or 500 error if the Browser is unable to initiate a direct connection with the iNotes server. This is one reason it is important to test the integration with the Gateway running in SSL mode, because it helps catch embedded objects which aren't being rewritten correctly.
Do I Need to Associate the New Ruleset with the Appropriate Gateway Instance?
To prevent the default ruleset from breaking the iNotes interface, ensure that iNotes will launch from the Bookmark provider. To get the web page panel types to work in the customized iNotes layout, the rulesets must be associated with the proper Fully Qualified Host Names (FQHNs) or DNS domains.
Do I Need to Create a Domains|Subdomains Entry for iNotes Server?
This is necessary if the Notes server is in a different DNS subdomain or domain than the portal server node. Adding an additional value to this section tells the rewriter that any content originating from that domain must be rewritten according to the mapping laid out in the Domain-Based Rulesets section. The most appropriate entry in the Domain-Based Rulesets section is used to determine how to find URLs which require rewriting in content originating from that hostname or domain.
Do I Need to Install a Portal Patch For iNotes to Work?
The iNotes integration requires a combination of configuration changes (the rewriter ruleset), and fixes or enhancements in the portal server Gateway component. The Portal patch contains the following fixes:
BugID 4780863 – Gateway strips off XML declaration tag.
Pages or response bodies that contain an XML namespace identifier which look like <?xml version="1.0" ?> end up having the root tag dropped. The direct effect on third-party applications is not clear, unless something depends on this root element being present.
BugID 4788050 – Rewriter should ignore comments which occur prior to opening the XSL tag.
If the opening Extensible Stylesheet Language (XSL) tag is preceded by anything else, the page will be rewritten. The correct fix for this particular problem needs to be carefully considered because there might be times when the XSL code must be rewritten because it is used in a transform that will control URL values.
BugID 4778676 – Gateway should not translate special characters (XML Entities) when rewriting XML.
For example, when an email message is expanded, Exchange sends a DAV SEARCH request with the following message body:
There are no URL references which matter that are not being rewritten correctly
But the > character is being translated by the Gateway XML parser. By the time it gets to the Exchange backend, the XML is no longer syntactically correct for the request to be serviced, and a multistatus response is sent with a 404 status in the response body.
BugID 4781754 – Not rewriting the URLs in CSS Content
CSS is used in many third-party applications for look-and-feel purposes. This is a Portal 3 fix for added functionality that has not yet been ported to the Sun ONE Portal Server 6 software.
Do I Need to Enable the Rewriting of CSS Content?
CSS content is used in various places throughout iNotes. Specifically, almost the entire skins implementation uses dynamically created CSS content to handle the look and feel of the primary interface.
Do I Need to Disable Rewriting of XML Content?
Disabling the rewriting of XML is used as a workaround for a corner case which still exists where specialized XML characters are still being translated by the Gateway. The visible result in Lotus iNotes is that if any of these characters are contained in the email headers (such as error notifications), none of the other headers will be fetched. By specifying the exact URL used to fetch the headers, the browser may display a similar error to the following:
The XML page cannot be displayed Cannot view XML input using XSL style sheet. Please
Note the translated ampersand. As the original XML indicates, the Gateway is translating the character as the XML passes through the rewriter.
... <entrydata columnnumber="5" name="$73"> <text>DELIVERY FAILURE: No route found to domain sun.com from server SUN/SUN. Check Server, Connection and Domain documents in Name & Address Book.</text></entrydata> ...
Do I Need to Modify the Notes.ini Start File?
More recent versions of iNotes contain an ActiveX component that does session-related cleanup once the logout link is selected. The result of this ActiveX running is that the Portal session is destroyed as well. This is not a rewriter problem because the behavior can be reproduced from a child browser by going directly to iNotes and logging out.
The modification to the notes.ini file circumvents the requirement to force the ActiveX not to run, or for ActiveX to be set to prompt instead of run in the browser security configuration. The following URL, when accessed through the Portal Gateway, destroys the Portal session:
/mail/uid.nsf/iNotes/Proxy/?OpenDocument&Form=s_Logout&CacheResults&MaxE
If s_ActXUpload is set to false, logout works fine, and without destroying the Portal session.
/mail/uid.nsf/iNotes/Proxy/?OpenDocument&Form=s_Logout&CacheResults&MaxExpires&TimeStamp=20021223T190926,36Z&charset=ISO-8859-1&PresetField
The code which runs this ActiveX looks something like this:
<script language="JavaScript"> if (s_UseActXUpload == "1"){var s='<div
style="display:none">'; s+='<object id="UploadControl" width="100%"
height="20" ' + 'classid="clsid:1E2941E3-8E63-11D4-9D5A-00902742D6E0"
' + 'codebase="' + getUploadAXCodebase() + '">' + '<param
name="General_Mode" value="' + 1 + '">' + '<param
name="General_DrawButtons" value="0">' + '<param name="General_URL"
value="' + getNsfPath(self) + '/' + "0" + "/" + h_PageUnid + '">' +
'<param name="General_ServerName" value="' + BTf () + '">' + '<param
name="Attachment_Lengths" value="">' + '<param
name="Attachment_Names" value=""><param name="Attachment_Times"
value="">'; s+='</object></div>'; document.write(s);}</script>
NOTE
If other applications require XML rewriting to be enabled to function correctly, a dedicated Gateway instance might need to be deployed specifically for iNotes users.
Do I Need to Modify Portlet URLs (if applicable)?
The portlets now ship with links that launch the native cross-browser webmail interface provided by IBM for web-based Notes accessibility. If the Notes user accounts are configured using the iNotes templates instead of the webmail templates, then selecting any of the creation links from the upper left corner of the individual portlets might result in an error similar to the following:
)
FIGURE 3
iNotes Warning Message
Do I Need to Restart the Portal Components?
The components need to be restarted to reread their profiles and pick up the new rewriter rulesets and domain mappings.