It's all about the answers!

Ask a question

RTC API confusion - defect creation - serverside

Zaid Al-Khishman (351115) | asked Dec 17 '14, 4:58 p.m.
edited Dec 18 '14, 12:05 p.m.
Hi guys

I'm trying to create a defect via the server RTC API through a deliver participant but I'm getting confused by the API once again. I'm running into problems setting the "filed against" field (At this point I can't tell whether it's a "Category" or an "Attribute" from RTC's perspective)

The loop that prints the required "Attributes" that need to be set before you could save a given Item prints that "category" is one of the things that needs to be set (and not "filed against") luckily I happened to stumble upon getCategory which, according to the documentation, "Returns the 'filed against' category". Now what is it really returning a 'template' category or the actual category? (i.e will I have to use it to eventually call setCategory) or just call methods on it and those will eventually have a side effect of setting the category?

I'm currently assuming the latter and have tried a couple of things: first of all I can't call setName on the category (which seems to be what I want) because it's deprecated. The documentation suggests that I try calling workItemService.renameCategory() in order to accomplish the same side effect (I think the function names are a bit misleading here in my humble opinion).

Currently the call to renameCategory throws a "null arguement" exception with no other details and I can't find documentation for this method either, and I can't figure out which of the arguements it's complaining about (neither of them look null to me) unless it can't make sense out of "Scrum_area" and is unable to report the error more thoroughly. If I comment it out filedagainst.getName() returns "Unassigned" which would make sense if the Category's name represented the "filed against" attribute's (or Cateogry's) value.

              Collection<String> required_attributes = fWorkItemServer.findRequiredAttributes(newWorkItem, null, monitor);
              List list = new ArrayList<String>(required_attributes);
              for (String z : required_attributes){
                  System.out.println("required attribute: " + z);
                  IAttribute attribute = fWorkItemServer.findAttribute(projectArea, z, monitor);
                  if (attribute != null ){
                      System.out.println("Attribute isn't null");
              ICategoryHandle filedagainsthandle = newWorkItem.getCategory();
              if (filedagainsthandle!=null){
                  fWorkItemServer.renameCategory(filedagainsthandle, "Scrum_area", monitor);
                  ICategory filedagainst = (ICategory) fItemService.fetchItem(filedagainsthandle, null);
                  if (filedagainst!=null){
                      System.out.println("found Cateogry");
                      System.out.println(filedagainst.getName() + " - " + filedagainst.getHTMLDescription());
                  }else {
                      System.out.println("found Category handle but not Cateogry");
                  System.out.println("Category not found");


Accepted answer

permanent link
sam detweiler (12.5k6192201) | answered Dec 17 '14, 5:52 p.m.
edited Dec 17 '14, 5:53 p.m.
Ok, you need to step back just a little

the system is 100% object oriented. and there are some basic rules..

  1. an object HANDLE is stored in the database such that it is persistent.
  2. the handle has limited data in it. you must reconstruct, in memory, the full object by loading some of its attributes from other (unknown) storage locations in the repository.. the itemManager (or service depending on client of server side perspective) does that work.  the ItemProfile specifies how many attributes are needed.
  3. a 'category' is an object. has a handle, and can be loaded from the repo like other objects.
  4. the object loaded into memory by the item manager is almost always read only.  to get a read/write copy you need the objects workingcopy. I do not know if createWorkItem2 creates the working copy.. but maybe.  (if u set fields and do not blow up with the immutable exception then you are probably good)
my sample that dumps out the workitem attributes (client side) may help you, see the accepted answer here.
I don't think it prints out the category name. but you could add that easily.

I don't understand why you did the rename on the category.. that is an admin thing..

there are (usually) MANY categories in a project area that COULD be used.. getCategory() returns the one ALREADY assigned to this workitem, but as the workitem is NEW, that field is empty.
you will want to use IWorkItemCommon
findCategoriesOfProcessArea(IProcessAreaHandle processArea,
                                                    ItemProfile<ICategory> profile,
                                                    org.eclipse.core.runtime.IProgressMonitor monitor)
to get the list of potential categories to use.. note that category is a team routing function.

enumerations are also a list of items,  the ID is whats needed, not the user readable name string.

I suggest you learn to do this in a client app.. and then the API won't be so different.. just the service points
client vs service

Zaid Al-Khishman selected this answer as the correct answer

Zaid Al-Khishman commented Dec 18 '14, 12:16 p.m.

"I don't understand why you did the rename on the category.. that is an admin thing.."

I'm not sure what this method does. All I'm trying to do is assign a value to what is returned by "getCategory" which, according to the documentation, "Returns the 'Filed against' Cateogry which I know for sure needs to be assigned for a defect before you could save it (that's how it is via the webclient). On the other hand according to the findReqiredAttributes Method 'Category' is one of the things that need to be set (before you could save a work Item I presume). I tried to call setName on whatever is returned by the category thinking that it would assign a value to 'Filed against' but the documentation says that this method is deprecated and renameCategory must be used instead. Now clearly if the two functions have the same functionality then one of the two names is ambiguous, which according to what I could figure from what you said it's the name of the deprecated function.

sam detweiler commented Dec 18 '14, 1:38 p.m. | edited Dec 18 '14, 2:04 p.m.

Ok, I think you are still stuck..

to create a workitem, you need to create an in memory copy of the workitem type model (room for all its defined attributes).. this in memory image is clean, and empty. (uninitialized)
YOU have to initiialize all the variables (required, and desired)

each variable will require some handling in your code to set/initialize the proper content

some get handles to other objects (categories, users, found in, ...)
some get strings (summary, description, comment text)
some get ids of entries in lists (priority, severity, ...)

you can also create links to other objects (aka references) before saving the workitem.

then after you have initialized the workitem, in memory, you have to then save it to the repository for it to become persistent.

setName on a category object is one of the methods you would call if you were creating (initializing) a NEW category object to be stored in the repository.

One other answer

permanent link
Zaid Al-Khishman (351115) | answered Dec 18 '14, 2:56 p.m.
edited Dec 18 '14, 3:18 p.m.
Hi Sam, this is what was missing. Its a result of the answer that you pointed me to and this link which I also dereferenced from your answer. Here is one approach to solve the problem. Scrum_area is the name of my project area and it can be chosen as a value for the 'Filed against' field in a defect .

              ItemProfile<ICategory> profile = ICategory.DEFAULT_PROFILE;
              List<ICategory> listofCategories = fWorkItemServer.findCategories(projectArea, profile, monitor);
              for (ICategory cateogry : listofCategories){

sam detweiler commented Dec 18 '14, 4:03 p.m.

yep, that is one method.. glad u are making progress.

Your answer

Register or to post your answer.