9.2

Edit

Set up WorkFusion repository

WorkFusion Repository is a feature that allows developers to package Bot tasks in WorkFusion Studio and publish them to a repository in the WorkFusion instance for inclusion in Business Processes. These artifacts contain everything that's needed to run a Bot task, including Java and Groovy classes, input data, Data Stores, and any required settings.

Repository usage demo

Bot Config Bundle (BCB)

Bot Config Bundle is a bundled Java library containing bot config and the Java code used in this config.

Deployment options

This article describes how to automatically build and deploy Bot Config Bundle (BCB) project from local WorkFusion Studio to remote server-based Control Tower.

Configure Maven and kickstart archetype

Maven is used to build projects for publishing, so first you need to set some preferences for Maven archetypes and provide their URLs. Archetypes define a special WorkFusion project structure which can be compiled into a Java archive, uploaded to a Nexus repository and automatically published into WorkFusion instance, ready for integration testing and production usage.

  1. Open WorkFusion Studio.
  2. Go to Window > Preferences > Maven > Archetypes.
  3. Add a remote catalog by clicking the Add Remote Catalog button:

Use following Remote Archetype Catalog settings for training:

On-premises installation configuration

If there is no Internet access, edit the Maven settings.xml file. It is located in the %user home%/.m2 folder (for example, if your username is User, the path will be: C:\Users\User.m2) and should look as follows:

``` bash
<mirrors>
    <mirror>
        <id>local-nexus</id>
        <name>Local Nexus</name>
        <url>http://{host}:{port}/nexus/service/local/repositories/{repository}/content</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
</mirrors>
```

Where {repository} stands for the repository name with Maven dependencies required for goals execution.

  1. To resolve Bot Config Bundle (BCB) dependencies during training, you can use Nexus from WATT training instance. To point your Maven to it, edit the settings.xml file. It is located in the %user home%/.m2 folder (for example, if your username is User, the path will be: C:\Users\User.m2) and should look as follows:

    ``` xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  
    <servers>
        <server>
            <id>mcb-repo</id>
            <username>bcbdeploy</username>
            <password>********</password>
        </server>
    </servers>

    <profiles>
        <profile>
            <id>wf-repo</id>
            <repositories>
                <repository>
                    <id>mcb-repo</id>             
                    <url>https://watt-db1.workfusion.com/nexus/content/repositories/local-mcb-repo/</url>
                </repository> 
            </repositories>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>wf-repo</activeProfile>
    </activeProfiles>
       
</settings>
```

  2. Click the Verify button to test connection and the repository contents

  3. Finally, click Apply and OK

On-premise configuration

Maven repository configuration

To proceed, you should add Maven dependencies. It can be done in 2 ways:

  1. Using the settings.xml file:

    1. Add a new or edit an existing profile.
    2. Add a new repository to it.
    3. Activate the new repository (by default or during the mvn invocation).
    <settings>
    ...
    <profiles>
        <profile>
            <id>profile-id</id>
            <repositories>
                <repository>
                    <id>repo-id</id>
                    <url>https://{host}:{port}/nexus/content/repositories/repo/</url>
                </repository>
            </repositories>         
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>profile-id</activeProfile>
    </activeProfiles>
    ...
</settings>

  2. Using pom.xml.

    1. Edit pom.xml inside the project you've created.
    2. Add a new repository to it.
    <project>
    ...
    <repositories>
        <repository>
            <id>repo-id</id>
            <url>https://{host}:{port}/nexus/content/repositories/repo/</url>
        </repository>
    </repositories>
    ...
</project>

Let's say, we configure the following repository:

https://watt-db1.workfusion.com/nexus/service/local/repositories/wf-machine-config-bundle/content/

The configuration for this repository is:

<project>
    ...
    <repositories>
        <repository>
            <id>watt</id>
            <url>https://watt-db1.workfusion.com/nexus/service/local/repositories/wf-machine-config-bundle/content/</url>
        </repository>
    </repositories>
    ...
</project>

Maven repository user

In case your Nexus repository requires authentication, you have to configure your Nexus credentials for Maven.

By default Maven will look for settings in the following file: C:\Users\[YOUR_WINDOWS_USER]\.m2\settings.xml. For example, if your username is User, the path will be: C:\Users\User\.m2\settings.xml.

You can create it using following content:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
       <servers>
            <server>
                <id>repo-id</id>
                <username>repo-user</username>
                <password>Password99</password>
            </server>
       </servers>
</settings>

Server ID should match the repository ID defined in settings.xml or pom.xml.

note

If you get the "Authentication ERROR" exception during deployment, the possible reason is: the updated settings.xml file was not linked to WF Studio. You can manually link it the following way:

  1. Select Update Settings.
  2. Select your settings.xml in Window > Preferences > Maven > User Settings.

Creating Bot Config Bundle Project

Now you can create a new project with a special type - WorkFusion Bot Config Bundle (BCB):

  1. Create a new project by pressing CTRL + N.
  2. Select the Workfusion->WorkFusion Bot Task Bundle item and click Next.
  3. Select an Archetype:
    currently WATT runs Intelligent Automation Cloud 9.2.0 - so archetype version should be 9.2.0
    1. The kickstart archetype contains a set of demo files and working config examples. It is perfect for understanding and testing the entire development workflow.
    2. The simple archetype contains only bare BCB project structure.
  4. Enter the Archetype parameters: Group Id
    Artifact Id
    Version
  5. (optional step) Modify the following project properties if needed:
    1. bundle-name – name of the project
    2. wf-version – version of your WorkFusion instance
    3. mcb-repo-url – Nexus repository URL for BCB deployment
  6. Click Finish.

As a result, a new project will be created and displayed in the project explorer.

Here is an overview of the BCB project structure:

robotics
    src
        main
            java
                com
                    workfusion
                        robotics
                            ExampleEntity.java
                            ExampleUtils.java
                            GroovyClazz.groovy
            resources
                configs
                    include
                        additional-config-1.xml
                        additional-config-2.xml
                    main
                        do_other.xml
                        do_this.xml
        test
            java
                TestExample.java
            resources
    target
        generated-sources
        maven-status
        test-classes
    wfs-data
        datastore
            my_storage_ds_wfs-working-copy.csv
            my_storage_ds.csv
        input
            my_input_data.csv
        output
            pom.xml
  • The src Java folder contains Java and Groovy classes.
  • Included and main Bot configs are in the resources folder. In a Bot config bundle, you can create your custom Java and Groovy classes and import them into Bot configs.
  • By default, all results are written to the target/output folder.
  • The wfs-data folder contains Data Stores and input .CSV files.
  • The pom.xml file stores all information about the project and the URL to Nexus repository.

Running and developing bot configs

The config development process is the same as standard WorkFusion Studio projects process. You can edit configs code, use include-config, run, and debug configs.

Refer to the Using WorkFusion Studio documentation.

BCB project allows the user to:

  1. Create custom Java and Groovy classes in the src/main/java folder. For example, ExampleEntity.java, ExampleUtils.java
  2. Import these classes in the Bot configs (src/main/resources/configs) in their <script> sections.
  3. Use properties and methods from custom Java and Groovy classes inside <script> sections.
``` xml
    <script><![CDATA[

            import com.workfusion.robotics.ExampleEntity;
            import com.workfusion.robotics.ExampleUtils;

            ExampleEntity entity = new ExampleEntity();
            entity.setExampleStringProperty(some_variable.toString());

            calcResult = ExampleUtils.multiply(2, 5);

    ]]></script>
```

When Bot configuration has been tested, you need to run the project as a Maven build and set the "clean deploy" command as a target. Maven creates a Bot Config Bundle (BCB) – a jar-file in the "target" folder that contains main and included Bot configs together with Java and Groovy classes – and uploads this bundle to the Nexus repository.

Deploying BCB to Nexus repository

Deploying BCB means pushing a Maven Artifact into a Maven Nexus repository.

URL can be provided by changing the mcb.repo.url property during the project creation or by modifying the pom.xml file.

To deploy to the WATT training Maven repository change mcb.repo.url as follows:

\<mcb.repo.url\>https://watt-db1.workfusion.com/nexus/content/repositories/wf-machine-config-bundle/\</mcb.repo.url\>

BCB repository should come from the archetype.

For example, let's say we have the following repository:

https://watt-db1.workfusion.com/nexus/service/local/repositories/wf-machine-config-bundle/content/


<mirrors>
    <mirror>
        <id>local-nexus</id>
        <name>Local Nexus</name>
        <url>http://{host}:{port}/nexus/service/local/repositories/{repository}/content</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
</mirrors>

If your Nexus repo requires authentication, you can setup it using the following manual: http://maven.apache.org/plugins/maven-deploy-plugin/usage.html.

To deploy BCB to Nexus:

  1. Right-click the project folder > Run As > Maven Build.
  2. In the Goals field, enter the "clean deploy" command.
  3. Click Run.
  4. Watch the build process logs. If the build was successful, you will see the following result.

Importing BCB to Intelligent Automation Cloud

There is an option in Control Tower to enable Bot Config Bundles update and plugins update from a Nexus repository. This option can be enabled in the WorkFusion Secure Properties.

Secure Properties are as follows:

  1. nexus.url – URL to a server where Nexus is located;
  2. nexus.user – a user name to access Nexus (the user should have the read permission in the respective repository);
  3. nexus.password – user password.

Example

nexus.url=https://edu.workfusion.com/nexus
nexus.user=nexus-api-user
nexus.password=nexus-api-password

For more information on Secure properties management refer to Manage Secure Properties topic.

note

When the access to a Nexus repository is configured as described above, the Import from Repository button in Advanced > Bot Configurations is enabled.

Additional parameters of the import function are defined in the Platform Configuration properties workfusion.properties file.

Platform Configuration Properties are as follows:

  1. webharvest.plugins.dir – local directory to store the downloaded plugins.
  2. webharvest.plugins.repo – a Nexus repository to download the plugins from.
  3. webharvest.machine.config.bundle.dir – local directory to store the downloaded Bot config bundles.
  4. webharvest.machine.config.bundle.repo – a Nexus repository to download the Bot config bundles from.

The default values of the properties are as follows:

webharvest.plugins.dir=${webapp.root}/../crowdcontoldata/plugins/
webharvest.plugins.repo=webharvest-plugins

webharvest.machine.config.bundle.dir=${webapp.root}/../crowdcontoldata/machine-config-bundle/
webharvest.machine.config.bundle.repo=wf-machine-config-bundle

Automatic Import from Nexus

Control Tower scans through the configured Nexus repository and imports new versions of Bot Config Bundles on a predefined schedule in Platform Configuration properties.

Manual Import

To import all Bot config bundles manually:

  1. Open Campaigns > Bot Configurations menu in Control Tower.
  2. Click the Import from Repository button that will obtain all the new config versions from Nexus.
  3. Wait for some time until the repository is indexed and a new config appears in the list.

When a BCB has been imported from Nexus, the WorkFusion engine automatically creates a Bot campaign, and your robotics tasks are available in the process designer.

Afterwards, developers can create new versions of the same project, make changes, and upload them to Nexus where they will be version controlled.

Troubleshooting

Dependencies load from the Central Maven Repository instead of Nexus

Problem: On-premise installation: dependencies load from the central Maven repository instead of Nexus.

Solution: Go to Preferences > Maven > Installations and add you local maven installation where you have configured settings.xml with mirror.

No JDK Compiler on the environment

Problem: Error during Maven goals execution:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:31:compile (default-compile) on project trial1: Compilation failure
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?[ERROR] -&gt; [Help 1]

Solution: It means that you need to check Preferences > Java > Installed JREs. You need to add JDK at this page and switch configuration to it.

Artifact does not appear in WorkFusion

Problem: Artifact does not appear in WorkFusion.

Possible reasons:

  • Your artifact is not deployed to the right repository in Nexus. WF scans the following folder by default:

    http://{host}:{port}/nexus/service/local/repositories/wf-machine-config-bundle/content/

  • Your artifact has not loaded automatically yet (artifacts are synchronized by a background job to synchronize artifacts but it launched ones a day by default). You can import artifacts manually: Bot Configurations > "Import from Repository" button.

  • Your artifact was already exist in WF. If you redeploy artifact to nexus and do not change groupId, artifactId and version (gav) then WF will not update this artifact, because we check: does this gav exist in application and download only artifacts with nonexistent gav.

Wrong URL setup

Problem: On-premise installation yields the following error.

[ERROR] Plugin org.apache.maven.plugins:maven-clean-plugin:2.5 or one of its dependencies could not be resolved: Failed to read artifact descriptor for org.apache.maven.plugins:maven-clean-plugin:jar:2.5: Could not transfer artifact org.apache.maven.plugins:maven-clean-plugin:pom:2.5 from/to internal-repository (http://{host}:{port}/nexus/service/local/repositories): Not authorized , ReasonPhrase: Unauthorized. -&gt; [Help 1]

Solution: Check mirror setup in Maven settings.xml. The error points out to the wrong URL setup.

← PreviousNext →