Project history export/import tool

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.gradle/
+build/
+dist/
+bin/

tools/README.md

@@ -1,4 +1,7 @@
 # Intelligent Advisor tools
 
+## project-history-migrator-tool
+A CLI utility that allows the migration of the full project version history from a self-managed instance of Intelligent Advisor to a cloud instance. The tool migrates the project version history for both Policy Modeling projects and Decision Service projects.
+
 ## web-projects-migrator
 A tool for migrating rules in Oracle Policy Modeling projects to Intelligent Advisor Flow projects and Decision Service Projects. Supplied in source form to encourage project-specific enhancements.

tools/project-history-migrator-tool/README.md

@@ -0,0 +1,89 @@
+# Project History Migrator Tool
+This is a CLI utility that allows the migration of projects along with their full version history from a self-managed instance of Intelligent Advisor to a cloud instance. The tool migrates both Policy Modeling projects and Decision Service projects.
+
+## Prerequisites
+### System requirements
+- The tool must be run on a machine that has the Java 8 Runtime Environment (JRE) or newer installed
+- For running in export mode - network access (JDBC) to the database associated with your self-managed Intelligent Advisor installation is required
+- For running in import mode - network access (HTTP) to the Intelligent Advisor cloud instance is required 
+
+### Pre-migration setup
+Before beginning the migration process for the project history, the following steps must be taken:
+- Migrate users to the cloud instance using the [Users REST API](https://docs.oracle.com/en/cloud/saas/b2c-service/opawx/using-users-rest-api.html), or by creating manually
+- Migrate workspaces to the cloud instance using the [Workspaces REST API](https://docs.oracle.com/en/cloud/saas/b2c-service/opawx/using-workspaces-rest-api.html), or by creating manually
+- Migrate connections to the cloud instance using the [Connections REST API](https://docs.oracle.com/en/cloud/saas/b2c-service/opawx/using-connections-rest-api.html), or by creating manually
+- On the cloud instance, create deployments for any decision service projects that are used as references in other projects
+- On the cloud instance, create an API client to use for importing project history. This API client must have both the **manager** and **author** roles for **all workspaces**
+
+## Building the tool
+The tool can be built from source using the Gradle wrapper:
+
+```bash
+# macOS/Linux
+./gradlew clean build
+
+# Windows (PowerShell/CMD)
+gradlew.bat clean build
+```
+
+The JAR will be created under `build/libs/`. It is named after the project directory:
+```
+build/libs/project-history-migrator-tool.jar
+```
+
+## Usage
+### Export mode
+Usage:
+```bash
+java -jar project-history-migrator-tool.jar --export <dbUrl> [timeZoneId]
+```
+Parameters:
+- `dbUrl`: JDBC URL that references the MySQL or Oracle database associated with your self-managed Intelligent Advisor installation. Examples `jdbc:mysql://hostname:3306/schema_name`, `jdbc:oracle:thin:@//hostname:1521/PDBNAME`
+- `timeZoneId` (optional): Sets the time zone for interpreting and formatting timestamps values read from the database. Examples: 'UTC', 'Europe/London', '+10:00'. Defaults to system time zone. See Java 8 Javadoc ZoneId.of(String): <https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html#of-java.lang.String->
+
+Output:
+A zip archive containing the exported data, with filename `export-<timestamp>.zip`
+
+### Import mode (with resume)
+Usage:
+```bash
+java -jar project-history-migrator-tool.jar --import <IAHostUrl> <exportedPayloadPath> [resumeJournalPath]
+```
+
+Parameters:
+- `<IAHostUrl>`: Base host URL of the Intelligent Advisor site, e.g. `https://name.custhelp.com` 
+- `<exportedPayloadPath>`: Path to the exported zip created by this tool
+- `[resumeJournalPath]` (optional): Path to a previously written journal file used to resume a previous failed import of project history
+
+Output:
+A journal file in JSON format, with filename `import-<timestamp>.json`. In the event of a failure part way through the import process, the journal file can be used to resume the process. To resume, pass the path to this file as the "resumeJournalPath" parameter.
+
+## Troubleshooting
+- Database connection failed:
+  - Error: "Failed to connect to the database: ..."
+  - Verify network, credentials, and JDBC URL.
+
+- Name clashes on IA Hub:
+  - Error: "Projects with the following names already exist on the IA Hub: ..."
+  - Rename or remove conflicting projects on the Hub, or import into a different environment/workspace.
+
+- Missing workspaces:
+  - Error: "Target hub is missing workspaces: ..."
+  - Create the required workspaces on the IA Hub, then retry.
+
+- OAuth errors:
+  - Error: "Authentication failed. HTTP code: <code>"
+  - Or: "Authentication succeeded but access_token not found"
+  - Verify client id/secret and the Hub URL.
+
+- HTTP upload failures:
+  - Error includes the HTTP code and response body. Check that your client has sufficient permissions.
+
+- Snapshot not found in zip:
+  - Error: "Snapshot file not found in zip: <fingerprint>"
+  - Ensure the payload zip was produced by this tool and not modified.
+
+- Resume validation errors:
+  - "Journal file does not match payload"
+  - "Journal file does not match specified IA Hub"
+  - Ensure the correct journal file is provided for the payload and target Hub.

tools/project-history-migrator-tool/build.gradle

@@ -0,0 +1,35 @@
+plugins {
+    id 'application'
+}
+
+mainClassName = 'com.oracle.determinations.migration.Main'
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'com.mysql:mysql-connector-j:8.3.0'            // correct coords for MySQL 8.x
+    implementation 'com.oracle.database.jdbc:ojdbc8:21.12.0.0'     // Java 8-compatible Oracle JDBC
+    implementation 'org.json:json:20240303'
+    implementation 'org.apache.httpcomponents:httpclient:4.5.14'
+    implementation 'commons-codec:commons-codec:1.19.0'
+
+    testImplementation 'junit:junit:4.13.2'
+}
+
+// Optional: build a self-contained runnable (fat) JAR
+jar {
+    manifest {
+        attributes 'Main-Class': mainClassName
+    }
+    from {
+        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
+    }
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+}

tools/project-history-migrator-tool/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists