Introduction
DOORS Next provides great functionalities for managing requirements within your team, but as your project grows sooner or later you need to export and import the data using external formats.
For DOORS Next data the first format to think of is project template (or component template, in case if configuration management feature is enabled in RM). Content of template can be set up to include different types of data but all items of included types will be included to a template (e.g. you can include artifacts to a template - and it means that all folders will be added to a template). Another option is the ReqIF package - it allows interchange requirements between requirements management platforms which are compatible with ReqIF, with more data selection options (e.g. you can include only certain artifacts or modules).
CSV/spreadsheet format is also an option to export and import data to DOORS Next, and this article provides some details on these functions.
The purpose of this article is to describe several cases of CSV/spreadsheet import and export, prerequisites and limitations.
Import from CSV/spreadsheet is initiated from the ‘Create’ drop-down list, ‘Import Artifact…’ item
1.) Where you find the import artifacts option
On the ‘Import’ form several options are listed, CSV/spreadsheet import is the second
2.) Different import options
Importing and exporting data to and from IBM DOORS Next Generation (DNG) is essential for efficient requirements management because it enables seamless data handling across tools. This article is focused on providing you with tips and tricks on how to streamline the import/export process, troubleshoot common issues, and ensure your Excel or CSV spreadsheets work effectively within DOORS Next Generation.
Mandatory attributes
On the second step of import requirements action after choosing CSV/spreadsheet import the list of import options is displayed. Depending on chosen location for import and required actions CSV/spreadsheet file must include certain attributes. Import will not proceed if mandatory attributes are missing. Mandatory for all cases attribute is ‘Artifact Type’.
If the purpose of import is creation of new artifacts - CSV/spreadsheet file must include either Name or Primary Text attribute. In case if Primary Text is used - Name attribute will be updated automatically with Primary Text value (with Name attribute type constraints).
If the purpose of import includes update of existing artifacts - then ‘ID’ of artifacts becomes mandatory attribute, and so is any of attributes which are supposed to be updates (could be Primary Text or any custom attribute).
3.) Import window interface
Another import option which defines mandatory attributes is location. With CSV/spreadsheet import artifacts can be imported to a selected folder (as base artifacts) or to a module - in this case import allows to update module structure (positioning of artifacts in module) and module specific attributes.
4.) Specify location preffered settings
If you want to import an artifact into a module - in the simplest case, create a new artifact - you need to include module specific attributes to a spreadsheet. They are:
- isHeading - boolean value, related to module specific option of an artifact, regardless of artifact type (must be set to ‘true’ to use as heading in a module, could be empty or ‘false’ in other case
- parentBinding - ID of parent artifact (an artifact to which inserted artifact will be demoted) for the new one. The value is empty if an artifact is on the top of module hierarchy or contains ID of ‘parent’ for the current artifact (e.g. Heading of a chapter to which current artifact is related)
As well as for base artifact import (in other words import into a folder) you have options to update and/or create new artifacts, and if you are going to update existing artifacts - you need to have an ID attribute in your file.
For more precise positioning of inserted artifact you can have in your file existing artifact before which you expect your artifact to appear in a module, but this is not mandatory to perform import of artifact to a module.
Another special case which requires not yet mentioned mandatory data in a file is deletion of artifacts from a module with CSV/spreadsheet import. On Figure 4 you can see that when ‘Import requirements into a module’ is selected an additional checkbox is available below this option - ‘Delete artifacts from the module…’. This option allows you to exclude artifacts from the module when you upload your file. To do this you need to use a file created by export from the module you are planning to update and besides excluding artifacts which are not expected to be in the module you need to keep the ‘METADATA’ section in your file.
5.) Metadata table example
Use cases
There are several use cases which can be covered with CSV/spreadsheet Import, some of them are explained below.
Links creation
You can use CSV/spreadsheet import for links creation, and here there are options. The very straightforward option is to literally insert links directly. In this case you can use a spreadsheet column to build a link to another item (either another artifact in DOORS Next or work item in EWM application or test artifact in ETM). For EWM and ETM this is the main option, you can better understand the format of a spreadsheet after exporting some samples. It can help you to build your spreadsheet for importing links either for base artifacts or for artifacts in a module - depending on the import option you use.
For this case CSV/spreadsheet can solve creation of links to the same targets from the new destination (e.g. if you moved your requirements to some new component or application and you need to relink them to the same work items and test artifacts).
It is possible only to add new links, CSV/spreadsheet import won’t remove existing links. The format of this attribute is shown no Figure 6 - it includes column name, defining link type and it’s direction, the attributes value consists of id (or pair of module id and artifact id for link to/from artifact in a module as shown on Figure 6), name of artifact and URI of artifact. So it is quite not trivial to reproduce such values outside of DOORS Next.
6.) Link Table example
For links to other DOORS Next artifacts you can use CSV/spreadsheet to prepare your requirements for linking via ‘Link by Attribute’ feature. In this case you need to have a special attribute which is supposed to hold IDs of artifacts to be linked. And you can fill values of this attribute via spreadsheet.
Depending on your linking policy and needs (linking to base artifacts or linking to artifacts in certain modules) you will use either IDs of artifacts you need to link to (e.g. 12345 is an ID of artifact you want to build a link to) or pairs of module ID and artifact ID (e.g. 23456.34567 - where 23456 is ID of a module and 34567 is ID of an artifact in this module when you want to create a link to a modular artifact). After successful import of these values you can proceed with using the ‘Link by Attribute’ feature, which can be invoked on a view or selection of artifacts.
7.) Link by attribute interface
Tables in Primary Text
You can export tables for import to CSV - but it will be only pseudo-graphics. Some tables can be exported and imported via spreadsheet, and the limitation for this case is size of table. If your table is exceeding the limitation - you will be notified with an alert (see Figure 7). Originally built in DOORS Next tables from our experience look more lean.
8.) Export alert showcase
If a table was successfully exported to a spreadsheet - you should use an original file for import (copy-pasting the content can break the structure).
Embedded artifacts
Embedded artifacts can be handled via spreadsheet but they must be present at destination prior to running spreadsheet import.
Tips and tricks
Few general tips which could help you when working with CSV/spreadsheet import and export:
- Use column names from exported spreadsheets to be sure they are right
- If you are importing values of modular artifacts (pairs of IDs separated with dots) - check formatting of cells, by default they might be decided by spreadsheet as numbers with decimals and therefore trimmed
- If you are sure you are doing everything right but import fails - try switching to English locale
- If you need to exclude some artifacts from a module - be sure to keep the ‘METADATA’ section from the initial state of a module (it includes list of IDs of artifacts), otherwise ‘delete artifacts from the module’ option won’t work
- When you import from a spreadsheet file - only first tab will be processed by DNG
- Use Arial font size 10 to keep DOORS Next automatically formatting headings in modules
- Reasons to decide module as a location (besides need to update module structure) could be links and tags for modular artifacts
- Use a changeset for bulk changes (a sort of which CSV/spreadsheet import is) to keep an option to quickly revert changes
- If you need to handle spreadsheet import with support of embedded artifacts - reach us for ready to go script for this case
- Be careful with enumeration values - not really visible space in spreadsheet attribute can break import operation
Softacus Services
We, in Softacus, are experts when it comes to consulting and service delivery of IBM software products and solutions in your business. We help our clients to improve visibility and transparency when licensing and managing commercial software, providing measurable value while increasing efficiency and accountability and we are providing services in different areas (see Softacus Services).
IBM ELM extensions developed by Softacus are free of charge for the customers who ordered IBM ELM licenses via Softacus or for the customers who ordered any of our services. If you are interested in any of our IBM ELM extensions, you found a bug or you have any enhancement request, please let us know at info@softacus.com.
Related and Referenced Topics
Blog Articles:
Basics of Links and Link Types in IBM DOORS Next Generation - learn the basics about the linking and link types in IBM DOORS Next.
Linking Techniques in IBM DOORS Next - article explaining basic concepts and showing multiple ways of creation of links between artifacts.
Link By Attribute Feature in IBM DOORS Next - the article explains how to use the "Link by attribute" function to automatically create, update, or delete one or more links between artifacts based on values in the attributes of the artifact.
Softacus Widgets:
Link Switcher - widget developed by Softacus, that converts the context of artifacts links in a very short time.
Module Link Statistics - extension that provides users with a quick overview of the amount of the links in specific link types in a module.
Link Type Change- extension developed by Softacus designed to enhance the functionality of DOORS Next Generation by allowing users to manipulate the direction of a link or convert it to another type of link.
Links Builder- extension that allows the users to create a link between two artifacts in DOORS Next Generation according to the certain rules.
Link by Foreign Attribute - this extension allows users to create links between artifacts in the selected module(s), based on the attributes values.
Show Attributes of Linked Artifacts - this extension shows the attributes and links of the artifact that is currently selected.
