​​​​​​​​​​​​​​​​​​​​​​​​Draft documentatio​​n for using DOORS NG for LBNF

Anne Heavey

Getting started

Prior to posting the requirements to EDMS, the SE group uses the Requirements Management Tool, “DOORS NG" to gather requirements are establish traceback links. DOORS also provides a platform for reviewing the requirements with the various stakeholders of the project. The DOORS environment is used to define, update, and review requirements in the early stages of the requirements' lifecycle before being placed under configuration control. Once the requirements are placed under configuration control, they are exported to EDMS and subjected to a formal approval process.​

Please read the relatively short Requirements Management Plan (docdb 7626​). It defines terms (e.g., requirement, objective, specification), describes the hierarchical structure for requirements, and describes how to draft requirements and the other items that accompany them. It also lists the metadata that goes with each item. (It also describes some processes for the systems engineering team that you can ignore.)

In DOORS NG we have configured a template according to this plan, and created what DOORS calls a "project" for LBNF/DUNE using this template. It provides a field for each defined piece of metadata.​

Instructions for Approvers to approve/disapprove requirements

  1. Click the link in the automated email from "pawelg@fnal.gov"
  2. The following pop-up window appears. Enter your services account information.



3.  The following window appears after login. Now Click the box next to the requirement/artifact to review as shown below.

4.  Upon completion of the approval/disapproval process click "DONE". This ends the "review" of the artifacts/requirements.


5. NOTE: If you have somehow navigated away from this page, please use browser back button to bring you back or just go back to your email and click the link again.


How to access DOORS NG

DOORS Next-Generation is web-based. It is designed with the intention that manipulation and review of requirements be conducted within the app, rather externally, using exported information. That said, the latter option is always available.

Fermilab owns two floating licesnces for this product. If you try to access but can't, you'll have to try back later. We don't expect there to be much if any conflict given the number of people likely to use it at any given time.  To get access:​

  1. First get a Fermilab services account (give link) if you don't have one.
  2. Request authorization to this application by sending an email to dune-communication@fnal.gov.
  3. If you are not onsite at Fermilab, you must connect through VPN (give link).
  4. Development version link: https://cdv-doors-d.fnal.gov:9444/jts/​
  5. Go to the URL https://requirements-mgmt.fnal.gov:9443/jts​ and log in with your FNAL services account.
  6. Production link is https://cdv-doors.fnal.gov:9443/jts ​
  7. You will see a screen like this (get screenshot):

Select the project (whatever it will be - show in screenshot)
Click on "Artifacts".

Notice the folder structure, and use it to locate the set of requirements that you want to access.


How to manipulate your vie​​​w of a module's requirements (which columns to show)

  1. Start on the Artifacts page, with "All" selected).
  2. In the (grey) module heading, click the icon with the two rectangles and the down arrow (usually second from left).
  3. Select "Configure columns to display..."
  4. In the popup, you can select the attributes and/or link types that you'd like to display, add or remove them, set the column widths, and order the attribute fields.
  5. To save the view, click "Views" (to the right of "Folders" on the left side of the Artifacts page). 
  6. Click the icon with the yellow plus sign to add this view and name it. You can choose it to be a personal view or a shared one.

How to add a tr​aceback link

  • Start with a child requirement (to make a link back up to its parent.)
  • (Note that you could do it the other way around - parent down to child - but we'll document how to do child-up-to-parent)
  • Make sure you have easy access to the list of parents for each child (prepare ahead of time). You will need to match legacy ids and new ids.
  • Make a note of different child requirements that link to the same parent or parents - you can make all these links in one operation.
  • Select your child requirement(s) - check box(es) at left of each requirement.
  • Click edit button of one of them, select "Add link to (n) artifact(s) --> Child of"
  • On the popup, choose the module that the parent(s) is/are in.
  • Order the list of requirements in that module by id (if function is available) and find the first parent.
  • If there are more parents, hold down control (or command on Mac) button and select all the parents you want.
  • Click OK.

How to add a tag to all artifacts in a module

  • Display the module with all the artifacts listed.​ (Best to make sure all are listed on first page.)
  • On first listed artifact row (either a heading or a requirement, usually), click the edit button.
  • Click "Select tags for (n) requirements..." (where n=the number of artifacts displayed on the page)
  • On popup, select New Tag, and write in the appropriate abbreviation for the module, e.g., FDSP-TPC or FDDP-HV.
  • Select the new one in the box that lists all the available tags.
  • Click OK

Documentation for the DOORS​​-NG "Gurus" 

(​requirements owners will not be responsible for these actions)

Prepare requirements s​​preadsheets for import into DOORS NG​


Make sure your spreadsheet corresponds exactly to the template.

  • Columns correspond to attributes, EXCEPT the "Artifact Type" column is used to set the type -- it is not an attribute.
  • The spreadsheet may have fewer columns (i.e., it is ok if not all attributes are accounted for), but it may not have any extra columns. 
  • The column name must correspond exactly to the attribute name, or the Type name.
  • Column values (i.e., the values in the cells of a column under the column name row) must correspond to the attribute data type (not case sensitive).
  • The spreadsheet format is uploaded, too, so make it look the way you want (e.g., white background, black text, bold/not bold...)
  • ​Double and triple check format and data; it's easy to get errors!
  • When it's all ready, copy the active portion of the sheet into a brand new workbook and import the new one. I don't know why, but this is how I get it to work.

Find the list of attributes and types:

  • In upper right corner of screen, pull down the gear menu and select: Manage Project Properties.
  • In white ribbon (under blue ribbon), click "Artifact Types" or "Artifact Attributes" to find them.
  • For the actual requirement (or other type) text, title the column: Primary Text.
  • For the requirement heading, title the column: Name.


​​How to create a folder

  • Select top level folder (under which you want your new folder) and click the "edit pencil" icon.
  • Select "Create Folder..."
  • Give it a name, click Ok.
  • The popup may not go away without clicking ok or X a couple of times (ask Pawel)
  • If you want to move it to a different location:
    • Select it and click the "edit pencil" icon
    • Select the folder you want it to reside under and click OK.


How​ to create a module

Notice the folder structure. Folders can contain other folders, or they can contain artifacts directly. A module is an artifact; so is a requirement (a row in a module).

We want to set up a structure of folders for our project that follows our traceback structure, more or less. 

Remember: one spreadsheet equals one module. 

  1. Go to top level folder (I'm selecting the container folder) 
  2. Click "Create" and select the item that says "Use with Module format".
  3. This brings up a popup.
  4. Give the module a Name.
  5. Under "Type" make sure that Artifact Type is set to "Use with Module format" and Artifact format is set to Module.
  6. Leave Template as "None" (Unless we decide to change this)
  7. Under "Location" check that the Folder is the one you want to contain your module.
  8. Click Ok​
  9. (see 'after-create-new-module.png) under requirements)
  10. This brings you to a page that tells you "this module is empty. To add content you can..."
  11. Don't do this now. We'll have separate instructions for uploading a new/updated spreadsheet, and adding artifacts (requirements) one-by-one. 
  12. In upper left, click the folder name that contains this new module to get back to the page that lists the folders and modules.
  13. Now open the top level and see a new folder that has the module name. The module exists in the parent folder.
  14. From where you are, now import into the module​
  15. Select module
  16. Create -> import artifact
  17. pick spdsheet
  18. Click "import into a module"
  19. choose module
  20. create new or update (whatever's appropriate)
  21. To see the artifacts in the module, make sure that you click on "All" at the top, not "Modules" or "Collections".


How to import your spreadsheet into your module​

  1. Go to the "Artifacts" page
  2. Select the folder representing your module.
  3. Mouse over it and a "pencil and down arrow" (for "edit") icon appears; click the icon to pop up a menu.
  4. Select "Import artifact..."
  5. In the popup, select the 2nd item, "Import requirements from a CSV file or spreadsheet" (Use xlsx spreadsheet)
  6. Click "Next>"
  7. For Select file, choose the file containing your spreadsheet.
  8. For Specify location, select "Import requirements into a module" (see screenprint)
  9. Select your module
  10. For Import options, select "Create new artifacts for all entries"
  11. Click "Finish"
  12. Make sure that "All" is selected (top left of screen). If either Modules or Collections is selected, you won't see your new artifacts listed​ (the requirements you uploaded to your module).

If you get errors, read what they are, fix them in the orig spreadsheet, copy to new one, then try the import again.

The IDs will be assigned in the order of the spreadsheet rows. To see the requirements in the order they were imported, order them by the "ID" column in DOORS.

You can update a module from an updated spreadsheet. Set up the data properly, make sure the ID column is included. In step 10 above for Import options, select one of the two options that start with "Update artifacts that match entries, and..." according to your needs.

How to schedule a review of a set of requirements

Click on Reviews at the top of the page.

Click Create. 

In the popup window please give your review a name in the form yyyy-mm-dd-xyz-reason, where 

  • "yyyy-mm-dd" is the date that you set up the review in DOORS, not the date of the actual review,
  • "xyz" is your initials, and 
  • "reason" is the reason for the review.  
"Reasons" to choose ​from:
  • ​test
  • CD-(n)
  • directorate​​
  • LBNC
  • int-DUNE
  • int-LBNF
  • IPR
  • monthly
  • RRB
If your review doesn't match any of these "reasons" please see Nandhini or Anne. 

You can add a description or not. Click OK. Notice that if you create the review from here, the artifacts are not locked down; you have the option of creating a review in a baseline instead.​

First, choose a due date.
Click Add Participants. Each participant must be known to the DOORS-NG system.
Follow the instructions on the popup to choose a participant and choose the role to assign him or her.
Oops, you added an extra reviewer! To delete her, check the box in front of her name and click Remove Participants.

Now select the set of artifacts (requirements, etc.) you want the team to review. 
Click Add Artifacts.
Choose one or more modules and/or individual requirements.

Once you have set up the review the way you want it, click Start Review.  Your reviewers, the system admin and you (the creator of the review) will receive emails.



How to set a baseline for a set of requirements

Near the top, center-right of your screen click on the down arrow to the right of Project name Initial Stream (exact text depends on your project). On the dropdown menu, select "Create Baseline..."

In the pop-up window, choose a name for your baseline according to this system -- this will allow everyone to identify all baselines easily:

Use the same naming conventions as for "Review" above. 

E.g., 2018-03-19-ah-test (currently the image below shows it without hyphens - please use hyphens!)

How to compare requirements against a baseline

Near the top, center-right of your screen click on the down arrow to the right of Project name Initial Stream (exact text depends on your project). On the dropdown menu, select "Compare Configuration..." The system will compare the open project (Project name) to the baseline that you will select.​

In the pop-up window under "Component:" choose "Baselines."  Search for your baseline, e.g., 2018, or ah or test. Do not use asterisks with the search text. 

Click OK.

It takes a moment to load, then​ tells you that no differences exist. THIS IS A GLITCH! ​ Click "Next" in upper right corner of screen. On the following screen it looks like you can click on a portion of the project, but no matter what you select, it will show you a comparison of the entire project. Click "Next" ​ again.

It shows you the current state (initial stream in our case) on the left and the selected baseline on the right. This first image shows new folders (and/or modules) have been added (to the initial stream which is also the current stream) since the 3 March baseline.

The second image shows a single requirement that has been changed (its primary text field). (I do not see how to compare two older baselines to each other.)​



How to delete one or more requirement ​artifact(s) (or other "row" type artifact) from a module.

Go to the "Artifacts" page for the folder that contains the requirements (objectives, ...) that you want to delete.

Click the box to the left of the requirement(s) you want to delete. In my example, I selected three.

Click the edit button on one of the selected rows.