Migrate Oracle JET Legacy Components to Core Pack Components

C Migrate Oracle JET Legacy Components to Core Pack Components

You can use the Oracle JET Core Pack migrator to migrate Oracle JET legacy components (oj-*) to their equivalent Core Pack components (oj-c-*) without breaking your app’s functionality. It also migrates Selenium WebDriver test files written for legacy components to work with the migrated Core Pack components.

The Core Pack migrator is packaged with the Oracle JET Audit Framework (Oracle JAF). To begin the Core Pack migration workflow, first download Oracle JAF and run audits on your app. Then use the information in the audit report to prepare your app’s code for migration; there are specific issues that must be manually addressed in your app because they will either cause the migration to fail or be ignored by the migrator.

Once you’ve assessed your code and prepared it for migration, you can perform a dry-run migration that generates a migrator.log file where you can review the migrator’s intended changes to your code.

You also have the option to create a migration configuration file that will tailor the behavior of the Core Pack migrator. You can run the migrator using its default settings, but you can use the migrationConfig.json file to modify its operations so that, for example, it migrates only test files or excludes certain components from migration.

When you are satisfied with your pre-migration code and the results of the dry run, you can perform the full migration.

Note:

Not all migration can be automated, and some components may need manual correction after migration in order to function. For a list of known migration issues and help resolving them, see Troubleshoot Core Pack Migration Issues.

After you successfully migrate your app’s legacy components to Core Pack, you can migrate the components in its Selenium WebDriver test files. See Migrate WebDriver Test Files to Core Pack.

For information on installing and using Oracle JAF, see Install the Oracle JET Audit Framework. You can verify what versions of Oracle JAF and the Core Pack migrator are installed by running the commands ojaf -v and ojaf -mig -v in a terminal window.

Prepare Your Oracle JET App for Core Pack

Before you use the Oracle JET Core Pack migrator on your app’s code or test files, run an Oracle JAF audit to inspect for issues that might impact migration. For example, deprecated APIs are not available in Core Pack components and will cause your migration to fail if they are present in your code.

Oracle JAF’s built-in audit rules assist you in identifying and fixing invalid functionality.

Additionally, in the Oracle JET API documentation, there is a section labeled “Migration” for each legacy component that has a Core Pack equivalent to which you can migrate. This section facilitates the migration of a given legacy component to Core Pack by providing specific guidance and information on the differences between the two component versions. See, for example, the oj-button component’s migration section. Only legacy components with an equivalent Core Pack component are eligible for migration.

Note:

If you don’t see the API documentation for superseded components on the API page, you can select the “Show Maintenance Mode” checkbox in the sidebar to reveal it.

To prepare your app for migration, install the latest version of Oracle JAF and run an audit on your code:

Open a terminal window and enter the following command to install Oracle JAF globally:

npm install -g @oracle/oraclejet-audit
After you install Oracle JAF, navigate in your terminal window to your app’s root directory, then initialize a default JAF configuration:

ojaf --init

Oracle JAF tooling scaffolds a default JAF configuration file named oraclejafconfig.json in your app’s root directory.
In your terminal window, enter the command to run an audit:

ojaf

The audit generates a report in your terminal window. Using the report, resolve any issues flagged in your code. For example, you should fix issues raised that include the word “deprecated.” Deprecated APIs are not available in Core Pack components, and your migration will fail if your components use a deprecated API.

Note:

Oracle JET Core Pack components do not support the Alta theme. If your app uses Alta, then you must migrate to Redwood before you can use these components in your app. See Oracle JET App Migration to Current Release.

After auditing your code and verifying that all issues have been resolved, you can proceed with your migration.

Migrate Legacy Components Using the Core Pack Migrator

After preparing your app for migration, perform a dry-run migration to understand the migrator’s intended changes to your code and find any issues that should be addressed before or after migration. If there are aspects of the migrator’s behavior that you would like to modify, you can create a migration configuration file that you can use to customize its operations.

Follow the steps in the migration procedure below as a guide.

Perform a dry-run migration. The dry-run migration does not update or migrate code but generates a detailed log of all code that would get migrated.

Open a terminal window in your app’s ./src directory and enter the command ojaf -mig -dr.

A message will appear once the dry run finishes, which provides information on how long the migration took and how many files and components were updated. It also points you to the migrator.log file, which was created in the app’s ./src directory and contains details on the files and components that would be affected by migration.
Review the results of the dry run in the migrator.log file and decide whether to use the migrator’s default settings or to modify its behavior using a migration configuration file.

To learn more about the migration configuration file, see Customize the Core Pack Migrator’s Behavior.

If you create or modify a migration configuration file, then you can test out the changes to the migrator in a dry run by executing the following command in a terminal window, replacing the path with the location of your own configuration file: ojaf -mig -dr -c ./migrationConfig.json
When you’re satisfied with your code and migration configuration, run the migration command from a terminal window in your app’s ./src directory.
- If you have modified the configuration file, run the following command with the configuration option pointing to the location of your configuration file:
  
  ojaf -mig -c ./migrationConfig.json
- To run the migrator with its default configuration, execute the following command:
  
  ojaf -mig

Customize the Core Pack Migrator’s Behavior

You can fine-tune how the Core Pack migrator operates by using a migration configuration file. The migrationConfig.json file supports a range of properties that allow you to configure how the Core Pack migrator behaves. For example, you can specify that the migration only affects certain components or subsets of components, rather than your entire app.

The migration configuration file contains properties that you can use to specify:

If your migration is for only WebDriver test files and what extension they use.
What folders, files, and components should be skipped during migration or, conversely, should be the only targets of migration.
Whether to force the migration of specific legacy components to Core Pack.
Whether to exclude from migration any components with tags that contain attributes with an expression as a value.
The base folder where the migration will execute.
The name and location of the migrator log file.

Any name can be provided to the migrationConfig.json file. Therefore, a user can have different sets of migration rules defined by multiple configuration files.

To begin, create the migrationConfig.json file in your chosen directory, typically in the directory from which you will run the migrator, such as your app’s ./src directory.

The following sample migrationConfig.json file displays the available configuration options that you can include.

{
  "testFiles": "",
  "testFilesExtension": "",
  "excludeFolders": [],
  "excludeFiles": [],
  "excludeComponents": ["legacyTag1", "legacyTag2"],
  "includeFiles": [],
  "includeFolders": [],
  "includeComponents": ["legacyTag1", "legacyTag2"],
  "forceMigration": ["legacyTag1", "legacyTag2"],
  "excludeAttributeExpressions": {
    "legacyTag1": ["attributes"],
    "legacyTag2": ["attributes"]
  },
  "baseMigrationDir": "",
  "logFileName": "",
  "logFilePath": ""
}

Note that all configuration settings are optional; you can choose to include only those needed for your migration.

The following table describes the available migration configuration options and how to use them.

Table C-1 Properties in the migrationConfig.json File

Property Name	Value Type	Description
`testFiles`	Boolean	Set this value to `true` if you intend to migrate only WebDriver test files and the directory you will migrate contains only test files.
`testFilesExtension`	String	Tells the migrator the specific extension it can use to locate test files.
`excludeFolders`	Array	Contains folder names that the migrator will skip. Provide the full path for each folder name.
`excludeFiles`	Array	Contains file names that the migrator will skip. Provide the full path for each file name.
`excludeComponents`	Array	Contains legacy component tags that the migrator will skip.
`includeFiles`	Array	Contains the names of the only files that the migrator will process for migration. Provide the full path for each file name.
`includeFolders`	Array	Contains the names of the only folders that the migrator will process for migration. Provide the full path for each folder name.
`includeComponents`	Array	Contains the only legacy component tags that the migrator will process for migration.
`forceMigration`	Array	Contains legacy component tags for which the `IgnoreRuleSet` will be ignored and the tags will be migrated to Core Pack.
`excludeAttributeExpressions`	Object	Contains component-specific attributes that should not be migrated if they contain an expression as a value.
`baseMigrationDir`	String	Determines the root directory that the migrator will run from. By default, the migrator runs from the calling directory if not specified. You can use a relative or absolute path.
`logFileName`	String	Determines the name of the log file generated during migration. If not specified, the name `migrator.log` will be used by default.
`logFilePath`	String	Determines the output location for the migration log file. If not specified, the calling directory will be used by default.

Migrate WebDriver Test Files to Core Pack

The Oracle JET Core Pack migrator helps you migrate your WebDriver test files written for apps with legacy components so that they work with Core Pack components.

To migrate your test files, first follow the pre-migration steps found in Prepare Your Oracle JET App for Core Pack, which include initializing an Oracle JAF configuration in your app, running audits on your test files, and resolving any issues you find.

Note:

Before running audits, make sure that your oraclejafconfig.json file is configured so that Oracle JAF can locate your test files. Include any paths to your test files within the files property as string values, such as "./src/**/*.spec.ts".

"files": [
  "./src/**/*.html",
  "./src/**/*.js",
  "./src/**/*.ts",
  "./src/**/component.json",
  "./src/css/**/*.css",
  "./src/**/*.spec.ts"
],

Once you have audited your test files and prepared them for migration, open or create your migrationConfig.json in your chosen directory, typically your app’s ./src directory, and configure it as follows.

Set the testFiles property in the migrationConfig.json file to true.
If your test files have a unique extension, such as .spec.ts or .test.ts, then add it to the migration configuration file as a string value to the testFilesExtension property.

If you do not add an extension for test files to the testFilesExtension property, then all files in a directory that will be migrated must be test files.
Review the rest of your configuration to ensure that it meets your requirements for migration. For instance, verify that the baseMigrationDir property, which affects the directory that the migrator runs from, is correct.

At a minimum, your migrationConfig.json file should resemble the following example.
```
{
  "testFiles": "true",
  "testFilesExtension": ".spec.ts"
}
```
Open a terminal window in the same directory as your migration configuration file. Execute the dry-run migration command while pointing to the configuration file:

ojaf -mig -dr -c ./migrationConfig.json
Review the results of the dry run in the migrator.log file. Once you have made any necessary changes and are satisfied with your code and configuration, run the actual migration:

ojaf -mig -c ./migrationConfig.json

When the migration is complete, try running your test files against the app that uses the Core Pack components they are meant to test. You may need to make manual corrections to get your tests to pass.

For instance, a property that is called using a function in a test file may not have been properly migrated, or perhaps your test files were properly migrated and a legacy component in your app’s code contains an attribute that is not supported in Core Pack.

Use the migration report in the migrator.log file to troubleshoot issues. To assist you, the migrator.log file has links to migration sections in the API documentation for each legacy component that has a Core Pack equivalent.

Troubleshoot Core Pack Migration Issues

Some components may need manual correction after migration. For guidance on migrating specific legacy components to their Core Pack equivalents, read their migration sections in the Oracle JET API docs, which are accessible at the end of the migrator.log file. You can also refer to the Core Pack section of the JET API docs for more information.

Here is a list of instances that require manual migration:

Formatting changes

Users will see formatting changes in files as a result of migrating. Run formatters post-migration in order to ensure files remain in the correct formats.
Deprecated APIs

Deprecated APIs are not available in Core Pack components and must be removed before migration. If a deprecated API is present in your code, then your migration will fail.
Components that switched to a data-driven approach

There are some legacy components that took children that are instead data-driven in their Core Pack equivalents. These will be ignored by the migrator and must be migrated manually. See the section on data-driven components in the Core Pack API documentation, as well as the component-specific migration section.
CSS

CSS will no longer work as expected with some components. See the section on CSS in the Core Pack API documentation, as well as the component-specific migration section.
Components where a property type has changed

If a component’s property is set, but the property type has changed, then the legacy instance can’t be migrated.

For example, on form controls, such as oj-input-text and oj-input-number, the Core Pack converter type and the legacy converter type don’t match. Therefore, if the converter property is set, then the instance won’t be migrated. When this is the case, the migrator.log file will have a variation of the following message: Rule to ignore: "oj-input-text" filtered out due to attribute "converter".
Class attributes with an expression as a value

Class migration will only happen if the value is a string, otherwise migration will not modify anything in the expression.
References to strongly typed properties

In TypeScript code, there may be cases where you want to type variables or properties based on the existing types declared by the JET components you are consuming.

An example of this is when you define a custom component and want to define a chroming property on that component that can be passed directly down to a legacy oj-button component that you use as part of that component implementation. This type of dependency must be migrated as well if you are migrating the legacy component to its Core Pack equivalent
When using the JET legacy components, you would typically use the IntrinsicProps of the component that is exported:
```
import { ButtonIntrinsicProps} from 'ojs/ojbutton';
...
const localChroming:ButtonIntrinsicProps['chroming']
```
In Core Pack components, the props type is not re-exported from the Core Pack class because there is a more generic way to access the same information using the Preact ComponentProps convenience type. Instead, the code would be migrated as follows:
```
import { ComponentProps } from 'preact';
import 'oj-c/button';
...
type ButtonProps = ComponentProps<'oj-c-button'>
...
const localChroming:ButtonProps['chroming'] = ...
```
References to strongly typed event payloads

When coding in TypeScript, you can strongly type events emitted from JET legacy components by referencing the event map for the component:
```
import 'ojs/ojbutton';
import { ojButtonEventMap } from 'ojs/ojbutton';
...
private async onChatActionClick(event: ojButtonEventMap['ojAction']){...}
```
With Core Pack components, rather than import the eventMap, you can directly reference the type from the component interface:
```
import 'oj-c/button';
import { CButtonElement } from 'oj-c/button';
...
private async onChatActionClick(event: CButtonElement.ojAction){...}
```