How to deploy Living App artifacts

This page describes how to deploy Bonita Living Application artifacts from the command line.

BCD deployer is deprecated/being phased out.

As of September 2023, BCD deployer is deprecated (no more updates or improvements as it is being replaced by new functionality). The deployer supports Bonita 2023.2, but support for future versions is not guaranteed. Bonita artifacts are now deployed and updated at startup using the standalone application feature.

This change is due to the introduction of our Self Contained Application approach (from 2023.2 version), we are moving to a new deployment mode that no longer relies on the "BCD" mechanism as you knew it. In fact, the SCA mode natively integrates this capability into the build package (via Maven).

This means that we are gradually phasing it out and that there will be no more updates or improvements to this functionality. However, platform mode is still supported for versions 2023.2, 2024.1, 2024.2, it’s just no longer our 'nominal' mode.

First make sure your maven installation is configured to access Bonita Artifact Repository !

Deployer installation guide

You can download the bonita-la-deployer with a single maven command (that will reuse the credentials declared in your maven settings.xml configuration file).

Download with maven

mvn dependency:copy -Dartifact=com.bonitasoft.deployer:bonita-la-deployer:<deployer.version>:jar -Dmdep.stripVersion -Dmdep.stripClassifier -DoutputDirectory=./

Then just use the CLI jar once downloaded :

Execution sample

java -jar bonita-la-deployer.jar -f <path to the bonita archive to deploy> -t http://localhost:8080/bonita -u <username> -p <password>

You can call bonita-la-builder with the --help (or -h) option to get available options and commands as follows:

java -jar bonita-la-deployer.jar -h
usage: java -jar bonita-la-deployer-x.y.z.jar [-bc <bonita-configuration>] [--debug] [--development]
       [--disable-certificate-check] [-f <file>] [-h] [--http-timeout <http-timeout>] [-p <password>] [-t <targetUrl>]
       [-u <username>]

Deploy an Application Archive and/or Application Configuration to a Bonita platform
 -bc,--bonita-configuration <bonita-configuration>   the Application Configuration to deploy
    --debug                                          activate debug logs
    --development                                    Deploy for development environment (Eg. processes / profiles are
                                                     replaced if existing, ...)
    --disable-certificate-check                      disable all certificate validation when connecting to a https
                                                     server. Use this option when a self-signed certificate is used on
                                                     the target server.
 -f,--file <file>                                    the Application Archive to deploy
 -h,--help                                           print this message
    --http-timeout <http-timeout>                    the timeout (in seconds, default to 120) for http interactions
                                                     (read and write) with Bonita
 -p,--password <password>                            password to use to connect to Bonita
 -t,--targetUrl <targetUrl>                          url of the Bonita platform
 -u,--username <username>                            username to use to connect to Bonita

Examples:
java -jar bonita-la-deployer-x.y.z.jar -f <application_archive_zip_path>
java -jar bonita-la-deployer-x.y.z.jar -f <application_archive_folder_path> -t http://myhost/bonita

How it works

This section provides detailed information of Bonita artifacts deployment.

Deployment concepts

First, here are the types of artifacts that can be deployed:

applications
business data model
business data model access controls
layouts
organizations
pages
processes
profiles
REST API extensions
themes

The deployment entry point is called an Application Archive. It consists of all artifacts to be deployed and an optional configuration file called Deployment Descriptor. This file describes which Policy should be applied while deploying each artifact.

From Bonita 7.8.0 onwards, Application Configuration artifacts can also be deployed. An Application Configuration artifact has a .bconf extension and is generated by the Living App Build command.
Application Configuration artifacts can be customized using the bonita-la-builder extract|merge commands as described in this documentation.

Read carefully the deployment supported policies per artifacts before deploying a Living Application on an existing environment. Using the default policies may result in cleaning the resources of the whole Bonita runtime.

Application Archive structure

The Application Archive can be a directory or a zip file. It may contain a Deployment Descriptor in the form of a deploy.json file. If not provided, then a Deployment Descriptor is generated in-memory using the following rules:

the type of artifact is determined from the nature of each file
a default policy is applied for each supported artifact to deploy

Here is an example of Application Archive structure:

bonita-vacation-management-example
├── applications
│   └── Application_Data.xml
├── bdm
│   └── bdm.zip
├── deploy.json
├── extensions
│   └── tahitiRestApiExtension-1.0.0.zip
├── organizations
│   └── ACME.xml
├── pages
│   └── page_ExampleVacationManagement.zip
├── processes
│   ├── Cancel Vacation Request--1.4.1.bar
│   ├── Initiate Vacation Available--1.4.1.bar
│   ├── Modify Pending Vacation Request--1.4.1.bar
│   ├── New Vacation Request--1.4.1.bar
│   └── Remove All Business Data--1.4.1.bar
└── profiles
    └── default_profile.xml

If you provide several artifacts for a resource which is supposed to be single (for instance Business Data Model, Organization), only one of the artifacts will be deployed. There is no guaranty about which file is kept so please avoid this situation to ensure deployment reproducibility.

Deployment Descriptor file

The Deployment Descriptor file must be a valid JSON file named deploy.json, and it must be located at the root of the Application Archive.

Each artifact to deploy must be defined with the following attributes:

file: (Mandatory) the relative path to the artifact in the Application Archive
policy: (Optional) the name of the policy to apply in case the same artifact is already present in the target Bonita platform. If omitted, then the default policy of the artifact’s type will be applied.

If a deploy policy is declared in a deploy.json file, it overrides the policy specified as a CLI option (like --development-mode).
If no policy is specified in the deploy.json file, the policy specified as a CLI option will be applied.
If no policy at all is specified, production mode will be applied.

Make sure to add the --development-mode option if you want to deploy using Development policies (eg. replace processes and profiles, merge organization data). Otherwise Production deployment policies will be used (eg. existing processes are left untouched).

Example of Deployment Descriptor file

{
  "organization": {
    "file": "organizations/ACME.xml",
    "policy": "MERGE_DUPLICATES"
  },
  "profiles": [
    {
      "file": "profiles/default_profile.xml",
      "policy": "REPLACE_DUPLICATES"
    },
    {
      "file": "profiles/custom_profile.xml",
      "policy": "REPLACE_DUPLICATES"
    }
  ],
  "processes": [
    {
      "file": "processes/New Vacation Request--1.4.1.bar",
      "policy": "IGNORE_DUPLICATES"
    },
    {
      "file": "processes/Initiate Vacation Available--1.4.1.bar"
    }
  ],
  "restAPIExtensions": [
    {
      "file": "extensions/tahitiRestApiExtension-1.0.0.zip"
    }
  ],
  "pages": [
    {
      "file": "pages/page_ExampleVacationManagement.zip"
    }
  ],
  "layouts": [
    {
      "file": "layouts/customLayout1.zip"
    },
    {
      "file": "layouts/customLayout2.zip"
    }
  ],
  "themes": [
      {
        "file": "themes/customTheme1.zip"
      },
      {
        "file": "themes/customTheme2.zip"
      }
    ],
  "applications": [
    {
      "file": "applications/Application_Data.xml",
      "policy": "REPLACE_DUPLICATES"
    }
  ],
  "businessDataModel": {
    "file": "bdm/bdm.zip"
  },
  "bdmAccessControl": {
    "file": "bdm/bdm-access-control.xml"
  }
}

Supported Policies

Applications:
- FAIL_ON_DUPLICATES: deployment fails if the Application or ApplicationPage already exists
- REPLACE_DUPLICATES: (default) if the Application or ApplicationPage already exists, the existing one is deleted, and the new one is deployed
Organization:
- FAIL_ON_DUPLICATES: if an item already exists, the deployment fails and is reverted to the previous state
- IGNORE_DUPLICATES: existing items are kept
- MERGE_DUPLICATES: (default) existing items in the current organization are updated to have the values of the item in the imported organization
Processes:
- FAIL_ON_DUPLICATES: if the process already exists (same name and version), the deployment fails
- IGNORE_DUPLICATES: only deploys a process when it does not already exist (same name and version)
- REPLACE_DUPLICATES: (default) if the process already exists (same name and version), the existing one is deleted and the new one is deployed. As a reminder, deleting a process means: disable the process, delete all related cases and delete the process

The following artifacts are used with implicit policies. It means that you do not have to declare those policies in the Deployment Descriptor file. There is no other policy available for those artifacts.

Business Data Model: REPLACE_DUPLICATES
BDM access control: REPLACE_DUPLICATES
Layouts: REPLACE_DUPLICATES
Pages: REPLACE_DUPLICATES
Profiles: REPLACE_DUPLICATES
REST API extensions: REPLACE_DUPLICATES
Themes: REPLACE_DUPLICATES

Caveats

FAIL policy implies that the deployment stops right after the failure meaning that subsequent elements of the deployment are not deployed at all.
Prior to deploying a Business Data Model, the Bonita tenant is paused. So a downtime of the tenant occurs. The tenant is resumed after the deployment of the BDM.
REST API extension authorizations are not configured as part of the deployment process. They have to be configured while provisioning the Bonita platform.