Updating Entity Data

If you need to update entity data, you can use the Data Migrator to import the updates into APM from a spreadsheet.

You can prepare the spreadsheet with your updates in several ways:

• Modify the data in your original import spreadsheet.

• Prepare a new spreadsheet.

• Download a spreadsheet populated with information about the entities, and make changes to the entity data as necessary. (For instructions for downloading entity data, see Downloading Entity Data to a Spreadsheet.)

Regardless of which type of spreadsheet you use, the spreadsheet must have at the very minimum, a header row, a row for each entity you are updating, and two columns. One column must contain the request number assigned by the Data Migrator to each of the entities for which you are making a change, and the second column—and additional columns, if necessary—must contain the updated values. The spreadsheet can also contain columns with data that does not need to be updated.

To update entity data:

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 Update Existing Records icon to update entities of the type you selected when you connected to the PPM Server.

   The Map Attributes to Columns dialog box opens.

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 this 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 step 4.

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. 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 uses the tokens in this row to attempt to map the fields in the Spreadsheet list to the fields in the Entity Type list. Successfully mapped columns and fields are displayed in blue text.

8. From the Unique record identifier drop-down list, select the column that contains the request numbers that were assigned to the entities by the Data Migrator when they were created.

9. Manually map any unmapped columns in the Spreadsheet list to the fields in the Entity Type list. 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:

   • You must map the column that contains the request number 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 updating.

   • You are only required to map the columns in which the values have changed.

   For additional information about mapping columns to fields and instructions, see the notes and instructions in step 9.

10. Click Next.

    The Update 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 you want to update are selected. To clear the selected checkboxes, click Uncheck All. To select the checkboxes for all the fields, click Check All. By default, all fields are selected.

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 updated successfully are highlighted in light green and entities that were not updated 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.

      • In the Pre-processing box, select the Ignore attributes with empty values checkbox to ignore fields in the spreadsheet that do not contain a value. For example, if a spreadsheet field is empty and the corresponding field in the entity you are updating contains a value, the empty field in the spreadsheet is ignored and the value of the field in the entity remains unchanged. By default, this checkbox is not selected.

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

        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, updates to an application entity that contains ratings are 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.

        By default, this checkbox is not selected.

    • On the Data tab, define the delimiters for fields that have more than one value. 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.

    Note: The Dependencies tab is not used when updating entities.

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

13. Click Next.

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

    The Data Migrator attempts to validate and update the selected entities. This could take several minutes. When the process is complete, the message Update Request... Done! and a summary of the results of the import are 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 might also be displayed:

    • <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 need to fix these errors before attempting to update the entities again.

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

    • <N> requests failed to update. <N> entities were not updated.

15. If the update was not successful, click View Log to view information about any errors that were reported. For instructions 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 updated successfully, click Finish.

    The Data Migrator closes.

17. Save the spreadsheet.