Migration Packages

Overview

The following information provides information for Migration Packages using the Redwood Admin UI.

Migration packages allow admins to create groups of objects to be quickly referenced for repeated migrations. Packages can also be downloaded as ZIP files and passed along to other admins to upload to another site. The Oracle CPQ Team and its Partners may also use packages to create and distribute groups of objects to customers to implement certain functionality on an Oracle CPQ site.

Migrating or importing a package to a site will modify objects on the target site according to the state of the objects in the package.

Components in a package will be compared to components on the target site and the results of the comparison will be reflected by the Migration Center icons, as follows: No Change Icon No Change, Added Icon Added, Updated Icon Updated, and Removed Icon Removed.

Packages View

Migration Center Packages

Item Description

1

 Click Packages to view existing migration packages and perform migration package-related actions.

2

Click the Actions drop-down to:

  • Import Package

  • Connect To Source or Manage Connections

3

Click Create Package to submit details for a new package. Oracle CPQ will step you through the package creation process.

4

To search for an existing migration packages click inside the search field and type the migration package name.

5

 When multiple migration packages are selected, click Delete to remove all the selected packages at the same time.

6

 Click the package name link under Name to view or edit the migration package details.

7

Click the migration package actions ellipsis to:

Administration

ClosedCreate or Edit a Package

To create a new migration package, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Select Create Package from the Actions drop-down. The Basic Details page displays, continue to Basic Details to create a new migration package.

To edit an existing migration package from the target site, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Click on migration package name link under Name. The Basic Details page displays with the selected migration package details. Continue to Basic Details to edit the migration package.

    You can initiate changes to the current version of the package or you may version the migration package. If you make change to the current version, you will override the current version selections. If you version the package, you will retain a copy of the the existing selections while editing the package. Refer to Version a Package.

The Migration Center steps you through creating or editing a migration package.

Basic Details

Enter the Basic Details for the migration package.

    • Name - (Required) The name for the migration package.

      This field cannot be edited once a package is created. The name and package version will be concatenated to generate the identifier.

    • Description - The description for the migration package.

    • Release Date - The date the migration package is released.

    • Package Dependencies - Select available dependencies that this package requires prior installation of to function.

    • Custom Dependency Name- The name of the custom dependency for this package.

    • Custom Dependency Version - The version of the custom dependency defined for this package

    • Add - add the custom dependency name and version to the package dependency list.

    • Click Continue to continue creating the package or Cancel to cancel the migration package selections.

Create Package - Step 1 Basic Details

Customize Package Contents

Select the components you want to include in the new migration package from the Customize Package Contents page.

  • Select the checkboxes of the desired objects in the Categories pane or the Details pane.

  • Click Compare with another site to connect to a remote site to view the site details. If not already connected to the site, you will need to enter the site URL and access credentials. Refer to Connect to Destination Site to Compare to Target Site.

  • Click Cancel to cancel the selections, Save to save the selections, or Continue to continue creating the package.

    This page displays the Category and the Details panes for the content tree and low level content, respectively. The checkboxes are used to select items to be included in the package currently being viewed.  Elements which are checked reflect elements included in the package.  

    When a high level Commerce object in the Categories pane is selected to be included in a package, the low level Commerce checkboxes in the Details pane will not appear checked.  However, those objects are in the package.

Create Package - Step 2 Customize Package Contents

Dependencies

As applicable, selected dependencies are included in the new package after export. By default all dependencies based on previously defined contents are selected.

  • Click Select Dependencies toggle to select/unselect an individual dependency.

  • Click Cancel to cancel the selections or Continue to continue creating the package.

Create Package - Step 3 Dependencies

Review and Export

You are able to review the content of the package prior to exporting the contents of the package.

  • Click on Basics, Customize Package Contents, or Dependencies to return to that page to modify the package content.

  • Click Cancel to keep the selections but not initiate the package export.

  • Click Begin Export to create the package. The package export is started. Once completed, a Package Export Status message displays with a Download option. The package is included in the list of available migration packages for that site.

Create Package - Step 4 Review and Export

ClosedImport Migration Package via Package Upload

To import a package, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Activities or Packages.

  3. Select Import Package from the Actions drop-down. The Upload Package displays.

    Upload Package for Import

  4. Click into the Drag and Drop box to browse to the exported ZIP package file or select the package ZIP file and Drag and Drop the file for import.

  5. Click Continue. The Customized Package Contents displays. Refer to Customized Package Contents.

    Customize Package Contents

  6. Initiate any customized package content modifications as desired.
    Components in a package will be compared to components on the target site and the results of the comparison will be reflected by the Migration Center icons, as follows: No Change Icon No Change, Added Icon Added, Updated Icon Updated, and Removed Icon Removed. By default, all objects in the package are selected.

    You can choose to import the entire package, or you can deselect certain objects within the package before importing.

  7. Click Continue. The Import page displays.

    Import Package

  8. Enter a description for the package import.

  9. Enter the email addresses of any additional individuals who are to receive the status notification in the Send Notificaton to field. Separate each email address with a semi-colon.
    By default, the administrator who initiated the migration receives email notifications for the migration.

    When the migration completes, a status notification is sent to each email address specified.
    The email indicates the success or failure of the migration.

  10. Click Begin Import to start the import of the migration package.

    A status message will appear in at the top of the page to show the status of the import. When the import is complete, you can view the import status in the Migration Activities to see the import migration activity log details.

    If the migration is successful, the package has been imported and will appear in the list of packages and in the activities list for the target site.

    If the migration is not successful, the package import is not complete and none of the objects in the package will be added or modified on the current site. Refer to Migration Activities for import status and migration log details.

    Notes:

    • If a package with the same Name and Version combination already exists on the site, the packages will be recognized as being the same, even if they don’t contain the same objects.
    • In this case, a dialog box appears to ask if the existing package should be overwritten. If the admin then selects Yes, and the import is successful, the uploaded package will replace the existing package, and the objects within the uploaded package will be modified on the site according to their state in the uploaded package.

ClosedImport Migration Package from Source Site for CPQ Running in Fusion

To show migration packages from a connected site, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Connect to the source site. Go to Connect To Source.

  4. Select the desired connected source site from the Show Packages From Current Site drop-down.

    Show Current Site Packages

    A message displays that you are connected to the source site and the source site migration packages are listed. You can click on the package name link to view the migration log details for the packages.

    Show Packages From Source Site

  5. Click Import from the source site migration package's Action ellipsis drop-down. This initiates the migration steps for importing the source site migration package. The Package Contents displays with the package contents that will be migrated available for you to review

    Package Contents

  6. Review the package contents. Components in a package will be compared to components on the target site and the results of the comparison will be reflected by the Migration Center icons, as follows: No Change Icon No Change, Added Icon Added, Updated Icon Updated, and Removed Icon Removed. The comparison helps you determine if the package components are what you desire to import.
  7. Click Continue to view the Dependencies for the package.
    As applicable, selected dependencies are included in the new package after export. By default all dependencies based on previously defined contents are selected.

    1. Click Select Dependencies toggle to select/unselect an individual dependency.

    2. Click Cancel to cancel the selections or Continue to proceed to Review and Import the package.

  8. You can review the content of the package from Review and Import page.

  9. Enter a description for the package import.

  10. Enter the email addresses of any additional individuals who are to receive the status notification in the Send Notificaton to field. Separate each email address with a semi-colon.
    By default, the administrator who initiated the migration receives email notifications for the migration.

    When the migration completes, a status notification is sent to each email address specified.
    The email indicates the success or failure of the migration.

  11. Click Begin Import to start the import of the migration package.

    A status message will appear in at the top of the page to show the status of the import. When the import is complete, you can view the import status in the Migration Activities to see the import migration activity log details.

    If the migration is successful, the package has been imported and will appear in the list of packages and in the activities list for the target site.

    If the migration is not successful, the package import is not complete and none of the objects in the package will be added or modified on the current site. Refer to Migration Activities for import status and migration log details.

ClosedImport Source Site Components to Target Site for CPQ Sites Running in Fusion

Note this migration may be referenced as a site to site migration between two CPQ sites running in Fusion.

To select components from a CPQ running in Fusion source site to migrate to a CPQ running in Fusion target site, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. If you are not already connected to the CPQ running in Fusion source site, the connection must be created by registering an External Application Client in IAM for Oracle CPQ Running in Fusion. Go to Register an External Application Client in IAM for Oracle CPQ Running in Fusion for instructions.

  4. If you do not have a migration connection already established between the CPQ running in Fusion source site and target site, one must be created. Go to Create Migration Connection for instructions.

  5. If you are not already connected to the source, click Connect To Source from the Actions drop-down. Connect to Source Site displays. Refer to Connect to Source Site.

  6. Select the desired connected source site from the Show Packages From Current Site drop-down.
    The available migration packages for the selected source site display. You can click on the package name link to view the migration log details for the packages.

  7. Click Import from Site to initiate the steps before you can import the source site migration package. Select Components displays showing the components for the source site.

    Select Components

  8. Review the source site contents. A comparison showing differences between the source site and target site content is displays to help you determine the package contents you want to migrate to the target site.
  9. Click Continue to display the Dependencies for the components of the source site.
  10. Review the dependencies.
  11. Click Continue to display the Review and Import page.

  12. Enter a description for the site to site migration. This description will appear in the target site activities list.

  13. Enter the email addresses of any additional individuals who are to receive the status notification in the Send Notificaton to field. Separate each email address with a semi-colon.
    By default, the administrator who initiated the migration receives email notifications for the migration.

    When the migration completes, a status notification is sent to each email address specified.
    The email indicates the success or failure of the migration.

  14. Click Migrate to import the source site components to the target site.

  15. You can view the status of this migration in the target site Migration Activities. Once completed, you will be able to view the migration activity log details also.

ClosedImport a Migration Package using FTP Automation

Migration packages are administrator-defined packages of components that can easily be moved from site to site without the administrator having to reselect components before each migration. Migration packages and individual components of a migration package can be imported into Oracle CPQ using the Migration Center or using FTP Automation data transfer.

To import a migration package using FTP, perform the following steps:

  1. If you haven't done so already, contact My Oracle Support for the creation an FTP profile and its corresponding "automated" folder on the FTP server.

  2. Prepare an XML controller file for the migration package ZIP file. The controller filename must include the prefix upload_list.

    The upload_list.xml file lists the migration ZIP file. The following shows the XML format for the migration package upload_list.xml file.

    <?xml version="1.0" encoding="UTF-8
    <files>
      <file>
        <name>migrationpackagefilename.zip</name>
        <type>REGULAR</type>
      </file>
    </files>
  3. Upload the migration package ZIP file referenced in the migration package upload_list.xml controller file.
  4. Upload the migration package upload_list.xml controller file.
  5. Navigate to the Bulk Data Upload Status page to view the migration package status.
    Admin Home > Developer Tools & Utilities > Bulk Data Services > Upload
When uploading a migration package via FTP Automation, the following default values are set (and not able to be changed by an administator) for the migration:
  • The migration package Description is set to Automatic Bulk Upload of migration package
  • The Send Notification is not set to send email notifications
  • The Include Snapshot is not set to take a snapshot of the target site immediately before performing the migration
  • The Target Process is set to Default Migration where a standard package migration is performed
  • Cross Process Migration is not supported when uploading a migration package via FTP Automation.
  • Forward Version Migration is not supported when uploading a migration package via FTP Automation.

  • FTP Automation support full package migration only and doesn't allow granular selection for migration.

ClosedVersion a Migration Package

To edit an existing migration package or create new version, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Select the migration package to version by clicking in the row of that package.

  4. Click Version under the Actions ellipses drop-down for the migration package.

    The version number auto-increments to the next available sequential number. The Basic Details page displays the new version of the package with its existing package details. Continue to Basic Details to create a new package version.

ClosedConnect to a (Destination) Source Site to Compare with the Target Site

  • The site you are currently logged into is referenced as the "target site". If you are connected to a site, that site may be referenced as the destination source site.

  • This procedure assumes you are using basic authentication. Note that we recommend transitioning away from basic authentication and to OAuth as part of your overall plan for secure communication connection.

To connect to a source site to compare with the destination source site, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Select Create Package from the Actions drop-down.

  4. Enter the Basic Details for the migration package.

    • Name - (Required) The name for the migration package.

      This field cannot be edited once a package is created. The name and package version will be concatenated to generate the identifier.

    • Description - The description for the migration package.

    • Release Date - The date the migration package is released.

    • Package Dependencies - Select available dependencies that this package requires prior installation of to function.

    • Custom Dependency Name- The name of the custom dependency for this package.

    • Custom Dependency Version - The version of the custom dependency defined for this package

    • Add - add the custom dependency name and version to the package dependency list.

    • Click Continue to continue creating the package or Cancel to cancel the migration package selections.

      Create Package - Step 1 Basic Details

  1. Click Compare with another site to connect to a destination source site to view the site details.

  2. Enter the base Site URL for the desired source site. Do not include anything after the “.com” of the URL.

  3. Enter the username and password of the source site’s Application Administrator or a FullAccess user with permission to create/modify users on the source site into the Username and Password fields, respectively.

Connect to Remote Site

  1. Click Connect. The connected site name information displays above the page title.

    The differences between the connected site and target site objects are displayed within the Categories and Details sections.

    View Differences Between Remote and Target Site

  2. Select one of the following options:

  • Click Cancel to cancel the package creation and return to the target site. , Save to save the selections, or Continue to continue creating the package.

  • Click Save to save the package and Cancel to return to current site. The package is saved, and you can come back to edit later the package at a later time.

  • Click Continue to continue creating the package. Go to Dependencies and follow the steps to complete the package creation and migration.

ClosedConnect To Source

  • The site you are currently logged into is referenced as the "target site". If you are connected to a site, that site is referenced as the "source site."

  • Connect To Source is available to sites currently using basic authentication. Note that we recommend transitioning away from basic authentication and to OAuth as part of your overall plan for secure communication connection.

  • Connect To Source is available for migrations that are not between two CPQ sites running in Fusion. Refer to Manage Connections for CPQ Sites Runnning in Fusion for source site connections between two CPQ sites running in Fusion.

Connect to source allows you to connect to a source site and perform a migration from the source site to the target site.

Once connected, you can import a package from a source site or connect to a (destination) source site to compare with the target site.

To connect to a source site, perform the following steps:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

    Manage Connections is available from both the Activities and Packages Actions drop-down.

  2. Select Connect To Source from the Actions drop-down. Connect to Source Site displays.

  3. Enter the base Site URL for the desired source site. Do not include anything after the “.com” of the URL.

  4. Enter the username and password of the source site’s Application Administrator or a FullAccess user with permission to create/modify users on the source site into the Username and Password fields, respectively.

  5. Click Connect.

ClosedManage Connections for CPQ Sites Running in Fusion

In order to connect to a CPQ source site, the two sites must be connected with an OAuth client via Oracle Identity Management. The IAM connections details are required to set up the migration connection. Contact your Oracle IAM administrator for this information. Go to Register an External Application Client in IAM for Oracle CPQ Running in Fusion for instructions.

You only need to register the CPQ running in Fusion source site as an external application client in IAM and create the migration connection for the CPQ source site one time. After the initial connection setup, you can maintain the connection if there are updates to the connection information such as the Client ID or Client Secret by selecting Manage Connections and selecting the source site from the Actions drop-down.

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

    Manage Connections is available from both the Activities and Packages Actions drop-down.

  2. Select one of the following:

    1. Manage Connections > Create Connections from the Actions drop-down to create a new migration source connection.

    2. Manage Connections > select connection from the Actions drop-down to modify the credentials of an existing migration source connection. This lists only available and existing source site connections for the target site.

  3. (Required) Enter the Connection Name.
  4. Enter a description for the connection.
  5. Select the Active check box to activate the connection. The connection is inactive when the Active check box is empty.
  6. Enter the Site URL. This is the URL for the source site.
  7. Enter the IDCS URL. This is the IDCS instance URL for the source site.
  8. Enter the Client ID, Client Secret, and Scope. This information is generated when your Oracle IAM administrator establishes the OAuth Client connection.

    Create Connection to Migration Source Site

    • If your company requires OAuth credentials be updated for security reasons, you may periodically have to update the Client ID and Client Secret to maintain the source site connection.
    • The Client ID and Client secret are extremely sensitive information. They MUST be stored securely. Contact your Oracle IAM administrator for the source site credentials and proper handling of this information.
    • To connect CPQ sites running in Fusion using IAM OAuth credentials, refer to Register an External Application Client in IAM for Oracle CPQ Running in Fusion.
  9. Click Create to create or update the source site migration connection for the Migration Center. If the connection is made, a success message displays.

ClosedTroubleshooting Common Migration Connection Errors

Error Cause/Resolution
Failed to get access token for the given Client Id. Client authentication failed. Enter correct Client ID and Client Secret as provided by IAM/IDCS.
Failed to get access token for the given Client Id. Invalid scope. Please use the correct scope as provided by IAM/IDCS.
Failed to get access token for the given Client Id. The OAuth Client app is inactive or the OAuth Client facet is not enabled for app. Log in to remote site IAM/IDCS instance and activate the client that was created for migration purpose.
Failed to validate connection with the source site. Access Denied.

  • CPQ remote site IAM/IDCS instance URL is incorrect. Verify you are using correct IAM/IDCS instance URL. This must be the CPQ source site's IAM/IDCS URL.

  • Integration user is not created on remote CPQ site. Refer to Integration Users instructions.
Failed to validate connection with the source site. You do not have access to perform this action. Contact your Access Administrator to request access. The Migration Center permission is not given to the integration user that was created for site to site migration. Verify Migration Segment Access for the integration user.

ClosedDelete Migration Package

To delete a migration package, perform the following:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Select Delete from the specific migration package Actions drop-down. The Delete Package confirmation pop-up displays.

  4. Click Delete to delete the package or Cancel to return to Migration Packages.

To delete multiple migration package at the same time, perform the following:

  1. Navigate to: Admin Home > Developer Tools & Utilities > Migration

  2. Click Packages.

  3. Click the select all checkbox or the checkbox for each of the migration packages to delete. The Delete Package confirmation pop-up displays.

  4. Click Delete to delete all the selected migration packages or Cancel to return to Migration Packages.

Notes

  • Commerce components cannot be deleted from a target site when migrated individually, apart from the entire Commerce Process—objects can only be deleted in a full migration of a Commerce Process.

    For example, if a Commerce Main Document attribute exists on the target site but does not exist on a source site, that attribute will not be deleted from the target site if a Main Document's attributes are selected and then migrated.

  • After migrating individual components within a Commerce Process, differences calculated between the source and target site within the Content pane may show the sites to be different, even if all the differences within the Details pane show the sites to be the same.

    In order to completely sync a Commerce Process between two sites, perform a full migration of the Commerce Process using the Content pane.

  • Administrators should use caution when using migration packages that contain Configuration layouts and rules. All Product Family attributes are deleted from the target Configuration if a source migration package that contains Configuration layouts or rules without All Product Family references is migrated to a Configuration with All Product Family references. This will cause deployment and Configuration Flow errors for Configurations that reference the deleted All Product Family attribute.
  • If necessary dependencies are not included in the migration, the migration may fail.

  • Dependent Packages need to be installed first in the target system before installing the migration package in order to ensure all the data is migrated as desired. The Dependencies field in the Create Package UI does note that the packages in the Include list be available in the target system prior to installing the package; however, this validation is not enforced. If you don't have the dependent packages in the target system, it will not stop you from installing the package.

Notes:

  • Oracle CPQ does not recommend migrating between blank and Standard Processes due to dependencies and validation issues. The following methods are recommended:
    1. The preferred method is to perform granular migration of only attributes and actions that don't exist in the Standard Process.
      1. The source attributes and actions should not have any customizations or dependencies with other attributes, actions, or rules.
      2. All customizations need to be manually added to the target Standard Process.
    2. The second and more secure option is to manually create everything from scratch in the Standard Process.
  • Packages cannot contain other packages.
  • A package cannot be imported or downloaded while a migration is in progress, a Rollback is progress, or a Snapshot is being applied.
  • Note than the site you are currently logged into is referenced as the "target site". If you are connected to a site, that site is referenced as the "source site."

Related Topics

Related Topics Link IconSee Also