Configure automatic Work Item recognition

Before you begin importing Microsoft Word documents, there are several things to set up and to know about.

• Target project: You should already have a project set up in Polarion, and you should know what Work Item types are defined in the project's configuration.

• Document types: You should know whether your project configuration defines different types of Documents. If it does, you will be able to choose the type into which your content is imported. If not so configured, consider whether you your project should be configured for different Document types before importing your content.

• Work Item types: You should decide which Work Item type or types you want to create in Polarion when importing a Microsoft Word document.

• Content to Work Item mapping: you should review your Microsoft Word document and identify what elements should become Work Items or Work Item attributes such as description after the document is imported. This is key successful Work Items recognition from your document's content. The next section discusses how to prepare a document for import to Polarion.

Carefully go through the Microsoft Word document you plan to import and make sure you know what content should be managed as Work Items in Polarion after import.

Consider a requirements specification document as an example. What elements of your document should Polarion recognize and mark as Requirement type Work Items? Should it recognize some words? Should it recognize some paragraph or list item styles, or entire sections under headings? Will you need to define just one simple Work Item Rule to achieve the recognition you want, or will you need a more complex Rule, or multiple Rules? While it's possible devise quite complex strategies that get very granular, you can actually achieve a great deal with fairly simple Rules.

For example, Polarion's default import configuration recognizes the words must and should, it will mark paragraphs containing those words as Requirement type Work Items, and it sets the Severity level to must have or should have respectively. The project configuration must have the Requirement Work Item type and the severity levels defined. This configuration is predefined in Polarion's project templates that support requirements management. Therefore, if you create a project based on such a template, and edit your Microsoft Word document so that only the content of Requirements contains the words must and should, you can very likely achieve quite a usable result when you import the document and use the default Work Item Rule.

Another easy to implement mapping strategy is to make sure all requirements in your Microsoft Word document have a particular style. For example, you might define paragraph style named Requirement and apply it to all paragraphs that should be recognized as Requirement type Work Items. When you subsequently import the document, create a Work Item Rule that specifies that elements in the document with that style applied to them should be recognized as Requirements.

Another mapping approach that is still fairly easy is to define a heading style named something like Requirement H3 in addition to the paragraph style named Requirement. On import, you can create a relatively simple Rule with multiple conditions that says to mark content styled Requirement 3 as a Work Item, and include in the description any following paragraphs styled with the Requirement style.

Suppose that you have a bullet list after a paragraph styled as Requirement, and you also want to include the list in the Work Item description. To do that, add another condition to the Rule that says to include paragraphs styled as list items which occur after a Requirement 3 styled heading. This gives you a very powerful, but still fairly easy-to-define Work Item Rule.

A simple Work Item Rule is one using only basic options and specifying one or more conditions. A Rule's components are like an instruction sentence. For example:0

Mark paragraphs from [whole document or specific section] as a [Work Item of this type] if [any/all] of the conditions are met.

— after which come one or more conditions: [contains words][words], [has style][style name], [contains text matching regex][regular expression], to name a few examples of conditions.

Let us see how to define a simple Work Item Rule with two conditions that will cause paragraphs anywhere in the imported document to be marked as a Requirement type Work Item if they contain any of the word shown, or if they are a list item.

Take the following actions:

1. In the Mark paragraphs from field, select the content element or elements of the original document to which Polarion should apply Rules to recognize Work Items. Select Document to allow Polarion to apply Work Item recognition Rules to all elements.

2. In the list following the word as, select the type of Work Item to be recognized in the content source. The list contains the Work Item types defined in the project configuration.

3. On the first conditions line, select a condition from the list of conditions. If your selection requires more input to complete the condition, an appropriate text, list, or other field will appear on the line. Fill in the additional information.

4. If you need another condition in this Rule, select it in the list on the second conditions line and as before, fill in any additional information.

5. If you need more conditions, add new condition lines by clicking the icon. Fill in the data as needed. If you make a mistake, you can remove any condition line from the Rule by clicking the icon at the end of the line.

If you need one or more additional Rules to achieve the Work Item recognition you want, you can click the Add Work Item Rule button near the top of the Rules pane. A new simple Rule is added each time you click. Repeat the above steps for each simple Rule you add.

Each simple Rule you define can have Advanced options added to it to make it even more robust and selective. Advanced options are disabled by default. To enable these options for any Rule, select the Show advanced options check box. The Rule panel expands to show the advanced options.

Advanced options fall into the following categories which appear as labeled sections in the Rules panel:

• Paragraph inclusion conditions: Specify conditions for including paragraphs that follow a content element marked as a Work Item per the conditions defined in the simple Rule. For example, suppose the simple Rule specifies that elements styled as Heading 3 are to be recognized as Work Items. You would probably want the paragraphs that follow the heading included in the Work Item description, so you can specify one or more conditions under Include next paragraph to the Work Item description. You might specify paragraphs that have some style, and/or that are list items to include after the heading.

• Actions: Define actions which set the value of Work Item fields when document content is recognized as a Work Item according to the Rule. Each Rule's Advanced options contain one action by default. If you don't want it, you can remove it by clicking the X icon in the upper right corner of the action's panel. If you want more actions, you can click the Add button at the bottom of the Actions section.

  Each Action applies to a selected Work Item field of recognized Work Items. Select the field in the Set field list. Depending on the field selected, a control appears which enables you to set the value of the selected field. The execute field enables you to specify whether the specified value will be set always, or conditionally. If conditionally, fields appear enabling you to define one or more conditions in a manner similar to conditions for other Rule parameters.

• Additional options: Opt to have the first paragraph of any block of content the Rule marks as a Work Item imported as the title of the recognized Work Item. The first paragraph of such a block might be a heading. You can also specify which fields, if any, you want to appear at the beginning, and at the end of recognized Work Items in the LiveDoc Document. You must specify the field ID in Fields at start and Fields at end. If you want the values of more than one field to appear at the start or end of recognized Work Items, specify multiple IDs separated by a comma.

Work Items can even be extracted from tables within a Microsoft Word document. You can target all the tables within a document or select only the sections, even subsections to include.

Multiple Rules can be created to extract different Work Item types such as Requirements or Tasks. Severity or priority levels can also be automatically extracted.

In the example below, requirement keywords within a table are detected and assigned different Work Item severity levels using the advanced table Rule options.

To import Work Items from within tables:

1. (Optional) To extract Work Items exclusively from tables within the document, close () the section Mark paragraph from.

2. Click + Add Work Item Rule and select Mark Tables.

   

3. Define the scope of the tables to include in the Mark tables from drop-down menu.

   (Clicking on Document will apply the Rule to the entire document.)

   

4. Select whether to invoke the Rule if any or all the conditions are met.

5. Select whether to apply to Rule to Whole Tables or only the Header Rows.

6. Under Import Rows, select a Work Item type in the as list.

   Types listed vary depending on the project configuration.

7. Select the Rule's behavior in the drop-down list.

   Tip:

   Mouse over the option to view a tooltip describing what it does.

   

8. Enter the condition details in the field that appears on the right.

   If contains text is selected like the example above, enter the text that the Rule should search for.

   

9. Click to add additional conditions.

   Tip:

   To assign different Work Item attributes to each condition — Severity, for example — rather than adding it here, create an entirely new Rule by clicking Add after the initial Rule is defined. See optional step below.

10. Polarion will automatically detect the target area’s columns and try to match the text to existing Work Item definitions.

    Any Column headers that cannot be recognized can be assigned manually or excluded by leaving them as not selected.

    

11. (Optional) Select the Show Advanced Options check box.

    The Fields at start and Fields at end can be customized to change what attributes appear at the beginning and end of the work item in the imported document.

    

    Fields at start

    Fields at end

12. (Optional) Click Add then select an option in the Set Field to enter additional Work Item attributes like Severity or Priority.

    (The available options can be customized by administrators.)

13. (Optional) The available options under the To field change depending on what was selected in Set Field.

    In this example, Severity is selected to convert table cells that contain the word should, to requirements with a severity level of Should Have.

    

14. (Optional) Specify when the Rule should be implemented in the Execute list. The default is Always.

15. Click Preview to see how the Rule affects the document.

    Tip:

    It is important to understand that the document has not been fully imported yet, and nothing has been written to the repository.

    Clicking Preview displays what the Rule will mark as Work Items when you finally click Import.

    (This way, you can thoroughly test Rules and Rule combinations without creating, and later having to delete, unwanted Work Items.)

    Any table rows that do not have a Work Item Rule applied to them are highlighted in red.

    Table rows that contain data that the Rule(s) recognize are converted to work items that appear below the table.

    Detected table data looks like this:

    

16. Check the Replace Table with Imported Items box to replace the table(s) with the extracted Work Items.

    If left unchecked, the created Work Items will appear directly below the table in which they were detected.

17. (Optional) Click Add above Replace Table with Imported Items to add another table Rule.

    

18. (Optional) You can also extract fields from tables that match enumerations with the following regular expression:

    

    Severity[\s&&[^\t]]*\tLow\t\n

    

    (See Import Rules for Tables for more regular expressions you can use with tables.)

    Tip:

    you can click to the right of + Add Work Item Rule to save the set of Rules for later use.

1. Click Import when you are satisfied from the preview that all the information you want shown as Work Items is correctly shown.

Once you have defined a Work Item Rule or a set of Rules and run Preview to verify that they cause Work Items to be marked correctly, you can save your Rules as an Import Configuration that can be reused when importing similar documents in the future, thereby eliminating the need to specify the same Work Item Rules again.

1. In the Rules pane, click and choose Save. The Save Import Configuration dialog appears.

2. If you are saving Rules to a new configuration, select Create new configuration and enter a name in the Name field.

3. If you want to save your current Rule definitions to overwrite an existing configuration, select Update existing configuration, and select which configuration you want to update from the list of existing configurations.

4. Click Save to save the new or updated configuration. If you saved a new configuration, it now appears in the list of Import Configurations, which users can select when importing Microsoft Word documents.

If you or a colleague saved a set of Work Item Rules as an Import Configuration, you can reuse it to import a document in some instances. The content of the document you are importing must conform to the rules defined in the Import Configuration so that Work Item content is correctly recognized.

1. With the imported Microsoft Word document in Preview mode, click () and choose Load.

2. In the dialog, select the Import Configuration whose Work Item recognition Rules you want to reuse for the current import operation.

3. Optionally, click the Preview button and check the document preview to verify that the document's Work Items are marked as expected.

4. Click the Import button to import the Microsoft Word document reusing the selected Import Configuration.

See Manage saved import configurations for more information.