From 94afdd62af6a8a5654c8f1f4844ddd12d20d8def Mon Sep 17 00:00:00 2001 From: Haroun El Alami Date: Thu, 12 Oct 2023 15:43:25 +0200 Subject: [PATCH] fix(doc): adjust maintenance-mode terms (#2457) Co-authored-by: abirembaut --- .../pages/bonita-bpm-overview.adoc | 2 +- .../data/pages/define-and-deploy-the-bdm.adoc | 6 +++--- .../pages/admin-application-process-list.adoc | 2 +- ...bdm-management-in-bonita-applications.adoc | 12 +++++------ .../runtime/pages/how-a-bdm-is-deployed.adoc | 16 +++++++-------- .../pages/platform-maintenance-mode.adoc | 20 +++++++++---------- ...er-administrator-application-overview.adoc | 2 +- .../pages/update-with-migration-tool.adoc | 4 ++-- .../pages/update-with-update-tool.adoc | 2 +- 9 files changed, 32 insertions(+), 34 deletions(-) diff --git a/modules/bonita-overview/pages/bonita-bpm-overview.adoc b/modules/bonita-overview/pages/bonita-bpm-overview.adoc index d3b959ea34..5a4f01bd32 100644 --- a/modules/bonita-overview/pages/bonita-bpm-overview.adoc +++ b/modules/bonita-overview/pages/bonita-bpm-overview.adoc @@ -69,7 +69,7 @@ As mentioned before, the Bonita User Application is the part of Bonita that is v Bonita also comes with three other very useful applications: * Bonita Administrator Application: the tool used by the administrator to xref:runtime:admin-application-process-list.adoc[install, deploy and manage processes], monitor process execution, [xref:runtime:live-update.adoc[perform some evolutions] in organization, resources, and applications, and recover from errors. -* Bonita Super Administrator Application: the tool used by the technical user to setup the Bonita Runtime environment with organization, Business Data Model, and applications. It also allows to enable the maintenance mode to, for example, update the Business Data Model. +* Bonita Super Administrator Application: the tool used by the technical user to setup the Bonita Runtime environment with organization, Business Data Model, and applications. It also allows to activate the maintenance mode to, for example, update the Business Data Model. * Application Directory Application, THE ONE URL to remember for all Bonita users, displaying the catalog of all applications accessible by the logged user. diff --git a/modules/data/pages/define-and-deploy-the-bdm.adoc b/modules/data/pages/define-and-deploy-the-bdm.adoc index 9e4297994c..6c801db5de 100644 --- a/modules/data/pages/define-and-deploy-the-bdm.adoc +++ b/modules/data/pages/define-and-deploy-the-bdm.adoc @@ -348,7 +348,7 @@ To deploy the BDM, you export it as a ZIP file from Bonita Studio and then impor [WARNING] ==== -Before deploying the business data model, you must xref:ROOT:platform-maintenance-mode.adoc[Enable] the maintenance mode, so that the update can be performed without affecting ongoing processes. +Before deploying the business data model, you must xref:ROOT:platform-maintenance-mode.adoc[Activate the maintenance mode], so that the update can be performed without affecting ongoing processes. ==== [IMPORTANT] @@ -369,13 +369,13 @@ Follow these steps: . Click *Export*. A file called `bdm.zip` is written to the folder that you specified. . Log into the Bonita Runtime as the technical user. . Go to the *Platform maintenance* page. -. Click *Start maintenance*. +. Click *Activate maintenance mode*. . Then, go to the *Business Data Model* menu (and, for Efficiency, Performance and Enterprise editions, choose *Definition*). . Specify the file containing the business data model that you exported from Bonita Studio. . Click *_Activate_*. A warning is displayed, reminding you that installing this new BDM will overwrite the existing BDM. . Click on *Install* to complete the deployment. The Bonita Runtime loads the file, and retrieves the object definition enabling processes to use them at runtime. It also creates or updates the database schema in the business database, to store business objects appropriately when modified by processes. When the deployment is complete, a message is displayed. If deployment fails, use the Engine logs to analyze the problem. . Go to the *Platform maintenance* page. -. Click *End maintenance*. +. Click *Deactivate maintenance mode*. WARNING: the database model is automatically updated when you deploy a new BDM. Avoid changing the database schema manually as it may jeopardize the persistence of business objects and cause errors at process runtime. diff --git a/modules/runtime/pages/admin-application-process-list.adoc b/modules/runtime/pages/admin-application-process-list.adoc index d70136e300..cb953809d4 100644 --- a/modules/runtime/pages/admin-application-process-list.adoc +++ b/modules/runtime/pages/admin-application-process-list.adoc @@ -49,7 +49,7 @@ To resolve a process for business variables: . Logout . Login in Bonita Administrator Portal with the xref:ROOT:tenant_admin_credentials.adoc[technical user credentials] -. xref:ROOT:platform-maintenance-mode.adoc[Enable the maintenance mode] +. xref:ROOT:platform-maintenance-mode.adoc[Activate the maintenance mode] . xref:ROOT:bdm-management-in-bonita-bpm-portal.adoc[Update the BDM] . End the maintenance mode . Come back to the application _BPM_/_Processes_ and check the status. diff --git a/modules/runtime/pages/bdm-management-in-bonita-applications.adoc b/modules/runtime/pages/bdm-management-in-bonita-applications.adoc index 3d172b20f7..298fcc9701 100644 --- a/modules/runtime/pages/bdm-management-in-bonita-applications.adoc +++ b/modules/runtime/pages/bdm-management-in-bonita-applications.adoc @@ -22,11 +22,11 @@ The Business Objects must match the structure used by the deployed processes. Ma . To import the Business Data Model created in Bonita Studio, first xref:data:define-and-deploy-the-bdm.adoc[export the Business Data Model] from Bonita Studio where it was designed. . In the Bonita Runtime, log in as the technical user (default login 'install', default password 'install'). . Go to the *Platform maintenance* menu. -. Click on *Start maintenance* to xref:ROOT:platform-maintenance-mode.adoc[enable the maintenance mode]. +. Click on *Activate maintenance mode* button. + [NOTE] ==== -The deployment of a Business Data Model requires enabling the maintenance mode during the operation, so that the update can be performed without affecting ongoing processes. +The deployment of a Business Data Model requires xref:ROOT:platform-maintenance-mode.adoc[activating the maintenance mode] during the operation, so that the update can be performed without affecting ongoing processes. For Enterprise, Efficiency and Performance editions, you must have no <> file installed in order to be able to install or update the Business Data Model. ==== @@ -34,7 +34,7 @@ To do so: . Log in as the technical user (default login 'install', default password 'install', or refer to the internal documentation if modified as it should be). . Go to the _Platform maintenance_ menu. -. Click on the _Start maintenance_ button to xref:ROOT:platform-maintenance-mode.adoc[enable the maintenance mode]. +. Click on the _Activate maintenance mode_ button. Then, you can install or update the BDM. [WARNING] @@ -64,7 +64,7 @@ It will also create or update the database schema (set of tables, columns, index The Business Data Model will now be installed. Maintenance mode can be disabled. + To do so: . Go to the _Platform maintenance_ menu. -. Click on the _End maintenance_ button to xref:ROOT:platform-maintenance-mode.adoc[disable the maintenance mode]. +. Click on the _Deactivate maintenance mode_ button. + [WARNING] ==== @@ -112,7 +112,7 @@ No data are lost in these cases. No restore action is needed. If you need to update the BDM, and your update includes one of the cases listed above (both those that generate an error at installation, and those that do not), you will need to do the update manually. Get some help from your database administrator: -. Stop your Tenant services (via maintenance mode) +. Stop the BPM and BDM services (by activating the maintenance mode) . Stop your Bonita server . Ask your database administrator to update manually the BDM schema in your BDM database to make it correspond to your new BDM. The easiest way to do it is to first install your new BDM on a clean database. Then compare the new schema with the old one, and manually create a sql script to update your BDM database to match the new one. @@ -145,7 +145,7 @@ Please note that a delay is required after the import for the engine to process [NOTE] ==== -Contrary to the BDM definition, the deployment of a BDM Access Control file does not starting the maintenance mode during the operation. +Contrary to the BDM definition, the deployment of a BDM Access Control file does not require activating the maintenance mode during the operation. ==== . xref:identity:bdm-access-control.adoc[Export the BDM Access Control file] from Bonita Studio where it was designed. diff --git a/modules/runtime/pages/how-a-bdm-is-deployed.adoc b/modules/runtime/pages/how-a-bdm-is-deployed.adoc index 5b3d772b59..858127baf2 100644 --- a/modules/runtime/pages/how-a-bdm-is-deployed.adoc +++ b/modules/runtime/pages/how-a-bdm-is-deployed.adoc @@ -182,15 +182,13 @@ On the other side, the database refactoring is xref:ROOT:bdm-management-in-bonit == Constraints to (re-)deploy a BDM -A BDM is defined at *tenant* level. +To be able to deploy or redeploy a BDM, the *maintenance mode must be activated* first. -To be able to deploy or redeploy a BDM, the *maintenance mode of this tenant must be started* first. - -Indeed, as deploying the BDM changes the tenant classloader and all process classloaders on the same tenant, no process +Indeed, as deploying the BDM changes the tenant classloader and all process classloaders, no process can safely run during this operation. -Pausing the services means that the work service does not execute works anymore on this tenant, the Job service does not triggers any job anymore on this tenant, etc. Only the vital services stay alive, to be able to operate the BDM and the rest of the platform. Other tenants are not affected. +Pausing the services means that the work service does not execute works anymore, the Job service does not triggers any job anymore, etc. Only the vital services stay alive, to be able to operate the BDM and the rest of the platform. -After (re-)deploying the BDM, the maintenance mode must be ended to be able to use +After (re-)deploying the BDM, the maintenance mode must be deactivated to be able to use it. == Deploying a BDM via the Bonita Super Administrator application @@ -200,7 +198,7 @@ See xref:ROOT:bdm-management-in-bonita-applications.adoc#_manage_the_bdm[how to Internally, the runtime will call the method `updateBusinessDataModel()` to install the new BDM. This method implicitly performs the following steps in a single database transaction: -* if a BDM already exists on the current tenant, it is uninstalled +* if a BDM already exists, it is uninstalled * the new BDM is installed / deployed -* the Bonita Engine loads the new BDM in the tenant -classloader (and in the process classloaders of all processes on this tenant), and creates / updates the database accordingly. +* the Bonita Engine loads the new BDM +classloader (and in the process classloaders of all processes), and creates / updates the database accordingly. diff --git a/modules/runtime/pages/platform-maintenance-mode.adoc b/modules/runtime/pages/platform-maintenance-mode.adoc index b9d1efba53..c064e49bae 100644 --- a/modules/runtime/pages/platform-maintenance-mode.adoc +++ b/modules/runtime/pages/platform-maintenance-mode.adoc @@ -1,12 +1,12 @@ = Put Runtime in maintenance mode :page-aliases: ROOT:platform-maintenance-mode.adoc -:description: Learn how to execute maintenance tasks by disabling and enabling Bonita Runtime maintenance mode. +:description: Learn how to execute maintenance tasks by activating and deactivating Bonita Runtime maintenance mode. {description} For certain maintenance tasks that require a change to database tables or to information used by several processes (for example to update the Business Data Model), it is necessary to enable Bonita Runtime maintenance mode temporarily while it is updated. + -When the maintenance mode is enabled, this has the following consequences: +When the maintenance mode is activated, this has the following consequences: * BPM and BDM APIs are not accessible (except BDM installation) * Users who are currently logged in, including Administrator users, are automatically redirected to a maintenance page. @@ -15,12 +15,12 @@ When the maintenance mode is enabled, this has the following consequences: Those are the reasons why such maintenance procedures must be planned at a time of low usage and must be communicated carefully to the users. + -The following sections explain how to notify users about incoming maintenance and also how to enable/disable maintenance mode using the Bonita Super Administrator application. + +The following sections explain how to notify users about incoming maintenance operations and also how to activate/deactivate the maintenance mode using the Bonita Super Administrator application. + You can also use the https://javadoc.bonitasoft.com/api/{javadocVersion}/index.html[Engine API] or the xref:ROOT:rest-api-overview.adoc[Web REST API]. == Notify users about incoming maintenance -As a technical user, you can set a maintenance message to be displayed to logged-in users in advance. This message should inform users about when and what the maintenance is about. It is also displayed on the maintenance page (503 error page) when the maintenance mode is enabled. +As a technical user, you can set a maintenance message to be displayed to logged-in users before the scheduled maintenance window. This message should inform users about when and what the maintenance is about. It is also displayed on the maintenance page (503 error page) when the maintenance mode is activated. To perform that you need to: @@ -40,16 +40,16 @@ To perform that you need to: . Log into Bonita Super Administrator application. . Go to *Platform maintenance*. -. Click the *_Start maintenance_* button. -. In the popup, click *_Enable maintenance mode_* to confirm that maintenance mode is to be enabled. -. The maintenance mode is immediately enabled. +. Click the *_Activate maintenance mode_* button. +. In the popup, click *_Activate maintenance mode_* to confirm that maintenance mode is to be activated. +. The maintenance mode is immediately activated. == Disable maintenance mode . Log into Bonita Super Administrator application. . Go to *Platform maintenance*. -. Click the *_End maintenance_* button. -. In the popup, click *_Disable maintenance mode_* to confirm that maintenance mode is to be disabled. -. The maintenance mode is disabled. +. Click the *_Deactivate maintenance mode_* button. +. In the popup, click *_Deactivate maintenance mode_* to confirm that maintenance mode is to be disabled. +. The maintenance mode is deactivated. After the services are resumed, it is important to inform users that they can now log into all applications. diff --git a/modules/runtime/pages/super-administrator-application-overview.adoc b/modules/runtime/pages/super-administrator-application-overview.adoc index 0f1f63db86..72a21ef630 100644 --- a/modules/runtime/pages/super-administrator-application-overview.adoc +++ b/modules/runtime/pages/super-administrator-application-overview.adoc @@ -11,7 +11,7 @@ It is the tool needed to: * Bootstrap a Bonita Runtime in Non-Production and Production environments, for example, xref:first-steps-after-setup.adoc#_create_a_bonita_administrator_profile[creating the administrators] * Ability to notify users about a scheduled maintenance, by a custom message that will be displayed to logged-in users. this message is also displayed on the maintenance page when the maintenance mode is enabled. -* Enable maintenance mode for operations, among which the update of the Business Data Model (and the related database migration) +* Activate maintenance mode for operations, among which the update of the Business Data Model (and the related database migration) * Apply temporary fixes to some projects elements (resources, applications, organization entities) to recover from errors [CAUTION] diff --git a/modules/version-update/pages/update-with-migration-tool.adoc b/modules/version-update/pages/update-with-migration-tool.adoc index 167aece8d9..1d0cf266db 100644 --- a/modules/version-update/pages/update-with-migration-tool.adoc +++ b/modules/version-update/pages/update-with-migration-tool.adoc @@ -69,7 +69,7 @@ If you are updating to a new maintenance version within the same main version, y .*Special attention required on:* * *Custom reports :* Up to Bonita 2021.1 (Bonita Runtime 7.12) they may continue working, depending on the custom code you added. Starting with Bonita 2021.2 (Bonita Runtime 7.13), custom reports will not be supported in Bonita Runtime anymore. They have been replaced with a standalone Enterprise only - Reporting Application. * When the *source version* is Bonita 7.0.0, 7.2.0 or 7.2.4 and BDM used, the BDM will have to be redeployed, once the update is done, in order to avoid getting errors in automated processes as the platform will be restarted after the update procedure. -* Do not pause the BPM services or enable the maintenance mode before the update (unless your source version is than is higher than 2021.1). Several bugs affect legacy Bonita versions by preventing a smooth Bonita Runtime update with BPM services paused when: +* Do not pause the BPM services or activate the maintenance mode before the update (unless your source version is than is higher than 2021.1). Several bugs affect legacy Bonita versions by preventing a smooth Bonita Runtime update with BPM services paused when: ** The source version is older than Bonita 7.8.0, and the target version is between Bonita 7.8.0 and Bonita 7.11.5 ** The source version is older than Bonita 7.10.5 and the target version is older than Bonita 2021.1 * Deployed process definitions: The processes will continue to run using the definition created in the previous Bonita version. @@ -270,7 +270,7 @@ For example, db.url=jdbc:mysql://localhost:3306/bonita-update?allowMultiQueries= [WARNING] ==== -*IMPORTANT:* Do *not pause the BPM services* (or enable the maintenance mode) before you stop the application server, unless your Bonita source version is higher than 2021.1, otherwise it will cause problems. +*IMPORTANT:* Do *not pause the BPM services* (or activate the maintenance mode) before you stop the application server, unless your Bonita source version is higher than 2021.1, otherwise it will cause problems. ==== . Stop the application server. diff --git a/modules/version-update/pages/update-with-update-tool.adoc b/modules/version-update/pages/update-with-update-tool.adoc index fa0b3604d1..09a98f4796 100644 --- a/modules/version-update/pages/update-with-update-tool.adoc +++ b/modules/version-update/pages/update-with-update-tool.adoc @@ -251,7 +251,7 @@ For example, db.url=jdbc:mysql://localhost:3306/bonita-update?allowMultiQueries= === Stop Bonita [WARNING] ==== -*IMPORTANT:* Do *not pause the BPM services* (or enable the maintenance mode) before you stop the application server, unless your Bonita source version is higher than 2021.1, otherwise it will cause problems. +*IMPORTANT:* Do *not pause the BPM services* (or activate the maintenance mode) before you stop the application server, unless your Bonita source version is higher than 2021.1, otherwise it will cause problems. ==== . Stop the application server.