# Switch to insureMO

This guide outlines the process for upgrading App Framework-based services to version 25.03 and migrating them to insureMO.

<div class="docs-note"><span class="docs-admonitions-text">note</span>
The App Framework described in this document is designed exclusively for the specific application referenced. It is not intended for developing new tenant applications, nor is it recommended for use or modification in other projects. Please ensure the framework is used strictly for its intended purpose.
</div>

## Overview

In Vela App Framework 25.03, all artifacts have been transitioned to insureMO. This transition includes changes to:

- Maven artifact `groupId` and `artifactId`
- Java package structure and class names

To upgrade your Vela dependency to version 25.03, you must update your BFF service by following the migration steps below.

## Migration Steps

The migration process involves two main phases:

1. **Automated Code Replacement**: Before upgrading the Vela version, utilize the provided Maven plugin to automatically update artifact names, package declarations, and class references throughout your codebase.
2. **Version Upgrade**: Once the code replacement is complete, update the Vela dependency version in your `pom.xml`.

### Step 1: Execute Automated Code Replacement

First, configure the `code-replacer-maven-plugin` in the `<build>` section of your project's `pom.xml`:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>com.insuremo.tools</groupId>
            <artifactId>code-replacer-maven-plugin</artifactId>
            <version>1.1.4</version> <!-- Use the latest version available -->
            <configuration>
                <!-- Optional: Specify a custom rule: min or default -->
                <!-- default: replace all, min: only vela -->
               <!-- <ruleNames>min</ruleNames> -->
            </configuration>
        </plugin>
    </plugins>
</build>
```

#### Plugin Goals

The plugin provides the following goals:

1. `code-replacer:dryRun`
    - **Description**: Simulates the replacement process without modifying any files. It generates a comprehensive report of all pending modifications. **We strongly recommend running this goal before applying actual changes.**
    - **Usage**:

        ```bash
        mvn com.insuremo.tools:code-replacer-maven-plugin:dryRun
        ```

2. `code-replacer:replace`
    - **Description**: Applies the replacement rules and modifies the project files directly.
    - **Usage**:

        ```bash
        mvn com.insuremo.tools:code-replacer-maven-plugin:replace
        ```

To proceed with the migration, execute the `replace` goal.

### Step 2: Upgrade Vela Version

After successfully running the replacement plugin, update the Vela version to `25.03.xxx` in your `pom.xml`. Refer to the [Platform SDK](https://docs.insuremo.com/common/doc_00000047) documentation for detailed dependency information.

<div class="docs-caution"><span class="docs-admonitions-text">caution</span> Important Note
If you are upgrading from a version earlier than `25.02.xxx` (which utilizes JDK 11 and Spring Boot 2), you must also follow the [Spring Boot 3.x Migration Guide](https://docs.insuremo.com/common/doc_00000008) to ensure your BFF service is fully compatible with Spring Boot 3.
</div>

<div class="docs-note"><span class="docs-admonitions-text">note</span>
If your service's Maven parent is defined as `insuremo-maven-parent-ext`, please upgrade it to the following version:

```xml
<parent>
    <groupId>com.insuremo.appframework</groupId>
    <artifactId>insuremo-maven-parent-ext</artifactId>
    <version>2.0.14</version>
</parent>
```

</div>

## Special Considerations

If your service shares a database schema or a RabbitMQ virtual host with other services, you must configure the following properties in the service upgrading to `25.03.xxx` to maintain compatibility:

```properties
mq.custom-id.class.transform.enable=true
json.custom-id.class.transform.enable=true
```

## Security & Library Adjustments

For security and compatibility reasons, the following library changes have been implemented. You may need to manually adjust your code if the automated tool misses these references:

### CGLIB Replacement

The standalone `cglib` library has been replaced by Spring's internal version.

- **Search for**: `net.sf.cglib`
- **Replace with**: `org.springframework.cglib`

### Apache Commons Lang Upgrade

The older `commons-lang` library has been upgraded to version 3.

- **Search for**: `org.apache.commons.lang.`
- **Replace with**: `org.apache.commons.lang3.`

### StringEscapeUtils Transition

`StringEscapeUtils` functionality has been moved or updated.

- **Migration Destination**: `apache commons text`
- **Method Replacements**:
  - `StringEscapeUtils.escapeHtml` → `StringEscapeUtils.escapeHtml4`
  - `StringEscapeUtils.escapeXml` → `StringEscapeUtils.escapeXml11`
  - `StringEscapeUtils.escapeJavaScript` → `StringEscapeUtils.escapeEcmaScript`
  - `StringEscapeUtils.unescapeJavaScript` → `StringEscapeUtils.unescapeEcmaScript`

#### Important: SQL Escaping

There is no direct alternative for `StringEscapeUtils.escapeSql` in the new library, as it is generally insecure, and using `PreparedStatement` is the recommended safe practice.