Mapping Objects

Advanced Package Mapping enables you to review and modify how individual objects are mapped from the source instance to the target instance.

During package installation, if the system ID of an object in the source package does not match any system IDs in the target instance, the process creates a new object. However, in some cases, the object may already exist in the target instance, but with a different system ID. In this case, package installation creates a new object, and if the object name is the same in the source as it is in the target instance, a number will be appended to the new object in the target. For example, if a field called "First Name" exists in both the source and target instances and the system IDs do not match, the process creates a new field called "First Name (1)" in the target instance with all of the attributes of the field in the source instance. In this case, you do not want the package installation to create a new object.

Using Advanced Package Mapping, you can change the system ID of an object in the target instance so that it matches the system ID of an object in the source package. When the system IDs match, package installation updates the intended objects instead of creating new, duplicate objects.

Mapping object process

Download the source file of the diagram here: Platform - Mapping Object Process Diagram

Running object mapping does not make immediate changes to the object structure of the target instance, but it does change system IDs. You must run mapping and install the package to merge object structure changes from the source instance to the target instance. Objects in the target instance can be created, or created and updated, and layouts can be overridden during the installation process.

Note: For data-driven event notifications, recipients in the source instance replace the recipients in the target instance.

Mapping objects is extremely important to ensure that duplicate objects are not created in the target instance and that all objects in the target instance match the intended objects from the source instance. If objects are not mapped properly unintended consequences will occur in the target instance. For example, changing the system ID of a field can adversely affect any data feeds or calculations that use this field. These issues can be difficult to identify and remedy later. Always back up the instance database before importing and installing a package.

When a root object includes level 1 and level 2 objects, it is vital that the object is mapped to its lowest level. Some level 1 and level 2 objects also have child elements and dependencies. These objects must also be mapped. Map the parent objects before mapping the child objects.

Mapping process rules

When mapping objects, the Advanced Package Mapping process follows these rules:

• Does not change the system ID of objects that were mapped by the system.
• Does not change the system ID of system-protected objects.
• Does not change the system ID of objects in which Do Not Map was selected by the user.
• Only maps to objects of the same type. For example, you cannot map a Text field to a Date field or a custom Values List to a Global Values List.

Important considerations

• Advanced Package Mapping can create unintended consequences on the instance. For example, changing the system ID of a field can adversely affect any data feeds or calculations that use the field, and these issues can be difficult to identify and remedy later. Before executing the mapping process, back up your database.
• Advanced Package Mapping does not update data feeds and Web APIs. Modifying the system ID of an object used by a data feed or Web API will break the relationship with the object. The data feed or Web Service API will no longer function properly. The resolution is to update the data feeds and Web Service APIs to reference the new system IDs of those objects.
• During the mapping process, you may discover discrepancies in the data, such as unwanted objects in the source or target instance. Before installing the package, fix any discrepancies in the source or target instances, then re-creating the package. Otherwise, any data discrepancies will be retained after the package installation.
• Once a values list contains more than 1,000 values in a package, the link to display the mapping page for that list is disabled. This allows the package mapper to continue operating successfully without becoming over-stressed with excessive requests.
  

Mapping objects

1. From the menu bar, click > Application Builder > Install Packages.

2. In the Available Packages section, locate the package you want to map.
3. In the Actions column, click for that package.

   The analyzer examines the information in the package. The analyzer automatically matches the system IDs of the objects in the package with the objects in the target instance and identifies objects from the package that are successfully mapped to objects in the target instance, objects that are new or exist but are not mapped, and objects that do not exist (the object is in the target but not in the source).

   When the analyzer is complete, the Advanced Package Mapping page lists the objects in the package file and corresponding objects in the target instance.

4. On the Advanced Mapping page, click to open each category and review the icons next to each object to determine which objects you must map manually.

   The following table describes the icons.

   Icon	Name	Description
   	Awaiting Mapping Review	Indicates that the system could not automatically match the object or one of its children to a corresponding object in the target instance. Objects marked with this icon must be mapped manually. New objects should not be mapped. Select Do Not Map from the drop-down menu to clear this icon for an individual object, or click Do Not Map to clear the icon for all unmapped objects.
   	Mapping Completed	Indicates that the object and all children are mapped to objects in the target instance, or that they have been marked as Do Not Map. Nothing more needs to be done with these objects in Advanced Package Mapping.

   Note: You can run the mapping process without mapping all objects. The icon is for informational purposes only.

5. For objects awaiting mapping review, do one of the following:
   • To map each object individually, use the drop-down menu in the Target column to select the object in the target instance to which you want to map the source object. To leave an object unmapped, select Do Not Map in the Target column.
   • To automatically map all objects in a category that have different system IDs but the same object name as an object in the target instance, click Auto Map. Select whether to ignore case and spaces when matching object names. Click OK.
   • To mark all unmapped objects as Do Not Map, click Do Not Map.

6. (Optional) Click to enable filter fields that you can use to find specific objects in each mapping category. To undo your mapping selections, click Undo, then select whether to undo all mappings in the category or only the mappings on a single page. If you choose to undo all mappings, you will be returned to the categories list.

7. (Optional) To save your mapping selections and return to the categories list without committing changes to the target instance, click .
8. After you review and map all objects, click Execute.
9. Select I understand the implications of performing this operation. Click OK.

   When the mapping is complete, the Import and Install Packages page displays.

   Important: Advanced Package Mapping modifies the system IDs in the target instance. You must update any Data Feeds and Web Service APIs that use these objects with the new system IDs.