Skip to main content
Version: 10.2.9

Publish Asset Bundle with Maven

Developer approach to publishing​

Observing the everyday activities of an Automation Engineer reveals a few facts:

  • Developed Business Processes (BPs) are re-published about 20 times a day.
  • An essential requirement is the possibility to invoke a published BP within CI tools.

It means that packing, building, and deploying an Asset Bundle should require minimal effort and time. Ideally, it should be automated. Automation also works well for CI cases.

Publish Asset Bundle with Maven​

ODF includes workfusion-maven-plugin (bundle-maven-plugin for 10.1.0+). BP developers can use the tool to automate packing Asset Bundles and building RESTful POST requests to deploy the bundles to CT.

The Maven plugin is preconfigured in the pom.xml file of the bundle module in the archetype-generated project as shown below:

<!-- To import bundle to Control Tower execute "mvn bundle:import" -->
<plugin>
    <groupId>com.workfusion.odf</groupId>
    <artifactId>bundle-maven-plugin</artifactId>
    <version>10.1.0.0</version>
    <configuration>
        <server>
            <id>control-tower</id>
            <url>${workfusion.environment.url}</url>
        </server>
        <bundle>target/${project.build.finalName}.zip</bundle>
    </configuration>
</plugin>

Configure access to Control Tower​

Before publishing Asset Bundles with the plugin, configure CT. For that, in your project generated with ODF archetypes, perform the following actions:

  1. Specify the Control Tower URL where Asset Bundles are to be published. For that, modify the project's root pom.xml:

    <workfusion.environment.url>https://lux-ct1.workfusion.com</workfusion.environment.url>

    You can also configure the URL when you start a project from an Archetype in the Eclipse wizard.

  2. To specify the CT user credentials, modify [~USER_HOME]/.m2/settings.xml as shown below. Mind that the role set up for the user must have the Export/Import and Advanced Package Import permissions in CT. For details, refer to the Role management section.

    <!-- Credentials for Bundle Import API -->  
    <server>
        <id>control-tower</id>
        <username>importapi</username>
        <password>notastandardpassword!1</password>
    </server>
note

The id value in settings.xml must be the same as the id value of the workfusion-maven-plugin (bundle-maven-plugin in 10.1+) server configuration in pom.xml of the [ARTIFACT]-package module.

Deploy Asset Bundle to local Control Tower​

workfusion-maven-plugin (bundle-maven-plugin for 10.1.0+) features a Maven goal enabling to publish an Asset Bundle to CT. Execute the goal from the [ARTIFACT]-package module of your project.

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

  1. Open the Work.AI Developer's Launcher and start the Control Tower & Workspace group. Wait for the start indicator to light up. This is essential to ensure Control Tower (CT) is launched since the service accepting and processing imported Asset Bundles starts with Control Tower.

  2. Run mvn clean install to create a bundle packed as a zip archive in the [ARTIFACT]-package/target directory.

  3. Depending on which bundle import strategy you apply, use one of the following commands:

    • For the default REPLACE strategy, run mvn bundle:import for pom.xml located in the [ARTIFACT]-package module.

    In this case, if a file from the Asset Bundle is found on a target environment by a key attribute (for example, name), the file is overwritten. Instead, the target environment uses the imported one.

    • For the SKIP_DATASTORES strategy, run mvn bundle:import -DimportStrategy=SKIP_DATASTORES from the bundle module.

    The strategy behaves similarly to the REPLACE strategy for all files in an Asset Bundle, but for Data Stores and Training sets. If a Data Store or a Training Set from the Asset Bundle is found on a target environment by a key attribute (for example, name), the file is skipped during import. The target environment continues to use already existing files. Other files in the same Asset Bundle are imported in accordance with the REPLACE strategy.

caution

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

Deploy Asset Bundle to server Control Tower​

For instructions, refer to Deploy Asset Bundle.

Validate publishing results​

Always read the JSON response component-by-component to make sure all statuses are OK. Then, use one of the options below to validate that an Asset Bundle was published successfully to CT.

  • Check that Import API did put BCB JAR into the target CT's Nexus. The BCB JAR is expected to appear in the wf-machine-config-bundle repository.
  • Validate re-publishing of a Business Process (BP) package:
    1. Build a package containing a BCB and publish it to Control Tower for the first time.
    2. Get bots created in Control Tower using Eclipse.
    3. Assemble a BP manually using the Bot Tasks created in Eclipse.
    4. Download the BP packaged as a zip file to your workstation.
    5. Copy the BP zip package into the [ARTIFACT]-package/src/main/resources/business-process directory.
    6. Make changes to Bot Tasks (XML) and Java classes.
    7. Build a package containing the BCB and publish it to Control Tower for the second time.
    8. Check CT's Nexus. The BCB JAR must be re-deployed—that means, have a new timestamp.
    9. Go to Control Tower and check your Business Process. The Bot Tasks associated with the updated Java code must be updated automatically.

Troubleshooting​

Typical issues encountered when importing an Asset Bundle to a Control Tower instance are as follows:

  • The user account on which the import is happening lacks Import/Export and Advanced Package Import permissions.

  • The authentication to the Work.AI instance is SSO-based, and deployment happens not on behalf of a specially created API user. For more details, refer to Use REST API with SSO.

  • No AI Agent code is found in the package metadata. Typically, this happens when a project was started in 10.1.x or older platform versions. Both AI Agent code and version, or none of them, should be presented in the pom.xml file in the root directory of your project.

If you see the error related to the missed code or version, open the pom.xml file in the root directory of your project and check if both <usecase.code> and <usecase.version> tags are present. If one of them is missed, add the missed tag and rebuild your project. If the previous solution didn't help, add the missed value in the meta-info.json file inside the AI Agent bundle.

If both code and version are missed, the bundle is imported, but it does not appear on the Digital Workers page.

Check bundle import details​

If the import runs longer than the timeout for a Maven deploy job or import scripts, check the bundle details manually. If you lost your import UUID, look for it in the database. If you know the import UUID and can execute the rest API, check the bundle status via {{host_url}}/workfusion/api/v1/bundle-import/{uuid}. This request requires an X-CSRF-TOKEN to authorize.

If you're unable to execute the rest API call, but you can check the database, look for the bundle import details in the database. The main table is bundle_import, where you can find an ID by bundle_name and created_date. Then you can check for imported components within this bundle in the bundle_asset_import_log table by bundle_import_id. Check individual messages in the bundle_asset_import_log_message table using asset log IDs.

Check bundle import logs in Kibana​

To check import logs, go to Control Tower > Platform Monitor.

Bundle import threads have the following naming pattern: bundle-import-[${COMPONENT_NAME}]-${BUNDLE_UUID}, where:

  • ${COMPONENT_NAME} is a name of a specific component from the bundle, for example, MIGRATION_DATA_STORE or BUSINESS_PROCESS.
  • ${BUNDLE_UUID} is a UUID of a concrete bundle import. See bundle-import-[MIGRATION_DATA_STORE]-eafd2aa7-9984-4021-a8fa-8f29be50f365 as an example.

To look for all bundle import messages, use the following search:

thread_name : "bundle-import-["

To look for messages of all components within a specific bundle import, use the following search:

thread_name : "bundle-import-[" and thread_name :"${BUNDLE_UUID}"

To change the log level to see not only error messages, refer to Change component's log level.

Kibana doesn't show WorkFusion logs​

On dev instances going to sleep at night or on weekends, it is possible to freeze some indexes in Kibana for you not to observe logs for these components. To unfreeze, do as follows:

  1. Go to Kibana > Dev Tools.

  2. Put the following query in the Dev Tools console and execute the POST */_unfreeze command:

Import is failed with a message like: Problems during Liquibase migration apply occurred​

The exception is Could not acquire change log lock. Currently locked by autotest1 since 9/9/21 4:41 PM. The cause is the Liquibase lock that is not released within the configured timeout.

note

If you use a Maven job for import, you may not see this error since the timeout is greater than the timeout for the Maven import goal. To see this message, check logs or import messages in the database.

The reason for the error is as follows. Liquibase allows only sequential applying of migrations, so it creates a lock in the DATABASECHANGELOGLOCK table. Any migrations started after the processing migration should wait for the lock to be removed. If the Liquibase import process didn't end gracefully, for example, the process is killed with the kill -9 <PID> command, the lock will never be removed. Therefore, all further imports fail with this error. It's actual for any Liquibase migrations, Data Store migrations, and dashboard migrations.

To fix the issue, manually remove the lock record in the DATABASECHANGELOGLOCK table. For Data Store migrations, check the ds.DATABASECHANGELOGLOCK table, and for dashboard migrations—the dm.DATABASECHANGELOGLOCK table.

Error detected in Liquibase migration files​

The possible reasons are as follows:

  • The file structures are invalid.
  • The database already exists but does not match the imported definition checksum.

In this case, drop current database objects related to the AI Agent with the mvn bundle:drop-data-stores command or rewrite the migrations to differ from the current database state. To keep an older database structure with data, which is typical for the production environment, consider upgrading the AI Agent version. For details, refer to the Deploy Asset Bundle guide.

To use the mvn bundle:drop-data-stores command, you should have the Erase Use Case Datastores permission disabled for every role by default. To enable the permission on the development environment, go to Control Tower > System Settings > Role Management and turn it on for your role.

The Maven goal should be used for development purposes only, so enable it for the production environment. The recommended approach for the production environment is to raise the AI Agent version for every candidate for the production deployment. This helps avoid collisions with Data Stores and other assets in your project.