This section describes how to upgrade Business Services projets developed with BAMOE versions 9.1.0 and 9.1.1 to the most recent 9.2.x. See the following docs if you are upgrading from a version prior to this:

Depending on the complexity of your installation, you might want IBM® Services to participate in your project. If so, contact your IBM service representative.

This guide will walk you through upgrading your:

  • BAMOE development environment installation with BAMOE Maven repository, BAMOE Canvas, and BAMOE Developer Tools for VS Code

  • Business Service(s) project(s)

  • BAMOE production environment installation with BAMOE Management Console and upgraded versions of your Business Services

If you are using the 9.1.x technology preview for stateful Workflows, you will find instructions on what to do to migrate your stateful workflow projects in this section.

Step 1: Download product archives

Start by downloading the product archives from either IBM Fix Central which requires an active support subscription to IBM BAMOE, IBM Passport Advantage, or via the IBM Business Automation Manager Open Editions Developer Program. For more information see BAMOE 9.2 Download Document.

Step 2: Upgrade your BAMOE development environment installation

When you upgrade your BAMOE development environment, you must upgrade BAMOE Maven repository, BAMOE Canvas, and BAMOE Developer Tools for VS Code.

Upgrade BAMOE Maven repository

It is recommended using the blue-green deployment strategy for Maven artifacts to be available for both your current version and BAMOE version 9.2.1.

If you are using the BAMOE Maven repository .zip instead of BAMOE Maven repository container images, simply extract the contents of BAMOE Maven repository .zip version 9.2.1 to your local Maven repository.

In case you have installed BAMOE Maven repository in a Maven Repository Manager such as Artifactory or Nexus, follow the steps in Installing → BAMOE Maven repository to install the new BAMOE Maven repository version 9.2.1.

Upgrade BAMOE Canvas

The 9.2.1 version of BAMOE Canvas is a drop in replacement for the 9.1.x version (see Installing → BAMOE Canvas). The projects you saved to your browser before the upgrade can simply be opened after installing the new version.

If you prefer to install a parallel version using blue-green deployment strategies you can import projects into the newly installed version (see Importing existing projects) as long as the DNS domains between installations are different. If the DNS domains between installations are the same, your imported projects automatically show up in the new installation when you open it in your browser.

Note

If you have customized your previous BAMOE Canvas installation, remember to apply the same Environment Variables to the new installation. The same applies for customized container images for BAMOE Canvas Dev Deployments.

Upgrade BAMOE Developer Tools for VS Code

BAMOE Developer Tools for VS Code versions are managed by the Extension update mechanism in VS Code. You can set automatic update or manage it manually when notified. Because of version differences in the models supported by the BPMN, DMN, and Test Scenario editors it is recommended to choose when you upgrade to avoid issues when running models in services that have not been upgraded when the tools are upgraded.

See BAMOE Developer Tools for VS Code.

Note

After upgrading the new Test Scenario Editor (now compatible with DMN 1.5) will also open automatically when you first open SCESIM files in BAMOE Developer Tools for VS Code, even when the linked Decision is on an older version (e.g., DMN 1.2).

Step 3: Upgrade your Business Service(s) project(s)

Business Service(s) project(s) can be upgraded in two ways, by:

  • Updating an existing Business Service project with its artifacts by changing the Maven dependencies.

  • Creating a Business Service project from scratch and moving your existing assets to it.

The following tools are required to upgrade your Business Service projects to BAMOE version 9.2.0:

Step 3a: Upgrade Business Service(s) project(s) on BAMOE version 9.1.x

Once your BAMOE development environment installation is upgraded, it is straightforward to upgrade your Business Service(s) project(s) on BAMOE 9.1.x to BAMOE version 9.2.1.

The project structure is not changed, updates only need to be made to the dependencies versions, some dependency names, and files.

Warning

If you come across some difficulties when trying to upgrade your existing Business Service projects we recommend creating a new project following Step 3b: Upgrade Business Service projects on BAMOE versions 9.0.x or 9.1.x.

  1. Upgrade the Quarkus version in the project POM file to the currently supported version 3.15 (LTS):

  1. Upgrade the BAMOE BOM in the project POM file to 9.2.0-ibm-0004:

    <dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-bom</artifactId>
  <version>9.2.1-ibm-0005</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

  1. Update the application.properties file.

    BAMOE version 9.2.1 does not fully support Quarkus Dev Services and hence it is required to disable this feature by adding the following line to the src/main/resources/application.properties file:

     + quarkus.devservices.enabled=false
Note

Refer to Quarkus v3 migration guide for any other change related to Quarkus.

Step 3b: Creating a Business Service project on BAMOE version 9.2.1 from scratch

If you have experienced some difficulties when trying to upgrade your project you can create a new Business Service project from scratch and import your existing business automation assets (Workflows, Decisions, Rules, and Decision Tables) to the new project.

For more information, see Getting started → Initial Business Service project setup to create a new Business Service project on BAMOE version 9.2.1.

The most significant folder is src/main/resources, which is where new or upgraded business automation asset files must be stored.

Examples of supported business automation assets are:

  • Decision Model & Notation (DMN) decisions (.dmn)

  • Drools Rule Language (DRL) rules (.drl)

  • Business Process Model & Notation (BPMN) workflows (.bpmn)

  • Spreadsheet Decision Table files (.xls or .xlsx)

  • Standard Properties files (.properties)

  • Test Scenario files (.scesim)

Copy all your assets from your Business Service project on BAMOE version 9.1.x to the respective folders on the new project on BAMOE version 9.2.1. If you have custom Java code or any other type of file in your Business Service project, move them to the same location as you had before, following Maven’s standard directory layout.

Note

The proper folder for Test Scenario files is src/test/resources.

Step 4: Verify the upgrade of your Business Service(s) project(s)

  1. To verify that your upgrade is successful, build the project one more time using Maven’s standard command or any other customized build command you might have in your project.

    mvn clean package

    You might get Maven streaming text once again, and at the end of it you must have:

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.023 s
[INFO] Finished at: 2024-06-11T17:09:00-03:00
[INFO] ------------------------------------------------------------------------

    Now you can start using your Business Service project on BAMOE version 9.2.1.

Step 5: Upgrade your BAMOE production environment installation

After upgrading your Business Services source code (Steps 3a or 3b), you need to upgrade BAMOE Management Console before deploying a new version of the upgraded Business Services.

It is recommended that you use the blue-green deployment strategy for upgrading BAMOE Management Console so that you still have a reliable way of managing live Business Services that might not have been upgraded to BAMOE version 9.2.1 yet. Once all your Business Services are running BAMOE version 9.2.1, you can safely remove your previous BAMOE Management Console installation.

If you are getting started with stateful Workflows, follow Installing → BAMOE Management Console for information on installing BAMOE Management Console for the first time in your production environment.

Once you have a new installation for BAMOE Management Console version 9.2.1, you can follow the standard guidance on how to deploy a new version of your Business Services (see Building Business Services executables and Deploying Business Services).

Upgrading from BAMOE version 9.1.1 technology preview for stateful Workflows

In the 9.1.1 technology preview the Process API was used to call your stateful process. In this version a new User Tasks API is built on top of a dedicated User Tasks subsystem. As a direct impact of that there are three key changes to be taken into account:

The following sections show how the API calls changed based on the most important use cases:

Example 1 - Show Tasks assigned to a user / groups

Process API

curl -X GET \

'http://localhost:8080/{processId}/{uuid}/tasks?user=manager&group=managers'

User Task API

curl -X GET \

'http://localhost:8080/usertasks/instance?group=managers&user=manager'
Example 2 - Show a precise Task assigned to a user / groups

Process API

curl -X GET \

'http://localhost:8080/{processId}/{processInstance}/{taskName}/{taskId}?user=manager'

New API

curl -X GET \

'http://localhost:8080/usertasks/instance/{taskId}?group=managers&user=manager'

The JSON returned by the User Task API to represent a Task is significantly different from the JSON returned by the Process API.

Here, an example of the two returned objects for both endpoints.

The new User Tasks API returns the following information:

{
    "id": "e447c247-abc2-4ed4-a7ab-ef4ee2fe4a71",
    "userTaskId": "_8B62D3CA-5D03-4B2B-832B-126469288BB4", // UserTask ID Node
    "status": {
      "terminate": null,
      "name": "Reserved" //phase
    },
    "taskName": "firstLineApproval",
    "taskDescription": null,
    "taskPriority": null,
    "potentialUsers": [
      "manager"
    ],
    "potentialGroups": [
      "managers"
    ],
    "adminUsers": [],
    "adminGroups": [],
    "excludedUsers": [],
    "externalReferenceId": "c7f40ec0-0272-4e04-9f0b-91ffe78d2590",
    "actualOwner": "manager",
    "inputs": {
      "traveller": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "jon.doe@example.com",
        "nationality": "American",
        "address": {
          "street": "main street",
          "city": "Boston",
          "zipCode": "10005",
          "country": "US"
        }
      }
    },
    "outputs": {},
    "metadata": {
      "ProcessType": "BPMN",
      "ParentProcessInstanceId": null,
      "ProcessVersion": "1.0",
      "RootProcessInstanceId": null,
      "RootProcessId": null,
      "ProcessId": "approvals",
      "ProcessInstanceId": "e7822e65-abf3-4356-9cf9-15bde2c43641",
      "ProcessInstanceState": 1
    }
  }

While the Process API returns the following task information:

[
  {
    "id": "c7f40ec0-0272-4e04-9f0b-91ffe78d2590",
    "name": "firstLineApproval",
    "state": 1, // termination state
    "phase": "activate",
    "phaseStatus": "Activated",
    "parameters": {
      "traveller": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "jon.doe@example.com",
        "nationality": "American",
        "address": {
          "street": "main street",
          "city": "Boston",
          "zipCode": "10005",
          "country": "US"
        }
      }
    },
    "results": {
      "approved": null
    }
  }
]

The main differences are:

  • The User Tasks IDs will not be the same.

    The assigned ID for the Task in the new User Tasks API (e447c247-abc2-4ed4-a7ab-ef4ee2fe4a71) is scoped inside the User Tasks subsystem, and can only be used in that subsystem. It is the ID to be used as taskID parameter in all the entrypoints defined in the new User Tasks API. The rest of the engine is out of scope. Using this task ID in a Process API entrypoint will lead to an error.

  • The externalReferenceId element represents the Work Item ID, which is how the Process API identifies a User Task at the global level. The value is the same as the Task ID if you use Process API.

  • New data related to the assigned permissions for the Tasks has been added, such as the actual owner, potential users and groups and excluded users

  • The parameters object present in the old API has become inputs and outputs. These represents a Map of String, Objects entries that you can set as the User Task input or output. You can modify this list adding more entries with a specific entrypoint.

  • The new API Task object now contains a Metadata object. This contains relevant properties that describes the BPMN asset

With the dedicated API for User Tasks, it is now possible to directly put new Input and Output data for a given User Task, using the following entrypoints:

Example 3 – Add Inputs data

Process API

Not possible to modify inputs in the previous API version.

New API

curl -X PUT \

'http://localhost:8080/usertasks/instance/{taskId}/inputs?group=managers&user=manager'\

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"variable": "value"

}'
Example 4 - Add Output data

Process API

Not possible to pass Output data to a User Task when sending a termination (eg. completion) phase update call.

New API

curl -X PUT \

'http://localhost:8080/usertasks/instance/{taskId}/outputs?group=managers&user=manager' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"variable": "value"

}'

Here are some examples on how to manage Comments and Attachments

Example 5 Add Comments

Process API

Not possibile to add comments

New API

curl -X POST \

'http://localhost:8080/usertasks/instance/{taskId}/comments? group=managers&user=manager' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"comment": "test"

}'
Example 6 - Add Attachments

Process API

Not possibile to add attachments

New API

curl -X POST \

'http://localhost:8080/usertasks/instance/{taskId}/attachments?group=managers&user=manager' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"uri": "http://www.bamoe.com", "name": "bamoe"

}'

Similar operations (GET, DELETE) can be performed against Comments and Attachments. The precise endpoint definitions are shown above.

The following examples show how to apply a transition to a given User Task. The transition scope is to advance a User Task status, moving it from one status to another (transitionID), where the status can be: "activate", "claim", "release", "complete", "skip", or “fail”. The following example shows how to complete a User Task.

Example 7 - Approve User Task

Process API

curl -X POST \ 'http://localhost:8080/{processId}/{uuid}/{taskName}/{taskId}?user=admin&group=managers' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"approved": "true"

}'

OR

curl -X POST \ 'http://localhost:8080/{processId}/{uuid}/{taskName}/{taskId}/phases/{phaseId}?user=admin&group=managers' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"approved": "true"

}'

New API

curl -X POST \

'http://localhost:8080/usertasks/instance/{taskId}/transition?group=managers&user=manager' \

-H 'accept: application/json' \

-H 'Content-Type: application/json' \

-d '{

"transitionId": "complete"

}'

With the Process API there are two ways to change the User Task status. With the first entrypoint, the User Tasks change its status to complete, without specifying the phaseId. The second entrypoint gives the ability to pass a specific phaseId different than “complete”. It is possible to pass output values in the same call (E.g., “approved” = true)

The new User Task API requires that the transitionID is defined in the JSON payload, as in the example below. It is no longer possible to pass output values as was done in the Process API, so if you need to put some output data, you need to call the Add Output entypoint described later.

A new feature that the new User Tasks API introduced is to provide an endpoint that returns all reachable statuses that a given User Task can reach from the current status.

Example 8 – Retrieve reachable status for a given User Task

Process API

Not present

New API

curl -X GET \

'http://localhost:8080/usertasks/instance/{taskId}/transition? group=managers&user=manager' \