Copy configuration data between companies or legal entities overview

There are two options for copying configuration data in finance and operations:

• To move data between instances, you must first export it from one company, and then import it to another company.
• To move data from one legal entity to another legal entity in the same instance, you can use the Copy into legal entity feature.

Export a configuration

The Data management workspace is your hub for managing configuration data projects and exporting data packages. To build a configuration, you must define a data project and export the information that is represented by entities.

To create an export configuration data project, follow these steps.

1. Open the Data management workspace. If you're in Standard view, select Enhanced view.

2. Select the Export tile.

3. Select New to create an export configuration data project, and enter an ID and name for the configuration.

4. Set the operation type for the data project to Export, and set the project category to Configuration.

5. Add the entities that represent the information that you want to export. You can add entities by using several methods:

   • Add one entity – Enter the first part of the name of the entity until it appears in the lookup.
   • Add multiple entities – Enter any part of the entity name, use the lookup for the module, enter any part of the tag name, or use the lookup for the entity category to show a list of entities. Press Tab to move focus away from the Lookup field and activate the filter. In the grid, select the entities to add.
   • Add a file – Browse to a file that contains a name that matches the name of an entity and a file name extension that matches the file name extension that is in your data sources.
   • Add a template – Select from a list of templates that you loaded in your instance.

6. Select a target data format. The system stores the last data format that you selected. Alternatively, if you select a file, the system automatically sets the data format to the data source that matches the file name extension.

   Note

   Composite entities require XML format.

7. Select Add. If you load a template, and the project already includes an entity that matches an entity in the template, the entity in the project is replaced with entity in the template. Some templates are large, and they might take a few seconds to be loaded.

8. Select Remove entity to remove one or more selected entities.

9. When you complete the configuration, select Export to start the export. You can monitor the results on the Execution summary page that appears.

Before you export a configuration, you might want to use some more features that can help control the export process:

• To organize the list, use the Sort by button to reorder the entities by unit, level, and sequence.
• To change the execution sequence of any of the entities, you can manually edit the unit, level, or sequence. Alternatively, you can use the Resequence button to update any entities that you selected. The Resequence button appears only if you select more than one entity. You can change the unit, level, and sequence individually. Alternatively, you can enable multiple changes and make them all at the same time. If you want the unit, level, or sequence to remain unchanged when you change multiple parts of the sequence, set the increment to 0 (zero).
• To add filters to the entity, use the Filter button. If you add a filter, the Filter button changes to an Edit button. The data is filtered before it's exported. If you add a template, and the template includes filters, those filters are added to your project. However, you can modify or remove them as you require.
• If you must change the entity mappings, use the View map button. If you add a template, and the template includes mapping changes, those changes are applied to your project. However, you can modify them as you require.
• To temporarily prevent the entity from being used when you export a data project, use the check box in the Disable column.
• To open the contents of the grid in a Microsoft Excel workbook, use the Open in Excel button. Modify the entities as you require, and then use the Publish button to upload the changes back.

When the export is completed, complete the following tasks:

• Use the Download button on the Export page to download the configuration settings.
• Use the Download package button in the Data management workspace or on the Execution summary page to download the configuration settings and the data that was exported.

Set up considerations for some entities that are used to export configurations

Currently, several entities require more steps when you build configurations. Follow these recommendations as you build your configurations.

Using special-purpose entities

The following entities require special handling when they're used in configurations.

Remove the mapping and apply filters for specific entity fields

In a golden build, customer-specific fields might not be set up. To help guarantee that the import works, you should unmap those fields. For example, workers are stored in many tables, but they might not be set up in a golden build. Filters might also be required for some fields in an entity.

The following entities might have to be unmapped or filtered.

Golden builds that have multiple legal entities

The templates can be used to export data from any company in your golden build. When you export both shared data and company data, the templates first export the shared data for all legal entities. They then export the data for the legal entity that you're currently using. You can then switch companies and export the company data for more legal entities by using projects that don't include the shared entities.

If you're exporting from a golden build that contains multiple legal entities, but you want to import the data from only one of those legal entities, you must apply a filter on the legal entity fields, so that only the data that you require for that legal entity is exported. This filter must remove all data for all legal entities except the legal entity that you want. In some cases, you must complete more steps to clean up the exported data.

Most of the changes that are listed in the following table occur in the System setup and General ledger areas. If you export a golden build that uses a single legal entity, you shouldn't require these filters.

The following entities require filters or special handling when you export the data.

Changing the legal entity value before import

If you want to change the legal entity ID to another value, the value of all fields that resemble the fields that were listed earlier must be changed to the value of the new legal entity. For example, for Legal entities, change Company from the exported value to a new value in the exported file.

The legal entity ID is stored in many places. Therefore, it can be difficult to make this change, and you might cause errors if you try.

Selecting a single legal entity for export

To export a single legal entity, you can create a Copy into legal entity data project and specify the legal entity to copy as the source legal entity. When you add entities or load templates, that type of project automatically adds legal entity filters. You can then download the package or create a template from it on the Templates page. The package or template can then be added to an export project and used to export the legal entity.

Import a configuration

The Data management workspace is also your hub for importing configuration data projects. You can build a configuration project from an existing data project that you exported. Alternatively, you can build a configuration project from individual files that contain data that is formatted correctly for import.

To import a configuration, follow these steps.

1. Open the Data management workspace. If you're in Standard view, select Enhanced view.

2. Select the Import tile.

3. Select New to create a configuration data project, and enter an ID and name for the configuration.

4. Set the operation type for the data project to Import, and set the project category to Configuration.

5. Add the entities that represent the information that you want to copy. You can add entities by using several methods:

   • Add one entity – Enter the first part of the name of the entity until it appears in the lookup.
   • Add multiple entities – Enter any part of the entity name, use the lookup for the module, enter any part of the tag name, or use the lookup for the entity category to show a list of entities. Press Tab to move focus away from the Lookup field and activate the filter. In the grid, select the entities to add.
   • Add a file – Browse to a file that contains a name that matches the name of an entity and a file name extension that matches the file name extension that is in your data sources, and the source data format is set automatically. If you haven't set up the default file name extensions, you must select a source data format before you select the file.
   • Add a template – Select from a list of templates that you loaded in your instance.

   When you load a package, the Import page first reads the list of entities from the package. A progress indicator shows how much of the package has been read. After the list of entities is read, the Import page starts to load the data in the package. This process can take some time.

6. Select Remove entity to remove any selected entities, as required.

7. After you've completed the configuration, select Import to start the import. You can monitor the results on the Execution details page that appears.

Before you import a configuration, you might want to use some more features that can help control the import process:

• To organize the list, use the Sort by button to reorder the entities by unit, level, or sequence.
• To change the execution sequence of any of the entities, you can manually edit the unit, level, or sequence. Alternatively, you can use the Resequence button to update any entities that you selected.
• If you must change the entity mappings, use the View map button.
• To temporarily prevent the entity from being used when you export a data project, use the check box in the Disable column.

Copy into a legal entity

The Data management workspace is also your hub for copying configuration information from one legal entity to another. The process resembles an export and import that occur in one step. As in an import, if information that exists in the source legal entity doesn't exist in the destination legal entity, the copy process adds it. If information already exists in the destination legal entity, the copy process updates it.

To copy a configuration from one legal entity to another legal entity in the same instance, follow these steps.

1. Open the Data management workspace. If you're in Standard view, select Enhanced view.

2. Select the Copy into legal entity tile.

3. Select New to create a configuration data project, and enter an ID and name for the configuration.

4. Set the operation type for the data project to Copy into legal entity, and set the project category to Configuration.

5. Select the legal entity that should be the source of the data to copy. By default, the legal entity that you're currently using is selected.

6. On the Legal entities FastTab, you can select existing legal entities as a destination, or you can create new legal entities:

   • Select – Select one or more legal entities in the list, and then select Add selected. The legal entities are added to the list of destination legal entities.
   • Create – Enter the legal entity ID, the legal entity name, and the region that the legal entity belongs in. Then select Create legal entity. The legal entity is created and added to the list of destination legal entities.

   Note

   The functionality for creating destination legal entities is available in finance and operations 7.2.3.

7. After you add the destination legal entities, select Yes if the number sequences should be copied. The entities that are required in order to copy the number sequence codes and number sequence references is added to the project. The execution unit, level, and sequence number for these entities are set to the numbers in the default System and Shared templates. If you aren't using the default templates, adjust the entity sequences so that they're first in the list.

8. If you selected Yes for number sequences, select Yes or No to specify whether those number sequences should be reset to the smallest value.

9. Add the entities that represent the information that you want to copy. You can add entities by using several methods:

   • Add one entity – Enter the first part of the name of the entity until it appears in the lookup.
   • Add multiple entities – Enter any part of the entity name, use the lookup for the module, enter any part of the tag name, or use the lookup for the entity category to show a list of entities. Press Tab to move focus away from the Lookup field and activate the filter. In the grid, select the entities to add.
   • Add a file – Browse to a file that contains a name that matches the name of an entity and a file name extension that matches the file name extension that is in your data sources.
   • Add a template – Select from a list of templates that you loaded in your instance.

   To help guarantee that the correct order is maintained, we recommend that you use the default templates. Then add and remove entities to match the data that you want to copy. You can remove the entities that you don't want to copy.

   Note

   • If an entity has a field that represents the legal entity, a filter is applied to that entity, so that only the data for the source legal entity is included. The value for that field is changed to the destination legal entity.
   • Document, transaction, and composite entities aren't available when you copy to a legal entity.

10. Select Remove entity to remove any selected entities, as required.

11. After you've completed the configuration, select Copy into legal entity to start the import. The copy process exports the data from the source legal entity into the destination legal entity. Each destination legal entity has its own import data project. You can monitor the results on the Execution summary page that appears. All import projects that are related to the Copy into legal entity project appears in a list on the left of the page.

Any errors that occur are shown on the Execution summary page, just as they're for an import project. You can edit the errors in the staging tables and resubmit the values for each data project.

Special considerations when you copy into a legal entity

When you copy into a legal entity, you have the same validation that occurs when you import a file. It's important that you test your copy in a test environment, so that you can identify any dependencies that cause failures. If dependent information isn't included in your list of entities to copy, the entity shows errors when it tries to copy into the legal entity. For example, if a customer has a default site or warehouse, you must use one of these approaches:

• Import the sites and warehouses as part of the copy.
• Manually load the sites and warehouses before you copy the legal entity.
• Unmap the site and warehouse fields before you copy the information.

You might also experience import errors if you copy from one region to another region. For example, you can have 1099 fields in a legal entity in the US region. However, if you try to import those values into a legal entity in a German region, you see errors on the import. If a template that you load has entities that are incorrect for a region, you receive an error message that states that the incorrect entity wasn't loaded. However, the rest of the template continues to be loaded. You should copy only information that is appropriate for the destination region.

The following entities require special handling when they're used to copy into a legal entity.

Rules

The Copy into legal entity feature supports rules, which let you modify data before it's added to the import staging table. For example, rules are used to change the target legal entity to the destination legal entity and modify number sequences. You can extend rules.

Rule extensions require three changes:

1. Add the name of the rule to the extensible DMFRulesType enumeration (enum).
2. For each project definition group, insert the enum that you just created (for example, DMFRulesType::NewRule) into the DMFRules table. Use your source legal entity, your rule type, and the definition group name. If you require that more data be stored, such as various options for your rule, you can create your own table and extend the DMFRules table.
3. Create your own class to handle the data that the rule acts on. For the DMFRules framework to instantiate the rule, you must decorate the class with the [DMFRulesBaseFactoryAttribute(DMFRulesType::NewRule)] attribute.

The class must also extend the DMFRulesBase class. This extension requires an implementation of the DMFRulesBase.runRule(Common_staging) method. The _staging record is the buffer of the staging record that the rule is applied to.

More information about entities

Obsolete entities

As the application is updated, the functionality of an entity might have to be updated. A new entity might be created that has a different name. In this case, the original entity is marked as obsolete. You won't be able to add obsolete entities to a new data project or template.

If you load a data package that contains an obsolete entity, you receive a warning about the existence of obsolete entities. However, you're able to import your data. You can find the obsolete entity by selecting the Obsolete column and filtering on Yes.

Self-referencing entities

Some entities represent tables that have references to themselves. For example, when you create a cash discount, you can refer to a related cash discount that creates a tiered discount calculation. To import data, you must sequence the data so that the cash discount that is referred to in the Next cash discount field is imported before the cash discount that uses that cash discount.

A new DMFImportExportSequencer class sequences the data in self-referencing entities and enables the data to be loaded in a single pass. In the Cash Discount entity (CashDiscountEntity), you can view the code that is required in order to update entities.

The class has been added to several self-referencing entities. It will be added to more entities as required. Here are some other examples of self-referencing entities:

• Customers
• Customer definitions
• Customer details
• Tax codes
• Budget control groups
• Projects
• Product categories
• Warehouses
• Budget plan workflow stage
• Sales units

Adding entities in the appropriate country/region context

When you add entities, the mappings are created in the context of the country or region of the company that is currently active. If there are any issues with the mappings, a red X appears in the View map column. Select the red X, and repair the mappings as required.