DOORS Link Modules – Explained!

One thing that really confuses new DOORS adminisrators is link modules. When I say that DOORS is not Access, one thing that makes DOORS different than other databases is link modules.

I think Telelogic, both in their documentation and in the DOORS UI, makes way too big a deal out of link modules. Link modules are just a container, yet going through the documentation it’s not clear exactly what that container holds.

Link modules are like airports, and linksets and link mappings are like flight paths. Source formal modules objects are passengers, and target formal modules and objects are destinations.

Is everyone with me so far?

Let’s say we have DOORS modules representing Customer Requirements, System Requirements, and Software Requirements. Let’s say no link module exists, and no link mappings yet exist. Someone creates a link from Software to System. DOORS will ask if a link module should be created, and if the user says yes, DOORS will ask if a linkset should be made. If the user says yes to that, the link gets made.

The created link module, named DOORS Links, will be created in the same folder as the Software module. DOORS will have created a linkset for the relationship Software to System requirements. This linkset will be contained in the link module. At this point we should rename DOORS Links to something a little cleaner, like “Links to System.”

This linkset is like a flight path. A passenger just took a flight from Software through the DOORS Links airport, arriving at target destination System.

Let’s say another airport is created. We want to use this airport to link Software Requirements to a new module, SSDD. Let’s call this airport “Links to SSDD”. (In other words, in the same folder, create a link module called “Links to SSDD.”) In the Software Module, I can go to File>Module Properties and choose the “Linksets” tab. The name of this tab is misleading. What you are doing here is defining link mappings. Linksets are defined in Link Modules.

Link mappings are flight paths too. But unlike linksets, they can be mandatory flight paths.

In the “Linksets” tab, click the “Add…” button. As the target module choose SSDD, and then set “Links to SSDD” for the link module. Check the Mandatory checkbox and make sure Overridable is unchecked. Click ok. Finally, check the “Only allow outgoing links as specified in the above list” checkbox. Click OK.

When a user creates a link from a SW requirement to the SSDD requirement, DOORS will now use the “Links to SSDD” as the link module. When the first link is created, DOORS will ask to create a linkset for SW to SSDD links. When the user agrees to have DOORS create the linkset, the link is made.

In other words, SW passengers traveling to destination SSDD will be required to use the “Links to SSDD” airport and the SW to SSDD flightpath. Yes, there’s the “Links to System” airport as well, but that airport doesn’t feature the same flight path, and even if it did (and it can, in case you were wondering), we’ve mandated that our SW passengers traveling to SSDD have to use the Links to SSDD airport. They don’t have a choice, similar to many passengers who use the airport in real life.

What if we didn’t make that airport mandatory, or we made the airport overridable. Well, in DOORS you can do that, and in my opinion it’s a horrible idea. As Administrators, we’re like the FAA. We control the flight paths. Letting commercial pilots fly freely without using flight paths is a recipe for a crash, or at the very least, some near-misses.

This all sounds really complicated, I bet. To me, there is too much thought invovled for my end users, and I like to make things really easy for my users. The easier things are for them, the easier my job is.

 Once the above has been set up to be mandatory, DOORS does the work for the users automatically when it comes to creating links. Users don’t have to worry about link modules and mappings and linksets when it comes to creating links through the interface. But as soon as they use Link By Attribute, Delete Links, or the Analysis Wizard, they have to start worrying about link modules. And when you have multiple link modules, the user has be savvy enough to realize what they’re doing.

My rule of thumb is unless there is a very good reason to do otherwise, every folder should have a link module within it in DOORS, and every module within said folder should use the same link module.

So if I have a folder for Use Cases, with 10 Use Case modules inside, I set up my databases to have just one link module for Use Case Links. Now the target module (ie., destination) for each and every Use Case may be different.

So if Use Case 3 links to System Requirement modules A and B, and SSDD Modules 1 and 2, when I run the Analysis Wizard for all modules and choose the Use Case Links link module, I’m going to get all outgoing links. Whereas if I had set up a separate link module for System requirements versus for SSDD requirements, then using the analysis wizard, it would be much easier for me to see just the SSDD links, not bothering with the System links.

Why, then, would I put all outgoing links in one module? It’s simple–I can always edit the DXL that shows traceability to exclude certain target modules!

Therefore it’s a trade-off. I make my life a little harder because I have to create custom trace reports from time to time, to make everyone else’s life easier with not having to worry about which links go in which link module. There is nothing to worry about, as there is only one link module in each folder!

My personal opinion is that this is bad design in DOORS. An end user should never, ever have to worry about link modules. And most of the time they don’t. But if they ever do, you can make it easier on them by letting the answer be obvious.

And that can be done using multiple link modules or just one. The choice is up to you. The important thing for admins to realize is that link modules are containers for linksets, and a link “travels” along a linkset, thus you really want to define your flight paths, so that when it comes time to do traceability, your traceability matrix is easy to understand.

Each module that gets created needs to be maintained. This includes link modules. So my last piece of advice is to make link module maintenance easy. Since links can only be created from a user who has edit access on the source module, make the link module have permissions for group “Everyone else” to “RMC”. This way, you don’t have to manage group permissions for link modules. If I don’t have edit access to a module, then I can’t create a link. But once I do have rights to that module, you as the Admin won’t have to go in and grant me rights to the link module. I’ll be able to create links instantly, and thus don’t run the risk of creating another link module called “DOORS Links”.

 Once you make the choice on how to set up your link modules, be sure you know why and be sure it’s documented. Maybe you want a separate link module just for internal links rather than external links. Maybe you want to control traceability via DXL, like I tend to do. Just know why you’re doing what you’re doing and then be consistent. Easier said than done most of the time, but not with link modules.

Leave a Reply