Migrate Your Oracle Analytics Cloud

3 Migrate Your Oracle Analytics Cloud - Classic Instances

When your target environment is ready, capture the information you want to migrate in a snapshot and copy it to Oracle Cloud Infrastructure.

Task	Description	More Information
Understand snapshot options	Understand what you can include or exclude when you take a snapshot.	Understand Snapshot Options
Check your target is ready for migration and take a backup	Verify that the required users and roles are available in your target service and take a snapshot in case you need to roll back.	Back Up Your Target Service Before Migration
Take a snapshot of the source	Capture the content you want to migrate on the source system.	Take a Snapshot on the Source
Export the snapshot locally	Download the snapshot that you want to migrate to your local file system.	Export the Snapshot
Edit database connections	(Only if you migrated your data from Oracle Cloud Infrastructure Classic to Oracle Cloud Infrastructure) Extract the semantic model .rpd file from the snapshot (BAR), add the new connection string, and then upload the updated semantic model to the target system.	Edit Connections and Upload Semantic Model
Import the snapshot to the target	Sign in to the target system and import the snapshot.	Import the Snapshot on the Target
Restore the snapshot content	Select the newly imported snapshot in the list of saved snapshots and restore the content in the snapshot.	Restore the Snapshot on the Target
Migrate data files	(Only if the restore process fails due to connection issues) Use the Data Migration utility to migrate and restore data files from another environment.	Migrate File-based Data
Reconfigure data replication connections	(Only if you migrated replicated data from Oracle Cloud Infrastructure Classic to Oracle Cloud Infrastructure) Verify that the replicated tables and the required system tables exist on the new target database, and then edit the data replication connections to point to the new database.	Move Replicated Data to a Different Target Database
Reconfigure service settings	Verify various administrative settings on the target service.	Configure Service Settings
Activate deliveries	Disable deliveries on the source service and start delivering content from the target service.	Restore and Enable Delivery Schedules
(Optional) Migrate other snapshots	Export individual snapshots that you want to migrate and then import them to your target environment, as required.	Export Snapshots Import Snapshots

Understand Snapshot Options

You can set various options when you take a snapshot of the Oracle Analytics Cloud environment you want to migrate.

Options When You Take a Snapshot

When you take a snapshot you choose the content you want to include in it. You can take a snapshot of your entire environment (everything) or specify only specific content that you want to back up or migrate (custom).

Everything - Saves your entire environment in the snapshot. This option is useful if you want to:
- Back up everything in case something goes wrong.
- Migrate everything to a new environment.
- Clone an existing environment.

Custom - You select which content to save in the snapshot. Some content types are always included while others are optional.

Snapshot Option	Description	Optional?
Data	Data visualization content that users create (Data tab).
Datasets	Datasets that users create for data visualizations and data flows.	Always included
File-based Data	File-based data that users upload to create datasets. For example, data uploaded from a spreadsheet.	Optional
Connections	Data connections that users create so they can visualize their data.	Always included
Data Flows	Data flows that users create for data visualization.	Always included
Sequences	Sequences that users create for data visualization.	Always included
Data Replications	Data replications that users create for data visualization.	Optional
Machine Learning	Machine learning models that users create from data flows.	Always included
Jobs	Jobs that users schedule for data flows, sequences, data replications, and pixel-perfect reports.	Optional
Plug-ins and Extensions	Extensions that users upload to implement custom visualizations and custom maps.	Optional
Configuration and Settings	Service configuration and settings configured through Console. For example, mail settings, database connections, safe domains, data connectivity configurations, and so on. Note: System settings aren't included in the snapshot.	Optional
Day by Day	Day by Day content such as the "For You" feed, bring backs, comments, and shared cards.	Optional
Application Roles	User-defined application roles that administrators create through Console. Membership details for each application role, that is, the users, groups, and other application roles assigned to each application role.	Always included
Credentials	Data connections: Credentials and other connection parameters, such as host, port, user name, and password. If you exclude credentials, you must reconfigure the connection details after you restore the snapshot. Cloud storage: Credentials required to access cloud storage where file-based data that users upload is stored. If you include file-based data in your snapshot, include the storage credentials if you plan to migrate the content to another environment. If you exclude credentials, you can use the Data Migration utility to download and then upload your data files separately.	Optional
Classic Content	Content that users create using Classic tools in Oracle Analytics Cloud, such as analyses, dashboards, and pixel-perfect reports.	Always included
Semantic Model and Subject Areas	Semantic models and subject areas that users create.	Always included
Catalog Content	Catalog containing content that users create and save for future use, such as analyses, dashboards, reports, deliveries, agents, and so on.	Always included
Shared Folders (including Workbooks)	Content that is being shared, that is, content that everyone with access to Classic tools can see. This includes any data visualization workbooks saved in the shared folders.	Always included
User Folders and Personalizations (including Workbooks)	Content stored in user folders. Content that users create and store for their private use. This includes any data visualization workbooks that users save in their private folders and any personalizations that they make to these workbooks.	Optional

Options When You Restore a Snapshot

When you restore content from a snapshot you have several options. You can restore only the content that's inside the snapshot, restore everything in your environment, or restore a specific set of items in the snapshot (custom).

Replace Snapshot Content Only - Everything in the snapshot that's supported in your environment is restored. Any content type excluded from the snapshot remains unchanged in your environment.
Replace Everything - Replaces your entire environment using information in the snapshot.
Any content type excluded from the snapshot is restored to its default state, that is, "no content". For example, if you chose not to include jobs in the snapshot, any jobs that exist on your system are deleted when you restore the snapshot and the jobs feature is restored with default settings. There are some exceptions; if the snapshot doesn’t contain any file-based datasets, plug-ins, or extensions these items are left unchanged.

This option is useful if you want to:
- Replace everything after something went wrong.
- Migrate from another service.
- Clone an existing service.
Custom - You select the content you want to restore. If you don’t want to restore certain content types, exclude them before you restore.
In most cases, the options on restore are the same as the options when you take a snapshot. Some content types are always restored, while others are optional.

Note:
When you restore catalog content from a snapshot, delivery schedules aren’t automatically restored or activated. This is so you can restore and activate deliveries at a time that suits you. See Restore and Enable Delivery Schedules.

If your snapshot contains items that your environment doesn’t support, you see the message "Not supported in this environment".

Restoring a Snapshot Taken from a Different Product

You can take snapshots in several Oracle products; Oracle BI Enterprise Edition 12c, Oracle Analytics Cloud, and Oracle Analytics Server.

Unsupported Content

If you take a snapshot in one product and try to restore it in a different Oracle product, you might find the snapshot contains some items that the target environment doesn’t support. When Oracle Analytics detects unsupported content, warning icons display on the Custom page to highlight unsupported items in the snapshot that won't be restored.

For example, you take a snapshot in Oracle Analytics Cloud and include data replications, file-based datasets, plug-ins and extensions in the snapshot. When you restore the snapshot in Oracle Analytics Server, you notice that these items are marked not supported. Oracle Analytics Server doesn’t allow you to include data replications, file-based datasets, plug-ins and extensions in an Oracle Analytics Server snapshot or import them from snapshots you created in other products.

Back Up Your Target Service Before Migration

Verify that your target Oracle Analytics Cloud is ready for migration and then take a snapshot in case you need to roll back the service to its pre-migration state.

Sign-in to the target Oracle Analytics Cloud.
Verify that the users and roles you imported are available.
1. Navigate to Console, and click Users and Roles.
2. Click the Users tab and then the Roles tab to verify the users and roles.
Take a backup of the target Oracle Analytics Cloud.
1. Navigate to Console, and click Snapshots.
2. Click Create Snapshot.
3. For description, enter "Snapshot before content migration" or something similar.
4. Select Everything, and then click Create.

Migrate Your Content

Capture the content you want to migrate in a snapshot and restore that snapshot on your target Oracle Analytics Cloud.

Sign-in to the source Oracle Analytics Cloud.
Save the entire environment you want to migrate to a snapshot.
1. Navigate to Console, click Snapshots, and then Create Snapshot.
2. For name, enter Migrate content to Oracle Cloud Infrastructure or something similar.
3. Select Everything, and the click Create.
See also Take a Snapshot on the Source.
Export the snapshot (BAR file) locally.

You're asked to create a password for the snapshot. You'll need this password when you import the snapshot on the target system.
See Export the Snapshot.
If required, extract the semantic model .rpd file from the snapshot (BAR), add the new connection string, and then upload the updated semantic model to the target system.

This step is only required if you currently use Model Administration Tool for Oracle Analytics Cloud to manage semantic models and you migrated your data from Oracle Cloud Infrastructure Classic to Oracle Cloud Infrastructure. See Edit Connections and Upload Semantic Model.
Sign-in to the target Oracle Analytics Cloud and import the snapshot.
See Import the Snapshot on the Target.
Restore the snapshot.
Do one of the following:
- If you didn’t edit your semantic model in Step 4, select Replace Everything.
- If you edited and uploaded your semantic model in Step 4, select Custom, and deselect Data Model and Subject Areas.
See Restore the Snapshot on the Target.
In Console, verify and configure other settings to complete the migration.

Edit Connections and Upload Semantic Model

Sometimes you must reconfigure the database connection information that's saved inside your source semantic model .rpd file before you migrate to the new Oracle Analytics Cloud on Oracle Cloud Infrastructure. For example, if you moved your data from Oracle Cloud Infrastructure Classic to Oracle Cloud Infrastructure, this is required because the connect string for the new database is different. If you do need to edit the source semantic model, you must upload the updated semantic model on the target before you migrate the rest of your content.

Note:

These instructions only apply if you currently use Model Administration Tool for Oracle Analytics Cloud to manage semantic models. If you use Data Modeler, you edit database connections through Console in your target environment.

Determine the connection string for the new database on Oracle Cloud Infrastructure.
If you haven’t done so already, download and install the latest Model Administration Tool for Oracle Analytics Cloud from:

http://www.oracle.com/technetwork/middleware/oac/downloads/oac-tools-4392272.html

For instructions, see Download and Install Oracle Analytics Client Tools.
Locate the final snapshot of your source environment (BAR file) that you downloaded to your local system.

You must know the password you entered when you downloaded the snapshot. You'll be asked to provide the password later.
Run the expandarchive command to expand the BAR file and navigate to the semantic model .rpd file.
1. At a command window, set the DOMAIN_HOME variable.
  For example: C:\> set DOMAIN_HOME=<CLIENT_TOOL_INSTALL_HOME>\domains\bi
  
  Where CLIENT_TOOL_INSTALL_HOME is the directory where you installed the client tools.
2. Navigate to the required scripts directory:
  For example: C:\> cd <INSTALL_HOME>\bi\modules\oracle.bi.metadatalcm\scripts>ls
3. Run the expandarchive command to expand the BAR file.
  Use the format:
```
expandarchive.cmd  <BAR file location> <expand archive directory> [encryptionpassword=<password>]
```
  For example:
```
C:\TOOLS\Oracle\bi\modules\oracle.bi.metadatalcm\scripts>expandarchive.cmd C:\Downloads\Migrate.bar C:\OCIMigration encryptionpassword=secret123
```
4. Navigate to the expand archive directory and locate the semantic model file.
  A semantic model file named default.rpd is located under datamodel\rpd\default.rpd.
Use the latest Model Administration Tool to open default.rpd.
The password required to open default.rpd is the password you entered to download the snapshot.
Navigate to the Physical Layer pane, select the database connection you want to edit, and open the Connection Pool dialog.
Edit the connection details In Data Source Name, to specify the new database on Oracle Cloud Infrastructure.
Save the changes to default.rpd.
Copy the updated semantic model file (default.rpd) back to the BAR file.
Upload the updated semantic model file (default.rpd) to the target Oracle Analytics Cloud instance.
Navigate to the Console, click Snapshots, click the Page menu, and then click Replace Data Model.

Migrate File-based Data

Users upload data files, such as spreadsheets, to Oracle Analytics Cloud to create datasets. When you migrate to a new Oracle Analytics Cloud environment, you can take this file-based data with you. Sometimes, network connectivity or storage access issues might prevent you from migrating the data files in the snapshot. For such cases, Oracle Analytics Cloud offers a CLI utility (command-line interface) that enables you to move your data files to the new location. The snapshot CLI utility also moves any map-related plug-ins and extension files that users might upload for their data visualizations.

Run the data migration CLI utility if you see the message

Restore
          succeeded with errors - data restore failed

(or similar) when you try to restore a snapshot that contains data files. This message occurs when:

You migrate content from a different region.
You migrate content from Oracle Analytics Cloud on Gen 1 or Oracle Cloud Infrastructure Classic to Oracle Analytics Cloud on Gen 2.
The restore process fails due to some other network connectivity or storage access issue.

The CLI utility allows you to move data files directly from one environment to another in a single step. Or if you prefer, you can download your file-based data to a ZIP file and then upload the data files to your chosen environment in two separate steps.

Check your environment details.
- Verify that the source and target system both use Oracle Analytics Cloud 5.3 or later. The CLI utility isn't available in earlier versions.
  
  If you're not sure, ask your Oracle representative.
- Check that the source and target system are both up and running, and Oracle Analytics Cloud is configured with valid storage credentials.
- Check your local environment. You need Java 1.8 or later to run the CLI utility.
- Make sure you can access the source environment and the target Oracle Analytics Cloud from the local environment where you plan to run the CLI utility.
- Verify the name and location of the snapshot that you downloaded earlier containing your file-based data. For example, /tmp/20190307095216.bar.
Download the CLI utility.
1. In your target Oracle Analytics Cloud, click Console and then click Snapshots.
2. Click the Page menu , select Migrate, then Download Data Migration Utility.
  Follow the instructions to save the migrate-oac-data.zip file locally.
Unzip migrate-oac-data.zip.
The ZIP file contains three files:
- migrate-oac-data.jar
- config.properties
- readme

If you want to migrate data files stored in your source environment directly to the target in a single step, configure the section [MigrateData] in config.properties.

[MigrateData]
# Migrate data files from a source Oracle Analytics Cloud environment (OAC) to a target Oracle Analytics Cloud environment.
    # Specify the source environment as Oracle Analytics Cloud.
      SOURCE_ENVIRONMENT=OAC
    # Source Oracle Analytics Cloud URL. For example: https://sourcehost.com:443 or http://sourcehost.com:9704
      SOURCE_URL=http(s)://<Source Oracle Analytics Cloud Host>:<Source Port>

    # Name of a user with Administrator permissions in the source environment. For example: SourceAdmin
      SOURCE_USERNAME=<Source Administrator User Name>
    # Location of the source snapshot (.bar file). For example:  /tmp/20190307095216.bar
      BAR_PATH=<Path to Source Snapshot>
    # Target Oracle Analytics Cloud URL. For example: https://targethost.com:443 or http://targethost.com:9704
      TARGET_URL=http(s)://<Target Oracle Analytics Cloud Host>:<Target Port>
    # Name of a user with Administrator permissions in the target environment. For example: TargetAdmin
      TARGET_USERNAME=<Target Administrator User Name>

If you want to first download data files from your source Oracle Analytics Cloud to your local environment and subsequently upload the data files to the target Oracle Analytics Cloud environment, configure sections [DownloadDataFiles] and [UploadDataFragments] in config.properties.

[DownloadDataFiles]
#Download Data Files: Download data files from Oracle Analytics Cloud storage to a local repository
    # Specify the source environment as Oracle Analytics Cloud.
      SOURCE_ENVIRONMENT=OAC
    # Source Oracle Analytics Cloud URL. For example: https://sourcehost.com:443 or http://sourcehost.com:9704
      SOURCE_URL=http(s)://<Source Oracle Analytics Cloud Host>:<Source Port>

    # Name of a user with Administrator permissions in the source environment. For example: SourceAdmin
      SOURCE_USERNAME=<Source Administrator User Name>
    # Location of the source snapshot (.bar file). For example:  /tmp/20190307095216.bar
      BAR_PATH=<Path to Source Snapshot>
    # Local data file directory. Make sure you have enough space to download the data files to this directory. For example: /tmp/mydatafiledir 
      DATA_FRAGMENTS_DIRECTORY=<Data Files Directory>
     # Data fragment size. Data files are downloaded in fragments. Default fragment size is 500MB.
      MAX_DATA_FRAGMENT_SIZE_IN_MB=500

[UploadDataFiles]
#Upload data files: Upload data files to the target Oracle Analytics Cloud. 
    # Target Oracle Analytics Cloud URL. For example: https://targethost.com:443 or http://targethost.com:9704
      TARGET_URL=http(s)://<Target Oracle Analytics Cloud Host>:<Target Port>
    # Name of a user with Administrator permissions in the target environment. For example: TargetAdmin
      TARGET_USERNAME=<Target Administrator User Name>
    # Local directory containing the data files you want to upload. For example: /tmp/mydatafiledir
      DATA_FRAGMENTS_DIRECTORY=<Data Files Directory>
    # Location of the source snapshot (.bar file). For example:  /tmp/20190307095216.bar
      BAR_PATH=<Path to Source Snapshot>

Run the migrate-oac-data.jar file in your local environment.
Syntax:
```
migrate-oac-data.jar [-config configfile] [-d] [-help] [-m]  [-u]
```
Where:
- -config configfile : Name of the config.properties file
- -d : Downloads data locally using information in config.properties
- -help : Displays help
- -m : Migrates data using source and target information in the config.properties file
- -u : Uploads data using information in the config.properties file
For example, to migrate data files in a single step:
```
java -jar migrate-oac-data.jar -m -config config.properties
```
For example, to download data files locally:
```
java -jar migrate-oac-data.jar -d -config config.properties
```
For example, to upload data files:
```
java -jar migrate-oac-data.jar -u -config config.properties
```
Sign in to your target Oracle Analytics Cloud.
To expose the data files in Oracle Analytics Cloud, you must restore the snapshot that you used to migrate the rest of your content for a second time. This time, you must select the Custom restore option.
1. Open the Console, and click Manage Snapshots.
2. Select the snapshot containing your data files.
3. Select the Custom restore option, and then select the option File-based data.
  Deselect all other options.
4. Click Restore.
Verify that your data files are available.

Move Replicated Data to a Different Target Database

In data replication, if you change the target database, you can migrate the current data to the new database, and reconfigure your connections to replicate to your new database.

For example, you might need to do this if your organization migrates from Oracle Cloud Infrastructure - Classic to Oracle Cloud Infrastructure.

Make sure that your new target schema has the required privileges and permissions. See What Privileges and Permissions Are Required?.
Copy the replicated tables and the following replication system tables to the new target schema.
- All replicated tables (along with corresponding indexes, constraints)
- REPL$_ERR_SUMMARY
- E$_*
- SDS_*
Configure a replication connection for the new target database.
- If your new target database is of the same type as your old target database, then simply edit your existing replication connection and update the connection details.
  In the Connections page, locate the replication connection, click Inspect, and use the General tab to update the details for the new target database.
- If your new target database is of a different type, then create a new replication connection for that type and specify the connection details.
  Click Create, then Replication Connection, select the appropriate type, and specify the details.
Update each data replication entry that is configured to use the old target database connection details.
1. Open the Data Replications page, and select the data replication you want to edit.
2. In the Replication Target area:
  - If your new target database is of the same type as your old target database, make sure that Schema is set correctly for the new database.
  - If your new target database is of a different type, click Select and select the new target connection, then click Schema and set correctly for the new database.
From the Home page, navigate to Data and then Connections. Locate the replication connection for your target database, click Inspect, and use the Tables tab to verify the table information for the new target schema.

You can now resume data replication in incremental mode into the new database.

Configure Service Settings

Many settings are migrated for you. Take some time to review various settings on the target Oracle Analytics Cloud and reconfigure if required.

Sign-in to the target Oracle Analytics Cloud and navigate to Console.
Verify all the application roles that you want are available on the Application Roles page.
See Add Members to Application Roles.
Verify your email server configuration on the Mail Server page.
See Set Up an Email Server to Deliver Reports.
Verify your custom plug-ins and extensions on the Extensions page.
See Manage Custom Plug-ins.
Verify your virus scanner configuration on the Virus Scanner page.
See Set Up a Virus Scanner.
Verify your safe domains are configured on the Safe Domains page.
See Register Safe Domains.
If you customized advanced settings in your source service, verify the settings are correct on the System Setting page.
See Configure Advanced Options.
Verify map configuration for data visualizations on the Maps page.
See Add Custom Map Layers.
Verify map configuration for analyses and dashboards on the Manage Map Data page (Classic Administration).
See Set Up Maps for Dashboards and Analyses.

Restore and Enable Delivery Schedules

When you restore content from a snapshot or migrate content from a different environment, delivery schedules defined for agents, analyses, and dashboards in the snapshot aren’t restored or activated right away. When you’re ready to restore deliveries on your system, you can decide whether to enable or disable delivery schedules on your system. This is useful as you might not want to immediately start delivering content.

For example, if you're restoring a production environment, you probably want to restart deliveries as soon as possible. Whereas in a test environment, you might prefer to disable deliveries after restoration and activate them at a later date.

In the Oracle Analytics Home page, click the Navigator, and then click Console.
Click Monitor Deliveries.
To restore deliveries, click the Action menu for the page and select Restore Deliveries.
Select whether to restore and activate deliveries or restore deliveries only. Select one of the following:
- Maintain Delivery Schedule Status
  
  All delivery schedules maintain their status (enabled or disabled).
  - Existing delivery schedules remain unchanged.
  - New delivery schedules created during the restore process inherit the schedule status that’s defined in the corresponding agent, analysis or dashboard.
  For example, this option is useful when you restore deliveries in a production environment where you want deliveries to be active immediately.
- Disable Delivery Schedules for New Deliveries
  
  Delivery schedules that are created during the restore process for agents, analyses, and dashboards are disabled. Existing delivery schedules remain unchanged.
  
  For example, this option is useful when you restore deliveries in a test environment where you don’t need to activate deliveries immediately.
- Disable All Delivery Schedules And Delete All History (Not recommended)
  
  All delivery schedules are disabled during the restore process and any delivery history is deleted.
  - Existing delivery schedules are disabled.
  - New delivery schedules created for agents, analyses, and dashboards during the restore process are disabled.
  - Historical delivery details no longer available.
  This option is not recommended. If you do select this option, you must manually enable delivery schedules for all agents, analyses, and dashboards.
Click Restore.
To activate a delivery, click the Action menu for the delivery, and select Enable.

To activate multiple deliveries at once, select Shift + click or Ctrl + click to select all the deliveries you want to activate, then right-click and select Enable.

If necessary, click Edit to redefine the delivery schedule.