How to deploy Living App artifacts

This tutorial describes how to deploy Bonita Living Application artifacts from the command line using BCD.

How it works

This section provides detailed information of Bonita artifacts deployment with BCD.

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.

Since BCD 3.0.0 and for 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 bcd livingapp extract-conf|merge-conf 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 a clean 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.

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.

Preconfigured deployment policies

Production mode

Organization: IGNORE_DUPLICATES
Process: IGNORE_DUPLICATES
Profile: IGNORE_IF_ANY_EXISTS
Application: REPLACE_DUPLICATES

Development mode

Organization: MERGE_DUPLICATES
Process: REPLACE_DUPLICATES
Profile: REPLACE_DUPLICATES
Application: REPLACE_DUPLICATES

How to use

Use the bcd livingapp deploy command to deploy Living App artifacts:

bcd -s <scenario> livingapp deploy -p <application_path> -c <configuration_path>

where:

<scenario> is the path to the BCD scenario which defines the target Bonita stack. Artifacts will be deployed using tenant credentials defined by this scenario (bonita_technical_username and bonita_technical_password variables).
<application_path> is the path to the Application Archive to deploy (zip file or directory).
<configuration_path> is the path to the Application Configuration bconf artifact to deploy. This file can be generated for Bonita 7.8.0 onwards.

You may deploy an application archive and an application configuration artifact separately. The bcd livingapp deploy command requires at least one the deployable artifacts to be provided.

You can add a --debug option to enable debug mode and increase verbosity.

You can also add a --development-mode flag to perform the deployment in development mode. This flag allows for a more aggressive replacement policy. When this flag is not provided, the default production mode will be used which means more artifacts will be preserved.

Refer to the BCD Command-line reference for a complete list of available options for the bcd livingapp deploy command.

Complete example:

Here is how to deploy artifacts of the Bonita Vacation Management example Living App.

Assuming that:

a bonita-vacation-management-example-Test-20181206125838.zip Application Archive zip file has been generated in the bonita-vacation-management-example/target directory
a bonita-vacation-management-example-Test-20181206125838.bconf Application Configuration artifact bconf file has been generated in the bonita-vacation-management-example/target directory
a Bonita runtime is up and running as defined in a scenarios/build_and_deploy.yml scenario file

In the BCD controller container:

bonita@bcd-controller:~$ cd bonita-continuous-delivery

bonita@bcd-controller:~/bonita-continuous-delivery$ ls -nh bonita-vacation-management-example/target
total 9,0M
drwxr-xr-x 9 1000 1000 4,0K Dec   6 13:59 bonita-vacation-management-example
-rw-r--r-- 1 1000 1000 2,4K Dec   6 13:59 bonita-vacation-management-example-Test-20181206125838.bconf
-rw-r--r-- 1 1000 1000 9,0M Dec   6 13:59 bonita-vacation-management-example-Test-20181206125838.zip
drwxr-xr-x 3 1000 1000 4,0K Dec   6 13:59 bpmn
drwxr-xr-x 3 1000 1000 4,0K Dec   6 13:58 configurations
drwxr-xr-x 2 1000 1000 4,0K Dec   6 13:58 generated-jars
drwxr-xr-x 3 1000 1000 4,0K Dec   6 13:58 ui-designer

Then artifacts can be deployed as follows:

bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/build_and_deploy.yml --yes livingapp deploy \
    -p bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181206125838.zip \
    -c bonita-vacation-management-example/target/bonita-vacation-management-example-Test-20181206125838.bconf

Artifacts can also be deployed providing the Application Archive directory and without configuration as follows:

bonita@bcd-controller:~/bonita-continuous-delivery$ bcd -s scenarios/build_and_deploy.yml --yes livingapp deploy \
    -p bonita-vacation-management-example/target/bonita-vacation-management-example