Working with Templates

Templates enable you to store application or dimension configurations in an offline file for use in other Oracle Enterprise Data Management Cloud environments. Use templates to transfer applications or dimensions and their metadata objects across environments (for example, from a test environment to a production environment) or to get a quick start in new implementations.

To use a template, first you export an application or a dimension and all of its related metadata objects in the source environment to a .json file, and then you import that template in the target environment.

Templates contain metadata only and do not include any data, requests, or transaction history.

Best Practice

If you are creating an application in a test environment that you plan to transfer to an existing production environment, it is a best practice to refresh your test environment with a current snapshot of your production environment first, and then create the application to be transferred. This ensures that global objects such as properties and views have the same IDs in both environments.

Caution:

Templates are designed to migrate changes from one environment to another. For that reason, it is important to designate a source system where all changes are made and a target system where changes are migrated to. Do not make changes in both environments. You can use migration snapshots to resynchronize your environments if needed. See Best Practices in Migration Scenario Examples.

Considerations

• You must be a Service Administrator or have the Migrations - Administer application role (see Understanding Application Roles and Permissions) to import and export applications and dimensions to templates.
• When an application is transferred to the target environment:
  • If the application owner from the source environment also exists in the target environment, they are preserved as the application owner in the target environment.
  • If the application owner from the source environment does not exist in the target environment, a Service Administrator must assign an owner to the application in the target environment.
• You can transfer new applications or dimensions from the source to the target environment, or you can transfer applications or dimensions that already exist in the target environment. The template import process updates existing applications or dimensions in the target environment by creating objects that do not already exist and modifying existing objects for the target application or dimension. See Updating an Existing Application or Dimension using a Template.
• You can transfer active applications only.
• You can exclude archived data chain objects from template imports if the archived objects in the source environment do not already exist in the target environment.

  Note:

  Objects that are dependent on an archived object are also excluded from the template import if they do not exist in the target environment. If a dependent object would be partially excluded, the object will appear in the template preview or import with a warning message indicating it could not be imported.

  For example, if you exclude an archived dimension during the import and the dimension does not already exist in the target environment, then objects such as dimension bindings, node types, policies, and extracts are also excluded from the template import if they don't already exist in the target environment.

• You can transfer multiple applications in a single template file. If you are transferring at the dimension level, you cannot transfer multiple dimensions in a single template file.
• When transferring dimensions, the application that contains the dimension must exist in the target environment.
• To transfer an application or a dimension between environments, both environments must be on the same release version.
• When importing a template, if a user or group exists in both the source and target environment, the following user and group references for the associated objects are imported:
  • Permissions
  • Policy users and groups
  • Subscription Assignees
  • View filters for users and groups

  If a user or group in the source environment does not exist in the target, the associated user or group reference are not transferred. A message is displayed indicating the missing users and groups in the target environment and the associated objects that were not imported.

• Both the source and target applications or dimensions must exist in the target environment in order to import node type converters and subscriptions. Transfer both the source and target applications in the same template file, or else ensure that you import the source application or dimension for converters and subscriptions first, so that when you import the target application or dimension the converters and subscriptions get created.
• If you are transferring a dimension with properties that use a node data type to reference other dimensions, those source dimensions must already exist in the target system. If they do not, either transfer those source dimensions first or use an application template to transfer all of the dimensions in the same template file.
• When you import the following global objects, if the object already exists in the target environment with the same name but a different ID, the source object is renamed in the target environment to make it unique:
  • Properties
  • Views
  • Lookup Sets
  • Global Connections
• After you export an application or a dimension to a template, you can review the contents of the template file in a .json viewer.

  Caution:

  Manually editing the template file is not supported.

To export applications or a dimension to a template:

1. From the Tools tile, select Templates.

   Note:

   The Tools tile is visible to Service Administrators or users with the Migrations - Administer application role only.
2. On the Export tab, perform an action:
   • To export applications, select an application from the left panel. Use Ctrl/Cmd+Click to select multiple applications. The applications that you select are listed in the Selected Artifacts section.
   • To export a dimension, expand the application in the left panel and select the dimension to export. You cannot select multiple dimensions in a single template file.

     Note:

     To export an attribute dimension, select the base dimension for the attribute dimension.
3. In Template File, enter a file name with a .json extension, and then click Export.

   The template is created and downloaded to your local file system. The status of your export is displayed.

To import an application or a dimension from a template:

1. From the Tools tile, select Templates.

   Note:

   The Tools and Templates tiles are visible to Service Administrators or users with the Migrations - Administer application role only.
2. On the Import tab, click Choose File.
3. From your local file system, select a file with a .json extension, and then click Open.
4. Optional: Choose one or more Import Options:
   • Replace Permissions: Replace existing permissions in the target environment with permissions from the source template.
   • Replace Policy Groups: Replace existing policy groups in the target environment with policy groups from the source template.
   • Exclude Archived Objects: Excludes archived objects in a template from a source environment from being imported into the target environment if the source objects do not exist in the target environment.

     Note:

     Archived objects in a source template which already exist in the target environment cannot be excluded from template preview or import.

   See Template Objects and Settings.

5. Click Preview to identify the objects in the template file and view the status of each. See Previewing Template Imports and Reviewing Import Results.
6. Click Import, and then click Yes on the confirmation message.

   The template is imported, and the status of each object in the template is displayed. See Previewing Template Imports and Reviewing Import Results.