README

FileNet Image Services Resource Adapter

Version 3.3.0

September 2006

This document provides last-minute product information, updates to the documentation, and troubleshooting tips. For more information, refer to the documentation on the product CD or visit the CSS Website. This document contains the following sections:

Introduction to 3.3.0
New Features in 3.3.0
Layout of Product CD
Supported Platforms
Installation and Deployment
Issues Resolved in this Release
Known Software Problems and Restrictions
General Notes
ISRA Support

Introduction to 3.3.0

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.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. The ability to configure ISRA to use a JAAS Authentication Realm - Support for ISRA to use JAAS Authentication Realm is provided on two Application Servers: IBM WebSphere and BEA WebLogic Application Servers.

5. Security Cache creation at Application Server startup - ISRA internally creates a Security Cache for performance and optimization of Security Data. The cache will now be created at Application Server startup instead of at the time of first successful user login. 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 CD

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.

FileNet Image Viewer

Sun JRE 1.4.2 or 1.5.0_04 (5.0) is required for FileNet Image Viewer. ISRA will support viewer issues on other runtime(s) if it is determined that the same issue can be produced in Sun JRE 1.4.2 or 1.5.0_04 (5.0).

Installation and Deployment

ISRA 3.3.0 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_ISRA330.bin from the respective folder on the product media. For example, to install ISRA on Sun Solaris 9, execute setup_ISRA330.bin from the /Solaris folder, and for Microsoft Windows 2003, execute setup_ISRA330.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:

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.

Known Software Problems and Restrictions

BEA WebLogic Application Server

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

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

1. 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. 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.
   Fix pack for IBM WebSphere 6 is not available.
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

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. 

ISRA 3.3.0

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. ISRA installer uses the JVM bundled within it for the installation. If the installer does not find a platform specific JVM bundled, then it tries to launch the setup using the JVM installed on the server. Sometimes user might get an error "No VM found", in that case the workaround is to ensure that the bin directory of the installed JDK/JRE on the server is in the PATH. ISRA installer supports JDK/JRE 1.3 and above.
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

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.

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.