Item Revisioning
Item revisions mark an unambiguous point in the history of an item. When viewing an item in Windchill RV&S, the revision provides an identifier into its history. Furthermore, if you export the same item to a partner using a report or through ReqIF, and they call you to discuss it, you are assured that any discussion of Item 123, revision 1.2, for example, is done with the exact same item definition and understanding.
This is also true for everyone with direct access to Windchill RV&S. When listing items, you have clear visibility to the item revision. As with the partner scenario, any internal communication through conversations, reports, or e-mail, can include a specific revision to ensure all parties are using the same exact definition.
The revision identifier is numbered as a two-part decimal in the format major.minor, where the number to the left of the decimal point is the major revision, and the number to the right of the decimal point is the minor revision. You define the revision pattern for revision numbers by specifying values in workflow and document properties. For example, the default revision number sequence is 0.1, 0.2, 0.3, ... 1.0, 1.1, 1.2.
How to Increment Revisions
Windchill RV&S provides the following options for incrementing revisions for items.
|
|
• There is no way to arbitrarily set a revision number. When an item is revisioned, the revision number will be set by the next available number defined by the revision schema.
• When copying a revisioned item, any revision labels on the existing item are not copied to the new item.
|
• GUI command: > increments the revision for an item.
For detailed information about how to increment revisions, see the Windchill RV&S Help Center.
• CLI command: im incrementrevision increments the revision for an item..
The following CLI commands are provided for incrementing revisions:
For detailed information about the CLI command, see the CLI man pages.
• Windchill RV&S Trigger methods and JavaBeans
Windchill RV&S provides trigger methods and JavaBeans that allow the administrator to define custom item revision solutions. A custom solution can be used to:
◦ automatically increment the revision for an item based on workflow changes, for example, a state transition such as when state is “Review”
◦ block or prevent certain edits, such as attempting to edit an item that has un-revisioned changes
Information about the Windchill RV&S trigger methods and JavaBeans is located in the Event Trigger Java Documentation on the Windchill RV&S server home page located at:
http://localhost:port/documentation/javadocs/triggers/index.html
Finding and Viewing Item Revisions
Windchill RV&S provides visibility to item revisions from the GUI, Web interface, and CLI.
• To open a revisioned item at a specific revision, specify the revision label in the format itemID revisionID, for example, 184 2.1, as follows:
◦ In the GUI, for an item, specify the item revision label in the Item field.
◦ In the Web, specify the item revision in the go to item field.
• Item Details view:
◦ Custom tabs may display the following revision fields:
Revision is the latest revision of the item, for example, 2.1.
Revision Increment Date is the date and time of the latest revision.
Significant Edit Date is the date and time a change occurred to the item.
Significant Change Since Item Revision indicates if any fields were changed since the item was last revisioned. When changes exist, the value is true. If changes do not exist, the value is false.
Item Significant Edit Date on Shared Item is an FVA field that displays the value of the Input Revision Date on the Shared Item that is related to the Node item via the References relationship field. This field is generally not required to be visible to users.
◦ Labels tab displays revision labels, if labels are enabled for the type. Revision labels display in ascending order by default. The Label field displays each revision number, for example, 2.1. The Date field displays the date and time of each revision increment, for example, 10-Apr-2012 4:45:52 PM.
To navigate using a revision label, right click a label, and choose View or View as of.
The label :head is a system provided label that always appears first in the list. The date and time of :head are updated by revision operations; therefore, the :head label always represents the latest item revision.
|
|
Revisions labels are not usually distinguishable from other non-revision labels. In addition, revision labels and system provided labels that begin with “:” cannot be manually added, moved, or deleted for any type that is enabled for revisioning.
|
◦ History tab displays the history of each revision. Select a revision date hyperlink to view the item as of that date and time. Historical items are denoted with a title and header that indicates the revision and the date and time you are viewing the item as of, for example, Requirement:184 [2.1] as of Apr. 10, 4:45:52 AM
• Item revisions can be included in reports and queries, including a Historical report and Item Differences report.
For more information about finding and viewing revisions, see the Windchill RV&S Help Center.
Setting Up Item Revisioning
The following table describes the steps required to set up item revisioning:
|
Task
|
Supporting Information
|
|
“Step 1: Access your existing label format”
|
|
|
“Step 2: Define the revision scheme for initial major and minor revision numbers”
|
|
|
“Step 3: Enable revisioning for a type”
|
|
|
“Step 4: Review and optionally change the visibility of type revision fields and significant edit fields”
|
|
|
“Step 5: Optional: Create a trigger script”
|
|
|
“Step 6: Optional: Create an event trigger”
|
|
Perform the following procedures in the Administration Client, in the Workflows and Documents node.
Step 1: Assess your existing label format
|
|
This step is only applicable if you have existing labels in the format ‘n.n’. or labels that start with ‘:’ If this is not applicable, go to step 2.
|
Labels in the format of major.minor and labels that have a leading colon (:) use syntax reserved for revision labels. Once revisioning is enabled for a type, attempting to add a non-revision label containing reserved syntax will result in an error.
If you enable revisioning for a type that has pre-existing labels of the format major.minor, it is recommended that you delete or replace those labels, since they will conflict with revision labels.
For example, non-revision label 1.3 is added to an item before revisioning is enabled. Revisioning is later enabled with a revision format of 1.0. Revisions 1.1 and 1.2 increment successfully. However, when the next revision increment to 1.3 is attempted, it conflicts with the existing non-revision label 1.3, and results in an error. In this case, you have to delete or replace the conflicting label before the revision increment is allowed.
To replace existing labels, first create new labels using a form other than major.minor, and then delete the existing labels. For more information on this topic, see the Windchill RV&S Help Center.
Step 2: Define the revision schema for initial major and minor revision numbers
|
|
Changes to the following properties will take effect immediately; you do not need to restart the Windchill RV&S server. Changing these values has no impact on revisions that have already been set.
|
1. Select the > node. The Properties view displays.
The properties mksis.im.initialRevisionMajor and mksis.im.initialRevisionMinor control the initial starting values of revisions for item types that have been enabled for revisioning.
◦ mksis.im.initialRevisionMajor is the first part of the revision, known as the major revision (the number to the left of the decimal point).
◦ mksis.im.initialRevisionMinor is the second part of the revision number, known as the minor revision (the number to the right of the decimal point).
Set these properties in combination to form a revision number schema. Windchill RV&S supports four revision number schemas: 0.0, 0.1, 1.0, and 1.1. The default schema is 0.1.
The following table describes the revision patterns constructed by each revision schema:
|
Set the initial Major Revision to...
|
and set the initial Minor Revision to...
|
If the desired revision pattern is...
|
|
0
|
0
|
0.0, 0.1, 0.2, ... 1.0, 1.1, 1.2, ... 2.0, 2.1, ...
|
|
0
|
1
|
0.1, 0.2, … 1.1, 1.2, ... 2.1, 2.2, ...
|
|
1
|
0
|
1.0, 1.1, 1.2, … 2.0, 2.1, ...
|
|
1
|
1
|
1.1, 1.2, … 2.1, 2.2, ...
|
|
|
A major increment sets the first or next major revision as indicated in the sequence. A minor increment sets the first or next minor revision in the sequence.
|
Select the schema based on the desired pattern and set the following properties accordingly.
2. Right click the mksis.im.initialRevisionMajor property, and select Edit.
a. In the Value field, type 0 or 1. The default value is 0.
b. Click OK.
3. Right click the mksis.im.initialRevisionMinor property, and select Edit.
a. In the Value field, type 0 or 1. The default value is 1.
b. Click OK.
Step 3: Enable revisioning for a type
1. From the Types view, select the type you want to edit, and select > . The Edit Type dialog box displays.
2. Click the Attributes node.
3. Under the General tab, enable May have revisions.
Revisions are disabled by default. When this attribute is selected, the Rule for Incrementing Major Revision and Rule for Incrementing Minor Revision buttons are enabled. Selecting either of these buttons displays the Edit Add Revision Rule dialog box, which closely resembles the Item Editability dialog box.
These rules allow you to define rules for incrementing the major revision and minor revision, respectively, based on explicit user gestures. For example, you can define a rule that allows only a specific user or group to increment revisions.
|
|
If the attribute May have labels applied is enabled for the type, then revision labels appear on the Labels tab when viewing the type in the Windchill RV&S client, Web interface, and CLI.
|
4. Click OK.
Step 4: Review and optionally change the visibility of type revision fields and significant edit fields
Windchill RV&S provides the following built-in fields that are enabled for a type when the attribute May have revisions is enabled for the type:
• Revision
• Revision Increment Date
• Significant Change Since Item Revision
• Significant Edit Date
• Item Significant Edit Date on Shared Item
When enabled, by default everyone can view these fields. If you want to change the users or groups who can view any of these fields, do the following:
1. From the Types view, select the type you want to edit, and select > . The Edit Type dialog box displays.
2. Click the Visible Fields node.
3. Select the field in the Fields list, and in the Selected Field Is Visible For list, select or unselect the user(s) or group(s) that can see the field.
|
|
Be sure to add the applicable fields and visibility to your existing presentation templates, if applicable. In most scenarios, the Revision field alone may be sufficient, since it shows the current revision and whether significant changes exist.
|
4. Click OK.
For more information about built-in fields, see
“Understanding Fields”. For more information about field visibility, see
“Setting Field Visibility for Types”.
Step 5: Optional: Create a trigger script
Write java script that defines the event(s) that cause a revision increment and/or prevents an edit if un-revisioned changes exist. The logic of your java script can be simple or complex. The java script runs on the Windchill RV&S server based on the event(s) you define, like a state transition.
The following example is a trigger script that causes a revision increment.
Create a trigger script named incrementMajor.js, for example, and place it in the following directory:
installdir/data/triggers/scripts
where installdir is the path to the directory where you installed the Windchill RV&S server:
The script should contain the following java script code that calls the incrementMajor() method on the issue delta bean.
var delta = bsf.lookupBean("imIssueDeltaBean");
delta.incrementMajor();
Step 6: Optional: Create an event trigger
In the Administration Client, event triggers are created from the Triggers view by selecting > . The general steps required to create a rule-based change trigger are as follows:
1. Provide a name for the event trigger, for example, incrementMajor.
2. Select the rule-based change trigger type.
3. Define the trigger to run Pre-event.
4. Provide a description for the trigger.
5. Under Condition, define a rule for when the trigger runs. The rule can be simple, for example,type = Requirement and state = Review, or as complex as you need.
6. Select the script file you created (in step 5) from the library for the trigger to run. Then, if required, fill out the parameters for it.
7. Click OK.
For detailed information on setting up an event trigger, see
“Creating Rule Based Change Triggers”.
