Release Notes

Optimal Trace^TMProfessional Version 5.0

August 2007

System Requirements for Optimal Trace^TMProfessional:

- Pentium 3-class processor or equivalent

- 256 MB of RAM

- 150 MB of available hard disk space

- Microsoft Windows 2000/XP/2003

- Microsoft Word 2000/2002/2003/2007

- Adobe Acrobat Reader for Optimal Trace^TM Professional Help Files

Optimal Trace^TMProfessional has not been tested to run on Windows 95/98, and is not supported on these platforms.

Installation Instructions

To Install Optimal Trace^TM Professional V5.0

- Ensure you have at least 150 MB of available disk space

- Ensure you have uninstalled any previous releases of Optimal Trace^TM Professional (See next section for details)

- Run the Optimal Trace_Professional.exe file to install.

To Uninstall Optimal Trace^TM Professional V5.0

- On the Start menu select Settings, Control Panel, Add/Remove Programs

- Select Optimal Trace^TM Professional and press the Add/Remove... button.

Never uninstall by just deleting files. This may prevent future installations of Optimal Trace^TM Professional from working.

Note: Uninstalling Optimal Trace^TM Professional will leave project files, generated documents and change logs on your hard disk. This allows you to preserve any previously created project documentation if migrating to a new version of Optimal Trace^TM Professional.

New Features In Optimal Trace 5.0

New Features For 5.0

Version 5.0 is the latest release of Optimal Trace Professional, the market leading Business Requirements Management solution.

The core themes of 5.0 are:

Ø Supporting Hybrid Project approaches - Combining the benefits of ‘Structured’ Requirements with ‘Simple' Requirements. These are designed to accommodate more assertion or flat requirements styles.

Ø Supporting infinite levels of structural customization on projects & project templates. This is facilitated by extending custom property definition from the project level down to the package (group) level.

Ø A number of key usage and currency enhancements that ensure that Optimal Trace is best of breed for requirements capture and management.

OT 5.0 offers complete structural freedom to link all forms of requirements (simple/flat/assertion based) to 'goal-directed' requirements that reflect business intent.

OT 5.0 carries on in the OT tradition of emphasizing ease of use (& ease of deployment) while at the same time offering the most flexible approach to creating projects that meet your unique needs.

Introduction of Simple Requirements and Items

Optimal Trace already emphasizes the importance of Requirements Structure fostering a Requirements Driven approach to Testing and all aspects of the software lifecycle.

Extending this, 5.0 now introduces a new construct called 'Simple Requirements'.

Simple Requirements can be used to capture a more 'flat/assertion' style of requirement augmenting the structured flow requirement style. Simple Requirements comprise lists of Requirement Items, consider these as sub-requirements. These Items can be associated through Refinement with more detailed Structured Requirements.

Some examples of usage scenarios for Simple Requirements/Items are:

§ High level marketing, product management and other 'flat' feature style requirements types where flow structure is not necessary and where a tabular structure is more suited

§ Business Rules where certain system wide rules apply to many structured requirements

§ Data oriented requirements where the need exists to specific format & validation information in a tabular fashion

Support for Package Level Custom Property Definition

Optimal Trace has always provided an extensive capability to customize project structure. This has meant that unlimited sets of additional fields were definable at project level and shared across the project.

5.0 now provides complete flexibility in project structure by extending custom property definition down to the package level. This means that Structured Requirements and Simple Requirements now can 'own' their own custom fields in the context of the current package.

For example now 'flat' style requirements categories such as performance etc. may have custom fields such as; 'Average Throughput', 'Peak Throughput', 'Concurrent Users' etc. defined, whereas other 'flat' style requirements in the same project may have different properties.

Key capabilities include:

§ An ability to apply different definitions to different packages

§ An ability to 'inherit' Custom Property definitions from the parent package

General

Other key highlights of this release include:

q Provision of Spell Check

q Option to Generate Clean Word Docs without hidden mark-up (non-reversible)

q Support for MS Word 2007

Known Issues

The following are known issues:

Issue No 1686

Inconsistent error message when cancelling word document generation, and Word may crash: Depending on when you interrupt the document generation process, you may get a strange COM exception returned from MS Word, and Word may crash.

Workaround: Ignore the exception from MS Word, Optimal Trace^TM Professional will continue as normal. You may additionally need to kill the 'winword.exe' process in Task Manager.

Issue No 2147

Document Generation and Form protected Style template: When using a MS Form document as a Style template for a document generation Profile, Optimal Trace will not generate the document if the Form is 'protected'.

Workaround: 'Unprotect' the Style template Form before generating.

Issue No 2172

Links don't work in generated document: If you generate a Form based profile (e.g. Default Form) you will notice that clicking on any link in the document (e.g. Table of Contents, hyperlinks, etc) will not work.

Workaround: This is a know feature of Word Forms, these links will not work if the document is protected. To allow them to work, 'unprotect' the form by un-clicking the 'Protect Form' toolbar button.

Issue No 2267

Incorrect Macro security settings in Word can lead to Application Error: If you generate a document from Optimal Trace and an Exception occurs, please ensure that your Security Settings in Word are set to 'Low'.

Workaround: In Word, select the 'Tools/Macro/Security' settings dialog box, and make sure that the option is set to 'Low'

Issue No 2354

Change History changes do not get included as part of a document update: This is by design, we purposely don't include any Change History additions as part of a document update if that profile has a Change History element.

Workaround: You can generate either a standalone Change History document or re-generate your document from scratch to see all the Change History entries.

Issue No 2364

Non-ASCII control characters in a Project produces errors generating Word documents: If you have non-ASCII characters in an Optimal Trace Project (this usually happens when copy/pasting from an external format such as PDF files) and you generate a Word document, this process can fail with a VB Exception.

Workaround: Ensure there are no non-ASCII characters in your Optimal Trace Project, these usually appear as a square character in Optimal Trace.

Issue No 2501

Out of Memory Errors while generating HTML or Image Maps from large Projects: Generating Image Maps from large Projects is very memory intensive. If you repeatedly generate the 'Full Project' HTML Report with a large Project you will eventually get an Out of Memory Error. The same can happen if you repeatedly 'Save Image' for a very large Project.

Workaround: Try and limit generating HTML for large Projects or Image Saving to once per Optimal Trace session. If you do get an Out of Memory error, restart Optimal Trace and re-try generating HTML or Save Image once again.

Issue No 4031

Orphaned Branch or Refinement in the Requirements Map: In certain rare situations a line representing a Branch or Refinement may get duplicated resulting in an orphaned line remaining on the graph. This line has no connection to any Requirements or Steps and as such will not result in any errors or corruption of projects, but may prove an annoyance.

Workaround: You need to open a new window (Window -> New Window) and close the original window and continue as normal.

Issue No 4241

Cannot add form fields to non-form document profiles: If you attempt to add form fields to a non-form document profile, Optimal Trace may not be able to reverse or update the profile.

Workaround: Avoid using form fields in non-form based profiles. It's perfectly ok to add custom fields to form based profiles, but just don't mix the two.

Issue No 4287

Table of contents page numbers can be incorrect: Sometime after updating or reversing a document, you may notice that the page numbers in the table of contents to not correlate correctly to the document content.

Workaround: This behaviour seems to be related to the large amount of hidden text that Optimal Trace documents contain. Removing all the hidden text can help here (but you will no longer be able to update or reverse the document). See the Document Generation: General Tips section below for details on how to remove all the hidden text in a document.

Issue No 4427

Document Generation will fail if you use 'xxxxx' as a Requirement name: 'xxxxx' is a reserved word used internally by Optimal Trace document generation, and if you use it as a Requirement name in your Project, document generation will fail.

Workaround: Avoid using 'xxxxx' as a Requirement name.

Issue 4672

Type of images generated during Report generation: It should be noted that the style of images generated during Report generation (using the 'Default HTML' report for example) all depend on what 'graph display option' is selected in the application.

Workaround: You can vary the images by right clicking on the Requirement Map and changing the Package display style.

Issue 4757

'Hide Steps' option can cause instability when moving Steps: under certain circumstances, using the 'Hide Steps' Requirement option along with moving Steps can cause Optimal Trace to crash.

Workaround: try and avoid using the 'Hide Step' Requirement options.

Issue 4861

Using the Change History in a Report: By default, the Project Change History is not passed to the Velocity Report generation engine. This is for performance reasons.

Workaround: to use the Change History from a new Report, change the 'passChangeHistoryToReportGenTemplates=No' setting in 'Default.properties' (located in the Optimal Trace installation directory) to 'passChangeHistoryToReportGenTemplates=Yes'.

Issue 4876

Problems with 'Create Reserved Area' menu option in Word: To begin with, it's recommended to display hidden text before using this feature (Optimal Trace->Toggle Hidden Tags). This is because the caret may not be at the correct position, even though it looks fine without the hidden text on screen. What can happen, for instance, is that the Reserved Area gets inserted into the middle of another XML tag, which destroys the document's structure.

Workaround: In any event, most of the time Reserved Areas are unnecessary, as it is possible to insert text as-is into almost all areas of the document without needing any "wrapping". Reserved areas are mainly needed for the characters '<' ,'&', or similar input that would interfere with the document's XML structure.

The best approach is the following:

1. Turn on hidden text

2. Insert your new content as-is, at the correct caret position

3. Save and close the document

4. Try reversing the document into the corresponding Optimal Trace project. If any XML parse errors are flagged, click on the error location '...' button and wrap the offending text in a Reserved section. This will presumably be the new content you have just entered.

5. If no errors were reported by the import process, then everything should be fine. You can either cancel or continue the merge process, as you like.

Issue 4877

Problems with 'Replace IDs and Names' menu option in Word: Indiscriminate use of this feature can cause problems and leave the document in an invalid state, so use it with caution.

Workaround: The following is recommended:

1. Make a backup of the document before doing any advanced editing along these lines.

2. Turn on hidden text.

3. Carefully select the area that needs updating. Make sure that any ID strings (usually at the start of a section) that you wish to update are included in the selection.

4. It will help to clarify exactly what 'Replace IDs and Names' does. It updates the IDs and names of any objects it detects in it's selection. However it does not update the IDs of other objects that these objects was refer to. So for instance, if you copy and paste a refinement, then selected the newly pasted area and click 'Replace IDs and Names', this new refinement will receive a fresh name and ID. However, it's source StepId and destination Requirement ID will not be updated. Therefore there will be 2 refinements starting from the same step and refining to the same Requirement, which is illegal. This will show up as an error when this document is reversed into Optimal Trace. In this and similar situations, further manual editing of the document is necessary after 'Replace IDs and Names' has been run.

5. Replace IDs and Names also corrects the Step Position numbers on any Step tables it finds. This is a convenience for the user as manually fixing Step Position numbers can be time-consuming.

Issue 4878

Problems with 'Duplicate current row' menu option in Word: This menu item will duplicate the current row the caret is positioned on (e.g. a Step in a Scenario Table). You cannot use this feature to add a new step to an empty table, there must be one already there for it to copy. The duplicated item will get a fresh name and ID, and if it's a Step, any affected Step position numbers will be updated. However it will not update any other properties of the duplicated object, so sometimes further manual editing is necessary.

Workaround:

1. Turn on hidden text and navigate to a branch table (which is hidden by default).

2. Place the caret on a particular branch and select 'Duplicate Current Row'

3. Select 'Toggle Hidden Tags' again as this macro turns off hidden text.

4. The new branch will have a new name and ID, but the IDs of it's source and destination Steps will remain the same. Therefore you now have 2 branches coming from the same Step and branching to the same Step, which is illegal. This will show up as an error when the document is reversed.

5. The new branch will have to manually edited to correctly contain whatever sourceID and DestinationID are required.

Issue 4984

Problems with manually setting tags to hidden in Word: Sometimes, if a document is being manually edited and the editing involves changing hidden text to visible text, or vice-versa, problems can occur. A typical problem is that even though only one word was changed from non-hidden to hidden, a large amount of the document surrounding that word automatically gets changed to hidden text as well. Including important Optimal Trace data such as the ActorList, for instance. Then, when the editing is finished and 'Optimal Trace->Toggle Hidden Tags' is selected, the ActorList will appear to have disappeared, as it is now rendered in hidden text.

The reverse problem can also happen, where a quantity of previously invisible content suddenly appears. Word is trying to automatically update the underlying style in that paragraph, rather than just update the selected text.

Workaround: - firstly, the document should always be backed up before commencing manual edits, as there are many traps like this.

To get rid of the immediate bad formatting, click undo until the document has reverted to it's state before the hidden-text edit had started.

Now click Format->Style (or Format->Styles and Formatting depending on your version of Word)-

Now select the Style type of the text you were editing. Usually 'Body Text', 'Hidden', or 'Normal' but it could be any of the other types as well. The style type of the selected text appears in the Formatting toolbar, which can be turned on under Tools->Customize->Toolbars.-

When the correct style type has been selected, click 'Modify...' and deselect the 'Automatically Update' checkbox.

Now it should be possible to change the text from hidden to non-hidden in safety. This problem typically occurs when some of the hidden XML tags in a generated document have been accidentally damaged, and the user is fixing the errors manually.

Issue 5122

Problem with validating a Skeleton Document that is already open: If your editing a Skeleton Document in Word, and you validate it in Optimal Trace (from the Document Settings screen), you risk loosing work as Word does not let you save and continue properly.

Workaround: avoid validating a Skeleton Document and editing it at the same time.

Issue 5389

Print Preview for Optimal Trace Documents shows hidden text.

Workaround: In Word, go to Tools/Options/Print and ensure 'Hidden Text' is unchecked.

Issue 5414

Problem copying locked Elements in Optimal Trace: copying/pasting Optimal Trace Elements that are locked by another user may cause problem in Optimal Trace under certain conditions.

Workaround: try to avoid copying/pasting locked Optimal Trace Elements.

Issue 5465

Canceling some actions in Optimal Trace does not release locks: if you do something in a dialog in Optimal Trace (e.g. move a Requirement) and then cancel the action, the objects in question will still remain locked by Optimal Trace.

Workaround: save your project to release the locks.

Issue 5470

Document Generation Custom Property restrictions:

1.  Custom Properties have to be contained in a table, they are bound to tables.

2.  Custom Properties are either row-or column based and again this is statically bound. You can't change your Step Custom Properties from column type to row type by editing the skeleton doc, for instance.

3.  Custom Property Template details (name, Id etc) have to appear before the corresponding Custom Properties in the skeleton doc. So you can't put your Custom Property name on the right of a row (if it's row-based), it has to appear to the left.

4.  Column-type Custom Properties can't appear in the leftmost column. There are no restrictions on row type Custom Properties.

Issue 5474

Document Generation Profiles cannot contain the same Element data twice:

E.g. in a Document Profile, you cannot have a Requirement 'Description' repeated twice anywhere in the profile.

Workaround: there is no workaround for this.

Issue 5535

Document Generation cannot reverse '...' values: '...' is a reserved word of sorts in reversing a document, any valid values of '...' will cause invalid conflicts in the Merge Tool.

Workaround: try avoiding using the value '...' in your data.

Issue 5549

Can't Auto-Generate a document if any Project Element has more than 13 Custom Properties: if you attempt to generate a document, where a Project Element has more than 13 Custom Properties, you will receive the following error message from Word:

"Internal error: Error code: 0x800403e8

Error description: Unable to automatically add and format Custom Property..."

Workaround: This is a Word restriction, however it is possible to create a Custom Profile with more than 13 fields ok.

Issue 5611

No locally locked icons when pasting/redoing: no locally locked icons appear in Optimal Trace in certain situations, e.g. if you undo a Requirement delete, or if you paste a Requirement.

Workaround: there is no workaround.

Issue 7073

Uninstall fully removes URI registry keys: If you uninstall Optimal Trace, it fully cleans up the windows registry. However, if you have a previous installation of Optimal Trace (or an installation of Optimal Trace Professional), the URI's will stop working. This is because the newer uninstall would of removed the 'Optimal Trace' URI setting.

Workaround: To re-register the 'Optimal Trace' URI setting in the registry, it is necessary to re-install the older version of Optimal Trace.

Issue 7494

Optimal Trace won't start if you have a shortcut to Desktop on your desktop: If you have a shortcut 'Desktop' on your desktop, Optimal Trace will not start correctly.

Workaround: This is a bug in the underlying java JDK version used in Optimal Trace (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5065874). To get Optimal Trace to start correctly, remove the shortcut to 'Desktop' on your desktop.

Issue 7544

Cannot split Custom Properties in Document Generation: Note that you cannot split up Custom Properties in a generated document, i.e. you can't have property values spread across different tables.

Workaround: There is no workaround for this, it is by design.

Issue 8443

Spell Check does not check Custom Property Templates: Spell Check will only check Custom Property Templates (i.e. the Custom Property Names, Definition, Default Value, etc) of a Package if that Package is not shared and there exists an element in that Package that has contains those custom properties.

Workaround: If you find this happening, create an element in the parent Package which is not being shared, and run Spell Check again. This will correct all sub Packages which are sharing with the parent Package.

Troubleshooting

Document Generation: Performance Tips

When generating documentation for very large projects, the generation performance can be dramatically improved (up to 50% with standard MS Office configurations) by adjusting the priority settings for Professional and Microsoft Word within the Windows task manager.

To do this, locate the Professional and Word processes; called 'Optimal Trace' & 'Winword' respectively. To adjust the priority, right click on each process and click 'Set Priority'. Set the priority to 'high' for each process.

WARNING: Setting the priorities to high will prevent other running applications from getting CPU time and you are effectively prevented from interacting with your machine until generation is finished. When finished generation, be sure to reset the priorities back to 'normal'

Document Generation: General Tips

The following settings can be set that can solve issues appearing when dealing with Word document generation.

1. Security settings. The Word generation in Professional relies on macros, which are embedded in word. If your security settings are set to high this will prevent generation. Ensure that the security setting is at 'low'. Access this from the tools>>macro>>security… menu option.

2. Spurious WinWord processes. In many cases where issues are encountered, these can be traced back to rogue Word processes that have not been shut down. Ensure that all such processes are shut down prior to document generation. To see how many 'WinWord' processes you have currently running look at the 'Processes' tab in the Task Manager. For each process right click on it and hit the 'End Process' option.

3. In cases where updates to word documents are failing, this can be isolated to a setting in word associated with background saves. If you see problems, try un-checking this option in Word. To do this, in Word go to the Tools>>Options menu and select the 'save' tab, then uncheck the 'Allow Background Saves' setting.

4. One way to decrease the size of a document is to remove all the hidden Optimal Trace text. Note that when you do this, you will no longer be able to update or reverse that documents, and re-generating the document will result in all the hidden text being re-inserted. To remove all hidden text in a document, do the following:

- Navigate to the top of the document, and select the Edit/Replace menu option

- Make sure that both the 'Find' and 'Replace' fields are empty

- Select the 'More' button

- Select 'Format/Font' button to bring up the 'Find Font' dialog box

- Click on 'Hidden' once, turning it from grey to black

- Hit 'OK', hit 'Replace All'

Optimal Trace Performance Tips: The following are performance tips to help Optimal Trace scale for large Projects:

1. Adjusting the Professional Server Upper memory limit for large Projects:

It is recommended to adjust the Professional Server upper limit for large Projects. To do this, follow the steps below.

1. Stop and close Optimal Trace Professional Server

2. Edit the server.properties file (in the installation directory).

3. The jvmArgs property tells the server the maximum amount of memory to use e.g. jvmArgs=-C-Xmx500m. Modify the number to the required upper memory in megabytes e.g. to set the upper memory limit to 800 megabytes, set jvmArgs=-C-Xmx800m

4. Close and Save server.properties. When the server is restarted it will use up to the specified amount of memory.

2. Turn off Activity Diagram Name:

1. Open 'default.properties' file that shipped in the Optimal Trace installation directory

2. Change the setting: "displayFlowDiagramName" to be 'false'

3. Use 'Show Current Package Contents' option in the Requirements Map:

1. Right click on the Requirement Map in a Project

2. Make sure that the 'Show Current Package Contents' is selected.

4. Use of Packages: We recommend that you use a Package approach and have a max of 15-20 Requirements in each.

Support

For all technical problems and support queries, please logon to frontline at http://frontline.compuware.com/products/ci/ Frontline contains the Optimal Trace forum as well as a FAQ area. Additionally, full up to date release information and contact numbers are provided. Optimal Trace Support can be contacted on 1-800-538-7822.

Optimal Trace^tm is a trademark of Compuware. All other trademarks are the property of their respective owners.

To Install Optimal TraceTM Professional V5.0

To Uninstall Optimal TraceTM Professional V5.0

To Install Optimal Trace^TM Professional V5.0

To Uninstall Optimal Trace^TM Professional V5.0