Upgrading Considerations
To support document versioning, introduced in Integrity 10.5, several components contain significant updates. If you are upgrading from Integrity 10.4 or older, review the affected components to determine what changes you need to make to your configuration.
|
|
Due to support for Java 8, upgrading from Integrity 10.4 or older to Integrity 10.5 or higher requires a full installation of the Integrity Client and Integrity Server. Although a full installation is required for the upgrade, Integrity 10.5 is an incremental release similar in scope to other 10.x releases. As with any release, PTC recommends full testing of the upgrade process. This change may affect the length of time your upgrade takes and should be accounted for in testing, preparation, and planning. For more information, see the PTC Integrity Upgrading Guide for Integrity 10.5 or higher.
|
Affected Integrity Components
To support document versioning capabilities in Integrity 10.5 and higher, the following Integrity components are affected:
• queries
• charts
• reports
• rules
• computed expressions
• computed fields
• Integrity API
• trigger scripts
Queries
To query for live and versioned items, the following query filters have been added (*) or updated:
|
GUI/Web
|
CLI
|
Description
|
|
Is versioned
|
item.versioned
|
Returns versioned items only.*
|
|
Is live
|
item.live
|
Returns live items only.*
|
|
Is a document node
|
item.node
|
Returns all items (live and versioned) that are a document model node type.
|
|
Is a content node
|
item.content
|
Returns all items (live and versioned) containing references to shared items.
|
|
ID
|
field[ID]
|
Returns live and versioned items by item ID. For example:
• display a specific live item only. For example, ID = 123 and Is live returns live item 123.
• display a live item and all versions of the item. For example, ID = 123 and include versions returns 123, 123-1.0, 123-1.1, and 123-1.2.
• display a range of live items. For example, ID > 123 and < 128 and Is live returns 124, 125, 126, and 127.
• display a specific versioned item. For example, ID = 123–1.0 returns 123–1.0.
|
|
Document ID
|
field[Document ID]
|
For document ID query filters in the GUI and Web interface, you can specify the following conditions to display content that is included in live and versioned documents:
• display the contents of a live document. For example, Document ID = 123 and Is live returns content that is included in live document 123.
• display the content from a range of live documents. For example, Document ID > 123 and < 128 and Is live returns content that is included in live documents 124, 125, 126, and 127.
• display the contents of a versioned document. For example, Document ID = 123–1.0 returns content that is included in versioned document 123–1.0.
|
After upgrading, existing queries display all items (versioned and live). To display live items only (pre-upgrade query behavior), modify the queries to include the Is live filter.
Charts
Using a backing query, you can display live and versioned item data in charts.
After upgrading, backing queries in existing charts display all items (versioned and live). Modify backing queries in existing charts as needed to display appropriate data. If you choose to include versioned content item data in charts, modify the chart definition to exclude computed expressions that refer to document context (Document ID, Contains, Contains By fields or the Aggregate ByDocument() function). If you do not exclude these computed expressions, they may return ambiguous results, preventing the chart from running.
Reports
To report on live and versioned item data, you can specify the report tags in report recipes. For information on the available report tags, see
Report Tags.
After upgrading, existing reports display all items (versioned and live). To display live items only (pre-upgrade report recipe behavior), modify the report recipes to include the live items report tag filter.
For example, to include live items only in a report recipe similar to Detail - HTML, Column, Relationships, modify the beginrelationshipsdetail line to:
<%beginrelationshipsdetail &relationshipsdetailfields%><%filter%>(item is live)<%endfilter%>
|
|
If a report recipe does not include the appropriate filter, users can modify the backing query to include a query filter that displays live or versioned items.
|
Including the Item ID Field in JavaScript Code
If document versioning is enabled and you have an existing report recipe that includes the item ID field in JavaScript code, you must put quotes around the item ID field.
For example:
<script type="text/javascript"> if(REPORT_ISSUES == "") REPORT_ISSUES = <%<%builtin ID%>%>; else REPORT_ISSUES = REPORT_ISSUES+","+<%<%builtin ID%>%>; selection = new Array(); level = 0; ReportID = <%<%builtin ID%>%>;</script>
Modify to:
<script type="text/javascript"> if(REPORT_ISSUES == "") REPORT_ISSUES = "<%<%builtin ID%>%>"; else REPORT_ISSUES = REPORT_ISSUES+","+"<%<%builtin ID%>%>"; selection = new Array(); level = 0; ReportID = "<%<%builtin ID%>%>";</script>
Rules
When defining rules in Integrity, you can specify conditions for live and versioned document model items. For more information, see
Rule Format.
Computed Expressions
To include live and versioned items in computed expressions, the following functions have been added (*) or updated:
|
Function
|
Description
|
|
IsLive()
|
Returns true if item type node or segment is live.*
|
|
IsVersioned()
|
Returns true if item type node or segment is versioned.*
|
|
IsNode()
|
Returns true if the items (live and versioned) are a document model node type.
|
|
IsContent()
|
Returns true if the items (live and versioned) contain references to shared items.
|
After upgrading, existing computed expressions include all items (versioned and live). To include live items only (pre-upgrade behavior), modify the computed expressions to include the IsLive() function.
For example, to include live items only in the following existing computed expression:
aggregate("Documented By", sum(IsSegment() ? 1 : 0))
add the IsLive() function:
aggregate("Documented By", sum(IsSegment() and IsLive() ? 1 : 0))
Displaying Ambiguous Computations From the CLI
From the CLI, the ! decorator indicates a computed field contains an ambiguous computation. To toggle the display of the ! decorator, specify the --[no]showDecorators option for the following commands:
• im exportissues
• im issues
• im viewissue
By default, --showDecorators is specified for im viewissue and --noshowDecorators is specified for im issues/im exportissues. If you have any scripts that currently use these commands, PTC recommends that you review those scripts and update as required.
Computed Fields
When creating or editing computed fields, a new option is available that specifies how values are computed in versioned items: Allow Computation Updates on Versioned Items (GUI) and [no]allowComputationUpdatesOnVersion (CLI). By default, computation values on versioned items continue to update based on the computed field definition. To record computation values at the time of versioning and prevent further updates, disable the Allow Computation Updates on Versioned Items option.
For existing computed fields, the option is enabled. Configure the option based on your requirements.
Integrity API
Integrity API 4.13 and higher include support for distinguishing literal null values from null values returned by ambiguous computed field values in workflows and documents items.
When viewing a workflows and documents item in versions of Integrity before 10.5, the API representation for a computed field value matched the representation of a non-computed field value for the same workflows and documents field data type. In Integrity API 4.13 and higher, computed field values are now represented by an API item of im.Computation model type containing the following API fields:
• value indicates the computation value
• isAmbiguous indicates the boolean value of whether or not the computation is ambiguous
• isDynamic indicates the boolean value of whether or not the computation is dynamic or static
|
|
With this update, older versions of the Integrity API may return null values with no context for simple data types.
|
Custom Integrations and Versioned Item Data
If you use the Integrity API to develop custom integrations, note the following about how API versions handle versioned item data:
• Integrity API 4.13 and higher may include versioned items, as specified by an Integrity query definition.
• Integrity API 4.12 or older excludes versioned items by default. The client/command removes versioned items from the query results; there is no change to operation of the query on the server and no modification to the query definition sent to the server.
Trigger Scripts
The following classes and methods have been added or modified to support document versioning functionality:
|
Class/Method
|
Description
|
|
LocalTriggerManager.ScriptIssueDeltaBean.revision
|
The trigger method ScriptIssueDeltaBean.revision has been modified to perform a check-in operation. The following changes have been made to the associated parameters:
• The conditionalSignificantEdit parameter is ignored and internally set to true. Document model items are only checked in when they contain significant changes.
• The conditionalModified parameter is ignored and internally set to false. Document model items are only checked in when they contain significant changes.
• The recurseInclude parameter is ignored and internally set to true. All included documents are automatically checked in.
• The recurseReference parameter is ignored and internally set to true. All referenced documents are automatically checked in.
• The recurse parameter applies only to content items. If the selection is a segment or a node that points to a segment, the option is ignored and internally set to true.
|
|
LocalTriggerManager.ScriptServerBean
|
The LocalTriggerManager.ScriptServerBean class has been modified to include the following new methods to look up the new versioning-related fields:
• getLiveItemIDFieldBean for the Live Item ID field
• getMajorVersionIDFieldBean for the Major Version ID field
• getMinorVersionIDFieldBean for the Minor Version ID field
|
|
LocalTriggerManager.ScriptIssueBean and LocalTriggerManager.ScriptIssueDeltaBean
|
The LocalTriggerManager.ScriptIssueBean and LocalTriggerManager.ScriptIssueDeltaBean classes were modified to include the isFieldValueAmbiguous(String fieldName) method to determine if a computed field value (in the context of a versioned item) is ambiguous.
isFieldValueAmbiguous(String fieldName) returns true if (in the context of a versioned item) the stored value for the provided computed field is null because of an ambiguous computation.
|
|
LocalTriggerManager.ScriptIssueBean, ScriptIssueBean.toString(), and ScriptIssueDeltaBean.toString()
|
The LocalTriggerManager.ScriptIssueBean class, ScriptIssueBean.toString() method, and ScriptIssueDeltaBean.toString() method were updated to support e-mail notifications containing versioned items.
The LocalTriggerManager.ScriptIssueBean class was modified to add the getIssueIDString() method to retrieve the versioned item ID from an item.
The ScriptIssueBean.toString() and ScriptIssueDeltaBean.toString() methods for issue beans were modified to include the versioned item ID.
To use these new methods, the following trigger scripts were updated:
• email.js
• signatureRequired.js
• postLinkedIssue.js
• PromoteIssue.js
• javamail.js
• hello.js
• escalate.js
• emailAdvanced.js
• dependentStatus.js
|
If you have any trigger scripts that currently use these methods or classes, or you are currently using the trigger scripts that were updated in Integrity 10.5 or higher, PTC recommends that you review those scripts and update as required.
How Document Versioning Affects Item Revisioning
If you are currently using item revisioning with your Integrity configuration, note how the new document versioning capabilities affect item revisioning:
• Syntax
The major/minor syntax for revision information is updated to use version instead of revision. For example, fields are named Major Version ID and Minor Version ID.
• Revision Information
Existing revision information no longer displays in live item title and header information, for example, 123 [0.1].
• Administering Document Model Types
When creating or editing a document model type, the Rules button under the Attributes tab now displays Version instead of Revision.
• Check In Command (GUI)
In the Integrity Client GUI, the Check In command replaces the Increment Revision command for document and content items.
• im ci Command (CLI)
From the CLI, the im ci command replaces the im incrementcontentrevision command. To ensure that existing scripts continue to work correctly, the im incrementcontentrevision command is aliased to the new im ci command, but it is now hidden from the CLI. The im incrementrevision command is unchanged.
Note the following changes to options:
◦ The im ci command only permits checking in significantly modified content. This means that the --significant and --force options are removed.
◦ The im ci command always recurses into included and referenced documents (if there are significant edits). This means that the --[no]recurseInclude and --[no]recurseReference options are removed.
◦ With item revisioning, you could select a node that referenced a subdocument but specify that the check in should actually be performed on the referenced subdocument. With document versioning, the --[no]subSegment option is no longer applicable and is removed.
◦ The --[no]recurse option indicates if child items of the selection should also be checked in. This option applies only to content and is ignored for documents. This option is also ignored for content items pointing to included or referenced documents.
• Checking In a Previously Revisioned Document and its Content
If a document and its content were previously revisioned using the Increment Revision command in Integrity 10.4 or earlier and they contained no significant edits, performing an initial check in of the document or content successfully creates a document version or content version. This applies to a previously revisioned document and its content only. Any other attempt to version a document or content with no significant edits since the last version is disallowed.
