Edit

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 WorkFusion Studio 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 IA Cloud 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 the following guides:

• Eclipse IDE (WorkFusion Studio)
• IDEA IDE

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 WorkFusion Studio.
  3. Assemble a BP manually using the Bot Tasks created in WorkFusion Studio.
  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 CT instance are related to the following:

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

• Authentication to the IA Cloud instance is SSO-based, and deployment happens not on behalf of a specially created API user. For login via API user should have configured Keycloak password. See Using REST API with SSO for more details.

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

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

If both code and version will be missed, bundle will be imported, but it will not appear on the Use Cases page.

• How to check bundle import details?

In case if the import is running longer, then timeout for maven deploy job or import scripts, you may need to check bundle details manually. Or if you lost your import UUID, you can look for it in the database. If you know the UUID of import and you can execute rest API, you can check bundle status via: {{host_url}}/workfusion/api/v1/bundle-import/{uuid}

Note, that this request requires a X-CSRF-TOKEN to be provided in order to authorize. If you're unable to execute the rest API call, but you can check the database, you can look for bundle import details in the database. The main table is bundle_import, where you can find id by bundle_name and created_date. Then you can check for imported components within this bundle in table bundle_asset_import_log by bundle_import_id And you can check individual messages in bundle_asset_import_log_message table, using asset log ids.

• How to check bundle import logs in Kibana?

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, e.g. MIGRATION_DATA_STORE or BUSINESS_PROCESS, and ${BUNDLE_UUID} - is a UUID of a concrete bundle import. E.g. bundle-import-[MIGRATION_DATA_STORE]-eafd2aa7-9984-4021-a8fa-8f29be50f365

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

thread_name : "bundle-import-["

To look messages of all components within specific bundle import you could use following search:

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

If you want to change the log level, to see not only error messages, you change it with the help of this guide: Change Component Log Level

• Kibana doesn't show workfusion logs.

On dev instances, that are going to sleep at night/weekends, it's possible that some indexes in Kibana will be frozen and you wouldn't be able to observe logs for these components. They can be unfrozen in Kibana -> dev tools. Put the following query in dev tools console and execute:

POST */_unfreeze

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

Could not acquire change log lock. Currently locked by autotest1 since 9/9/21 4:41 PM

It's caused by the Liquibase lock, which wasn't released within configured timeout. Notice, that if you use maven job for import, you may not see this error, since this timeout is greater than timeout for maven import goal, so you'll need to check logs or import messages in the database in order to see this message. The reason for this error is the following: Liquibase allows only sequential applying of migrations, so it creates lock in DATABASECHANGELOGLOCK table and any migrations, that are started after processing migration should wait for this lock to be removed. But if the Liquibase import process wasn't gracefully ended, e.g. process was killed with kill -9 <PID> command, then lock would never be removed, therefore all further imports will fail with this error. It's actual for any liquibase migrations, for datastore migrations and for dashboard migrations.

It can be fixed by manual removal of lock record in DATABASECHANGELOGLOCK table. For datastore migrations check ds.DATABASECHANGELOGLOCK table and for dashboard migrations check dm.DATABASECHANGELOGLOCK table.

• An error was detected in Liquibase migration files. Possible reasons are as follows: the file structures are invalid, or the database already exists but does not match the imported definition checksum.

  In this case, you may want to drop currently existing database objects related to this Use Case with the mvn bundle:drop-data-stores command or rewrite the migrations so that they would differ from the current database state. If you want to keep an older database structure with data, which is a typical case for a production environment, consider upgrading the Use Case version. For details, refer to the Deploy Asset Bundle guide.

note

To use the mvn bundle:drop-data-stores command, the user needs to have the Erase Use Case Datastores permission, which is disabled by default for every role. To enable this permission on a development environment, go to CT > System Settings > Role Management and turn it on for your role.

The Maven goal is assumed to be used for development only, so it is not advisable to enable it for a production environment. The recommended approach for a production environment is to raise the Use Case version for every candidate for production deployment. This helps avoid collisions with Data Stores and other assets in a project.