Comparing Documents
|
CLI EQUIVALENT
|
im diffsegments
|
Compare content and field-level differences between two document selections using the Document Difference view. For example, you can select a requirements document with two baseline labels and relevant fields of interest to see how the document has changed over time. The view presents structural and content changes side-by-side in two document panes. Item and field additions, deletions, moves, changes, as well as text differences are highlighted. You can use navigation tools to efficiently review and navigate the document differences.
To access the Document Difference view in the GUI, select > .
The workflow for comparing documents includes the following steps:
1. Select documents to compare.
2. Select fields to compare.
3. Filter comparison results in the view.
4. Review document differences.
|
|
If you are upgrading to Integrity 10.8 from a previous Integrity Lifecycle Manager version, you must customize existing Integrity Lifecycle Manager viewsets and the shortcut menu to enable this view in the GUI. Viewset and shortcut menu customization is saved and remembered the next time you access the client.
To customize existing viewsets, select > . On the Actions tab, select > > > to make the option visible in the Document menu. On the Views tab, under Workflows and Documents, configure View Differences as floating or docked. The view is docked by default.
To customize the right-click shortcut menu, right-click on a document node and select Customize This Menu. Click Add Action. Select Workflows and Documents/Item and then select View Differences.
|
Selecting Documents to Compare
You can specify the following types of document selections:
• One document at two different points in time.
• Two versions of the same document (and optionally at different points in time).
• Two branched documents that share a common branch ancestor item ID (and optionally at different points in time). For example, you can compare a versioned document to a document that was branched.
1. Select > .
The View Document Differences window displays.
2. Specify a primary document to compare by entering a Document ID or by clicking Select and finding existing items. Then, do one of the following:
◦ To compare a single document at two different points in time, clear Compare to a version or branch. Expand and select an As of option for the source and the target document. The following table describes the As of options for document comparisons:
|
To compare a document as of
|
Do this...
|
|
Now
|
Select Now to compare the current version of the document.
|
|
Revision
|
Select Revision. A list of all of the labels associated with revisions displays. Select the revision that you want to perform the document comparison against.
|
|
This option is available only when you are comparing a document that allows versioning.
|
|
|
Label
|
Select Label. A list of all labels on the document displays. Select the label that you want to perform the document comparison against.
|
|
Branch
|
Select Branch. A list of all the branches associated with the document displays. Select the branch that corresponds to the time you want to compare the document as of.
|
|
This option is available only when you are comparing a document that was branched or is a branch.
|
|
|
Edit
|
Select Edit. A list of all dates when the document item was significantly modified displays. Select the date that you want to perform the document comparison against.
|
|
Date
|
Select Date to select an arbitrary date and time for the document comparison using the calendar and time fields.
|
◦ To compare a document against one of its branches, select Compare to a version or branch, and then specify a branch Document ID or click Select to find existing branches for the source document.
◦ To compare a document against one of its versions, select Compare to a version or branch, and then specify a version Document ID or click Select to find existing versions of the source document. When document versioning is enabled, you can find versioned documents using the format Live Item ID-major.minor. For example, 184–1.2.
When searching for existing items, you can filter by visible text or fields, and you can search by item ID. For more information, see
Document Finder.
Selecting Fields to Compare
1. Expand Options and select the content fields you want to compare:
◦ 
specifies fields to add to the
Additional fields to compare list. You can filter the list of fields.
◦ 
removes selected fields from the
Additional fields to compare list.
◦ 
adjusts the order in which the fields display in the
Document Difference view.
2. Click OK. Your field selections are remembered the next time you compare documents of the same document type.
Key Considerations for Field Selections
• The primary text field is always compared.
• You can only compare content fields that are relevant to the content type for the selected document types. Supported field types for comparison include the following types: long text, rich text, short text, picklist, attachment, category, trace relationship, integer, floating point, state, logical, date, FVA to long text, FVA to rich text, FVA to short text, FVA to picklist, FVA to attachment, FVA to integer, FVA to floating point, FVA to logical, and FVA to date. Unsupported field types may contain differences; however, the document comparison algorithm ignores differences in unsupported field types.
• Except for the text field, any field you do not choose to compare may contain differences; however the document comparison algorithm ignores differences in fields that are left out of the document comparison.
• Parameter and parameter value field types cannot be selected for comparison. Parameters are not substituted in the
Document Difference view. For more information on field types, see
Working With Field Types.
Filtering Comparison Results
While selecting fields to compare, you can filter the document comparison results in the Document Difference view.
• To hide items that have no field or document structure differences, select the Hide items without differences checkbox.
• To hide fields in the Additional fields to compare list that contain no differences, select the Hide fields without differences checkbox.
Your field filter selection is remembered the next time you compare documents of the same document type. Your item filter selection is always remembered.
Reviewing Document Differences
The Document Difference view contains two document panes. The source document you specified first displays in the left pane. The target document you specified second displays in the right pane. You can navigate through each pane independently. The document pane currently in focus is outlined in blue.
The view visually presents differences using color-coded highlighting, color-coded connector arrows, text difference highlighting, and interactive row header icons representing the type of difference. Color-coded connector arrows dynamically join content and field-level differences between panes when both differences are at least partially visible in each pane. As you scroll through either document, the connector arrows refresh to connect visible content in the view.
The following table describes how the view visually represents document differences:
Type of Document Difference | Highlight/Connector Arrow Color | Interface Icon |
Added content An item that is not present in the source document but is present in the target document. A placeholder offers a visual indication of where the addition was made in the source document. | green | |
Moved content An item present in both the source document and target document that: • has a different parent • has the same parent but is in a different relative position • has a parent that has been moved. | blue | |
Deleted content An item that is present in the source document but is not present in the target document. A placeholder offers a visual indication of where the deletion was made in the target document. | red | |
Modified content Any non-structural change to item or field content. | yellow | |
Moved and modified content | purple | and |
Text differences The Document Difference view compares document content at the text level, including alpha-numeric characters, punctuation, spaces, and hypertext link text. Text differences are highlighted in each document pane, as follows: • Deleted text is highlighted red in the source document in the left pane. • Added text is highlighted green in the target document in the right pane. • Changed text displays as a deletion in the left pane and an addition in the right pane. The view does not compare or highlight the following document elements: • Text formatting, such as italics, font attributes, or numbered lists • Images • Hypertext link target content • Short text field content | Text difference highlighting is dependent on how the built-in Java library identifies language-specific word boundaries. As a result, entire sentences may be highlighted instead of individual differences for some languages, such as Japanese or Chinese. Also, under some conditions, white space or non-breaking spaces can be highlighted in cases where spaces are interpreted as part of a difference. |
| Left pane: Deleted text is highlighted red Right pane: Added text is highlighted green | |
Click an interactive row header icon in one document pane to see the related content at the top of the other pane. To compare content side-by-side, click the coordinating row header icons in both panes. Hover over a row header to display a tool tip with section information. Status details also display in the bottom left corner of the view window.
You can perform item operations, such as editing or viewing items, from the Item menu or from the shortcut menu with a specific node selected.
The view displays all items by default. To hide items that have no field or document structure differences, select > . To hide fields in the Additional fields to compare list that contain no differences, select > .
Refresh the view at any time by selecting > or by pressing F5.
Key Considerations for Document Difference View Results
• The view presents relationship fields using the CSV format, regardless of how the field's display format has been configured by the administrator. The use of the CSV format allows the document comparison algorithm to find differences in the content of the relationship field itself (including the item IDs, their order within the field, and any associated flags). However, the algorithm does not find differences in the field values on the items referenced in the relationship field.
• The Document Difference view presents the net differences of the text changes between the document selections. However, the differences visible in the view may not represent the actual changes the user made to the documents.
• Fields selected for comparison display in a stacked vertical format for each node.
• Attachment fields are rendered as comma-separate filename values.
• When the documents you compare contain subdocuments, all included subdocument differences are highlighted including added, moved, deleted, and modified content. Cyclical references to subdocuments are displayed as inserted (or referenced) subdocuments.
• For inserted (or referenced) subdocuments, the view highlights only added and deleted subdocument operations.
• Modified content items do not necessarily include text difference highlights. For example, a single paragraph split into two paragraphs displays as a modified content change with no text differences.
Navigating Document Differences
You can navigate incrementally through each difference in the current document pane using View menu options, or by using the following toolbar or shortcut key options:
• Previous difference:
or press F7
• Next difference:
or press F8
• First difference:
or press CTRL+F7
• Last difference:
or press CTRL+F8
Select > to configure the Previous and Next difference search options to wrap to the top or bottom of the document pane. Clear the Wrap Difference Search option to stop at the beginning or end of the document pane.
Navigating the Document Panes
The following document pane keyboard navigation options are available in the Document Difference view for the current document pane:
Shortcut Keys | Action |
CTRL+TAB | Switches the focus to the other document pane. |
TAB | Selects the next field. |
up arrow key | Selects the previous row header. |
down arrow key | Selects the next row header. |
HOME | Selects the first row header. |
END | Selects the last row header. |
SPACEBAR | Selects the row header icon in focus and moves to the corresponding difference in the other document pane. |
PAGE UP | Scrolls up approximately one page. |
PAGE DOWN | Scrolls down approximately one page. |
