Page 1 of 1

Document structure roles (structureLinkRole)

Posted: Mon Mar 02, 2020 11:39 pm
by CoJeff
I seem to be having some issues with this. Some documents can be created with role to headings as 'Parent' and others 'Refines'. I don't see the option to create a document with a link role as parent for a particular workitem. If a document has a structural role as refines then how can I change it?

Also I saw this in the user/admin manual, Have a dedicated role for your Document structure role. (One that cannot be used for normal Work Item links.)

I had someone try to link a product req to another product req but got the following error "Sorry you cannot create a Module structure link here. To Change the module structure please use the Module's Designer tab". Is this the link item roles? I don't see Module's Designer tab anywhere. Why would one Prod Req have Refines listed as a link and some do not?

Re: Document structure roles (structureLinkRole)

Posted: Wed Mar 04, 2020 6:16 pm
by J├╝rgen

the document structure role "parent" is very special. It seems to be a normal link role but there are some dependencies that a normal link role does not have. Its behavior looks so strange that in my company we decided to forbid the use of a different role than parent in a document.

If you use "refines" instead of "parent" in a document, that in the first place means that the following links have a different role
- heading to parent heading
- work item to parent heading
- work item to parent work item (when indenting).

Another consequence is this: Normally it is not possible to use the parent role outside the document, so you cannot use it for example in the link section of a work item. It is set and removed only by editing the document or moving work items in and out.

The used role for a document is defined when the document is created. If I remember correctly it cannot be changed afterwards (can't test it at the moment). I think the slightly misleading error message tells you that (module = document). I assume that the "Designer View" is the view when you open a work item in a separate windows. I have googled that expression and it seems to be kind of ancient, so maybe this is a very old message that was never adapted.

When you use refines instead of parent for the document, that means refines takes the place of the parent role, so for all the work items in that document you cannot use the refines role manually any more, so you cannot create manual links to items e.g. in other documents with that role. That explains that for some work items you can use the refines role normally (all work items that are in another document for example), and for some you can't.

If you generally use the refines role for formal traceability, it is (imho) a bad idea to use it within a document as document role, else you will probably not be able to create a correct traceability. You should probably create a new document with the default link role and move the items into that document, afterwards deleting the wrong doc.

The hint in the manual tells you exactly that: use one role (parent) in all documents and only that one. You can also create a separate link role just for that purpose, but never mix it up with the other link roles.