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.

1. 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.
2. Download the CLI utility.
   1. In your target Oracle Analytics Cloud, click Console and then click Snapshots.
   2. Click the Page menu , and select Download Data Migration Utility.
      Follow the instructions to save the migrate-oac-data.zip file locally.
3. Unzip migrate-oac-data.zip.

   The ZIP file contains three files:

   • migrate-oac-data.jar
   • config.properties
   • readme
4. 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>

5. 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 [UploadDataFiles] 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>

6. 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

7. Sign in to your target Oracle Analytics Cloud.
8. 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 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.
9. Verify that your data files are available.