Enhanced Promotion Process
There is currently no out of the box solution to refresh promotion objects to their latest iterations or automatically revise the promotion candidates that are being promoted through a revision series change.
Background
During the Promotion Request review and approval process, it is not uncommon for the participants to uncover issues associated with the promotion candidates. Rather than rejecting the Promotion Request, the process can be more efficient with the introduction of a rework loop. This rework loop allows the creator of the Promotion Request to review the comments, make appropriate adjustments to the promotion candidates, and have the workflow automatically refresh the Promotion Request for another review and approval.
It is also good practice to avoid sending promotion targets for approval when the result will be a validation error. The rework loop contains this validation based on the current iterations of promotion targets or the refreshed iterations if Automatic Refresh is enabled.
For companies that use the Promotion Request as a "Gate Review" for production, a best practice is to switch the revision labels for objects from a numeric series to an alphanumeric series. With a proper life cycle design, such a gate state can be modeled that achieves the desired target state and automatically revises the promotion candidates to the initial revision label of the new revision series.
Scope/Applicability/Assumptions
These instructions assume a pre-existing knowledge of modifying workflow processes and how to call Windchill methods within the workflow.
Intended Outcome
The expectation is that you will be able to add the auto-refresh or the automatic revise functionality to your customized workflows.
Solution
The out-of-the-box promotion request process templates illustrate how to implement both the auto-refresh and the automatic revise functionality. Also included in the template is the review validation.
Prerequisite knowledge
To achieve this result, you need to have an understanding of the following:
• Basic Java development
• Workflow process modification including tally expressions and robot expressions
• The management of resource bundle file.
• Windchill Preference Management utility
|
|
The workflow process templates provided out-of-the-box should not be modified directly. These process templates should be renamed prior to modification.
|
Solution Elements
|
Element
|
Type
|
Description
|
|
wt.maturity.MaturityServerHelper.service.unlockTargets (pn)
|
method
|
This method call can be added to a workflow expression that will unlock the promotion targets in this case for rework. The result of this is the promotion targets will be at the state they were at, at the moment the promotion request was created. Unlocking the promotion targets may allow the user assigned to rework to perform updates on the objects (subject to access control).
|
|
wt.workflow.work.WfTally
|
class
|
This class is used to tally votes of a workflow task. For example if a task is assigned to the approval role multiple users could receive that task and vote differently. This class provides methods that define which route to take based on if ‘all have to vote for that option” or any have to vote for that option.
|
|
com.ptc.windchill.enterprise.maturity.PromotionNoticeWorkflowHelper.refresh(pn);
|
method
|
This method can be added to a workflow expression that provides the update handling of promotion objects. Internally this method uses a new preference Latest Iteration Refresh to control the behavior. Here are the values
1. Refresh promotion candidates (default setting). This value only refreshes the promotion candidates.
2. Refresh all objects. This value refreshes all promotion objects: The promotion candidates and the other objects in the Maturity baseline.
3. Do nothing. This option will not refresh any promotion objects.
4. Validate promotion targets. (For more information, see the section: Procedure – Validation of Promotion Targets in Rework.)
|
|
wt.maturity.MaturityServerHelper.service.lockTargets (pn);
|
method
|
This method call can be added to a workflow expression that will lock the promotion targets. Only promotion targets that have a lock transition will be subject to locking.
|
|
com.ptc.core.ui.validation.UIValidationResultSet set= com.ptc.windchill.enterprise.maturity.PromotionNoticeWorkflowHelper.revisePromotables(pn, pn.getCreator(), locale);
|
method
|
This method can be added to a workflow expression to automatically revise promotion objects. Internally this method uses two new preferences :
1. Automatic Revision Mode. There are 3 modes:
a. Do nothing.
This mode will not perform any automatic revisioning.
b. Automatically revise only the promotion candidates.
This mode will automatically revise only promotion candidates
c. Automatically revise only the promotion candidates with versioning scheme changed
This mode will only revise promotion candidates that will be revising to a state that result in a versioning scheme change.
2. Automatic Revision States.
This preference is a multi valued list containing states that are valid for automatic revisioning. This preference only takes effect if the Automatic Revision Mode preference is something besides Do-nothing.
|
Procedure — Adding Automatic Refresh
A customized workflow process template used by promotion requests can be modified to support automatic refresh. The following example will outline to procedure used in the latest iteration of the “Promotion Request Approval Process” provided out-of-the-box.
In this example a rework loop has been added. The loop begins at the Approve Promotion Request task. Members of the Promotion Approvers receive this task. An addition route has been added to the Approve Promotion Request task called Rework.
In this example, a tally expression is defined that determines, based on all the approvers’ votes, which route to take.
Vector v = new Vector();
v.addElement("Approve");
v.addElement("Reject");
v.addElement("Rework");
Vector vResult = wt.workflow.work.WfTally.any(self, v);
if( vResult.contains("Rework")) {
result = "Rework";
} else if ( vResult.contains("Reject") ) {
result = "Reject";
}else {
vResult = WfTally.all(self,v);
if( !vResult.isEmpty() ) {
result = (String)vResult.get(0);
}
}
This expression says if any approvers choose Rework then the Rework option is taken. If no approvers select rework but any select Reject then Reject is taken. Otherwise the Approve route is taken.
The approver task no longer contains special instructions. However, there exists a process variable called special_instructions. This field is global to the process and therefore can be set programmatically. The enhanced workflow uses the Comment field of the Approve Promotion Request task to assemble a string of comments that approvers voted Rework. This String is set on the Rework special instructions. For example, if there are three users in the approvers role: user1, user2 and user3.
• User1 votes approve with the comment: “Looks good”
• User2 votes rework with the comment: “Modify”
• User3 votes rework with the comment: “Resize”
In this case, the reworker will receive a task with the special instructions:
• [User2]: Modify
• [User3]: Resize
Once the Rework route is chosen the promotion targets are locked for rework and the promotion creator will receive the Rework Promotion Request task. This task will provide special instructions supplied by the approver of what promotion items need rework. This special instructions field is writable for the Approve task and read only for the Rework task. The creator can then iterate certain promotable objects for this task. The creator could determine that the promotion in not longer viable and can choose the reject option. In this case the promotion request is rejected.
The user performing the rework can only update objects that they have permission to modify. If the content of the promotion request is not able to be modified, major reworking of the promotion request will require a rejection followed by a new promotion request with the reworked items. The rework loop is meant to address minor issues such as typographical errors, issues with quantity or units, minor geometry changes rather than significant structural changes.
Once the promotion creator chooses the ‘Submit’ option the promotion request will execute the Refresh Promotion Objects expression.
wt.maturity.PromotionNotice pn = (wt.maturity.PromotionNotice)primaryBusinessObject;
try
{
com.ptc.windchill.enterprise.maturity.PromotionNoticeWorkflowHelper.refresh(pn);
wt.maturity.MaturityServerHelper.service.lockTargets (pn);
catch( Exception wte )
}
{
wte.printStackTrace();
}
The PromotionNoticeWorkflowHelper.refresh(pn) method will refresh the promotion objects to their latest iteration following the preference rules defined in the Solution section. Finally the loop is finished and the approvers again receive the Approve Promotion Request task. It is important to include the call to lockTargets() to ensure the promotion targets are not inadvertently modified before approval if locking is supported.
FIT Table
The following fit table describes how the Latest iteration Refresh preference affects automatic refresh.
Promotable | Is Promotion Target | Latest iteration refresh preference value | Eligible to be Refreshed |
part_1 | N/A | Do Nothing | false |
part_2 | Y | Refresh promotion candidates | true |
part_3 | Y | All | true |
part_4 | N | Refresh promotion candidates | false |
part_5 | Y | All | true |
Procedure — Adding Automatic Revisioning
The workflow template used by the promotion request can be modified to support automatic revisioning.
The following example will outline the procedure used in the latest iteration of the “Promotion Request Approval Process” provided out-of-the-box.
In this example an additional conditional expression is added. It is added after the conditional that promotes the targets. The Conditional looks like the following:
The Routing Expression expanded:
wt.maturity.PromotionNotice pn = (wt.maturity.PromotionNotice)primaryBusinessObject;
try
{
java.util.Locale locale = wt.session.SessionHelper.getLocale();
com.ptc.core.ui.validation.UIValidationResultSet set= com.ptc.windchill.enterprise.maturity.PromotionNoticeWorkflowHelper.
revisePromotables(pn, pn.getCreator(), locale);
reviseValidationMsg= com.ptc.windchill.enterprise.maturity.validators.PromotionTargetsReviseValidator.getReviseResultSetMessage(set, locale);
if (!reviseValidationMsg.isEmpty() )
result="Partial";
else
result="Full";
}
catch( Exception wte )
{
wte.printStackTrace();
}
The method revisePromotables(pn, pn.getCreator(), locale); performs the revision of the promotion objects following the preferences defined above in the Solution section.
Once the eligible promotion objects have been revised a message is created containing any promotion targets not eligible for promotion along with the reason why the promotion object was disqualified. This message is sent to the promotion creator. Any valid promotion targets will be revised independent of whether there are any disqualified targets.
| If promoting CAD Documents and Parts together, if the revise disqualifies either the part or CAD document, the objects will not be revised together and will need to be correctively fixed by the promotion request creator (or another user) after promote. |
Promotion Process as a Gate Review Process
For companies that use the Promotion Request as a "Gate Review" for production, a best practice is to switch the revision labels for objects from a numeric series to an alphanumeric series. With a proper life cycle design, such a gate state can be modeled that achieves the desired target state and automatically revises the promotion candidates to the initial revision label of the new revision series.
The following FIT table describes how this scenario would work based on various values of the preferences described in the Solution section.
Promotable | Is Life Cycle State Based | Preference | Preference Value | Preference | Preference Value | Valid for revise |
part_1 | No | Automatic Revision States | Released | Automatic Revision Mode | Automatically revise all the promotion candidates | Yes |
part_2 | Yes | Automatic Revision States | Released | Automatic Revision Mode | Automatically revise only the promotion candidates with versioning scheme changed | Yes |
part_3 | No | Automatic Revision States | Released | Automatic Revision Mode | Automatically revise only the promotion candidates with versioning scheme changed | No |
part_4 | No | Automatic Revision States | In Work | Automatic Revision Mode | Automatically revise all the promotion candidates | No |
For this example the Maturity State of the promotion request is “Released”. In addition each part is in its own unique container.
Procedure – Validation of Promotion Targets in Rework
The automatic refresh capability detailed in the section: Procedure — Adding Automatic Refresh, has been extended to check that if there is a later iteration of the promotion target to be refreshed, that this iteration is valid for promotion. The following checks are made:
• Promotion Target is not checked out.
• The creator has modify access on the Promotion Target.
• The LifeCycle of the promotion target has not changed since the promotion was created.
• The State of the promotion target has not changed since the promotion was created.
Workflow Template
Here is the expanded promotion notice workflow template with validation.
A conditional has been added to perform the above checks. An email is sent to the creator with a list of promotion targets that cannot be promoted (if any). If some targets of the Promotion Request cannot be promoted, the Promotion Request is sent back for rework where the creator can either submit or reject. If all targets are valid the promotion request is sent for approval.
