Format requirement data

Before you can export requirement data from a Word document to ALM, data must be placed as paragraphs or as tables. In addition, if you want to export requirement types and user-defined fields, you must first import their definitions from your ALM project.

You then use the Microsoft Word add-in toolbar buttons to mark the requirement fields. You can format the requirements so that when you export them to ALM, the requirements are on the same hierarchical level, or on different hierarchical levels in the requirements tree.

Place requirement data in Word document

The Word document can contain requirement data as paragraphs or as tables.

Data as paragraphs

When the data are provided as paragraphs, each field of the requirement must be on a separate line. For each requirement, the name of the requirement must appear first, followed by other requirement fields. The following example shows data for two requirements placed as paragraphs:

Data as tables

When the document contains a table, each row must contain the data for a requirement. The first column must be the name of the requirement. The following example shows the data for the same two requirements, listed in a table:

Back to top

Import requirement types

You can import definitions for requirement types and their associated user-defined fields from an ALM project to your Word document. You can then define and export the requirement type for each requirement in your Word document. After you define a requirement type for a requirement, you can export values for user-defined fields that are available for requirements of that type.

To import requirement types from an ALM project:

  1. Click to open the Requirement Type Definitions Wizard.

  2. Enter your ALM URL in the format of http://<ALM server name>[:port]/qcbin and click Next.

    For single sign-on users, enable Add basic auth header mode.

    Note: Add basic authenticationheader mode is optional, and should only be enabled if you get an invalid server response message.

  3. Enter your ALM user name and password and click Next.

  4. Select an ALM domain and project and click Import.

    The add-in imports the requirement types and user-defined fields from the ALM project.

  5. After the add-in imports the requirement types and user-defined fields, the Requirement Type Definitions Wizard - Step 5 of 5 dialog box opens. Click Finish. The requirement types and user-defined fields are updated in the Word document.

Back to top

Mark requirement fields

After placing your data as paragraphs or as tables, you must mark your requirement fields. To mark a requirement field, highlight the text and click the appropriate button on the ALM Requirements toolbar. An icon is added next to the marked text line. A bookmark is inserted into the document to allow the add-in to identify the marked text when it is exported to ALM.

When marking requirement fields, consider the following:

  • For each requirement, the requirement name must be provided. You can also export the requirement type, review status, author, priority, description, and rich text. In addition, if you export the requirement type, you can export data for user-defined fields available for the type.

  • If a requirement with the same name exists in the requirements tree, the fields of the requirement are changed to contain the new values. If your document contains two requirements on the same hierarchical level with the same name, only the second requirement is created.

  • If the review status is not provided, the default value is Not Reviewed.

  • The data for each field should be on the same line as the icon that marks it. The only exceptions are the Description field, memo user-defined fields, and rich text.

    Description field

    Data can extend to additional lines and can include returns and indents.

    memo user-defined fields Data can extend to additional lines but only the first line is exported to ALM.
    Rich text data

    Data can include any content that you can include in a regular Word document. When rich text data are exported to ALM, the rich text data are added as an attachment to the requirement. The attachment is named Legacy_Rich_Content.doc.

    Note: With every additional export of this requirement to ALM, the Legacy_Rich_Content.doc file is overwritten.

  • Data intended for ALM fields that have selection lists must match the entries in those selection lists exactly. For example, the Priority field can only accept one of the following entries: 5-Urgent, 4-Very High, 3-High, 2-Medium, or 1-Low.

  • You cannot export data for user-defined fields that do not exist in the ALM project, or which are not available for the requirement type.

To mark the requirement fields:

  1. Open a Word document containing requirement text.

  2. You can use the Structure Checker to ensure that you do not insert bookmarks that invalidate the structure. For example, the Structure Checker makes sure that you do not add more than one name to a requirement, or close a requirement before you have opened it. To switch the Structure Checker on or off, in the ALM Requirements toolbar, click the Turn On Structure Checker button or Turn Off Structure Checker button.

  3. Highlight a text line or a table cell in your document, and click the appropriate button in the ALM Requirements toolbar:

    Field Toolbar Button Icon
    Requirement name
    Review status of the requirement
    Author of the requirement
    Priority of the requirement
    Description of the requirement
  4. To assign a requirement to a type, add and highlight a new text line in the data for the requirement, or add a new table column and highlight the cell in the new column corresponding to the requirement. In the ALM Requirements toolbar, in the Type box, select a requirement type. Click the Type button to add the requirement type to the document. The requirement type is added and is indicated by the Requirement Type icon .

  5. To assign a value to a user-defined field, highlight the text line or table cell in your document containing the value. In the ALM Requirements toolbar, in the Field box, select a user-defined field. Click the Field button to mark the value with the User Defined Field icon .

  6. To add rich text to be exported to ALM, highlight the rich text and click the Open Rich Text button. The Open Rich Text icon is added to indicate the beginning of the rich text.

    Place the cursor at the end of the rich text you want to add and click the Close Rich Text button. The Close Rich Text icon is added to indicate the end of the rich text.

  7. Repeat for all requirement data. Any text in the document that is not marked is ignored.

  8. Click the Close Requirement button to close each requirement with the Close Requirement icon . The location of this mark depends on whether the requirements are on the same hierarchical level or on different hierarchical levels.

    For more information, see Example: requirements on the same hierarchical level or Example: requirements on different hierarchical levels.

  9. To unmark one or more fields, use the undo buttons or remove the mark manually. For more information, see Delete formatting from Word document.

  10. When all requirement fields have been marked, export the requirements to ALM. For more information, see Export data from Microsoft Word to ALM.

Back to top

Example: requirements on the same hierarchical level

To define requirements on the same hierarchical level in the requirements tree, use the Close Requirement button to place the Close Requirement mark directly after each requirement. This causes a requirement to be placed on the same level as the preceding requirement.

When the document contains paragraphs, insert a line after the last line of the requirement and mark it with the Close Requirement mark:

When the document contains a table, add a column to the end of the table, and insert the Close Requirement mark for each requirement:

After you export the requirements to ALM, the requirements are displayed on the same hierarchical level, under the root requirement.

Back to top

Example: requirements on different hierarchical levels

You can define a requirement to be a child requirement of the preceding requirement. Use the Close Requirement button to place the Close Requirement mark for the parent requirement after all its child requirements.

For example, to define Req_2 as a child of Req_1, and Req_3 and Req_4 as children of Req_2, place the Close Requirement mark for Req_2 after the definitions of its child requirements. Place the Close Requirement mark for Req_1 at the very end.

When the document contains paragraphs, place each Close Requirement mark on its own line in the appropriate location. Note that the Close Requirement marks for Req_1 and Req_2 are inserted after Req_3 and Req_4.

When the data are provided as a table, add a column to the end of the table and place each Close Requirement mark in the appropriate location:

After you export the requirements to ALM, Req_2 is displayed as a child of Req_1, and Req_3 and Req_4 are displayed as children of Req_2.

Back to top

Next steps: