Creating New Entities

To create new entities:

  1. Access the Select an Action to Perform dialog box. For instructions, see Connecting to the PPM Server using the Data Migrator Wizard (for Entity-Related Tasks).

  2. Click the Create Records icon to create entities of the type you selected when you connected to the PPM Server.

    The Map Attributes to Columns dialog box opens.

    Note: In this context, attributes are the entity fields.

  3. Do one of the following:

    • If you are working with a spreadsheet that was created from a Data Migrator template, review the preconfigured entries in the Map Attributes to Columns dialog box. If you need to make changes, go to the next step. If the default settings are correct, go to step 10.

    • If you are working with a spreadsheet that you created, go to the next step.

  4. To the right of the Column Header Row field, click the selection icon ().

    The Select a Row dialog box opens.

  5. In the spreadsheet, click a cell in the row that contains the column headings.

    The identifier for the cell you clicked is entered in the Please select the row for field headers field in the Select a Row dialog box.

  6. Click OK.

    The Select a Row dialog box closes, and the number of the selected row is displayed in the Column Header Row field in the Map Attributes to Columns dialog box. The headings from the row you selected—with the letter identifying the column they are in as the prefix—are added to the options available in the Unique record identifier drop-down list. The headings are also displayed in the Spreadsheet list.

  7. If the spreadsheet contains a row of tokens, do the following:

    1. Select the (Optional) Token Row checkbox.

    2. To the right of the (Optional) Token Row field, click the selection icon ().

      The Select a Row dialog box opens.

    3. In the spreadsheet, click a cell in the row that contains the tokens.

      The identifier for the cell you clicked is entered in the Please select the row for field tokens field in the Select a Row dialog box.

    4. Click OK.

      The Select a Row dialog box closes, and the number of the selected row is displayed in the (Optional) Token Row field. The Data Migrator automatically attempts to map the spreadsheet columns to the fields in the Entity Type list. Successfully mapped columns and fields are displayed in blue text.

      Figure 3-2. Map Attributes to Columns dialog box after the Token Row is selected shows the Map Attributes to Columns dialog box after the token row is selected.

      Figure 3-2. Map Attributes to Columns dialog box after the Token Row is selected

  8. From the Unique record identifier drop-down list, select the heading of the column that contains a unique identifier for each entity listed in the spreadsheet. For example, select the column that contains a unique identification number or name for each entity.

  9. Manually map any unmapped columns in the Spreadsheet list to the fields in the Entity Type list following the guidelines and instructions in this step. The list of fields is displayed in the same order—and in the same sections—as the fields appear in the entity. For descriptions of entity fields in the sections and order in which they appear, see Entities.

    Note the following:

    • The color of a column in the Spreadsheet list determines if it has been mapped. Mapped columns are displayed in blue text. Unmapped columns are displayed in gray text.

    • To see additional information about a field such as its data type and token, scroll to the right in the Entity Type list. If necessary, you can expand a column by dragging the column divider to the right.

    • Not all columns need to be mapped. Unmapped columns are ignored.

    • To view a mapped relationship, click a blue column heading or field to highlight its corresponding column or field.

    • (Optional) If you created an empty column for the request number, you must map it to the field listed in Table 3-2. Field, by entity type, to be mapped to the request number column for the type of entity you are creating.

      Note: A request number is the same as an entity number.

      Table 3-2. Field, by entity type, to be mapped to the request number column

      Entity Type

      Field

      Application

      Application No.

      Application Set

      Set No.

      Business Survey

      Survey No.

      General Survey

      Survey No.

      Location

      Location No.

      Process

      Process No.

      Server

      Server No.

      Survey Registration

      Request No.

      Technical Survey

      Survey No.

      Transformation Proposal

      Proposal No.

      Workstream

      Workstream No.

    To map the spreadsheet columns to entity fields:

    1. Click a column in the Spreadsheet list, and then click its corresponding field in the Entity Type list.

    2. Click Map.

      The column name is added to the Column column in the Entity Type list and the mapped column and field are colored blue.

    3. Repeat step a and step b until all the necessary columns are mapped.

  10. Click Next.

    The Create New Requests in PPM dialog box opens showing the mapped fields and their corresponding sections, tokens, and columns. The field containing the request number and fields designated as being read-only by gray column headings in the template spreadsheet are not included in this list.

  11. Select or clear the checkboxes as necessary so only the fields for which you want to include values are selected. To clear all the selected checkboxes, click Uncheck All. To select the checkboxes for all the fields, click Check All.

  12. Click Advanced Options to configure additional settings. To cancel any changes you make to the Advanced Options dialog box, click Cancel.

    • On the General tab, configure the following settings:

      • In the Coloring box, select the colors from the Highlight Success and Highlight Failed fields that the Data Migrator uses in the spreadsheet to show the status of the entities after the import is completed. To change a color, click the Color button and select a new color. To define custom colors, click Define Custom Colors in the Color dialog box.

        By default, entities that are created successfully are highlighted in light green and entities that were not created are highlighted in light red.

      • In the Concurrency box, select the maximum number of concurrent threads—up to 20—from the Maximum Threads drop-down list. When you configure this field, consider the performance objectives for your environment. Setting this field to a higher number could improve throughput but might also put more of a load on your  PPM Server. The default value is 5.

        Note: The Ignore attributes with empty values setting in the Pre-processing box is ignored when you create entities.

      • In the Post-processing box, select the Reload all attributes from server checkbox to allow the Data Migrator to update fields in the original spreadsheet when the fields have a new value after the entities are created.

        Some of the field values in entities that are uploaded to the PPM Server could change because of rules that run on the PPM Server. When this occurs, the results of the rules are downloaded to the original spreadsheet if you selected the Reload all attributes from server checkbox. For example, an application entity that contains ratings is uploaded to the PPM Server. The PPM Server applies rules to the ratings and calculates a score. Because you selected the Reload all attributes from server checkbox, the scores are then downloaded to the spreadsheet.

        Note: The column mapped to the request number is always updated, whether or not this checkbox is selected.

        By default, the Reload all attributes from server checkbox is not selected.

    • On the Data tab, define the delimiters for fields that can have more than one value. For example, if you have more than one person listed as a subject matter expert (SME) and have separated the users names with commas, you would select the checkbox for SMEs and enter a comma (,) in the Set Delimiter field. The default delimiter is a semicolon (;).

      1. In the Set Delimiter field, type the delimiter.

      2. Select the checkbox for each field in which this delimiter is used.

      3. Click Apply.

        The delimiter is displayed in the Delimiter column for each of the selected fields.

      4. Clear the selected checkboxes and repeat step i through step iii to define delimiters for additional fields.

    • On the Dependencies tab, specify one or more fields to be ignored during the first pass at creating entities. Do this when one or more fields in the entities you are creating require other entities or fields to be created before the fields can be populated successfully. When you select a field on this tab, it is ignored during the first pass. The entity is created but the value of this field is empty. After the first pass is complete, the Data Migrator automatically makes a second pass at populating the selected fields.

      To configure the Dependencies tab:

      1. Select the Enable multi-pass to handle attribute dependencies between records checkbox to run two passes at importing the data.

      2. Select the checkboxes for the fields that are to be left empty the first time the Data Migrator imports the spreadsheet.

      Note: If you specify dependencies on this tab and later cancel the create process while the entities are being created, the second pass might not complete successfully. For more information, see Cancelling a Download, Create, or Update Process.

    When you are finished, click OK to save your changes and close the Advanced Options dialog box.

  13. Click Next.

    Caution: If you click Cancel before the process is completed, only some of the entities might be created. For more information, see Cancelling a Download, Create, or Update Process.

    The Data Migrator attempts to validate and create the selected entities. This could take several minutes. When the process is complete, a summary of the results of the import is displayed.

  14. Review the summary information. Towards the top of the dialog box, <N> of <N> is displayed (where <N> represents the number of entities). This indicates the number of entities—out of the total number of entities in the spreadsheet—that were processed (successfully or not).

    Statements such as the following could be included at the bottom of the dialog box.

    • <N> requests pass pre-validation. <N>entities were validated.

    • <N> requests do not pass pre-validation. <N>entities contained errors and were not validated. You will need to fix these errors before attempting to create the entities again.

    • <N> requests successfully created. <N>entities were created successfully.

    • <N> requests failed to create. <N> entities were not created.

    • <N> requests have been skipped. <N> entities were skipped because the entities with the same identifier already existed in the PPM Server.

  15. If the import was not successful, click View Log to view information about any errors that were reported. For instructions for saving the Detail Log and for using the information in the log file to fix the errors, see Viewing the Detail Log and Fixing Logged Errors.

  16. When all of the entities are created successfully, click Finish.

    The Data Migrator closes.

  17. Save the spreadsheet.