How does IBM Rational RequisiteWeb cache documents?

RequisiteWeb leverages Microsoft DCOM technology to convert documents to HTML in RequisiteWeb. This technology is used when an end user chooses to simply "view" a RequisitePro document from the web interface. When a document is opened in RequisiteWeb it is rendered in HTML format. The HTML rendering displays the most current information in the Word document. This rendering displays non requirement content in a read only state (basic text, headers, footers, table of contents, pictures, etc....) that are not part of the RequisitePro requirements. RequisitePro requirements are displayed as a hyperlink. The hyperlink allows a user to select the requirement and open it and the Requirement Properties will display. Because we leverage RequisitePro "extended" editing functionality if the requirement content is changed the most current information will display in these documents.

DCOM Basics

RequisiteWeb relies upon the install of Microsoft Word on the webserver in order convert documents to HTML. The Microsoft Word DCOM module is used to perform this conversion. During the configuration of RequisiteWeb we suggest to create a Windows account and place that account in the local administrators group on the webserver. The local administrators have access writes to invoke DCOM on the web server. The RequisiteWeb account associated with the RWP ReqWeb Servlet Service is the user leveraged to perform the authentication and convert the document to HTML through DCOM.

Document Conversion Process

The RequisiteWeb account associated with the RWP service is used with the rqproxy.exe process to navigate to the RequisitePro project directory. If the account has the appropriate rights, the project can be opened and any resources in the project directory can be accessed. When a RequisitePro document is opened in the RequisiteWeb interface a project directory is created in GenDoc for the project. The default location of the GenDoc directory depends on the version of RequisiteWeb installed

Each project directory will have a unique number which matches the RQGUID in the project.rqs file:

Caching and Additional Details

The first time a document is opened in RequisiteWeb, the document will be copied to the file server and an HTML rendering of the document will be generated. The document is copied from the RequisitePro project directory to GenDoc. Each time the document is opened, a comparison process is compared between the RequisitePro project directory and RequisiteWeb. If there are updates found in the document then the version of the document is replaced on the webserver with the new version of the document. If the document has not changed then the current version is rendered.

Conversion Issues

Due to the fact RequisiteWeb is reliant on Microsoft Word DCOM, if the document cannot be converted to HTML, RequisiteWeb may not be able to render the document in RequisiteWeb. In this case a timeout type error message is received by the user in RequisiteWeb. A timeout is received because we DO NOT persist any conversion errors that happen in the HTML conversion process through Word from the webserver in the end user's browser. If an administrator were to review the webserver directly, he\she may see such Word conversion errors on the webserver directly.

Troubleshooting:

Conversion problems may occur as a result of: characters are present in the document which cannot be converted to HTML (some font types, tables, and more) and in some cases document corruption. If conversion errors are displayed by RequisiteWeb to end users indicating a document cannot be opened, generally IBM Support will recommend for the customer to attempt some troubleshooting activities including:

• Converting the document to HTML outside of RequisiteWeb in Microsoft Word. If dialogs are received that font types cannot be converted to HTML, RequisiteWeb will likely not be able to convert the document. At this time it is suggested to head the prompts in the Microsoft Word document conversion process and change the fonts accordingly.
  Limitations when displaying a Word document in the Rational RequisitePro® client for Web
• In other cases, document corruption can also be a culprit. There are some Microsoft Word technotes to address document corruption, but generally a quick way to address the document corruption is to save the document in rich text format and then save back to a .doc format. (In some cases document formatting may be removed as part of the conversion process.) The complete steps are documented in the following technote.
  Methods to fix a corrupt RequisitePro document

When there are conversion issues on the RequisiteWeb server there can be issues with latent Winword.exe processes. In some cases these processes remain latent even though the document conversion failed. Winword processes may need to be killed through Task Manager on the web server. In instances like this there can be failed conversion files on the RequisiteWeb server that will impede the document from opening until GenDoc is cleared. (for example, content is deleted).

If there are conversion problems a systematic approach should be taken to rectify these Microsoft Word conversion issues. (Please note the behavior experienced in RequisiteWeb is by-product of Microsoft's failed DCOM conversion process.)

• Troubleshoot the documents and ensure documents may be rendered in an HTML format outside of RequisiteWeb in Word by using the save as HTML option. One of the solutions documented in the following technote provides instructions on how to convert the document to html outside of RequisiteWeb.
  Unable to generate the HTML document:AutomationException: 0x80044e2d in ReqWeb
• Ensure there is no corruption in the document and address the corruption and replace the original document in the RequisitePro project directory with the updated file.
• Remove the "suspect" document and or documents from GenDoc on the webserver. If there are multiple documents failing, the html and version of the document should be removed from the server, and or the entire project directory under GenDoc.
• The document files will be replaced and or the project directory the next time the document is opened.