It's all about the answers!

Ask a question

ERM - When to link Module Artifacts versus Linking Base Artifacts

Robyn Riley (153) | asked Sep 28 '22, 3:15 p.m.
Does anyone have any recommendations for linking to base artifacts vs module artifacts in ERM? We actually don't see any reasons to link module artifacts to EWM or EQM, plus those links don't seem to create the traceability we are interested in seeing between the 3 tools.

But within ERM, is there a valid reason to link to module artifacts?

Accepted answer

permanent link
Davyd Norris (2.4k217) | answered Sep 28 '22, 9:56 p.m.
edited Sep 29 '22, 3:19 a.m.
Modules in ERM are described really badly in the Knowledge Center and it causes so many misconceptions and problems!

I personally hate the way they talk about "Base Artefacts" and "Module Artefacts" - this is a hangover from the folks who came from DOORS 'Classic' and really hampers understanding the power of DOORS Next. The best way to think about this is that a piece of text is just an artefact, and it lives in, and is owned by, a project area. There are 4 ways you can aggregate or group artefacts:

 - Folders: this is actually pseudo-attribute on an artefact (nav:parent) and is set when you create or move artefacts around in the folder structure in the UI. Artefacts can only belong to one folder at a time because the pseudo-attribute can contain only one value at any time. It's a neat way to organise artefacts in the UI

 - embedding: I won't discuss this here as it's not relevant

 - Collections: a Collection is like a virtual "bag of stuff" but, unlike a real bag or DNG Folders, the same artefact can be put into multiple Collections at the same time. Collections are defined as Artefact Types in DNG for ease of management, but they are a separate thing in the OSLC spec and there are API services that let you manage and retrieve them. Under the hood they are a list of references to artefacts within the Project Area

 - Modules: a Module is best thought of as a "Collection with a Context" and this is what makes them so powerful in DNG. If you use the OSLC API and ask for all Collections, you'll get back Modules as well, and you can see that, just like Collections, they are a list of references to artefacts. However, Modules extend the Collection concept by also adding a Context for each of these references that then identifies the order, indenting, and styling applied to the artefact within the context of that Module. The Context also remembers the link ends, tags and Comments made for that artefact in that Module's context.

This is what makes Modules powerful, and allows you to do some very cool (and very confusing!) things:
 - the context keeping track of the order, indentation and styling of artefacts makes it great for making the contents look and feel like a document, and this is the most common reason people create Modules

 - a Module's context means that the same artefact in two different modules can be in different positions, at different levels of indentation, and even styled in one module to show as a numbered heading but in another as regular text (not to be confused with creating a Heading Artefact Type). You can even add the exact same artefact into a Module multiple times and style/indent it differently. This is often done by mistake, but I've used this deliberately to create "Executive Summary" sections or Appendices for requirements that need calling out in some way in a document

 - a Module's context also means that tags and Comments made in one module will not show up in any others. By being careful about where you apply tags and comments, you can make sure they are seen EVERYWHERE (add at artefact level), or just within that specific Module. This is great when you have different versions of a document, or a subset of requirements reused across different places and your comments (such as within a review) should only apply in one specific Context.

 - finally a Module's context means that visibility of the ends of Links can be controlled. Again, many people do this by accident, but it's super powerful when used deliberately. A great example is where you have a set of requirements that get reused across several subsystems or components. If you set up the upward traceability to stakeholder requirements at the artefact level, then no matter which component you add them to you'll see where they were derived from. But if you set up downward traceability to test cases at the module level, then the test cases and results will be specific to that component only. Even better, you can then report on every component where that requirement has been used, and the current individual status of the testing or design process for each of the subsystems or components.
Robyn Riley selected this answer as the correct answer

Robyn Riley commented Sep 29 '22, 2:32 p.m.
Thank you so much for all of this information. First, it's nice to know that I am not alone in my confusion regarding base vs module artifacts. The information that you have provided has verified what I've been trying to document for my users.

When linking between requirements artifacts and EWM work items or ETM test cases, you also could use either base or module artifacts depending upon your reporting needs. We need to be able to show full traceability throughout ELM, and Report Builder reports seem to rely upon the base artifact links for that. As a best practice, how is your team handling the validated by and implemented by links?

Davyd Norris commented Sep 29 '22, 8:22 p.m. | edited Sep 29 '22, 8:23 p.m.
Hi Robyn,

Report Builder can use links at either level very successfully, but once again it requires you to really understand and be rigorous about your linking strategy.

Again I personally really struggle with how Report Builder (or actually the Data Warehouse) does things - the warehouse generates different internal ID numbers for the same artefact in each different context (global or a module) and uses those IDs in the query for traceability. I really wish it just used the DNG ID because life would be so much easier

What this means is that you can use the wizard UI to create a report as long as you can draw an unbroken line from artefact to artefact - if you need to build a trace from a link end at global/artefact context to one in a module context, you have to use Advanced mode and change the query to use the DNG ID and not the DW ID

Full disclosure - I worked for Rational and IBM for 20 years in this area, and am now an IBM Business Partner. I know most of the product team and yell about this constantly!

Davyd Norris commented Sep 29 '22, 8:33 p.m.
To answer your question at the end - it depends :-)

The key thing is whether a requirement appears in a single subsystem/component spec or not - if you never reuse your requirements then it really doesn't matter whether the link end sits at artefact or module context, but if you manage your product versions and variants by reusing requirement text within multiple modules, then it's important to know how the implementation of each component is going and so you will want to link tasks and tests to the requirement within the module.

That way you can create reports that show testing coverage for specific component specs, the progress of a requirement in one specific component, or the total progress across all components that rely on the requirement. More importantly you can very easily see the impact of changing a requirement and everything it might affect

Robyn Riley commented Sep 30 '22, 12:13 p.m.
So it sounds like we just need to come up with a strategy and document for our organization. Linking from base or module artifacts is available in the report (I spent an hour yesterday creating a report that shows modules, artifacts within them, and links to higher level requirements (stakeholder and business requirements).
We currently are dealing with a mish mash of linkings; in some cases users have used module links and base artifact links for the same link.

Thank you for sharing your experience and knowledge with me; I greatly appreciate it.

Davyd Norris commented Oct 01 '22, 11:21 p.m.
I think you've identified your biggest issue - lack of a standard approach. Once you have this in place you'll find things get so much simpler.

One other answer

permanent link
David Sedar (2818) | answered Oct 27 '22, 5:29 a.m.

 Many of my ERM users (v7.0.2) suffer from this same problem when creating links between Artefacts (thanks for the proper spelling) in Modules.

They often forget to select the Module, before the Artifact when creating a link and end up inadvertently creating a 'Base Artifact' link.
These show up with the famous blue arrow next to the link icon in Views, but are excluded by /jrs when put into a report, hence wasting their effort.
Short of better education, has anyone found a better way to address this problem??

Davyd Norris commented Oct 27 '22, 9:52 p.m.
The ability to create link ends in either global or module context is not a problem - it's actually a really powerful capability. However, it does require you to think through your RM strategy and schema and make sure people understand it.

What would be good is if link constraints allowed you to specify context as well, or if you could easily change context on links - I've written a DNG Extension widget that allows this to be done in bulk for my clients.

David Sedar commented Oct 28 '22, 5:23 a.m.


any chance you could persuade IBM to incorporate your DNG extension into the mainstream SaaS product? 
I would love to see a restriction placed in the Add Link dialogue that greyed out the Folder radio-button if only Module links were permitted and ideally to only include valid modules in the selection list.

Your answer

Register or to post your answer.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.