This post is about a Participant that resolves the parent work item, if all children are resolved. It is the example I used to understand the server API for manipulating work item states. I would probably not use it on a production system, because I strongly believe that a human being should do a conscious decision in cases like that, but it is a nice example about the RTC Work Item Server API.
License and how to get started with the RTC API’S
As always, our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license, which basically means you can use it for internal usage, but not sell. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!
If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.
You should be able to use the following code in this environment and get your own automation or extension working.
The example in this blog shows RTC Server and Common API.
Download
You can download the code here.
The download contains the (slightly enhanced) UpdateParentDuration Participant described in this post, the UpdateParentStateParticipant and the WorkFlowPathfinder from this post as Eclipse projects. In Eclipse use File>Import and select Existing Projects into Workspace. Select the downloaded archive file and do the import. This version of the WorkFlowPathFinder has the Plain Java Client Libraries dependency removed and is treated as real plug in, to provide its services to the other plug ins.
Please note, If you just get started with extending RTC, I would suggest to start reading this and the linked posts to get some guidance on how to set up your environment. Then read the article Extending Rational Team Concert 3.x and follow the Rational Team Concert 4.0 Extensions Workshop at least through the setup and Lab 1. This provides you with a development environment and with a lot of example code and information that is essential to get started. You should be able to use the following code in this environment and get your own extension working.
UpdateParentSateParticipant
The project com.ibm.js.team.workitem.extension.updateparent.participant contains the class UpdateParentState. This implements the Participant that
- Checks if there was a state change
- Checks if the new state is a closed state
- Checks if there is a parent
- If there is a parent, checks if all children are closed
- Resolves the parent If all children are closed
The UpdateParentStateParticipant can use different strategies to do the state change. The code below shows some of the available options.
if (!resolveBF(parentHandle, monitor)) {
// if (!resolveDF(parentHandle, monitor)) {
// if (!resolveWithResolveActionID(parentHandle, monitor)) {
// if (!gotoStateBF(parentHandle,"4",true, monitor)) {
The methods resolveBF() and resolveDF() use the Breadth First and the Depth First strategy against the resolve action. The method gotoStateBF() uses the Breadth First strategy but uses a target state instead. The method resolveWithResolveActionID() only tries to apply the action ID. You can play around with the different strategies and pick the one you like best.
The resolve Action needs to be defined in the RTC work Item workflow as shown below, otherwise the state change can’t be done, because no path can be found.
The WorkflowPathFinder class in the download provides two other ways to find a target state, instead of a target action. The methods are called findPathToState_DF() and findPathToState_BF().
UpdateParentDurationParticipant
The UpdateParentDurationParticipant is slightly enhanced compared to the state in RTC Update Parent Duration Estimation and Effort Participant post. It checks if there are changes to the duration and estimate values before doing anything else.
The code also contains several methods to analyze the work item links on the server as described in The RTC WorkItem Server Link API post.
Summary
The code is experimental. I have tested it in a Jetty based test server using the Scrum template. It is by no means production ready and can be enhanced for various scenarios. However, as always, I hope the code is an inspiration and helps someone out there to save some time. If you are just starting to explore extending RTC, please have a look at the hints in the other posts in this blog on how to get started.
rsjazz 
Pingback: Manipulating Work Item States | rsjazz
Pingback: RTC Update Parent Duration Estimation and Effort Participant | rsjazz
Pingback: The RTC WorkItem Server Link API – Linking to Work Items and Other Elements | rsjazz
Very important concept. Thanks.
question on the close parent code.
in both the DF and BF functions you do
Path path = tManager.findPathToAction_DF(workItem.getState2(), resolveActionId);
ArrayList transitions = path.getElements();
for (Iterator iterator = transitions.iterator(); iterator.hasNext();)
{
PathElement pathElement = (PathElement) iterator.next();
return saveWorkItemStateTransition(workItem, pathElement, workflowInfo, monitor);
}
if u return on the first iteration in the for loop, why use a for loop? why not just use the first element in the returned path list? transitions.get(0);
if u intended to see if the transition WORKED before exiting the loop, then u have to check the returned status from saveWorkItemStateTransition()
right?
Sam,
in what I have on disk, the _BF calls _BF and _DF calls _DF – at least on first glance. The difference between the algorithms are:
DF – depth first, picks the first action in the list and tries to find a path to the target, by recursively calling itself. If there is no path at some level for any of the available actions, it falls back up to the next higher level. There it needs to take the next possible action and try that on that level. Therefore it needs the for statement. This is called recursive descend and path theory proves that, if there is a path, you will find one. It is the first you can find, but not necessarily the shortest one.
BF – breadth first: This tries all actions from the current state first. If it does not find a direct path, it tries from the states the available actions lead to. It also does this recursively, but it will pick the shortest available path it finds first.
In my example I am only interested in that there is a path I can follow.
If I found a path, I follow it. If the transition can’t be done due to other advisors, this will stop with an error on the way.
You could potentially try other paths and make the algorithm return a path list, but this is way too complex for my purpose. I want to show how this works in general and not show a one-size-fits-all solution. So the example and assumptions need to be simple enough.
Dependent of your environment, you might have to adjust it to what you need.
How deploy it in production ?
Follow The extensions workshop mentioned https://jazz.net/library/article/1000
Hi Ralph,
If I’m resolving a child WI, and the parent WI is being resolved automatically, but by some conditions, the parent WI can’t be saved (due to precondition that prevent the parent WI to be saved) –> I receive an exception in the saving function –> this cause the saving of the child WI also get error & it can’t be saved. Even if I catch the exception from saving parent, the save action is still impossible. What I want is whenever there is an error in saving the parent, I can catch the error & put it in the log, the child WI still can be saved. Do you have any idea on how to “cancel” the saving error in the participant?
Thanks.
There is no way to cancel the saving error. It is most likely happening due to an advisor or some other operational behavior. All you can do is to get the error and present it as a status. Automation can not break the rules.
Another approach would be, if this is in some automation e.g. build, to give the user a role that does not have the operational behavior enforced.
Hi,
Is there a way to do pre-validate for a work item before saving it? Or a way of “try-save”? Is it possible to detect if the work item can be save or not? Then decide to call the save function, otherwise nothing will happen.
A pre-condition or advisor is used to do that. See https://rsjazz.wordpress.com/2014/05/26/only-owner-can-close-workitem-advisor/for an example. The code is pretty similar to the code for participants. Other, field based, options are validators as discussed in https://jazz.net/library/article/1093.
You can however not try the save and then decide. This runs in a framework. I have no idea if you could run some code (and when) to test the save and then abort it.
HI Ralph, I have gone through the https://jazz.net/library/content/articles/rtc/4.0/extensions-workshop/downloads/RTC4xExtPoT.pdf workshop completely using (RTC 501) and all results were matching the lab exercise. Now, i need to simulate this to my original requirement “Auto close the parent Story, when the child tasks are closed”. Can you please tell me what all, i may need to inherit from this workshop and list of things that i need to achieve this task ? I downloaded the code from above post.
This post https://rsjazz.wordpress.com/2012/11/27/resolve-parent-if-all-children-are-resolved-participant/ contains all the code you’d need. You basically only have to download the code and import it as Eclipse project. Once you have done that, review the code and you will see that it is very similar to the code you know from the workshop.
The purpose of my blog is to provide people with examples that they an start with. On top of that, there s very limited I can do.
Hi Ralph, Thanks for the details on this “Resolve Parent If All Children Are Resolved Participant”. I tried to download the package. There is a error message popup with following link.
https://dl.dropbox.com/u/12668004/UpdateParentParticipants/20121127_UpdateParentParticipants.zip might be temporarily down or it may have moved permanently to a new web address.
If it is moved to NEW address, can you please let me know where I can find it?
I can download it without any problems. As suggested in the download description, your company might prevent access to dropbox and you would need to use a private account.
Hi Ralph. Thanks a lot for these great posts. Do you have a sample how to create child task for defect? Thanks in advance.
See https://rsjazz.wordpress.com/2016/10/24/using-the-work-item-server-api-to-create-work-items/ note you can search the blog. That is server API, I believe I have client API examples as well.
Thank you very much. Appreciate