Readme

IBM FileNet Image Services Resource Adapter [ISRA] 3.4.0
© Copyright IBM Corporation 2008. All Rights Reserved.

March 2008

Introduction to 3.4.0

New Features in 3.4.0

Layout of Product Distribution
Supported Platforms
Installation and Deployment
Issues Resolved in this Release

Known Software Problems and Restrictions
General Notes
ISRA Support

Contact Customer Support

Notices and Trademarks

Readme Revision log

Introduction to 3.4.0

ISRA is a Resource Adapter for IBM FileNet Image Services (IS). This Resource Adapter is compliant with the J2EE Connector Architecture v 1.0. ISRA is a system-level software driver, which can be used by a Java application component (client) to interact with the IS. ISRA provides an alternative to IDM Web Services for accessing IS in a web application. In addition, it provides a Java based Web solution independent of Microsoft technologies or products.

ISRA is packaged in two editions as follows:

• View edition supports read-only interactions, namely:
  Logon/Logoff, FindDocuments, GetDocumentContent, GetDocClassIndices, GetMenuValue, IsAnnotated, GetAnnotations, GetPasswordStatus, GetVersion, GetFolderAttributes, ChangePassword interaction and getInteractionSpecsSupported.
• Professional edition supports:
  AddDoc, DeleteDocs, GetDocProperties, GetDocumentContent, GetDocumentContent2, UpdateDocProperties, CancelDocPropertiesUpdate, FileDocsInFolder, RemoveDocsFromFolder, GetDocFolders, GetFolderFolders, SaveAnnotations, GetWorkspaces, GetQueues, GetQueuesFields, GetQueueEntries, InsertQueueEntries, DeleteQueueEntries, UpdateQueueEntries, GetSecurityInfo, GetMenuDesc, GetDocClassDesc, PrintDocs, GetPrinterAttributes, CreateQueue, CreateWorkspace interactions, CreateFolders, DeleteFolders, UpdateFolderProperties and GetCacheList SetFCLOSEDProperty, GetWQServerName, GetWQSList, IsValidWQS, and getInteractionSpecsSupported.

New Features in 3.4.0

ISRA version 3.4.0 provides additional functionalities and features in this release:

• The IBM International Program License Agreement is added.
• ISRA 3.4.0 installer does not prompt a user to enter license keys for installing ISRA View/Professional editions. Instead of the License Key Screen, an Option screen is displayed that includes a set of radio-boxes for View and Professional editions for which the installation is planned.
• Deploying ISRA in an Application Server Cell: The Resource Adapter Archive (RAR) for ISRA deployment within a Websphere Application Server(6.x and above) cell is now Supported.
• ISRA Upgrade Capability from 3.2.1_P1 and 3.3.0 to 3.4.0: ISRA GA installer detects existing installed GA versions and performs an upgrade of ISRA (Interative/Silent mode) on all supported platforms.
• Deploying ISRA as an EAR file is now supported.
• Interaction using F_CLOSED property: A new interaction SetFCLOSEDProperty is added to ISRA, using which custom applications can set the value of F_CLOSED property in IS. Please refer the Programmers Guide for more details.
• Retrieving WQS Server names: A new interaction GetWQServerName is added to ISRA that helps to retrieve the WQS Server names. Please refer the Programmers Guide for more details.
• Fax Headline Message: In order to fax a document, currently, users can enter a single headline message in a single field that includes sender’s name, recipient's name and the relevant subject which is passed to ISRA as a single field. Instead of the single headline field, the custom applications can now be enhanced to have three fields, namely, From, To, and Subject. ISRA will continue to receive a single field and pass the same to IS.
• There is no more Crimson.jar dependency in Sample Application: ISRA Sample Application was using the Crimson implementation of XML classes to implement the Remote Printing functionality. IBM WebSphere Application Server did not provide this implementation, so this jar file was bundled with Sample Application only for WebSphere Application Server. With 3.4.0, this dependency is removed and ISRA Sample Application uses a generic implementation. For usage of crimson.jar for remote printing, please refer WAS6 deployment guide section "Configuring Sample Application".
• Enhancing the cache refresh mechanism in ISRA: The cache mechanism is enhanced to get refreshed periodically based on a specified interval. Other features are:
  • Choice to select Groups only or Users & Groups: A choice to cache groups only or users and groups is provided through a property in the “ra.xml”. If the customers choose to have only IS groups in cache they can do so and this will be faster for them to create/load the cache, which will improve ISRA performance.
  • Selective caching of metadata: Customers can now do selective caching of metadata, like having to choose among - Printer, Document Class, Menu and Key Field Objects through an option provided in “ra.xml”.
  • Reduction of JVM heap memory usage by 50% (676 MB > 340 MB): Several unused elements have been removed from security Cache data structure and that helped reducing the heap memory usage from 676 MB to 340 MB on WAS 6.x.
    
  • Fixed printer stub hanging: The issue with printer stub hanging in IS side during cache creation now has been fixed.
  • Avoiding redundant Cache creation/refresh at first logon: On WAS, the ISRA classes won't get loaded until first user logon even if its deployed already. So there is a chance for security cache creation to happen twice, one for deployment and the other for first user logon. This redundant cache creation has been avoided in this release, by checking for a Cache in progress flag. This feature implementation gives the user quicker login performance at first user logon.
• Enhancements to logging: Automatic purging of old ISRA RPC log files has been implemented leaving behind only 5 latest versions. Please refer the Deployment Guides for more details.
• LoadISRA Utility: A new utility application is introduced in 3.4 that can be deployed on AppServer to kick start the ISRA class loading. Please refer the Deployment Guides for more details.
• The Root Level Search in iPlanet has been extended: With this functionality, the ISRA administrators now will be able to mention the root level DN and because of that all users existing in the sub-hierarchies will be able to login to IS. So the administrators can simply specify the name of the domain in the ISRA deployment descriptor, and all users in the domain will be able to login successfully.
• IS Error Message Mapping Utility: A command-line utility, isra_msg accepts inputs as either IS error number or IS error tuple and returns the corresponding error message along with ISRA error code. This error code can be retrieved from a properties-file that is bundled in the jar file. This utility could be executed as a batch file (.bat) or a shell script (.sh), on Windows or UNIX platforms respectively.
• Common Installation Guide: There is a common Installation Guide available for ISRA 3.4.0.

Layout of Product Distribution

Supported Platforms

• BEA WebLogic Server 8.1 SP6/9.0/9.1 (WLS) on Microsoft Windows 2003 Service Pack 1, Sun Solaris 9/10, HPUX 11i v1, IBM AIX 5.2 SP2/5.3 SP3 and RedHat Linux AS 3.0/4.0.
• IBM WebSphere Application Server 5.1.1.x/6.0.2/6.1 (WAS) on Microsoft Windows 2003 Service Pack 1, Sun Solaris 9/10, HPUX 11i v1, IBM AIX 5.2 SP2/5.3 SP3 and RedHat Linux AS 3.0/4.0.
• JBoss 4.0.x Application Server on Microsoft Windows 2003 Service Pack 1, Sun Solaris 9/10, HPUX 11i v1, IBM AIX 5.3 SP3(JBoss 4.0.4 only) and RedHat Linux AS 3.0/4.0
• Oracle 10g (9.0.4) and 10g Release 3 (10.1.3) Server on Microsoft Windows 2003 Service Pack 1, Sun Solaris 9/10, HPUX 11i v1, IBM AIX 5.2 SP2/5.3 SP3 and RedHat Linux AS 3.0/4.0.
• Sun One 8.1/9.0 Server on Microsoft Windows 2003 Service Pack 1, Sun Solaris 9/10, HPUX 11i v1 and RedHat Linux AS 3.0/4.0
• SAP NetWeaver 6.4 Server on Microsoft Windows 2003 Service Pack 1.
• Sample Application supports Netscape 7.x and Internet Explorer 6.0.

• ConnectionFactory is qualified with a secured JAAS Authentication Realm on additional Application Servers.
• Daeja is qualified with new IDM COLD Module: ISRA is qualified with the new Daeja version that is bundled the IDM module for rendering of COLD documents. This module enhances the alignment of COLD and background templates.

Installation and Deployment

ISRA 3.4 can be installed on Microsoft Windows 2003 (Standard, Professional and DataCenter), Sun Solaris 9/10, HPUX 11i v1, IBM AIX 5.2 SP2/AIX 5.3 SP3 and RedHat Linux AS 3.0/4.0 Servers. To install ISRA on AIX, HPUX, Solaris or RedHat Linux platform, execute setup_ISRA340.bin from the respective folder on the product media. For example, to install ISRA on Sun Solaris 9, execute setup_ISRA340.bin from the /Solaris folder, and for Microsoft Windows 2003, execute setup_ISRA34.exe from /Windows folder on the product media.

To deploy ISRA on the target Application Server, follow the steps explained in ISRA deployment guides for the respective Application Servers. To verify the successful deployment, deploy and access the ISRA Sample Application. The Sample Application deployment and configuration is also explained in the ISRA deployment guides. ISRA Programmer's Guide and Deployment Guides for all supported Application Servers are located in the /Docs folder of the product media.

After installation, the installer creates the following files/directories in the installed directory:

Note: Adobe Acrobat Reader should be installed in your machine for reading the PDF Guides.

Issues Resolved in this Release

The following issue has been resolved with Release 3.4.0:

ecmdb	APAR	Files Affected	Lib	Description
00745723	35590537	Originally deployed ISRA.rar (ISRA 3.4.0), ISRA.jar	IS	Unable to view annotations that was created by a deleted IS user: After upgrading from ISRA 3.3 FP2 to FP5 (to fix a mem-leak issue on their WAS server), annotations that were created by a deleted IS user cannot be viewed by other users. The following error appeared: "Annotation Exception: Annotations failed to load".

Known Software Problems and Restrictions

BEA WebLogic Application Server

On WebLogic 8.1 Application Server, a blank page is displayed during login in ISRA Sample Application. To fix this problem, edit the file <WebLogic Installation Directory>\user_projects\mydomain\startWebLogic.cmd (or startWebLogic.sh for UNIX platforms) to include ISRA.jar in CLASSPATH environment variable, and restart the server. Alternatively, you can set ISRA.jar in the CLASSPATH on the server.

SAP NetWeaver Application Server

While deploying FNImageViewer on SAP NetWeaver Application Server 6.4, an error is thrown as "At least one <welcome-file> tag must exist in the <welcome-file-list> tag. This problem will be fixed in SAP NetWeaver WAS 6.4 SP19. Until this service pack is released, please refer ISRA Deployment Guide for SAP NetWeaver Application Server for a workaround to resolve this problem.

IBM WebSphere Application Server

1. IBM WebSphere 5.1.1.x/6.0.2/6.1 Application Servers destroy the CCI connection stored in HTTP Session object on exit of doPost()/doGet() methods of Servlets or JSPs. To fix this problem in IBM WebSphere 5 apply the IBM WebSphere 5 Fix Pack 2. Please refer http://www.ibm.com/Search?y=11&lang=en&cc=us&q=PQ73966&Search.x=28&Search.y=11 for details on how to apply the fix pack.
   For IBM WebSphere 6.0.2 and 6.1, please refer http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg1PK25725 to fix this problem.
2. IBM WebSphere Application Server does not provide the crimson implementation of DocumentBuilderFactory class. The Sample Application uses crimson implementation of DocumentBuilderFactory class to implement the Remote printing functionality. Please refer to the IBM WebSphere Deployment guide, which gives detailed steps on how to use the crimson.jar with the Sample Application. For reference, the PMR number for the case opened with IBM is PMR 83866,756,000.
3. IBM WebSphere will not destroy the last connection with IBM FileNet IS. IBM WebSphere creates parked connections because of which one user always remains logged on to IS. To fix this problem in IBM WebSphere 5 apply the IBM WebSphere 5 Fix Pack PK00210. Please refer
   http://www-1.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q1=PQ86338&uid=swg27004936&loc=en_US&cs=utf-8&lang=en for details on how to apply the fix pack.
4. IBM WebSphere Application Server passes the subject as null for container managed sign on, hence ISRA throws an "Invalid Arguments Passed" error with container managed sign on. IBM provided the following links related to this issue: For setting up the context so that the lookup is not cached:
   http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/rnam_example_behavior.html For JNDI caching in WebSphere:
   http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/cnam_naming_caching.html
5. In case of failover scenarios, there is a possibility that the user may have to perform the operation again to complete the request. For example, in case of AddDoc interaction in the Sample Application, ISRA will throw the "Invalid InputStream object" error if the primary server goes down.
6. If a client application packages any external jars in the WEB-INF/lib of the application and the Web Module class loader is set to Parent Last, then a ClassCastException occurs. To fix this problem in IBM WebSphere 6.x, apply the IBM WebSphere fixpacks 6.0.2.15 and 6.1.0.2. Please refer http://www-1.ibm.com/support/docview.wss?uid=swg1PK26233 to apply this patch. 

General Notes

Supportability on Development Platforms

IBM FileNet has not qualified ISRA and the ISRA Sample Application to run under development platforms such as WSAD, BEA Workshop, or any other development platforms. This is primarily because IBM FileNet Engineering may not be able to keep up with the dependencies on specific development platform configuration.

However, ISRA and ISRA Sample should be able to run under any development platform that provides managed environment and runtime support for JCA 1.0. Since, IBM FileNet has not qualified these development platforms with ISRA and ISRA Sample, it is customer's responsibility to determine the proper setup and/or configuration that enable ISRA and Sample Application to work under the specific development platform. If there are any problems during configuration, deployment, development or runtime relating to ISRA under these development platforms, it is the customer's responsibility to verify if the same problem also occurs under the qualified Application Server environment.

Globalization

ISRA supports all character sets supported by Image Services, which are single byte character sets, as well as some multi-byte character sets. Unicode character sets, such as AL16UTF16, AL32UTF8, or UTF8 are not supported at this time. For a detailed overview of the supported character sets, please refer to the Image Services System Administrators manual.

For "Points to be noted for Globalization", please refer the Appendix for Globalization in ISRA 3.4.0 Programmers Guide.

ISRA Supports

Note: ISRA is currently supported for production deployment only in the Managed Environment. If you experience any difficulties with the product media or ISRA, please contact your IBM FileNet Customer Support personnel for assistance.

Contact Customer Support

For information about contacting customer support:

1. Navigate to the Information Management support page ( www.ibm.com/software/data/support ).
2. Select the appropriate IBM FileNet product from the "Select a category" list.
3. From the Product Support page, click Flash 8 Oct. 2007: How to get support for IBM FileNet products.

Notices and Trademarks

• IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both.
• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
• Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom.
• Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
• Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
• UNIX is a registered trademark of The Open Group in the United States and other countries.
• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office.
• IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency, which is now part of the Office of Government Commerce.
• Other company, product, or service names may be trademarks or service marks of others.