Planning to import documents

Edit online

You can import entire documents or parts of documents to requirement artifacts by using the import wizard. To avoid issues when the artifacts are extracted and imported, ensure that you plan the import before you run the wizard.

When you plan your import, you can more efficiently organize and structure the modules and artifacts that you want to create. Based on the content of your document, you must determine the folder structure, location, and name of the module, and the types of requirement artifacts. To identify requirement artifacts in your document, the wizard uses four criteria: headings, images, keywords, and delimiters. You can specify the artifact type that is created for each criterion.

Headings

In a document, if a heading style is applied to one or more entire paragraphs, you can specify that those paragraphs are imported as artifacts of a specific type. In addition, if the document contains delimiters or keywords, you can import them as specific types. For more information, see the following Keywords and Delimiters sections.

All other text in the document that is not a heading, delimiter, or keyword can be imported as an artifact type that you specify. For example, you can specify that all headings are converted into use case specification artifacts and that all other text is converted into feature artifacts.

Importing document text to modules: If you create a module from a document, the heading levels in the imported document are used to create the numbering for the module hierarchy. For example, a document might have a line of text at Heading 1 and a line of text at Heading 2. If you import that document to a module, the numbering for the module hierarchy might look like this example:

If you import data into a module and the data contains a name but no primary text, the name is used to populate the primary text. If the data contains primary text but no name, the name is created from either the first 156 characters or the first paragraph of the primary text.

Importing options

When you import a word document, you can specify the import option according to the document viewing criterion. The types of import options are:
  • Optimize for editing: This option imports the word document and converts the style information to match the styling and functionality of the rich text editor. For example, if a font is not supported by the editor, it is converted to a supported font. Some style information might be lost with this option, but this option will offer the best editing experience.
  • Maintain original style: This option imports the word document without converting any style information. The document can be edited, but with limited editing features. For example, unsupported fonts are not listed in the fonts drop down. This option is best suited for viewing documents.

Formatting

The rich text editor attempts to maintain the imported artifacts in a format that is as close as possible to their original format when the Import for editing and viewing option is selected. However, formatting is limited in a few ways:
  • Most fonts are supported. Unsupported fonts are converted to Arial or to a font and size that closely matches the specified font family.
  • Spacing between sentences might differ from the original document. However, spacing is maintained as close to the original formatting as possible.
  • Object anchors and text wrapping around images and other content is not supported. Any layout or formatting that is based on these Microsoft Word features is not preserved.
  • Tabs are converted to a sequence of spaces and paragraph indentation is rounded to the nearest multiple of 40 pixels. Any formatting or layout that uses tabs or indentation is not preserved exactly like the original document.
  • If a numbered list contains fractional or segmented parts, the list is converted to a paragraph.
  • Web address links that begin with http or https are imported as RM links. All other links are converted to text.
  • If any cell in a table has a border or a partial border, a full cell border is used.
  • For an imported table to be displayed correctly, its outer border must be perfectly aligned. Any slight misalignments in the left or right border of the original table can cause display issues after the table is imported.
  • If a document is structured into columns of text, that structure is not preserved in the imported content.

Images

You can map images to specific artifact types. When you import a document that contains images, a folder is created. These image formats are not supported, but are converted to .png format and might be missing some details such as the following items:
  • DrawingML content, such as diagrams and charts
  • Embedded images that are in .emf, .wmf, or .pict format
  • Word art

Keywords

If you use keywords throughout a document or table, you can use them to indicate specific artifact types. Before you start the import process, ensure that you know how keywords are affected:
  • Keywords are not extracted from tables.
  • Keywords cannot be used within tables. Lists and tables are extracted as a whole, not per item.
  • If a keyword is in a list, the entire list is assigned the artifact type that is associated with the keyword.
  • In version 4.0.4 and later, keywords are case-insensitive.
  • Keywords that are used for sentences are supported in English only.
  • During the import process, the white space around any keywords that you defined is ignored. As a result, text that contains keywords might be inadvertently identified as keywords. To avoid this issue, use infrequently used text as keywords. For example, if he is a keyword, commonly used text such as the, they, and them are inadvertently associated with that keyword's type.

Delimiters

Documents can be tagged with special characters, delimiters, to identify information, such as glossary terms. The delimiters that you use throughout a document can identify specific artifact types. The text that is within both sides of a delimiter becomes an artifact of the type that is associated with that delimiter. Any text that is before the opening side of the delimiter or after the closing side is treated as separate artifacts.

If you use delimiters in a document or table, before you start the import process, ensure that you know how delimiters are affected:
  • Delimiters cannot be used within tables. Lists and tables are extracted as a whole, not per item.
  • Delimiters cannot be nested. Only the delimiter that is specified first is used.
  • In version 4.0.4 and later, delimiters are case-insensitive.
  • During the import process, if you defined a delimiter, and either or both of its opening and closing parts are surrounded by white space, that white space is ignored. As a result, text that contains delimiters might be inadvertently identified as delimiters. To avoid this issue, use infrequently used text as delimiters. For example, if the first part of a delimiter is ( and the second part of the delimiter is ) , commonly used formatting such as that(s) are split by the delimiter.

All other text

Any content in your document that is not a heading, image, keyword, or delimiter can be assigned to specific artifact types. You can change the artifact types after the import is complete.

Unsupported items

These additional items are not supported in a document import:
  • Tables of contents
  • VBA macros
  • Mail merge fields, field codes, and frames
  • Text boxes
  • Table styles
  • OLE embedded documents, such as Microsoft Visio contents
  • Embedded XML
  • Document properties
  • Password-protected documents

Organizing data for import process

The size of the document determines the time that is required for the import process. If the size of the document is large, the time that is required to import the document might increase. Other elements in the document such as images, shapes, and OLE objects might also increase the import time. If the import process creates more than 10,000 artifacts, split the document further before the import. If you split the documents, the smaller sections get imported faster. This also speeds up the word import requests from other users. The resulting module or import folder that is created after the import also gets loaded faster. For more information, see Organizing requirements for best performance.