### Get Setup Tool Help Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/bonita-platform-setup.adoc Type 'setup help' to get general help or 'setup help ' for detailed assistance on a specific command. ```shell setup help configure ``` -------------------------------- ### List the processes I started Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc This example shows you how to list the open process instances started by the current user. ```APIDOC ## searchOpenProcessInstances (Started by Current User) ### Description Lists the open process instances that were started by the current user. ### Method ```java processAPI.searchOpenProcessInstances(builder.done()); ``` ### Parameters * `builder` (SearchOptionsBuilder) - Configured with search options, including filtering by the user ID. ### Request Example ```java final ProcessAPI processAPI = apiClient.getProcessAPI(); final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100); builder.filter(ProcessInstanceSearchDescriptor.STARTED_BY, apiClient.getSession().getUserId()); final SearchResult processInstanceResults = processAPI.searchOpenProcessInstances(builder.done()); ``` ### Response * `processInstanceResults` (SearchResult) - A search result containing a list of open process instances started by the current user. ``` -------------------------------- ### Configure Bonita Setup Files Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/bonita-as-windows-service.adoc Execute this command to configure the Bonita setup files. These configurations will be copied to the Tomcat installation directory. ```batch %TOMCAT_BUNDLE%/setup/setup.bat configure ``` -------------------------------- ### Start Bonita Platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/install-a-bonita-bpm-cluster.adoc Use this command to start the Bonita Platform on a node after the bundle is configured. ```bash ./start-bonita.sh ``` -------------------------------- ### Enable a process and start an instance Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc Enables a deployed process and then starts a new instance of it. ```APIDOC ## Enable a process and start an instance ### Description Enables a deployed process and then starts a new instance of it. A process must be enabled before an instance can be started. ### Method POST (implied by enableProcess and startProcess operations) ### Endpoint /process/{processDefinitionId} ### Parameters #### Path Parameters - **processDefinitionId** (long) - Required - The ID of the process definition to enable and start. #### Request Body (Not explicitly defined for enableProcess, but startProcess might take operations) ### Request Example ```java // enable the process processAPI.enableProcess(processDefinition.getId()); System.out.println("A new process was enabled: " + processDefinition.getId()); // start the process final ProcessInstance processInstance = processAPI.startProcess(processDefinition.getId()); System.out.println("A new process instance was started with id: " + processInstance.getId()); ``` ### Response #### Success Response (200) - **processInstance** (ProcessInstance) - The newly created process instance. #### Response Example (Response structure not explicitly defined in source, but would contain ProcessInstance details) ``` -------------------------------- ### Start a process Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/create-your-first-project-with-the-engine-apis-and-maven.adoc This snippet demonstrates how to start a new process instance using the Process API. It takes a ProcessDefinition object and returns a ProcessInstance. ```APIDOC ## Start a process ### Description Starts a new process instance based on the provided process definition. ### Method `processAPI.startProcess(processDefinition.getId()) ### Parameters - **processDefinition.getId()** (String) - The ID of the process definition to start. ### Response - **ProcessInstance** - An object representing the newly created process instance. ``` -------------------------------- ### Create a map of variables and values and start a process instance Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc Create a map specifying the values of the variables required to start a case, then pass it to the `instantiateProcess` method. ```APIDOC ## instantiateProcess ### Description Create a map specifying the values of the variables required to start a case, then pass it to the `instantiateProcess` method. ### Method ```java public void instantiateProcess(String processDefinitionName, String processVersion, Map variables) ``` ### Parameters * `processDefinitionName` (String) - The name of the process definition. * `processVersion` (String) - The version of the process definition. * `variables` (Map) - A map of variables and their values to initialize the process instance with. ### Request Example ```java // Example usage: // Map processVariables = new HashMap<>(); // processVariables.put("variableName", "variableValue"); // instantiateProcess("myProcess", "1.0", processVariables); ``` ### Response This method does not return a value directly, but starts a process instance. ``` -------------------------------- ### YAML Process Configuration Example Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/build-run/pages/build-application.adoc Example structure of a YAML file for process parameters, including process name, version, and individual parameters with their values and types. ```yaml --- processes: - name: "Modify Pending Vacation Request" version: "1.4.1" parameters: - name: "calendarApplicationName" value: "Bonitasoft-NewVacationRequest/1.4.0" type: "String" - name: "calendarCalendarId" value: "mydomain.com_4gc5656x7f57cfsrejgb@group.calendar.google.com" type: "String" ``` -------------------------------- ### Start a process instance Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc Starts a new instance of a deployed and enabled process using its definition ID. ```java // start the process final ProcessInstance processInstance = processAPI.startProcess(processDefinition.getId()); System.out.println("A new process instance was started with id: " + processInstance.getId()); ``` -------------------------------- ### Set string variables and start a process instance Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc Starts a process instance and sets string variables using a list of operations. ```APIDOC ## Set string variables and start a process instance ### Description Starts a process instance and sets string variables by converting a map of variables into a list of operations. Each operation is built as an assignment expression. ### Method POST (implied by startProcess operation) ### Endpoint /process/{processDefinitionId}/start ### Parameters #### Path Parameters - **processDefinitionId** (long) - Required - The ID of the process definition to start. #### Query Parameters - **listOperations** (List) - Required - A list of operations to set variable values. - **null** (null) - Optional - Potentially for context or other parameters not detailed. #### Request Body (Not explicitly defined, operations are passed as parameters) ### Request Example ```java public void createInstance(String processDefinitionName, String processVersion, Map variables) { ProcessAPI processAPI; try { processAPI = apiClient.getProcessAPI(); long processDefinitionId = processAPI.getProcessDefinitionId(processDefinitionName, processVersion); List listOperations = new ArrayList<>(); for (String variableName : variables.keySet()) { if (variables.get(variableName) != null) { Operation operation = buildAssignOperation(variableName, variables.get(variableName).toString(), String.class.getName(), ExpressionType.TYPE_CONSTANT); listOperations.add(operation); } } processAPI.startProcess(processDefinitionId, listOperations, null); } catch (Exception e) { e.printStackTrace(); } } private Operation buildAssignOperation(final String dataInstanceName, final String newConstantValue, final String className, final ExpressionType expressionType) throws InvalidExpressionException { final LeftOperand leftOperand = new LeftOperandBuilder().createNewInstance().setName(dataInstanceName).done(); final Expression expression = new ExpressionBuilder().createNewInstance(dataInstanceName).setContent(newConstantValue).setExpressionType(expressionType.name()).setReturnType(className).done(); final Operation operation = new OperationBuilder().createNewInstance().setOperator("=").setLeftOperand(leftOperand).setType(OperatorType.ASSIGNMENT).setRightOperand(expression).done(); return operation; } ``` ### Response #### Success Response (200) (Response details not explicitly defined in source) #### Response Example (Response structure not explicitly defined in source) ``` -------------------------------- ### Oracle Connection URL Example Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/bonita-platform-setup.adoc Example configuration for Oracle connection URLs within the internal.properties file, demonstrating how to add parameters like those needed for Oracle RAC. ```properties oracle.url=jdbc:oracle:thin:@(description=(address_list=(address=(protocol=tcp)(port=${db.server.port})(host=${db.server.name})))(connect_data=(INSTANCE_NAME=${db.database.name}))(source_route=yes)) oracle.bdm.url=jdbc:oracle:thin:@(description=(address_list=(address=(protocol=tcp)(port=${bdm.db.server.port})(host=${bdm.db.server.name})))(connect_data=(INSTANCE_NAME=${bdm.db.database.name}))(source_route=yes)) ``` -------------------------------- ### SAML Troubleshooting Log Example Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/single-sign-on-with-saml.adoc Example log output indicating an issue with the SP signing key lacking a PublicKey or Certificate. ```log 2018-10-10 13:22:45,921 SEVERE [org.bonitasoft.console.common.server.sso.filter.InternalSSOFilter] (default task-1) java.lang.RuntimeException: Sp signing key must have a PublicKey or Certificate defined: java.lang.RuntimeException: java.lang.RuntimeException: Sp signing key must have a PublicKey or Certificate defined at org.keycloak.adapters.saml.config.parsers.DeploymentBuilder.build(DeploymentBuilder.java:119) at org.bonitasoft.console.common.server.auth.impl.saml.BonitaSAML2Filter.getSamlDeployment(BonitaSAML2Filter.java:174) (...) Caused by: java.lang.RuntimeException: Sp signing key must have a PublicKey or Certificate defined at org.keycloak.adapters.saml.config.parsers.DeploymentBuilder.build(DeploymentBuilder.java:115) ... 51 more ``` -------------------------------- ### Download and Extract platform-setup-sp Tool Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/version-update/pages/upgrade-from-community-to-a-subscription-edition.adoc Use this Maven command to download the platform-setup-sp tool. Replace `` with your target Bonita version. The tool is extracted to the current directory. ```shell mvn dependency:copy -Dartifact=com.bonitasoft.platform:platform-setup-sp::zip -DoutputDirectory=. unzip platform-setup-sp-.zip -d ``` -------------------------------- ### YAML Process Configuration with Global Parameters Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/build-run/pages/build-application.adoc Example demonstrating how to configure parameters for specific processes and also define global parameters that apply to all processes. ```yaml --- processes: - name: "P1" version: "1.4.1" parameters: - name: "calendarApplicationName" value: "Bonitasoft-NewVacationRequest/1.4.0" type: "String" - name: "emailNotificationSender" value: "cancelvacationconfirmation@mail.com" type: "String" - name: "P2" version: "1.4.1" parameters: - name: "calendarApplicationName" value: "Bonitasoft-NewVacationRequest/1.4.0" type: "String" - name: "P3" version: "1.4.1" parameters: - name: "calendarApplicationName" value: "Bonitasoft-NewVacationRequest/1.4.0" type: "String" global_parameters: ``` -------------------------------- ### List the groups in an organization Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-an-organization.adoc This example shows how to get a list of groups in the current organization. The search options specify that a maximum of 100 items are listed, starting with the first one. Only one organization can be loaded in Bonita Engine at a time, so there is no need to specify the organization, and no organization identifier exists. ```APIDOC ## List the groups in an organization ### Description This example shows how to get a list of groups in the current organization. The search options specify that a maximum of 100 items are listed, starting with the first one. Only one organization can be loaded in Bonita Engine at a time, so there is no need to specify the organization, and no organization identifier exists. ### Code ```groovy final IdentityAPI identityAPI = TenantAPIAccessor.getIdentityAPI(apiSession); final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100); final SearchResult groupResults = identityAPI(apiSession).searchGroups(builder.done()); ``` ``` -------------------------------- ### Start Bonita Enterprise Runtime Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/version-update/pages/upgrade-from-community-to-a-subscription-edition.adoc Start the upgraded Bonita Enterprise Runtime. This command is executed from the Enterprise installation directory. ```shell /start-bonita(.sh/.bat) ``` -------------------------------- ### Initialize Bonita Platform Database Tables Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/bonita-platform-setup.adoc Use the 'init' command to create database tables and push initial configuration. This prepares the Runtime for a first start but does not initialize the default tenant. You can specify the database vendor using -D properties. ```bash setup.sh init ``` ```bash setup.sh init -Ddb.vendor=postgres ``` -------------------------------- ### API Permissions Structure Example Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/api-permissions-overview.adoc This example demonstrates the expected structure for listing API permissions for a given profile or user. It includes sections for general information, accessible pages, permissions, and specific API access (GET, POST). ```adoc = Profile 1 General profile information == Accessible pages * accessible page 1 for profile or user 1 * accessible page 2 for profile or user 1 ... == Accessible permissions * permission 1 * permission 2 ... == Accessible APIs * GET ** API 1 ** API 2 ... * POST ** API 1 ** API 2 ... ``` -------------------------------- ### Example README.md for Bonita Extension Library Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/software-extensibility/pages/custom-library-development.adoc A sample README.md file for your project, including build and license badges, and a brief description. Customize the owner and paths as needed. ```markdown # Bonita extension library ![Build](https://github.com//bonita-extension-library/workflows/build/badge.svg) ![Coverage](.github/badges/jacoco.svg) [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-yellow.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) This library provide a set of additional functions to deal with Bonita users. ## How to build ``` -------------------------------- ### Example Dynamic Check Script for Case Permissions Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/rest-api-authorization.adoc This Groovy script provides an example of a custom dynamic check for case-related API calls. It differentiates behavior based on the HTTP method (GET or POST) and checks user involvement or eligibility. ```groovy import org.bonitasoft.engine.api.* import org.bonitasoft.engine.api.permission.APICallContext import org.bonitasoft.engine.api.permission.PermissionRule import org.bonitasoft.engine.bpm.process.ArchivedProcessInstanceNotFoundException import org.bonitasoft.engine.identity.User import org.bonitasoft.engine.identity.UserSearchDescriptor import org.bonitasoft.engine.search.SearchOptionsBuilder import org.bonitasoft.engine.search.SearchResult import org.bonitasoft.engine.session.APISession import org.json.JSONObject class CasePermissionRule implements PermissionRule { @Override boolean isAllowed(APISession apiSession, APICallContext apiCallContext, APIAccessor apiAccessor, Logger logger) { long currentUserId = apiSession.getUserId() if ("GET".equals(apiCallContext.getMethod())) { return checkGetMethod(apiCallContext, apiAccessor, currentUserId, logger) } else if ("POST".equals(apiCallContext.getMethod())) { return checkPostMethod(apiCallContext, apiAccessor, currentUserId, logger) } return false } private boolean checkPostMethod(APICallContext apiCallContext, APIAccessor apiAccessor, long currentUserId, Logger logger) { def body = apiCallContext.getBodyAsJSON() def processDefinitionId = body.optLong("processDefinitionId") ``` -------------------------------- ### Create the platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-the-platform.adoc Create the platform's database structure and persist the platform state. This is a prerequisite for initializing the platform. ```bash // Create the platform platformAPI.createPlatform(); ``` -------------------------------- ### Recovery Mechanism Log Output Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/fault-tolerance.adoc Example log messages indicating the start, progress, and completion of the recovery process for flow nodes. ```log INFO (internalTasksScheduler-1) org.bonitasoft.engine.tenant.restart.RecoveryMonitor Start detecting flow nodes to restart... INFO (internalTasksScheduler-1) org.bonitasoft.engine.tenant.restart.RecoveryMonitor Recovery of elements executed, 12006 elements recovered. INFO (internalTasksScheduler-1) org.bonitasoft.engine.tenant.restart.RecoveryMonitor Restarting elements...Handled 1000 of 12006 elements candidates to be recovered in PT0.025S [...] INFO (internalTasksScheduler-1) org.bonitasoft.engine.tenant.restart.RecoveryMonitor Restarting elements...Handled 12000 of 12006 elements candidates to be recovered in PT0.452S INFO (internalTasksScheduler-1) org.bonitasoft.engine.tenant.restart.RecoveryMonitor Recovery of elements executed, 12006 elements recovered. ``` -------------------------------- ### Stop Bonita Community Platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/version-update/pages/upgrade-from-community-to-a-subscription-edition.adoc Stop the Bonita Community platform before starting the Enterprise version. This command is specific to the Community installation directory. ```shell /stop-bonita(.sh/.bat) ``` -------------------------------- ### Create a new user Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-users.adoc This example shows how to create a new user with basic credentials and assign the user to a profile. It also demonstrates creating a more complex user object with detailed contact information. ```APIDOC ## Create a new user This example shows how to create a new user and assign the user to a profile. *Create a new user* by calling the createUser method: [source,groovy] ---- // First of all, let's log in on the engine: org.bonitasoft.engine.api.APIClient apiClient = new APIClient() apiClient.login("install", "install") // create new user, with username john and password bpm IdentityAPI identityAPI = apiClient.getIdentityAPI() final User user = identityAPI.createUser("john", "bpm") System.out.println("New user created: " + user) ---- Alternatively, you can create a more complex user object as follows: [source,groovy] ---- // create complex user UserCreator creator = new UserCreator("john", "bpm") creator.setFirstName("Johnny").setLastName("B. Good") ContactDataCreator proContactDataCreator = new ContactDataCreator().setAddress("32 rue Gustave Eiffel").setCity("Grenoble").setPhoneNumber("555 14 12 541") creator.setProfessionalContactData(proContactDataCreator) final User user2 = identityAPI.createUser(creator) ---- Now add the user to a Bonita profile. A user who does not have a profile cannot log into Bonita Runtime. [source,groovy] ---- // The user must now be registered in a profile. Let's choose the existing "User" profile: org.bonitasoft.engine.api.ProfileAPI orgProfileAPI = apiClient.getProfileAPI() SearchOptionsBuilder searchOptionsBuilder = new SearchOptionsBuilder(0,10) searchOptionsBuilder.filter(ProfileSearchDescriptor.NAME, "User") SearchResult searchResultProfile = orgProfileAPI.searchProfiles(searchOptionsBuilder.done()) // we should find one result now if (searchResultProfile.getResult().size() != 1) { return } // now register the user in the profile Profile profile = searchResultProfile.getResult().get(0) ProfileMemberCreator profileMemberCreator = new ProfileMemberCreator( profile.getId() ) profileMemberCreator.setUserId( user.getId() ) orgProfileAPI.createProfileMember(profileMemberCreator) ---- To create a user with more complete information, use the UserBuilder to create an instance of User and then use the createUser method with the User as parameter. ``` -------------------------------- ### Deploy and Manage Processes Source: https://context7.com/bonitasoft/bonita-doc/llms.txt Demonstrates deploying a process from a .bar file, mapping actors, enabling the process, starting instances, and deleting processes and their instances. ```APIDOC ## Deploy and Manage Processes (ProcessAPI) `ProcessAPI` covers the full process management lifecycle: deploying a `.bar` archive, mapping actors to users, enabling/disabling processes, starting instances with initial variables, executing tasks, and deleting processes with all their instances. ```java import org.bonitasoft.engine.api.ProcessAPI; import org.bonitasoft.engine.bpm.bar.BusinessArchive; import org.bonitasoft.engine.bpm.bar.BusinessArchiveFactory; import org.bonitasoft.engine.bpm.process.ProcessDefinition; import org.bonitasoft.engine.bpm.process.ProcessInstance; import org.bonitasoft.engine.bpm.actor.ActorInstance; import org.bonitasoft.engine.bpm.actor.ActorCriterion; import java.io.File; import java.util.List; ProcessAPI processAPI = apiClient.getProcessAPI(); // --- Deploy from a .bar file --- BusinessArchive archive = BusinessArchiveFactory.readBusinessArchive(new File("/deploy/travelRequest.bar")); ProcessDefinition processDef = processAPI.deployAndEnableProcess(archive); System.out.println("Deployed and enabled process id: " + processDef.getId()); // --- OR: deploy, map actor, then enable separately --- ProcessDefinition pd = processAPI.deploy(archive); List actors = processAPI.getActors(pd.getId(), 0, 1, ActorCriterion.NAME_ASC); processAPI.addUserToActor(actors.get(0).getId(), apiClient.getSession().getUserId()); processAPI.enableProcess(pd.getId()); // --- Start a process instance --- ProcessInstance instance = processAPI.startProcess(pd.getId()); System.out.println("Started process instance: " + instance.getId()); // --- Disable and fully delete a process (instances must be purged first) --- processAPI.disableProcess(pd.getId()); while (processAPI.deleteProcessInstances(pd.getId(), 0, 100) > 0) { } while (processAPI.deleteArchivedProcessInstances(pd.getId(), 0, 100) > 0) { } processAPI.deleteProcessDefinition(pd.getId()); ``` ``` -------------------------------- ### Get Design Process Definition Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc Retrieve the definition of a deployed process. This example first deploys and enables a process, then retrieves its design definition. ```java // Create a process definition final ProcessDefinitionBuilder processBuilder = new ProcessDefinitionBuilder().createNewInstance("name", "1.0"); processBuilder.addDescription("description"); processBuilder.addAutomaticTask("AutomaticTask"); // Deploy and enable the process final ProcessDefinition processDefinition = getProcessAPI().deploy( new BusinessArchiveBuilder().createNewBusinessArchive().setProcessDefinition(processBuilder.done()).done()); getProcessAPI().enableProcess(processDefinition.getId()); // Get the design process definition final DesignProcessDefinition resultDesignProcessDefinition = getProcessAPI().getDesignProcessDefinition(processDefinition.getId()); ``` -------------------------------- ### Example Application Archive Structure Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/bcd/pages/deployer.adoc Illustrates the typical directory and file structure of an application archive used for deployment. ```text 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 ``` -------------------------------- ### List Groups in Organization Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-an-organization.adoc Retrieves a list of groups within the current organization. This example sets a limit of 100 items starting from the first. ```groovy final IdentityAPI identityAPI = TenantAPIAccessor.getIdentityAPI(apiSession); final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100); final SearchResult groupResults = identityAPI(apiSession).searchGroups(builder.done()); ``` -------------------------------- ### List open process instances Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/create-your-first-project-with-the-engine-apis-and-maven.adoc This example shows how to retrieve a list of currently open process instances. It handles pagination by retrieving instances page by page. ```APIDOC ## List open process instances ### Description Retrieves a paginated list of open process instances. The results are sorted by process instance ID in ascending order. ### Method `processAPI.searchProcessInstances(optionsBuilder.done()) ### Parameters - **startIndex** (int) - The starting index for retrieving the page of results. - **PAGE_SIZE** (int) - The maximum number of elements to retrieve per page. ### Response - **SearchResult** - A search result object containing a list of open process instances for the requested page. ``` -------------------------------- ### Get user contact data Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-users.adoc This example shows how to retrieve a user's professional contact data, including their email address, using the `getUserWithProfessionalDetails` method. ```APIDOC ## Get user contact data You can use the `getUserWithProfessionalDetails` method to retrieve a user and their professional contact data for a user. This example shows how to get a user and the email address. [source,groovy] ---- // Get the professional email address of a user UserWithContactData proUser = apiClient.getIdentityAPI().getUserWithProfessionalDetails(user.getId()) proUser.getContactData().getEmail() ---- ``` -------------------------------- ### Page Properties for REST API Extension Resources Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/rest-api-extension-archetype.adoc Declare REST API Extension resources in the page.properties file to grant access to users. This example shows how to include GET, POST, and PUT extensions. ```properties resources=[GET|extension/demoHeaders,POST|extension/demoXml,PUT|extension/putResource] ``` -------------------------------- ### Apache 2 reverse proxy configuration for Bonita Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/reverse-proxy-configuration.adoc An example Apache VirtualHost configuration file for proxying requests to a Bonita backend server. This setup redirects all requests to the Bonita application and handles URL rewriting. ```xml ServerAdmin webmaster@localhost ServerName your_domain ServerAlias www.your_domain.com DocumentRoot /var/www/your_domain ErrorLog ${APACHE_LOG_DIR}/error.log CustomLog ${APACHE_LOG_DIR}/access.log combined RewriteEngine on RewriteRule "^(?!/bonita)(.*)$" "/bonita$1" [R,L] RewriteRule "^/(.*)" "http://127.0.0.1:8080/$1" [P] ProxyRequests Off Order deny,allow Allow from all ProxyPass / http://127.0.0.1:8080/ ProxyPassReverse / http://127.0.0.1:8080/ Order allow,deny Allow from all ``` -------------------------------- ### Copy License File and Push to Platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/version-update/pages/update-with-migration-tool.adoc Use this command to copy your new license file into the platform's license directory and then push the updated configuration. ```bash cp BonitaSubscription-7.n-Jerome-myHosname-20171023-20180122.lic ./platform_conf/licenses/ ./setup.sh push ``` -------------------------------- ### Pull Bonita Platform Configuration Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/runtime/pages/licenses.adoc Use the setup tool to download the current platform configuration from the database. This is a prerequisite for modifying license files. ```bash cd setup ./setup.sh pull ``` -------------------------------- ### Custom Authorization Rule Mapping Implementation Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/custom-authorization-rule-mapping.adoc Implements the `AuthorizationRuleMapping` interface to specify which custom rules apply to different process actions. This example maps a single custom rule to process start, overview, and task actions. ```java package org.bonitasoft.example.authorization; import java.util.Arrays; import java.util.List; import org.bonitasoft.engine.core.form.AuthorizationRuleMapping; public class CustomAuthorizationRuleMapping implements AuthorizationRuleMapping { @Override public List getProcessStartRuleKeys() { return Arrays.asList("CUSTOM_RULE_UNIQUE_ID"); } @Override public List getProcessOverviewRuleKeys() { return Arrays.asList("CUSTOM_RULE_UNIQUE_ID"); } @Override public List getTaskRuleKeys() { ``` -------------------------------- ### Client-side JavaScript for CORS Demo Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/security/pages/enable-cors-in-tomcat-bundle.adoc This JavaScript code demonstrates how to perform cross-origin requests to a Bonita server. It includes functions for logging in, retrieving an API token, getting the user ID, and updating a user's password. This example is useful when CSRF security is enabled and requires specific headers like 'X-Bonita-API-Token'. ```javascript var bonitaServerPath; function loginToBonita() { var myHeaders = new Headers(); myHeaders.append("Content-Type", "application/x-www-form-urlencoded"); var urlencoded = new URLSearchParams(); urlencoded.append("username", document.getElementById("username").value); urlencoded.append("password", document.getElementById("current-password").value); urlencoded.append("redirect", "false"); var requestOptions = { method: 'POST', headers: myHeaders, body: urlencoded, redirect: 'follow', credentials: 'include' }; return fetch(bonitaServerPath + "/loginservice", requestOptions) .then(result => { if (!result.ok) { throw Error(result.status); } return getAuthToken();}) .catch(error => {document.getElementById("error").innerHTML += "
⚠ Login error. " + error;}); }; function getAuthToken() { var myHeaders = new Headers(); var requestOptions = { method: 'GET', headers: myHeaders, credentials: 'include' }; return fetch(bonitaServerPath + "/API/system/session/unusedId", requestOptions) .then(response => { if (!response.ok) { throw Error(response.status); } return response.headers.get("x-bonita-api-token");}) .catch(error => {document.getElementById("error").innerHTML += "
⚠ Unable to retrieve authentication token from session. " + error;}); }; function getUserId() { var myHeaders = new Headers(); var requestOptions = { method: 'GET', headers: myHeaders, credentials: 'include' }; return fetch(bonitaServerPath + "/API/system/session/unusedId", requestOptions) .then(response => { if (!response.ok) { throw Error(response.status); } return response.json();}) .then(body => body.user_id) .catch(error => {document.getElementById("error").innerHTML += "
⚠ Unable to retrieve UserId from session. " + error;}); }; function updatePassword(authToken) { var formData = {"password": document.getElementById("new-password").value} var myHeaders = new Headers(); myHeaders.append("X-Bonita-API-Token", authToken); myHeaders.append("Content-Type", 'application/json'); var requestOptions = { method: 'PUT', headers: myHeaders, credentials: 'include', body: JSON.stringify(formData) }; return getUserId().then(userId => fetch(bonitaServerPath + "/API/identity/user/" + userId, requestOptions) .then(response => { if (!response.ok) { throw Error(response.status); } return response.text();}) .then(result => {document.getElementById("success").innerHTML = "✓ Password updated!"}) .catch(error => {document.getElementById("error").innerHTML += "
⚠ Unable to update the password. " + error;})); }; function submit() { document.getElementById("success").innerHTML = ""; document.getElementById("error").innerHTML = ""; bonitaServerPath = document.getElementById("bonita-server-path").value; loginToBonita().then(authToken => updatePassword(authToken)); }; ``` -------------------------------- ### Basic Maven pom.xml setup Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/software-extensibility/pages/custom-library-development.adoc Initializes a Maven project for a Bonita extension library. Configure groupId, artifactId, and Java version. Ensure internet connection for Maven Central. ```xml 4.0.0 org.bonitasoft.extension <1> bonita-extension-library <1> 1.0.0-SNAPSHOT Bonita extension function library UTF-8 UTF-8 11 ${java.version} ${java.version} ``` -------------------------------- ### Initialize the platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-the-platform.adoc Initialize the Bonita Engine environment by creating the default tenant. After this step, the technical user can connect to the engine. ```bash // Initialize the platform platformAPI.initializePlatform(); ``` -------------------------------- ### Install Homebrew on macOS Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/ROOT/pages/bonita-studio-download-installation.adoc Use this command to install Homebrew, a package manager for macOS, if it's not already installed. This is a prerequisite for installing JDKs via Homebrew. ```bash # Install brew first if it is not installed yet, more details here: https://brew.sh /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` -------------------------------- ### Install Graphviz on macOS Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/best-practices/pages/project-documentation-generation.adoc Use Homebrew to install and link Graphviz on macOS. Ensure libtool is also installed and linked. ```shell brew install libtool brew link libtool brew install graphviz brew link --overwrite graphviz ``` -------------------------------- ### Install BDM artifacts locally with Maven Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/data/pages/define-and-deploy-the-bdm.adoc Use this command to install the BDM model and DAO client artifacts into your local Maven repository. Ensure Maven and Java are installed. ```shell $ mvn install ``` -------------------------------- ### Check if User Can Start Process Definition Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/rest-api-authorization.adoc Verifies if a user has the permission to start a specific process definition. It checks if the user is involved in the process and if the count of users who can start matches one. ```Groovy if (processDefinitionId <= 0) { return false; } def processAPI = apiAccessor.getProcessAPI() def identityAPI = apiAccessor.getIdentityAPI() User user = identityAPI.getUser(currentUserId) SearchOptionsBuilder searchOptionBuilder = new SearchOptionsBuilder(0, 10) searchOptionBuilder.filter(UserSearchDescriptor.USER_NAME, user.getUserName()) SearchResult listUsers = processAPI.searchUsersWhoCanStartProcessDefinition(processDefinitionId, searchOptionBuilder.done()) logger.debug("RuleCase : nb Result [" + listUsers.getCount() + "] ?") def canStart = listUsers.getCount() == 1 logger.debug("RuleCase : User allowed to start? " + canStart) return canStart ``` -------------------------------- ### Start Bonita engine Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-the-platform.adoc Starting the engine on a node starts the Scheduler service and restarts elements that were not finished by the Work service on the previous shutdown. Bonita Engine environment is marked as activated. ```APIDOC ## Start Bonita engine ### Description Starts the Bonita Engine on a node, activating the Scheduler service and resuming unfinished work. The environment is marked as activated. ### Method Not applicable (Java SDK) ### Endpoint Not applicable (Java SDK) ### Code Example ```java // Start the execution engine platformAPI.startNode(); ``` ``` -------------------------------- ### GET API Endpoints Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/identity/pages/admin-api-permissions.adoc Lists all GET endpoints accessible to the Administrator profile. ```APIDOC ## GET API Endpoints ### Description These endpoints allow retrieval of various resources related to identity, processes, cases, and system configurations. ### Endpoints * identity/user * identity/personalcontactdata * identity/professionalcontactdata * identity/role * identity/group * identity/membership * customuserinfo/user * customuserinfo/definition * customuserinfo/value * bpm/process * bpm/process/*/contract * bpm/processConnector * bpm/processConnectorDependency * bpm/processParameter * bpm/processSupervisor * bpm/actor * bpm/actorMember * bpm/category * bpm/processResolutionProblem * bpm/case * bpm/case/*/context * bpm/caseInfo * bpm/comment * bpm/archivedComment * bpm/archivedCase * bpm/archivedCase/*/context * bpm/caseVariable * bpm/caseDocument * bpm/flowNode * bpm/activity * bpm/task * bpm/humanTask * bpm/userTask * bpm/userTask/*/contract * bpm/userTask/*/context * bpm/manualTask * bpm/activityVariable * bpm/connectorInstance * bpm/archivedFlowNode * bpm/archivedActivity * bpm/archivedTask * bpm/archivedHumanTask * bpm/archivedUserTask * bpm/archivedUserTask/*/context * bpm/archivedManualTask * bpm/archivedConnectorInstance * bpm/document * bpm/archiveddocument * bpm/archivedCaseDocument * bpm/connectorFailure * bpm/timerEventTrigger * bpm/diagram * portal/profile * portal/bonitaPage * portal/page * portal/profileMember * system/session * system/log * system/tenant * system/feature * system/license * system/monitoring * system/i18nlocale * system/i18ntranslation * platform/platform * platform/jvmDynamic * platform/jvmStatic * platform/systemProperty * platform/tenant * tenant/bdm * living/application * living/application-page * living/application-menu * bdm/businessData * bdm/businessDataReference * bdm/businessDataQuery * accessControl/bdm * form/mapping * API/avatars * portal/custom-page/API/avatars * API/documentDownload * portal/custom-page/API/documentDownload * portal/documentDownload * API/formsDocumentImage * portal/custom-page/API/formsDocumentImage * portal/formsDocumentImage * portal/custom-page/API/formsDocumentDownload * portal/formsDocumentDownload * portal/exportOrganization * API/exportOrganization * portal/custom-page/API/exportOrganization * portal/pageDownload * API/pageDownload * portal/exportProfiles * API/exportProfiles * portal/exportAccessControl * API/applicationIcon * portal/downloadDocument * portal/custom-page/API/downloadDocument ``` -------------------------------- ### List the open instances of a process Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-a-process.adoc This example shows you how to list the open instances of a specified process. ```APIDOC ## searchOpenProcessInstances (Specific Process) ### Description Lists the open instances of a specified process, identified by its process definition ID. ### Method ```java processAPI.searchOpenProcessInstances(builder.done()); ``` ### Parameters * `processDefinitionId` (long) - The ID of the process definition to list instances for. * `builder` (SearchOptionsBuilder) - Configured with search options, including filtering by the process definition ID. ### Request Example ```java final ProcessAPI processAPI = apiClient.getProcessAPI(); final long processDefinitionId = 456; // Replace with a valid process definition ID final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100); builder.filter(ProcessInstanceSearchDescriptor.PROCESS_DEFINITION_ID, processDefinitionId); final SearchResult processInstanceResults = processAPI.searchOpenProcessInstances(builder.done()); ``` ### Response * `processInstanceResults` (SearchResult) - A search result containing a list of open process instances for the specified process definition. ``` -------------------------------- ### Login and Search Users with APIClient Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-users.adoc Demonstrates how to initialize APIClient, log in, and search for users. Ensure APIClient is properly initialized before use. ```java public static void main(final String[] args) throws Exception { // example code: APIClient apiClient = new APIClient() System.out.println("login with install//install") apiClient.login("install", "install") final IdentityAPI identityAPI = apiClient.getIdentityAPI() final SearchResult searchUsers = identityAPI.searchUsers(new SearchOptionsBuilder(0, 20).done()) System.out.println("20 first users:") for (final User user : searchUsers.getResult()) { System.out.println(" * " + user.getUserName() + " -- " + user.getId()) } apiClient.logout() System.out.println("logged out") } } ``` -------------------------------- ### Create the platform Source: https://github.com/bonitasoft/bonita-doc/blob/2023.2/modules/api/pages/manage-the-platform.adoc This will create the database structure and put the platform state into persistent storage. ```APIDOC ## Create the platform ### Description Creates the database structure and initializes the platform's persistent storage. ### Method Not applicable (Java SDK) ### Endpoint Not applicable (Java SDK) ### Code Example ```java // Create the platform platformAPI.createPlatform(); ``` ```