FileNet Image Services Resource Adapter 3.3a Release Notes
© Copyright IBM Corporation 2001, 2007. All Rights Reserved.

Introduction to 3.3a

New Features in 3.3a

New Features in 3.3.0

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

Source Code Sample
Known Software Problems and Restrictions
General Notes
ISRA Support

Contact Customer Support

Notices and Trademarks

Introduction to 3.3a

ISRA is a Resource Adapter for 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, GetDocumentContent2 (to retrieve multiple pages of a document in a single call) and ChangePassword interaction.
• Enterprise edition supports:
  AddDoc, DeleteDocs, GetDocProperties, 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 along with all the View edition interactions.

New Features in 3.3a

ISRA version 3.3a provides additional functionality in comparison to version 3.3.0. The following features have been added in ISRA 3.3a release:

• The IBM International Program License Agreement is added.
• ISRA 3.3a installer does not prompt a user to enter license keys for installing ISRA View/Enterprise editions. Instead of the License Key Screen, an Option screen is displayed that includes the set of checkboxes for View and Enterprise editions for which the installation is planned.

New Features in 3.3.0

ISRA version 3.3.0 provides additional functionality in comparison to version 3.2.1 Patch 1. The following features have been added in ISRA 3.3.0 release:

1. Farm or Cluster Support (Horizontal as well as Vertical) has been provided on BEA WebLogic and JBoss Application Servers with software based load balancing.
   Note 
   • ISRA 3.3.0 supports clustering on the following Application Servers: IBM WAS 5.1.1.x, 6.0.2, and 6.1
   • BEA WebLogic 8.1 SP6, 9.0, and 9.1
   • JBoss 4.0.x
2. Support for SAP NetWeaver 6.4 is provided on Microsoft Windows 2003 Service Pack 1.
3. Support for JBoss 4.0.4 on AIX 5.3 is introduced.
4. Support for ISRA to use JAAS Authentication Realm is provided on two Application Servers: IBM WebSphere and BEA WebLogic.
5. Security Cache creation at Application Server startup - ISRA internally creates a Security Cache for performance and optimization of Security Data. Starting with this release, the cache will be created at Application Server startup instead of at the time of first successful user login, provided the required IS patch is installed.
   In IBM WebSphere Application Server, security cache is created at the time of first successful user login and not at Application Server start up.

   The following IS patches support creation of Security Cache at Application Server startup:

1. 3.6.30 HFP 13 (and above)
2. 4.0.40 HFP 4 (and above)

The deployment descriptor attributes “CacheUserName” and “CacheUserPassword” are no longer supported.

6. Version Stamping - To check the version of installed ISRA and Sample Application, new utilities named “whichISRA” and “whichSA” are introduced. A new interaction named GetVersion is also provided to programmatically retrieve the version information of ISRA.
7. ISRA 3.3.0 functions independently of the locale of the server where it is running - A configurable property, "ISLocale" has been introduced which represents the ISRA Locale. The administrator can set the value of this configurable property as that of the IS locale. It is a lower-case two-letter code as defined by ISO-639. The default value of this parameter is “en”. 
8. Logging of separate instances of ISRA - Separate log files for all ISRA instances will be created and the ISRA Administrators are provided the ability to configure the names of the log files.
9. ISRA provides support for Multiple Workspace and Queue Services.

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.

Installation and Deployment

ISRA 3.3a can be installed on Microsoft Windows 2003 (Standard, Enterprise 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_ISRA33a.bin from the respective folder on the product media. For example, to install ISRA on Sun Solaris 9, execute setup_ISRA33a.bin from the /Solaris folder, and for Microsoft Windows 2003, execute setup_ISRA33a.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.

The installer supports jre versions 1.4.2 and below. jre should be installed on the machine before running the installer.

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

Issues Resolved in this Release

The following is the list of issues in ISRA 3.2.1 Patch 1 Release that have been resolved with Release 3.3.0:

• DTS 165153 : Users receive an error "Maximum Number of sessions reached" on re-logon through ISRA after changing password and logoff.
• DTS 173090 : ISRA pings all of the IS services (CSM, DOC) before it tries to start up. This impacts ISRA performance during start up/first logon.
• DTS 173105 : ISRA cache thread does not try to reconnect to IS in case IS is restarted.
• DTS 173106 : Password required for building ISRA cache is exposed in ra.xml.
• DTS 174659 : Customer is sporadically getting errors when browsing/retrieving a document through ISRA. Their application runs well for several hours or sometimes for several days before it gets stuck into ongoing broken connections with several J2CA0079E errors in different variations. The behavior seems to differ from user to user. Once an error appears, users cannot use the application further.
• DTS 174664 : A ResourceException occurs when performing the doCloseCache() RPC due to an Unknown Courier RPC message type. As a result, the connection is not closed properly.
• DTS 176452 : Cannot change some characters from Unicode to Shift-Japanese.
• DTS 177488 : Currently users with expired passwords can not change their passwords using ISRA as it requires a login into the IS system before a password can be changed. Users should be able to reset their own FileNet passwords even if their passwords have expired.
• DTS 177917 : The sticky notes shows an hour ahead than the time it was created or modified. The problem is noticeable after saving, closing and reopening the sticky note.
• DTS 178025 : ISRA passes incorrect queries to IS in some particular cases.
• DTS 178227 : Problems with viewing document with annotations through ISRA 3.1.
• DTS 178596 : FNImageViewer: Text annotation displaying white letters and white annotations for WFD created annotations.
• DTS 178782 : The error "<77,0,11> The object is busy (in use by others). Access not allowed at this time" pops-up randomly while trying to retrieve documents.
• DTS 180122 : Cannot retrieve 65536 byte size image with ISRA GetDocumentContent.
• DTS 180338 : Cannot display image when more than 20 application servers with a mixture of BES/Cache services are configured.
• DTS 181361/182173 : FNImageViewer: Cannot edit and delete margin notes created by WFD.
• DTS 181492 : Checksum Algorithm used in ISRA needs to be modified for improving its performance.
• DTS 195474 : ISRA installer fails to run against Solaris 10, but works fine for Solaris 9.

Source Code Sample

The FileNet ISRA 3.3a CD includes a Sample Application. This application was written in Java and is intended to illustrate the programming techniques used with the ISRA.

The source code for Sample Application is located in the directory where you installed ISRA, for example, \\fnsw\ISRA33a\Sample\Source.

Note: ISRA provides sample code for the purposes of demonstrating how to use the various APIs that are part of ISRA. All of the code that is around the particular API being explained is not suitable for any purpose other than the Sample Application. The assumption here is that the developer who wants to use ISRA has an understanding of Java and how it should be used. As such, we do not make any attempt to make the sample code “scale” or “perform”. No other intent is made or implied, and certainly, no warranty with regard to scalability or performance is being made. This sample should be used strictly as reference material.

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 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%20
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. 

ISRA 3.3a

1. If a user is deleted from IS and recreated, the ObjectID of the user will change, however ISRA will continue to hold the invalid ObjectID until the ISRA cache is automatically updated at the CacheRefreshInterval period. In this scenario, interactions involving Security objects might fail until cached meta-data is refreshed. ISRA cache can also be rebuilt by restarting the Application Server.
2. Any updates to IS like Doc Class information, Users/Groups information, Menu Values, Indices List, Printer Attributes etc. will be visible through ISRA only when cache is refreshed (after cache refresh interval specified in the deployment descriptor) or when Application Server is restarted.
3. The ISRA installer launches the setup using the JVM bundled within the ISRA installer. The bundled JVM is installed to a temporary directory and used to launch the installer.
4. WQS services allows user to create a queue in workspace on which user does not have permissions. WQS Service does not return any error tuple in this case.
5. Page Foot Note and Time Foot Note are always displayed while faxing documents. A fax operation always displays the page and time foot notes and the user cannot set his/her own values for them.
6. The implementation of digital signature functionality and COLD/COLD2 documents can be tested using the single page document content retrieval call on the Search/Browse page in the Sample Application. The digital signature and COLD/COLD2 document retrieval does not function as expected with the multi page document content retrieval in a single call. This is a limitation with the Sample Application.
7. Retrieval of multiple pages in a single call (getDocumentContent2) interaction could have performance issues while retrieving content of either large range of pages and/or if the range contains large page size.
8. IBM WebSphere 5.x and 6.x Application Servers destroy the CCI connection stored in HTTP Session object on exit of doPost()/doGet() methods of Servlets or JSPs. Because of this restriction, a user is allowed to fetch a set of records in a single call. For this, the corresponding changes have been done in the Sample Application. The Next button functionality has been removed, which was used to fetch the next set of records.
9. When a user with maximum concurrent logons (SLU) value set as 1 is logged into ISRA and the password is changed by applications other than ISRA (like IDM, IS etc.), he will not be able to login to ISRA using the new password till the time he logs off from IS. There is a JCA limitation that the user can be logged from IS only after the timeout of managed connection. Hence, the user will not be able to login again with the new password, instantly after logging off using the Sample Application. This problem can be avoided if the password of a user logged-in through ISRA is changed from ISRA and not from any external applications.
10. After ISRA deployment or Application Server startup, if the first user tries to log into ISRA with an expired password, he will not be able to change his password and login until some other user successfully logs in or until his password is changed at IS. This problem can be avoided if the following patches are installed on the IS:
    • 3.6.30 HFP 13
    • 4.0.40 HFP 4
11. On the HP-UX platform, when creating a response file for silent installation, formatting errors might be displayed. For example, "Error formatting options file entry (starting with "This file can be use..."): Illegal character "8" in encoding name." These type of errors can be ignored.

General Notes

Supportability on Development Platforms

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 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, 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.

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 FileNet Customer Support personnel for assistance.

Contact Customer Support

For information about contacting customer support:

1. Navigate to the Information Management support page ( http://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.
• ValueNet is a registered trademark of FileNet 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.