Migrate an Oracle Content Management Instance from Legacy Cloud Infrastructure
If you have Oracle Content Management instances running on legacy Cloud infrastructure using a non-metered subscription, Oracle recommends that you migrate those instances to the new native Oracle Cloud Infrastructure (OCI) environment—Gen 2 OCI (that is, using the Oracle Cloud Console to manage service instances). This will ensure that you’ll enjoy the benefits and advances of Oracle’s cloud platform in the future.
To initiate migration, you’ll need to perform a few steps prior to migration and work with Oracle Support to schedule the migration.
- Migrate your subscription to a universal credits subscription. Contact your Oracle Sales representative to assist you with this.
- Create a new instance of Oracle Content Management on OCI with the Oracle Cloud Console. This will be the target instance your data will be migrated to. Do NOT use this instance until migration has been completed.
- Migrate your users from traditional cloud accounts to Oracle Identity Cloud Service (IDCS) accounts. Make sure to preserve user names so that roles and permissions can be assigned appropriately as part of the migration process. In the exported CSV file, the user name entry is called "User Login". The application roles will be assigned according to the user mapping.
- Prepare for migration by collecting information you'll need for your service request and creating a list of any integrations you have for steps you'll need to take after migration.
- Submit a migration service request, and confirm the date and time of your migration.
- Watch the progress of the migration. Your service request will be updated as your migration progresses, and when it's done, you'll be asked to verify that your new instance is working as expected.
- Finalize the migration by completing any steps necessary to migrate any integrations that your instance has with other services or applications.
- Migrate your sites that include assets and make them multilingual compliant.
- Migrate your assets that were excluded from migration.
- Communicate the change to your users.
User Mapping
This table describes the mapping of Oracle Content Management permission groups to OCI application roles.
| Oracle Content Management Permission Group | OCI Application Role |
|---|---|
| DocumentsServiceUser | CECStandardUser |
| DocumentsServiceAdmin | CECServiceAdministrator |
| SitesServiceVisitor | CECSitesVisitor |
| SitesServiceAdmin | CECSitesAdministrator |
| ContentAdministratorRole | CECContentAdministrator |
| CECSStandardUser | CECStandardUser |
| CECSEnterpriseUser | CECEnterpriseUser |
Note:
If the target IDCS domain already contains a user with the same user name, the user will be assigned the OCI application roles corresponding to the user's Oracle Content Management permission groups.Prepare for Migration
- Make a note of the URL of the new instance (the target) you created, to include it in your migration request.
- Make a note the URL of your old instance (the source), to include it in your migration request.
- Make an inventory of all integrations that your old instance has with any other services or applications, either directly or through REST API calls. If there are any such integrations, then you’ll need to take some actions after the migration.
Submit a Migration Service Request
When you’re ready for your migration, you must submit a migration request to get the process started:
- Sign in to Oracle Cloud Support.
- Create a new service request.
- For the Problem Type, select Service Instance Migration, then choose From Non-Metered Subscription to OCI-Gen2.
- Provide the following information in your service request:
- The URL of your source instance (the instance you’re migrating from)
- The URL of your target instance (the instance you’re migrating to)
- If you use Akamai delivered by Oracle, mention that so we can coordinate a time to update the URLs in your Akamai configuration after migration
- Provide the preferred date you would like migration to start. We recommend that you give two weeks advanced notice.
Note:
We'll attempt to schedule your migration based on your requested date, but this may not always be possible given competing ongoing activities. - Submit your service request.
After Oracle Support receives your migration service request, they'll work with you to finalize a date that works for you and Oracle, and the service request will be updated with the date and time your migration will start.
- Confirm in the service request that you approve the migration start date and time.
Updates will be made to the service request to show how the migration is progressing. The data migration will be done at the back end; no action is required at your end other than to keep up with any service request updates, and to validate the migration after it's done.
The Migration Process
Here's what happens during the migration:
- Oracle Support updates the service request when migration begins.
Important:
At this point, you must not make any changes to your old (source) instance. Any changes made after migration starts won't be migrated to your new instance. - Your content and configuration data is exported from your old instance (the source), and imported into your new instance (the target).
- When the migration is complete, Oracle Support updates the service request, and you're asked to validate your new instance to make sure everything is working as expected.
- If you find any problems, note them in the service request. Oracle Support will work to resolve the issues, and will let you know through the service request when the instance is ready for validation.
- When everything is working as expected, note in the service request that you accept the migrated instance.
Note:
The old instance will remain up so that you can refer back to it for validation. You'll also need it to migrate any sites that use assets, and to migrate any other assets that were excluded during migration.Finalize the Migration
If your old instance integrated or communicated with other services or applications, either directly or through REST API calls, you might need to perform post-migration tasks.
The following items apply service-wide:
- Review the OCI application roles, and assign roles that didn't exist in your source instance, such as the CECRepositoryAdministrator application role.
- Reconfigure user credentials for all integrations that use them. Credentials aren't migrated.
- The Oracle Content Management URL pattern is different, so you'll need to update the URLs in your integrations that use them.
The old URLs used the following pattern:
https://<service-name>-<account-name>.<region>.oraclecloud.com/documents
The new URLs used the following pattern:
https://<service-name>-<account-name>.<service-type>.ocp.oraclecloud.com/documents
- Reconfigure CORS and embedded content settings. Target service settings aren't migrated.
- Standard sites will be migrated, but enterprise sites won't. Manually migrate enterprise sites and any digital assets and content items that are associated with the sites by creating a template for each enterprise site, exporting the template from the source instance, and importing it into the target instance.
- Remove or update any custom controllers used in migrated sites.
| Integration | Things to Do After Migration |
|---|---|
| Oracle Integration |
|
| Oracle Commerce Cloud |
|
| Oracle Process Cloud Service |
|
| Oracle Eloqua Cloud Service |
|
| Oracle Intelligent Advisor |
|
| Oracle Cobrowse Cloud Service |
|
| Responsys |
|
| Visual Builder Cloud Service (VBCS) |
|
| CDN/Akamai |
|
| REST API calls |
|
| Client SDK/CLI usage |
|
| Connectors |
|
Note:
Any bookmarks to content on your old instance will no longer work because the URL of your new instance has changed.Migrate Your Sites That Include Assets
Sites that don't include assets will be migrated automatically, but sites that do include assets require some additional steps to make them work in your new Oracle Content Management instance.
Install the Oracle Content Management Toolkit
The "cec migrate-site" command is new, so you'll need to install the Oracle Content Management Toolkit from webclient git repository even if you've downloaded and installed it previously.
Follow the directions on sites toolkit page to download and install the Oracle Content Management Toolkit.
Register the Target Server
Register the connection details for the target server (the server you're migrating your sites to):
> cec register-server <target_server_name>
-e http://<target_server>:<target_port>
-u <target_username> -p <target_password>
-t pod_ec- The <target_server_name> is used to identify the target endpoint and can be any name you choose.
- The <target_server> and <target_port> make up the URL you use to access the target server.
- The <target_username> and <target_password> must be the user name and password for the person who will export the site templates from the source server so that there won't be permission problems when the templates are imported during migration.
- The value "pod_ec" is the target server type, used to identify what type of server the instance is built on.
Migrate Your Sites
To migrate your sites, perform the following steps:
- On the source server, create templates from each site that includes assets.
- On the source server, export each template. Make sure you perform this step as the user you referenced when you registered the target server.
- On the target server, sign in as a repository administrator (a user with the CECRepositoryAdministrator role). Then, create a repository for the assets that will be imported with the template.
- For each downloaded template, run the following command, replacing <site_name> with the name you want the site to have on the target server:
> cec migrate-site <site_name> --template <template_path_and_name> --destination <registered_target_server_name> --repository <repository_name> - On the target server, share the migrated sites and assets appropriately.
Post-Migration Steps
After you've migrated your site, it will run using Content REST v1.1 calls. This may cause some issues that need to be resolved before the site runs correctly. Take a look at the following to determine what you need to do:
- If you're using the ContentSDK, your calls will be automatically updated to use v1.1 Content REST calls.
- If your content layouts do not say they support v1.1, the ContentSDK will also add in the "data" entry (v1.0) in the response which will simply point to the "fields" entry (v1.1) so your templates may continue to work without change.
- If you are using the "fields.type.equals=" v1.0 Content REST syntax in your additional query string, we do try to parse and modify this to be v1.1 syntax but you should validate this.
- If you are making any direct (rather than via the ContentSDK) Content REST v1.0 calls these will fail. You will need to fix your custom code and upgrade these calls.
- Likewise you need any custom content queries that make "fields.type.equals=" v1.0 syntax to be 'q=(type eq "..")' syntax.
- "updateddate" vs. "updatedDate": This is supposedly being fixed by CaaS but until we get an EC build where the Content REST v1.1 API supports both values, you need to change any "updateddate" values to be the camelCase: "updatedDate" value.
Make Your Migrated Site Multilingual Site (MLS) Compliant
Once you have your site running correctly, you then need to make your site MLS compliant. If you were to create an Enterprise site in an External Compute server, it would require a default language and localization policy. As your site was copied across, it is a non-MLS site so you need to upgrade it to an MLS site to ensure you can support future functionality.
The following table shows the differences between MLS and non-MLS sites.
| Site Object | MLS Site | Non-MLS Site |
|---|---|---|
| Content Items | The content item language variant will be displayed, not the content item dropped onto the page. The language can change depending on what language was requested when the site is rendered. | The content item that was dropped onto the page will be displayed always. |
| Content Layouts | Content Layouts must support v1.1 APIs. If they don't the content item won't appear, instead a warning will be shown. This is because all v1.1 API calls will have a "locale" added that isn't supported in the v1.0 API. | Content layouts can be either v1.0 or v1.1. If the content layout only supports v1.0, the ContentSDK will add a "data" entry in the response to match the "fields" entry. There may be still other issues so this should not be considered a "supported feature" for not upgrading the content layout. |
| Content Lists | Only content items available in the requested language variant will be displayed. | All content items regardless of language will be displayed. The user has the option within the content list to pin the results to a specific language so you can have two content lists on the page showing results in different languages. This settings panel option to choose a language is not available for MLS sites. |
| defaultLocale | MLS sites have a default site locale. This means that all content queries will only return content items that are in that locale (or non-translatable). | There is no default locale in an non-MLS site so, the content query used returns all content items regardless of language. |
| Localization Policy |
Defines the list of languages available to the site. There will be a drop-down of these in the builder. Also, in the management UI, there will be a drop-down of languages to allow you to open/preview in the requested language. |
Since there is no localization policy, the drop-down to switch languages is removed from the builder. In the management UI, there is no language listed, including no "default" language. This is how you recognize non-MLS vs. MLS sites in the management UI. |
| Translation/Translatable | The context menu in the management UI has "Translate" as an option. This allows you to create a translation job to translate the site. |
The context menu in the management UI will have a "Translatable" option. Effectively a non-MLS is non-translatable, so you need to make it a translatable (MLS) site first before you can translate it. This is also how you "upgrade" a site from non-MLS to MLS. Note: This is one-way only. You can't downgrade to non-translatable. |
Before you can turn your site into an MLS site, you need to do the following:
- Upgrade all of your content layout components to support Content REST APIs v1.1
- Upgrade any "additional query strings" in your content lists in the site to be Content REST API v1.1 compatible
Then, if you happen to have any custom component code that makes Content REST calls you also need to upgrade these to make v1.1 calls. This is uncommon since most content calls are made from content layouts.
Upgrading Content Layouts
Specifying Supported Content REST API Versions
Content layouts need to specify which version of the Content REST API they support. This is to ensure that the appropriate Content REST call is made to return the expected response data to the layout.
If you do not specify any version support it is assumed the content layout only supports v1.0.
The console will list the content layouts that are still on v1.0.
To allow your content layout to support other versions, add in the "contentVersion" property to your content layout object.
In this example, it says it supports all version between v1.0 and less than 2.0 (Note: 2.0 doesn't exist, but major version changes may introduce breaking changes)
// Content Layout
definition.ContentLayout.prototype = {
// Specify the versions of the Content REST API that are supported by the this Content Layout.
// The value for contentVersion follows Semantic Versioning syntax.
// This allows applications that use the content layout to pass the data through in the expected format.
contentVersion: ">=1.0.0 <2.0.0",
// Main rendering function:
// - Updates the data to handle any required additional requests and support both v1.0 and v1.1 Content REST APIs
// - Expands the Mustache template with the updated data
// - Appends the expanded template HTML to the parentObj DOM element
render: function (parentObj)
{Handling v1.1 Response Changes
The minimum you will need to do is to handle the Content REST API response change from: "data" to "fields". The simplest way to do this is to add back in the "data" property and point to the new "fields" property
render: function (parentObj)
{
...
if(!content.data)
{
content.data = content.fields;
}A better option is to change to use the v1.1 "fields" value throughout your content layouts. This will involve updating both your JavaScript and template code.
To fully support v1.1, you will need to handle the following Content REST API changes between v1.0 and v1.1:
| Content REST API Change | v1.1 | v1.0 |
|---|---|---|
| "fields" vs. "data" | |
|
| camelCase property names | "updatedDate" | "updateddate" |
| query format | /items?q=(type eq "Starter-Blog-Author") | /items?fields.type.equals="Starter-Blog-Author" |
| API version | /content/management/api/v1.1/items | /content/management/api/v1/items |
| language specific queries | /content/management/api/v1.1/items?q=((type eq "Promo") and (language eq "en-US" or translatable eq "false")) |
Not supported. You need to migrate all custom v1 calls to include the "language" option. This ensures the results are consistent with those returned for the MLS site when viewed in a specific language. |
Upgrading Content Query String
You may be making Content API calls in any custom code so you need to validate all the custom code used by your site that is making Content REST API calls.
- Custom Components: Check the following components:
- Content Layouts
- Local Components
- Section Layouts
- Remote Components
- Themes: JavaScript: Though less likely, you may have JavaScript in your theme that is making custom Content REST API calls so those should also be validated.
- Site Properties: Additional Query String: Once you've validated that you have upgrade all your custom code making Content REST API calls you should also upgrade the "Additional Query String" in any "Content List" components on any pages in your site. While we do try to parse and convert these at runtime, they should be upgraded to be compatible v1.1 Content REST calls for continued support.
Converting a Non-MLS Site to MLS
Once you've converted your site to fully support v1.1 Content REST APIs, you can add support for languages by changing into an MLS site.
If you select your site in the site management UI, you will see a "translatable" content menu option. Selecting this option will bring up a dialog asking you to choose a localization policy and a default language for the site from the list of required languages in the localization policy. If no localization policies exist, you will not be able to complete this step and you will first have to go to the content admin screens and create a localization policy with at least one required language.
After completing this step, your site will now render in the default locale. It will also allow you to switch to other locales specified in your localization policy.
You will need to validate that your site renders as expected in your default locale.
Migrate Your Assets
Assets that are associated with sites will be migrated when you migrate your sites, but any assets that aren't associated with sites need to be migrated separately.
Before you begin migration, take into account the following points:
- Only assets associated with a collection can be migrated. If you want to migrate assets that aren't associated with a collection, you must add them to a collection before you can migrate them.
- Non-metered instances don't support languages on assets, so when you migrate your assets, the default language will be inherited from the default language of the repository. Make sure your repository's default language is set to the desired default language before you migrate your assets.
- Only published items will be migrated. If, after migration, you're missing items, confirm that the items have been published in the source instance.
- If any of your published items have draft versions, the draft versions will become the published versions on the target instance, and the original published versions from the source instance will be lost.
- In the non-metered version of Oracle Content Management, when viewing a content item, users could choose "Content Layout" view or "Content" view. "Content" view was replaced by Content Form View in the current version of Oracle Content Management, and "Content Layout" view was removed.
To migrate your assets, perform the following steps:
- If you haven't already done so, install the Oracle Content Management Toolkit.
- Register the source and target servers.
- Migrate a collection of assets.
Register the Source and Target Servers
Register the connection details for the source and target servers.
Register the source server (the server you're migrating your assets from):
> cec register-server <source_server_name>
-e http://<source_server>:<source_port>
-u <source_username> -p <source_password>
-t pod_ic- The <source_server_name> is used to identify the source endpoint and can be any name you choose.
- The <source_server> and <source_port> make up the URL you use to access the source server.
- The <source_username> and <source_password> must be the user name and password for the person who can access the assets on the source server.
- The value "pod_ic" is the source server type, used to identify what type of server the instance is built on.
Register the target server (the server you're migrating your assets to):
> cec-install % cec register-server <target_server_name>
-e http://<source_server>:<source_port>
-u <target_username> -p <target_password>
-t pod_ec- The <target_server_name> is used to identify the target endpoint and can be any name you choose.
- The <target_server> and <target_port> make up the URL you use to access the target server.
- The <target_username> and <target_password> must be the user name and password for the person who will own the assets on the target server.
- The value "pod_ec" is the target server type, used to identify what type of server the instance is built on.
Migrate a Collection of Assets
Migrate a collection of assets by running the following command:
> cec migrate-content <source_collection_name>
--server <source_server_name>
--destination <target_server_name>
--repository <target_repository_name>
--collection <target_collection_name>
--channel <target_channel_name>The assets will be created on the target server in the specified repository and will be associated with the collection and channel. If necessary, the collection and channel will be created automatically. The default language for all migrated assets will be the default language that is set in specified repository.