Migrate ODF 2 project to 10.2.5 · WorkFusion Documentation

The guide describes steps to be taken when migrating an ODF 2-based project from v10.2.4 to v10.2.5.

important

An ODF 2-based project written for v10.2.4 and older 10.2.x versions is still fully compatible with IA Cloud Enterprise v10.2.5. But if you want to use the new features of IA Cloud Enterprise v10.2.5, the migration to the ODF 2 framework of v10.2.5 is required.

note

The guide utilizes an example project created from the ODF 2 Full archetype of the release v10.2.4. Starting from v10.2.5, the same project is referenced as the ODF 2 Example Project.

important

We strongly encourage users to get acquainted with the following new Platform v10.2.5 features. Although these features are not the main concern of this guide, they may significantly change the design of some Business Processes.

Migrate ODF 2 project

To migrate an ODF 2-based project from v10.2.4 to v10.2.5, do the following:

Open the root pom.xml of your project and in the <properties> section, find the <odf2.version> property.

Update the ODF 2 version according to the Compatibility matrix. Also, update the <bundle-versions-maven-plugin.version> and <bundle-maven-plugin.version> properties for Bundle version Maven plugin and Bundle Maven plugin accordingly.
```
<properties>
    <odf2.version>10.2.5.26</odf2.version>
    <bundle-versions-maven-plugin.version>0.0.20</bundle-versions-maven-plugin.version>
    <bundle-maven-plugin.version>10.2.5.19</bundle-maven-plugin.version>
</properties> 
```
Build the project with the mvn clean verify command and make sure there are no compilation errors, and all unit tests of your project have passed successfully.

The v10.2.5 release of ODF 2 introduces a few backward-incompatible changes on the code level. These minor changes mainly affect classes that, by default, are controlled by the framework. If you see a compilation error after upgrading the ODF 2 version, use the list of changes below and fix it accordingly.

Backward-incompatible code changes

The following repositories now require the Variation object to be provided during construction. The Variation object is available inside Feather context as part of the core WebHarvestIntegrationModule module.

Repository name	Before 10.2.5	10.2.5
ConfigRepository	`ConfigRepository(ConnectionSource connectionSource)`	`ConfigRepository(ConnectionSource connectionSource, Variation variation)`
TransactionRepository	`TransactionRepository(ConnectionSource connectionSource, TransactionBuilder transactionBuilder)`	`TransactionRepository(ConnectionSource connectionSource, TransactionBuilder transactionBuilder, Variation variation)`
MonitorConfigurationRepository	`MonitorConfigurationRepository(ConnectionSource connectionSource)`	`MonitorConfigurationRepository(ConnectionSource connectionSource, Variation variation)`
MonitorStateRepository	`MonitorStateRepository(ConnectionSource connectionSource, OdfTime odfTime)`	`MonitorStateRepository(ConnectionSource connectionSource, OdfTime odfTime, Variation variation)`

ErrorRepository now inherits from TransactionalEntityRepository, which effectively leads to one of the method's signature change from List<ErrorEntity> findAll(UUID transactionId) to List<ErrorEntity> findByTransactionId(UUID transactionId).
The TransactionRepository getTransactionRepository(UUID businessProcessId) method was removed from the OrmSupport interface. Instead, more sophisticated TransactionRepositoryBuilder together with TransactionRepositoryBuilder getTransactionRepositoryBuilder() method was added:

TransactionRepository repository = ormSupport.getTransactionRepositoryBuilder()
    .withBusinessProcessId(expectedBpId)
    .build();

At this stage, if you try to import the built bundle into IA Cloud Enterprise and start any of the project's Business Processes, most likely, you will encounter the "Invalid column name 'variation_id'" error:

org.webharvest.exception.ScriptException:
Config line 6: script block
com.workfusion.odf2.core.OdfFrameworkException: Exception was thrown inside ODF task 'com.example.task.intake.EmailMonitorTask': com.microsoft.sqlserver.jdbc.SQLServerException: Invalid column name 'variation_id'.

The error appears due to backward-incompatible changes introduced in v10.2.5 to the core data model of the ODF 2 framework.

To properly support Digital Worker configuration variations feature, ODF 2 introduced new abstract data model entity called OdfVariationEntity:

public abstract class OdfVariationEntity extends OdfEntity {

    public static final String VARIATION_ID_COLUMN = "variation_id";

    @DatabaseField(columnName = VARIATION_ID_COLUMN)
    private Long variationId;

    public Long getVariationId() {
        return variationId;
    }

    public void setVariationId(Long variationId) {
        this.variationId = variationId;
    }

}

Starting from the v10.2.5 release, the following entities directly inherit from the OdfVariationEntity:

Transaction
ConfigEntity
MonitorConfigurationEntity
MonitorStateEntity

All existing Data Store schemas respective to entities above must be changed to have a new variation_id column. For that:

Add variation_id column to the uc_[code]_transaction_[version], uc_[code]_config_[version], uc_[code]_monitor_configuration_[version], and uc_[code]_monitor_[version] tables. If one of these tables is not used in your project, skip it.

For example, if you do not work with monitors and don't have monitors-related tables in your migration script, only transaction and config tables should be adapted.

To add the variation_id column, navigate to the tables.xml file at [package_module]/src/main/resources/datastore/migrations/versioned/tables.xml, and for each required table, add the following statement:
```
<addColumn tableName="our_awesome_table">
    <column name="variation_id" type="BIGINT"/>
</addColumn>
```
It's recommended to keep this modification as a separate Liquibase changeset. In our example, the required changeset looks as follows:
```
<changeSet author="user" id="odf2_v1_0_0014">
    <addColumn tableName="uc_odf2_transaction_v1_0">
        <column name="variation_id" type="BIGINT"/>
    </addColumn>
    <addColumn tableName="uc_odf2_config_v1_0">
        <column name="variation_id" type="BIGINT"/>
    </addColumn>
    <addColumn tableName="uc_odf2_monitor_v1_0">
        <column name="variation_id" type="BIGINT"/>
    </addColumn>
    <addColumn tableName="uc_odf2_monitor_configuration_v1_0">
        <column name="variation_id" type="BIGINT"/>
    </addColumn>
</changeSet>
```
note
- When working with Liquibase migrations, mind that each table name contains the Digital Worker code and version. Remember to fill these values properly.
- Each new changeSet require the ID attribute, mind the identifiers requirements.
Build the project with the mvn clean verify command to produce a new bundle with updated migrations.

Configure Digital Worker

The Digital Worker configuration is a set of parameters that can change over time, depending on the environment or client. Starting from IA Cloud Enterprise v10.2.5, Control Tower stores and manages the configuration. ODF 2 provides tools to access this configuration.

Usually, Digital Worker configuration is accessed by injecting com.workfusion.odf2.core.settings.Configuration object into a Bot Task:

@Inject
public AwesomeBotTask(Configuration configuration) { ... }

Starting from v10.2.5 release, when injecting com.workfusion.odf2.core.settings.Configuration interface, the ODF 2 framework provides com.workfusion.odf2.core.settings.CombinedConfiguration implementation by default. This implementation looks for configuration items in a Configuration Data JSON object and if nothing is found, in a configuration Data Store. We recommend using it when compatibility with a legacy configuration is required. Note that the implementation requires configuration Data Store. Otherwise, SQLException is thrown by the framework.

If compatibility with a legacy configuration is not required, you can inject the com.workfusion.odf2.core.settings.JsonBasedConfiguration service.

@Inject
public AwesomeBotTask(JsonBasedConfiguration configuration) { ... }

This implementation uses a JSON-based configuration only (no configuration Data Store is required), and on top of the methods defined in com.workfusion.odf2.core.settings.Configuration, offers several new ones:

<T> Optional<T> getProperty(String name, Class<T> valueClass);

<T> T getRequiredProperty(String name, Class<T> valueClass);

<T> List<T> getArrayProperty(String name, Class<T> valueClass);

These methods take advantage of features offered by storing settings in the Configuration Data JSON object. New getProperty and getRequiredProperty methods try to deserialize a value of the configuration property as an object of the provided class. getArrayProperty does the same for the properties of an array type.

Follow the Digital Worker configuration guide for more detailed information.

Configuration migration from v10.2.4

The IA Cloud Enterprise v10.2.4 introduced a beta version of a Digital Worker configuration. It allows to create a configuration form layout in form.io, bind input controls of a configuration form to Data Store cells, and package it to an Asset Bundle of a Digital Worker. The platform is responsible for importing the configuration form layout, rendering the form according to the layout, and updating bound Data Store entries related to the submitted data.

The main difference between v10.2.4 and v10.2.5 is that instead of a JSON-based configuration provided in a Bot Task context, in the v10.2.4 release, the platform works with a configuration Data Store directly and, therefore, no JSON-based configuration is provided.

note

For more information on a Digital Worker configuration in IA Cloud Enterprise v10.2.4, refer to the Configuration UI guide.

If you have already employed a Digital Worker configuration as of the v10.2.4 release, choose between two options to migrate to v10.2.5:

If you bound a configuration form to the config Data Store and used the com.workfusion.odf2.core.settings.Configuration interface to read values from the Data Store, no additional actions are needed regarding the configuration migration.
In all other cases (for example, if you used a Data Store that differs from the config Data Store), adapt your code to work with the com.workfusion.odf2.core.settings.Configuration or com.workfusion.odf2.core.settings.JsonBasedConfiguration interface. This way you ensure that data coming from the UI form are properly read by the ODF 2 framework.

For example, you have a custom configuration Data Store and the related MyConfigRepository ORM repository. Reading the value in this case usually looks as in the listing below:

@BotTask
public class CustomBotTask implements AdHocTask {

    private final MyConfigRepository configRepository;

    @Inject
    public CustomBotTask(MyConfigRepository configRepository) {
        this.configRepository = configRepository;
    }

    @Override
    public TaskRunnerOutput run(TaskInput taskInput) {

        Optional<ConfigEntity> configEntry = configRepository.findByName("key");
        if (configEntry.isPresent()) {
            String value = configEntry.get().getValue();
        }
        
        return taskInput.asResult();
    }

}

Instead of custom MyConfigRepository, you will use the com.workfusion.odf2.core.settings.Configuration interface to let the ODF 2 framework deal with configuration reading under the hood.

@BotTask
public class CustomBotTask implements AdHocTask {

    private final Configuration configuration;

    @Inject
    public CustomBotTask(Configuration configuration) {
        this.configuration = configuration;
    }

    @Override
    public TaskRunnerOutput run(TaskInput taskInput) {

        Optional<String> property = configuration.getProperty("key");
        if (property.isPresent()) {
            String value = property.get();
        }

        return taskInput.asResult();
    }

}

Configuration migration from version prior to v10.2.4

IA Cloud Enterprise prior to v10.2.4 does not provide a UI-based configuration solution, and all configuration data are stored on the Data Store level. For such projects, it is recommended to keep a Data Store-based configuration as is. Although you won't be able to benefit from the UI-based configuration, no additional changes are required to your project.

If you want to use a new UI-based configuration feature, create a proper Digital Worker configuration and most likely re-write the configuration related logic in your codebase to make use of the com.workfusion.odf2.core.settings.Configuration or com.workfusion.odf2.core.settings.JsonBasedConfiguration interface on the ODF 2 level.