Skip to main content
Version: 10.3.2

Use Maven plugins

To facilitate the interaction with a Control Tower instance, a set of Maven plugins support the ODF 2 framework. The page describes working with these plugins.

Bundle Maven plugin​

bundle-maven-plugin is a Maven plugin used to do the following:

  • Import an Asset Bundle to a Control Tower.
  • Download a trained model and an artifact from Control Tower into the project structure.
  • Drop all AI Agent Data Stores from Control Tower along with all records about these Data Store migrations.

The plugin is preconfigured in the pom.xml file of the package module in the Archetype-generated project, as shown below:

<plugin>
    <groupId>com.workfusion.odf</groupId>
    <artifactId>bundle-maven-plugin</artifactId>
    <version>${bundle-maven-plugin.version}</version>
    <configuration>
        <server>
            <id>${workfusion.server.id}</id>
            <url>${workfusion.environment.url}</url>
        </server>
        <metaInfoFile>src/main/resources/meta-info.json</metaInfoFile>
        <bundle>target/${project.build.finalName}.zip</bundle>
    </configuration>
</plugin>

Before working with the plugin, make sure you configured the Control Tower instance correctly. For that, perform the following actions in your project generated from an ODF 2 Archetype:

  1. Specify the required Control Tower URL. For that, modify the project's root pom.xml:

    <workfusion.environment.url>https://instance.workfusion.com</workfusion.environment.url>

  2. If you create a project from an Archetype, configure the URL by using the control-tower-url parameter:

    -Dcontrol-tower-url=https://instance.workfusion.com

  3. To specify the Control Tower user credentials, modify [USER_HOME]/.m2/settings.xml as shown below. The role set up for the user must have the Export/Import and Advanced Package Import permissions in Control Tower. For details, refer to the Manage Control Tower roles and permissions article.

    <server>
        <id>remote-control-tower</id>
        <username>importapi</username>
        <password>notastandardpassword!1</password>
    </server>
note

The server’s id value in settings.xml must be the same as the id value of the bundle-maven-plugin server configuration in pom.xml of the [ARTIFACT]-package module.

Import Asset Bundle​

bundle-maven-plugin features a Maven goal that enables publishing an Asset Bundle to Control Tower. Execute the goal from the [ARTIFACT]-package module of your project.

To deploy an Asset Bundle to a local Control Tower, follow the instruction below:

  1. Open Work.AI Developer's Launcher and start the Control Tower group. Wait for the indicator to light up to ensure Control Tower has launched since the service accepting and processing imported Asset Bundles starts with Control Tower.
  2. Run the mvn clean package command on the project's root pom.xml file. The command creates a Bundle packed as a zip archive inside the [ARTIFACT]-package/target directory.
  3. Run the mvn bundle:import command for pom.xml located in the [ARTIFACT]-package module.
caution

Executing the mvn bundle:import command for the main pom.xml file in the root directory leads to the following code error: "No plugin found for prefix 'bundle' in the current project and the plugin groups".

To deploy an Asset Bundle to a remote Control Tower, follow the instruction below:

  1. Run the mvn clean package command on the project's root pom.xml file. The command creates a bundle packed as a zip archive inside the [ARTIFACT]-package/target directory.
  2. Run the mvn bundle:import -Premote command for pom.xml located in the [ARTIFACT]-package module.

Importing a bundle to a remote Control Tower server basically requires the same steps as importing to a local server. The only thing that changed is that you specify the remote profile. Initially, profiles are set up in the root pom.xml file generated from the ODF 2 Archetype. A local profile is activated by default:

<profiles>
    <profile>
        <id>local</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <workfusion.server.id>control-tower</workfusion.server.id>
            <workfusion.environment.url>http://localhost:15280</workfusion.environment.url>
        </properties>
    </profile>
    <profile>
        <id>remote</id>
        <activation>
            <activeByDefault>false</activeByDefault>
        </activation>
        <properties>
            <workfusion.server.id>remote-control-tower</workfusion.server.id>
            <workfusion.environment.url>https://instance.workfusion.com</workfusion.environment.url>
        </properties>
    </profile>
</profiles>

Download trained model​

As local machine's resources sometimes are not enough to perform the AutoML model training, it is recommended to use the remote environment cluster resources. As a result, a trained model appears in the remote environment. Let's take a look at how you can download the trained model to the local environment.

<plugin>
    <groupId>com.workfusion.odf</groupId>
    <artifactId>bundle-maven-plugin</artifactId>
    <version>${bundle-maven-plugin.version}</version>
    <configuration>
        <server>
            <id>${workfusion.server.id}</id>
            <url>${workfusion.environment.url}</url>
        </server>
        
        <!-- Optional parameters -->
        <downloadPath>target</downloadPath>
        <extractionPath>src/main/resources</extractionPath>
        <maxWaitingTime>10</maxWaitingTime>
    </configuration>
</plugin>

Your configuration should match the one provided above. Mind several optional parameters to omit or add depending on the situation:

  • downloadPath: the path where the package with the model and the artifact should be downloaded (by default, target).
  • extractionPath: the path where the downloaded model and the artifact should be extracted (by default, src/main/resources).
  • maxWaitingTime: the maximum wait time (in minutes) of the Control Tower export process.

Given the prerequisites above, you can run a Maven goal to pull the trained model to the [ARTIFACT]-package module of your project:

mvn bundle:pull-model -Dmodel=trained_model_name

After that, the automl/model/[trained_model_name] and automl/artifact/[hyper_model_name]/[hyper_model_version] sub-folders are created in the src/main/resources folder of the [ARTIFACT]-package module of your project.

  • automl/model/[trained_model_name] contains data corresponding to the trained model.
  • automl/artifact/[model_name]/[hyper_model_version] contains the hypermodel that was trained.

Drop all AI Agent Data Stores​

If the development environment is under your complete control and there is no problem deleting AI Agent data, you can erase the entire Data Model.

The bundle:drop-data-stores goal drops all AI Agent Data Stores from Control Tower along with all records about the Data Store migrations. After that, you can reimport the Asset Bundle with new changesets.

<plugin>
    <groupId>com.workfusion.odf</groupId>
    <artifactId>bundle-maven-plugin</artifactId>
    <version>${bundle-maven-plugin.version}</version>
    <configuration>
        <server>
            <id>${workfusion.server.id}</id>
            <url>${workfusion.environment.url}</url>
        </server>

        <useCaseCode>${usecase.code}</useCaseCode>
        <useCaseVersion>${usecase.version}</useCaseVersion>
    </configuration>
</plugin>

If you create the project from the ODF 2 Archetype, it already contains the usecase.code and usecase.version variables inside the root pom.xml file. Otherwise, define these variables manually.

  • useCaseCode: AI Agent code from where you want to remove Data Stores.
  • useCaseVersion: AI Agent version from where you want to remove Data Stores.

Given the prerequisites above, you can run a Maven goal to drop all AI Agent Data Stores:

mvn bundle:drop-data-stores

In the case of a successful run, there is no Data Model in the environment. Thus, you won't need to create a new changeset with another identifier. Update your existing changeset instead.

Alternatively, if you want to delete a Data Model other than the one specified in meta-info.json of your project, set parameters explicitly via the command-line arguments, for example:

mvn bundle:drop-data-stores -DuseCaseCode=CODE -DdataModelVersion=1.0.0

The command erases the Data Model for the AI Agent with the CODE code and Data Model version 1.0.0.

If the Data Model is not explicitly set for your AI Agent, it is the same as the AI Agent version. Therefore, you can use this version as well:

mvn bundle:drop-data-stores -DuseCaseCode=CODE -DuseCaseVersion=1.0.0

Mind that the command considers this version as dataModelVersion anyway.

Deletion can fail if there is a relationship between a Control Tower entity, for example, a Manual Task, and the Data Store you need to delete.

  1. After you run the Maven goal, see the details about the connected entity in the console.
  2. Find the object that prevents deleting and delete it manually in the environment.
  3. Repeat the deletion.

Migration templates​

Starting from version 10.2.8, the bundle-maven-plugin offers the capability to apply migration templates to a DW project.

The default setup of the plugin for applying migration templates is as follows:

<plugin>
    <groupId>com.workfusion.odf</groupId>
    <artifactId>bundle-maven-plugin</artifactId>
    <configuration>
        <server>
            <id>${workfusion.server.id}</id>
            <url>${workfusion.environment.url}</url>
        </server>
        <metaInfoFile>src/main/resources/meta-info.json</metaInfoFile>
        <bundle>target/${project.build.finalName}.zip</bundle>
    </configuration>
    <executions>
        <execution>
            <id>apply-migrations</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>apply-migration-templates</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Take note of the execution section with id set to apply-migrations. This part specifies that the apply-migration-templates goal will run during the prepare-package Maven phase. Essentially, this indicates that the migration templates are applied to a DW project prior to packaging it into a bundle. Depending on your requirements, you have the flexibility to enable or disable this feature or add the configuration within the profile section of your pom.xml file.

Bundle Versions Maven plugin​

bundle-versions-maven-plugin is a Maven plugin primarily intended to allow AI Agent developers to update versions of different Asset Bundle resources automatically. See AI Agent versioning to learn more about the plugin.