Configuring Business Central settings and properties
Abstract
Preface
As an administrator, you can customize the following on the admin Settings page:
- Roles: Set the home page, priority, and permissions of a role.
- Groups: Set the home page, priority, and permissions of a group as well as create and delete groups.
- Users: Create and delete users, add or remove groups and roles from users, and view user permissions.
- Artifacts: View M2 repository artifacts, upload artifacts, view, and download JAR files.
- Data Sources: Add, update, or delete data sources and database drivers.
- Data Sets: Create, modify, or delete data sets.
- Projects: View and edit project preferences such as file export properties, space properties, default values, and advanced GAV properties.
- Artifact Repository: Manage artifact repository properties.
- Languages: Set the Business Central language.
- Process Administration: Set the default pagination option in Business Central.
- Process Designer: Set diagram editor properties.
- SSH Keys: Add or delete SSH keys.
- Service Tasks Administration: Enable or disable default service tasks and upload custom service tasks.
- Profiles: Set the workbench profile as Planner and Rules or Full.
- Archetype: View, add, validate, set as default, and delete the archetypes. Used as a template when creating a new project in Business Central.
Prerequisites
- Red Hat JBoss Enterprise Application Platform 7.3.0 is installed. For more information, see Red Hat JBoss Enterprise Application Platform 7.3 Installation Guide.
- Red Hat Process Automation Manager is installed and running. For more information, see Installing and configuring Red Hat Process Automation Manager on Red Hat JBoss EAP 7.3.
-
You are logged in to Business Central with the
admin
user role.
Chapter 1. User management
Business Central defines three types of entities for security management: users, groups, and roles. You can assign permissions to both roles and groups. You can assign the following roles in Business Central:
- process-admin
- manager
- admin
- analyst
- developer
- user
User roles in the application Role Registry have a role identifier, whereas user groups do not.
Use Business Central to create and manage as many users and groups as you require. A user must be assigned to at least one user-specific role to log in to Business Central. User privileges depend on permissions from the groups and roles that the user is a member of. Note that the role or group priority is considered if a user has several roles or groups assigned to it.
1.1. Creating users
User privileges and settings are controlled by the roles assigned to a user and the groups that a user belongs to. You can create any number of users in Business Central.
Do not create a user called unknown
in process engine or KIE Server. The unknown
user account is a reserved system name with superuser access. The unknown
user account performs tasks related to the SLA violation listener when there are no users logged in.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Users.
- Click New user, enter a user name, and then click Next.
- To assign roles to the user, click the Roles tab, click Add Roles, select the desired roles, and click Add to selected roles.
- Optionally, to assign groups to the user, click the Groups tab, click Add to groups, select the desired groups, and click Add to selected groups.
- Click Create.
- Click Yes to set a password for the user, enter a desired password, and click Change.
The user must have at least one role to access Business Central.
1.2. Editing users
You can change the group and role of a user using the Users option on the Business Central Settings page. All user permissions are based on the group and role permissions of the user. You can view the user permissions from the Permissions tab.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Users.
- From the All users list, click the user you want to edit. The user details display in the right pane.
Click Edit to perform any of the following tasks:
- To change the groups of a user, click the Groups tab, click Add to groups, select the groups you want the user to be part of, click Add to selected groups, and click Save.
- To change the roles of a user, click the Roles tab, click Add roles, select the roles you want to assign to the user, click Add to selected roles, and click Save.
- To view the user permissions, click the Permissions tab and expand the attributes.
- To change the password, click Change Password, enter the new password, and click Change.
- To delete the user, click Delete and then click Yes to confirm removal.
1.3. Creating groups
In Business Central, you can use groups to control permissions for a collection of users. You can create as many groups as you want but a group must have at least one user.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Groups.
- Click New group, enter a group name, and then click Next.
Select the users that you want to add to this group, and then click Add selected users.
The newly created group is listed under All groups.
1.4. Editing groups
You can edit the attribute of a group such as home page, priority, and permissions according to your requirements. From the Groups option on the Business Central Settings page, you can modify or delete a group.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Groups.
- From the All groups list, click the group that you want to edit. The user details display in the right pane.
- Select the home page from the Home Page list.
- Select the priority from the Priority list.
In the Permissions section, expand the resource attribute and change its permission.
NoteYou can add exceptions to Pages, Editor, Spaces, and Projects permissions.
- Click Save to apply the changes.
Chapter 2. Security management
You can perform security and permission management tasks from the Security management page. To access the Security management page, select the Admin icon in the top-right corner of the screen and click Roles, Groups, or Users on the Business Central Settings page. Depending on which icon you click, the Security management page opens for the respective tab. Use roles and groups to manage privileges and settings for users. Any changes apply to all users with the affected role or group.
2.1. Changing permissions for groups and roles
You cannot change permissions for an individual user. However, you can change permissions for groups and roles. The changed permissions apply to users that have the role or belong to the group that you changed.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen.
- Click Roles or Groups to open the corresponding list.
- From the list, click the role or group you want to edit. All details are displayed in the right pane.
- Set the Home Page or Priority under the Settings section.
Set the Business Central, page, editor, space, and project permissions under the Permissions section.
You can expand the resource type whose permissions you want to change.
Optional: To add an item not listed, click Add Exception and then set the permissions as required.
NoteYou cannot add an exception to the Business Central resource type.
- Click Save.
Any changes that you make to roles or groups affect all of the users associated with that role or group.
If a user is a member of multiple groups that have the same priority and the groups have conflicting permission settings, the positive permissions override the negative permissions. You can verify the permission settings in Business Central by clicking the Admin icon in the top-right corner, select Users, and view each user’s group assignments and permissions.
Chapter 3. Artifact management
You can manage artifacts from the Artifacts page in Business Central. The artifact repository is a local Maven repository and there is only one Maven repository for each installation. Business Central recommends using Maven repository solutions like Sonatype Nexus™, Apache Archiva™, or JFrog Artifactory™.
The Artifacts page lists all the artifacts in the Maven repository. You can upload artifacts to the Maven repository.
You can only upload JAR, KJAR, and pom.xml
files to the Artifacts repository.
3.1. Viewing an artifact
You can view all the content of the local maven repository from the Artifacts page.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts.
- Click Open to view the artifact details.
- Click Ok to go back to the Artifacts page.
3.2. Downloading an artifact
You can download and save an artifact from Business Central repository to the local storage of a project.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts.
- Click Download.
- Browse to the directory where you want to save the artifact.
- Click Save.
3.3. Uploading an artifact
You can upload an artifact from the local storage to a project in Business Central.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts.
- Click Upload.
- Click Choose File and browse to the directory from where you want to upload the artifact.
Click Upload.
NoteIf you are using a non-Maven artifact, first deploy the artifact to the Maven repository using the
mvn deploy
command and then refresh the artifact list in Business Central.
Chapter 4. Data source management
Business Central provides data source management features that enable you to define data sources for accessing a database. These data sources are then used by other Business Central components such as the data sets. A database driver enables communication between a data source and the targeted database.
From the Data Source Authoring page you can add data sources and database drivers to Business Central.
Business Central provides a default data source that can be used but cannot be edited or deleted.
4.1. Adding a database driver
You can add a new database driver to Business Central.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, click Add Driver. The New driver window opens.
- In the New driver window, enter the Name, Driver Class Name, Group Id, Artifact Id, and Version of the database driver.
- Click Finish to add the driver to Business Central.
4.2. Editing a database driver
You can update the properties of a database driver from the Driver Definition pane.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, select the driver you want to edit.
- In the Driver Definition pane, make the necessary changes to the Name, Driver Class Name, Group Id, Artifact Id, and the Version fields.
- Click Update.
- Click Yes to save the changes to the driver.
4.3. Deleting a database driver
You can remove database drivers from the Data Source Definition pane of Business Central.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, select the driver you want to delete.
- Click Remove.
- Click Delete to delete the driver.
4.4. Adding a data source
You can add a new data source to Business Central from the Data Sources Authoring page.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, click Add DataSource. The New data source window opens.
- In the New data source window, enter the data source Name, database Connection URL, User and Password, and Driver.
- Click Test Connection to verify the connection to the database.
- Click Finish to add the data source to Business Central.
4.5. Editing a data source
You can edit the properties of a data source and also test its connection to the database in Business Central.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, click the data source you want to edit.
- In the Data Source Definition pane, make the necessary changes to the Name, Connection URL, User, Password, and the Driver fields.
- Click Test Connection to verify the connection to the database.
- Click Update.
- Click Save to confirm the changes to the data source.
4.6. Deleting a data source
You can delete an existing data source from the DataSource Explorer pane in Business Central.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Data Sources.
- In the DataSource Explorer pane, click the data source you want to delete.
- Click Remove.
- Click Delete to confirm the deletion of the data source.
Chapter 5. Data sets authoring
A data set is a collection of related sets of information. It can be stored in many ways, such as in a database, in a Microsoft Excel file, or in memory. A data set definition instructs Business Central methods to access, read, and parse a data set. Business Central does not store data. It enables you to define access to a data set regardless of where the data is stored.
For example, if data is stored in a database, a valid data set could contain the entire database or a subset of the database as a result of an SQL query. In both cases, the data is used as input for the reporting components of Business Central which then displays the information.
To access a data set, you must create and register a data set definition. This data set definition specifies the location of the data set, the ways to access it, read it, and parse it, and the columns that it contains.
The Data Sets page is visible only to users with the admin role.
5.1. Adding data sets
You can create a data set to fetch data from an external data source and use that data for the reporting components.
Procedure
- In Business Central, go to Admin → Data Sets. The Data Set Explorer page opens.
Click New Data Set and select one of the following provider types:
- Bean: Use to generate a data set from a Java class
- CSV: Use to generate a data set from a remote or local CSV file
- SQL: Use to generate a data set from an ANSI-SQL compliant database
- Elastic Search: Use to generate a data set from Elastic Search nodes
Execution Server: Use to generate a data set using the custom query feature of an Execution Server
NoteKIE Server must be configured with this option.
Complete the Data Set Creation Wizard and click Test.
NoteThe configuration steps differ based on the provider you chose.
- Click Save.
5.2. Editing data sets
You can edit existing data sets to ensure that the data fetched to the reporting components is up-to-date.
Procedure
- In Business Central, go to Admin → Data Sets. The Data Set Explorer page opens.
- In the Data Set Explorer pane, search for the data set you want to edit and click Edit.
In the Data Set Editor pane, use the appropriate tab to edit the data as required. The tabs differ based on the data set provider type you chose.
For example, the following changes are applicable for editing a CSV data provider:
- CSV Configuration: Enables you to change the name of the data set definition, the source file, the separator, and other properties.
Preview: Enables you to preview the data. After you click Test in the CSV Configuration tab, the system executes the data set lookup call and if the data is available, a preview appears. Note that the Preview tab has two sub-tabs:
- Data columns: Enables you to specify what columns are part of your data set definition.
- Filter: Enables you to add a new filter.
Advanced: Enables you to manage the following configurations:
- Caching: See Section 5.4, “Caching” for more information.
- Cache life-cycle Enables you to specify an interval of time after which a data set (or data) is refreshed. The Refresh on stale data feature refreshes the cached data when the back-end data changes.
- After making the required changes, click Validate.
- Click Save.
5.3. Data refresh
The data refresh feature enables you to specify an interval of time after which a data set (or data) is refreshed. The Refresh on stale data feature refreshes the cached data when the back-end data changes.
5.4. Caching
Business Central provides caching mechanisms for storing data sets and performing data operations using in-memory data. Caching data reduces network traffic, remote system payload, and processing time. To avoid performance issues, configure the cache settings in Business Central.
For any data lookup call that results in a data set, the caching method determines where the data lookup call is executed and where the resulting data set is stored. An example of a data lookup call would be all the mortgage applications whose locale parameter is set as "Urban".
Business Central data set functionality provides two cache levels:
- Client level
- Back-end level
Client cache
When the cache is turned on, the data set is cached in a web browser during the lookup operation and further lookup operations do not perform requests to the back-end. Data set operations like grouping, aggregations, filtering, and sorting are processed in the web browser. Enable client caching only if the data set size is small, for example, for data sets with less than 10 MB of data. For large data sets, browser issues such as slow performance or intermittent freezing can occur. Client caching reduces the number of back-end requests including requests to the storage system.
Back-end cache
When the cache is enabled, the decision engine caches the data set. This reduces the number of back-end requests to the remote storage system. All data set operations are performed in the decision engine using in-memory data. Enable back-end caching only if the data set size is not updated frequently and it can be stored and processed in memory. Using back-end caching is also useful in cases with low latency connectivity issues with the remote storage.
Back-end cache settings are not always visible in the Advanced tab of the Data Set Editor because Java and CSV data providers rely on back-end caching (data set must be in the memory) in order to resolve any data lookup operation using the in-memory decision engine.
Chapter 6. Archetype management
Business Central provides an archetype management feature that enables you to list, add, validate, set as default, and delete the archetypes. You can manage archetypes from the Archetypes page in Business Central. Archetypes are projects that are installed in Apache Maven repositories in which a template structure is set or can be created if required.
For the most up-to-date and detailed information about archetypes, see the Introduction to Archetypes page.
6.1. Listing archetypes
The Archetypes page lists all the archetypes that are added in Business Central. This list provides the detailed information about Group ID, Artifact ID, Version, Created Date, Status, and Actions of an archetype.
Prerequisites
- You have created an archetype and listed it in the Business Central Settings from the maven repository.
Procedure
In Business Central, select the Admin icon in the top-right corner of the screen and select Archetypes.
In the Status column, green icon indicates it is a valid archetype, red icon indicates it is an invalid archetype whereas blue icon indicates the corresponding archetype is the default one for the new spaces.
6.2. Adding an archetype
You can add a new archetype to Business Central.
Prerequisites
- You have installed an archetype in the Maven repository.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Archetypes.
- Click Add Archetype.
- In the Add Archetype panel, enter the GAV attributes in the Group ID, Artifact ID, and Version fields respectively.
- Click Add.
Business Central validates the newly added archetype and make it available to be used as a template in all the spaces.
6.3. Managing additional features of an archetype
You can delete, set a default, and validate the archetypes from the Archetypes page in Business Central.
Prerequisites
- You have created an archetype and listed in the Business Central Settings from the Maven repository.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Archetypes.
From the Actions column, click the
icon on the right side of an archetype.
- Select Delete from the drop-down menu to delete an archetype from the list.
Select Validate from the drop-down menu to validate whether the archetype is valid or not.
NoteWhen the Business Central is starting up, all the registered archetypes are automatically validated.
- Select Set as default from the drop-down menu to set an archetype as a default for the new spaces.
6.4. Creating a project using archetypes
You can use archetypes to create a project in Business Central. When you create a project in Business Central, it is added to the Git repository that is connected to your Red Hat Process Automation Manager installation.
Prerequisites
- You have created an archetype and listed it in the Business Central Settings from the Maven repository.
- You have set an archetype as default in your space in the Business Central.
Procedure
- In Business Central, go to Menu → Design → Projects.
- Select or create the space into which you want to add a new project from an archetype template.
- Click Add Project.
- Type the project name and description in the Name and Description fields respectively.
- Click Configure Advanced Options.
- Select the Based on template check box.
- Select the archetype from drop-down options if required. The default archetype is selected that is already set in the space.
- Click Add.
The Assets view of the project opens based on the selected archetype template.
6.5. Managing archetypes using space settings in Business Central
When you add the archetypes to Business Central, they can be used as a templates in all the spaces. You can manage all the archetypes from the Settings tab which is available in the space. This tab is visible only to users with the admin
role.
Prerequisites
- You have installed an archetype in the Maven repository.
- You have created an archetype and listed it in the Business Central Settings from the Maven repository.
Procedure
- In Business Central, go to Menu → Design → Projects.
- Select or create the space into which you want to manage the archetypes. The default space is MySpace.
- Click Settings.
- To include or exclude the archetypes in the space, select the Include check box.
-
From the Actions column, click the
icon on the right side of an archetype and select Set as default from the drop-down menu to set an archetype as a default for the space.
- Click Save.
Chapter 7. Customizing project preferences
A project stores assets and is part of a space. A space can hold multiple projects.
For example, an organization has many departments, such as HR, Payroll, Engineering, R&D, and so on. Each department maps to a space and every department can have its own projects.
You can create a new project from scratch or clone projects from an existing Git repository.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Projects. The Projects page opens.
In the Project Preferences pane, click the preference you want to modify. The following preferences are available:
File exporting: This preference has the following properties:
Table 7.1. File exporting properties Field Description PDF orientation
Determines whether the PDF orientation is portrait or landscape.
PDF units
Determines whether the PDF unit is PT, MM, CN or IN.
PDF page format
Determines whether the PDF page format is A[0-10], B[0-10], or C[0-10].
Spaces: This preference has the following properties:
Table 7.2. Spaces properties Field Description Name
The default name of the space that is created automatically if none exists.
Owner
The default owner of the space that is created automatically if none exists.
Group ID
The default group ID of the space that is created automatically if none exists.
Alias (in singular)
Determines the customized alias (singular) of the space.
Alias (in plural)
Determines the customized alias (plural) of the space.
Default values: This preference has the following properties:
Table 7.3. Default values properties Field Description Version
The default version number of a project when creating projects using the Quick setup option.
Description
The default description of a project when creating projects using the Quick setup option.
Branch
The default branch to be used when using a Git repository.
Advanced GAV preferences: This preference has the following properties:
Table 7.4. Advanced GAV preference properties Field Description Disable GAV conflict check?
Determines whether to enable or disable the GAV conflict check. Disabling this feature allows projects to have the same GAV (Group ID, Artifact, Version).
Allow child GAV edition?
Determines whether to allow child/sub-projects to have GAV edition.
NoteDuplicate GAV detection is disabled for projects in Development Mode. To enable duplicate GAV detection for a project in Business Central, go to project Settings → General Settings → Version and toggle the Development Mode option to OFF (if applicable).
- Click Save.
Chapter 8. Customizing artifact repository properties
In some cases, projects need to resolve external dependencies to build domain model JAR files. A repository contains the needed artifacts and has the following features:
- The repository is a Maven repository.
- All snapshots are time stamped.
- Assets are stored mostly in the local hard drive.
By default, the artifact repository is in $WORKING_DIRECTORY/repositories/kie
.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Artifact Repository. The Artifact Repository page opens.
- Make selections and enter information in the Properties section.
- Click Save.
Chapter 9. Customizing language settings
You can change the language on the Business Central Settings page. Business Central supports the following languages:
- English
- German
- Spanish
- French
- Japanese
- Portuguese
- Chinese(Simplified)
The default language is English.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Languages. The Language Selector window opens.
- Select the desired language from the Language list.
- Click Ok.
Chapter 10. Customizing process administration
You can customize the default pagination option in Business Central by editing the Default items per page property on the Process Administration page.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Process Administration.
From the Properties section, update the Default items per page property and click Save.
NoteYou can specify 10, 20, 50, or 100 items to display on each page.
Chapter 11. Customizing the process designer
You can customize the process designer in Business Central by editing the properties of the diagram editor on the Business Central Settings page.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Process Designer.
In the Properties section, update any of the following properties:
- Select the Auto hide category panel check box to automatically hide a category toolbar panel.
- In the Drawing area width field, enter an integer value between 2800 and 5600 to set the width of the drawing area.
- In the Drawing area height field, enter an integer value between 1400 and 2800 to set the height of the drawing area.
- Select the Enable HiDPI check box if you are using a high resolution display and are seeing blurry text and objects. This option is disabled by default.
- Click Save.
Chapter 12. SSH Keys
Business Central provides an SSH keystore service to enable user SSH authentication. Business Central provides a configurable default SSH keystore, extensible APIs (for custom implementations), and support for multiple SSH public key formats.
You can access the SSH Keys option on the Business Central Settings page to register your SSH public keys.
12.1. Default SSH keystore
The default SSH keystore included with Business Central provides a file-based storage mechanism to store a user’s public keys. By default, Business Central uses the *.security
folder as the root directory. However, you can also use a custom storage path by setting the value of the appformer.ssh.keys.storage.folder
system property to point to a different folder.
The SSH public keys are stored in the {securityFolderPath}/pkeys/{userName}/
folder structure.
Each SSH public key consists of the following files, located in the storage folder:
{keyId}.pub
: This file contains the SSH public key content. As the file name determines the logic key ID on the system, ensure that the file name is not modified during run time.For example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDmak4Wu23RZ6XmN94bOsqecZxuTa4RRhhQmHmTZjMB7HM57/90u/B/gB/GhsPEu1nAXL0npY56tT/MPQ8vRm2C2W9A7CzN5+z5yyL3W01YZy3kzslk77CjULjfhrcfQSL3b2sPG5jv5E5/nyC/swSytucwT/PE7aXTS9H6cHIKUdYPzIt94SHoBxWRIK7PJi9d+eLB+hmDzvbVa1ezu5a8yu2kcHi6NxxfI5iRj2rsceDTp0imC1jMoC6ZDfBvZSxL9FXTMwFdNnmTlJveBtv9nAbnAvIWlilS0VOkdj1s3GxBxeZYAcKbcsK9sJzusptk5dxGsG2Z8vInaglN6OaOQ7b7tcomzCYYwviGQ9gRX8sGsVrw39gsDIGYP2tA4bRr7ecHnlNg1b0HCchA5+QCDk4Hbz1UrnHmPA2Lg9c3WGm2qedvQdVJXuS3mlwYOqL40aXPs6890PvFJUlpiVSznF50djPnwsMxJZEf1HdTXgZD1Bh54ogZf7czyUNfkNkE69yJDbTHjpQd0cKUQnu9tVxqmBzhX31yF4VcsMeADcf2Z8wlA3n4LZnC/GwonYlq5+G93zJpFOkPhme8c2XuPuCXF795lsxyJ8SB/AlwPJAhEtm0y0s0l1l4eWqxsDxkBOgN+ivU0czrVMssHJEJb4o0FLf7iHhOW56/iMdD9w== userName
.{keyId}.pub.meta
: This file contains the key metadata in JSON format. A new metadata file is dynamically generated if a key has no metadata.For example:
{ "name":"Key", "creationDate":"Oct 10, 2018 10:10:50 PM", "lastTimeUsed":"Oct 11, 2018 12:11:23 PM" }
12.2. Custom SSH keystore
You can extend and customize the default SSH keystore according to your requirements. Use the appformer.ssh.keystore
system property to specify the Java class name of the SSH service to use. If this property is not defined or it contains an incorrect value, then the default SSH keystore is loaded.
To create a custom implementation of the SSH keystore, your Java class must implement the org.uberfire.ssh.service.backend.keystore.SSHKeyStore
class defined in the uberfire-ssh-api
module.
12.3. Creating an SSH key
Before you can add or register SSH keys to Business Central, you must generate an SSH key on your system.
Procedure
- Open a command terminal on your system.
Run the
ssh-keygen
command to create the SSH key as shown in the following example, where<user_login>
is your user name:ssh-keygen -t rsa -b 4096 -C "<user_login>"
NoteThe SSH key formats supported by Business Central keystore are
ssh-rsa
,ssh-dss
,ecdsa-sha2-nistp256
,ecdsa-sha2-nistp384
, andecdsa-sha2-nistp521
.When prompted, press Enter and accept the default key file location as shown in the following example, where
<user_login>
is your user name:Enter a file in which to save the key (/home/<user_login>/.ssh/id_rsa): [Press enter]
At the command prompt, enter and confirm the passphrase:
Enter passphrase (empty for no passphrase): [Type a passphrase] Enter same passphrase again: [Type passphrase again]
Start the
ssh-agent
:eval "$(ssh-agent -s)" Agent pid <any-number-here>
Add the new SSH private key to the
ssh-agent
. If you have used a different key name, replaceid_rsa
in that code:ssh-add ~/.ssh/id_rsa
12.4. Registering your SSH public key with the SSH keystore
You must register your newly created SSH public key with the Business Central keystore.
Procedure
- Open a command terminal on your system.
Run the
cat
command as shown in the following example, whereid_rsa
is your key name:cat ~/.ssh/id_rsa.pub
- Copy the contents of your SSH public key.
- In Business Central, select the Admin icon in the top-right corner of the screen and select SSH Keys.
- On the SSH Keys page, click Add SSH Key.
In the Add SSH Key window, enter a name in the Name field and copy the contents of the SSH public key to the Key field.
NoteThe Name and the Key fields are mandatory.
- Click Add SSH Key to register the key.
12.5. Deleting an SSH key
You can delete an SSH key from Business Central by from the SSH Keys page.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select SSH Keys.
- On the SSH Keys page, click the delete icon of the SSH key you want to delete.
- Click Delete SSH Key to confirm the deletion.
Chapter 13. Managing service tasks in Business Central
Service tasks (work items) are tasks that you can customize and reuse across multiple business processes or across all projects in Business Central. Red Hat Process Automation Manager provides a set of service tasks within the service task repository in Business Central. You can enable or disable the default service tasks and upload custom service tasks into Business Central to implement the tasks in the relevant processes.
Red Hat Process Automation Manager includes a limited set of supported custom tasks. Custom tasks that are not included in Red Hat Process Automation Manager are not supported.
Procedure
In Business Central, click
in the upper-right corner and select Service Tasks Administration.
This page lists the service task installation settings and available service tasks for processes in projects throughout Business Central. The service tasks that you enable on this page become available in the project-level settings where you can then install each service task to be used in processes. The way in which the service tasks are installed in a project is determined by the global settings that you enable or disable under Settings on this Service Tasks Administration page.
Under Settings, enable or disable each setting to determine how the available service tasks will be implemented when a user installs them at the project level.
The following service task settings are available:
- Install as Maven artifact: Uploads the service task JAR file to the Maven repository that is configured with Business Central, if the file is not already present.
-
Install service task dependencies into project: Adds any service task dependencies to the
pom.xml
file of the project where the task is installed. -
Use version range when installing service task into project: Uses a version range instead of a fixed version of a service task that is added as a project dependency. Example:
[7.16,)
instead of7.16.0.Final
Enable or disable (set to ON or OFF) any available service tasks as needed. Service tasks that you enable will be displayed in project-level settings for all projects in Business Central.
Figure 13.1. Enable service tasks and service task settings
-
To add a custom service task, click Add Service Task, browse to the relevant JAR file, and click the Upload icon. The JAR file must contain work item handler implementations annotated with
@Wid
. - Optionally, to remove a service task, click remove on the row of the service task you want to remove and click Ok to confirm removal.
- After you configure all required service tasks, navigate to a project in Business Central and go to the project Settings → Service Tasks page to view the available service tasks that you enabled.
- For each service task, click Install to make the task available to the processes in that project or click Uninstall to exclude the task from the processes in the project.
If you are prompted for additional information when you install a service task, enter the required information and click Install again.
The required parameters for the service task depend on the type of task. For example, rule and decision tasks require artifact GAV information (Group ID, Artifact ID, Version), email tasks require host and port access information, and REST tasks require API credentials. Other service tasks might not require any additional parameters.
Figure 13.2. Install service tasks for use in processes
- Click Save.
Return to the project page, select or add a business process in the project, and in the process designer palette, select the Service Tasks option to view the available service tasks that you enabled and installed:
Figure 13.3. Access installed service tasks in process designer
Chapter 14. Exporting and importing Dashbuilder data
Dashbuilder is a dashboard and reporting tool integrated in Business Central and is used by the Datasets editor and Content Manager page. There are three data types:
- Datasets
- Pages
- Navigation
You can import and export Dashbuilder data as ZIP files in Business Central.
This feature is only accessible by administrator users.
14.1. Exporting Dashbuilder data
You can export the dashbuilder related data such as datasets, pages, and navigation from Business Central as a ZIP file.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Dashbuilder Data Transfer.
To export the dashbuilder related data, do any of the following tasks:
If you want to export all dashbuilder data as a ZIP file, do the following tasks:
On the Dashbuilder Data Transfer page, click Export all.
An
export.zip
file containing all dashbuilder data is downloaded. Theexport.zip
file structure is separated by data type. For example:dashbuilder/datasets/definitions/dataset-example1.dset dashbuilder/datasets/definitions/dataset-example2.dset dashbuilder/datasets/readme.md dashbuilder/perspectives/page1/perspective_layout dashbuilder/perspectives/page1/perspective_layout.plugin dashbuilder/perspectives/page2/perspective_layout dashbuilder/perspectives/page2/perspective_layout.plugin dashbuilder/perspectives/readme.md dashbuilder/navigation/navigation/navtree.json dashbuilder/navigation/readme.md VERSION
If you want to export customized user created dashbuilder data as a ZIP file, do the following tasks:
- On the Dashbuilder Data Transfer page, click Custom export.
- In Export Wizard panel, select the datasets that you want to include in the ZIP file and click Next.
Select the pages that you want to include in the ZIP file and click Next.
The Export Wizard panel validates the selected datasets and pages. The summary of the datasets and pages is available on the panel.
NoteNavigation is always included in the exported
ZIP
file.Click Download if your export is ready.
An
export.zip
file containing customized dashbuilder data is downloaded.NoteYou must select the pages and the datasets associated with those pages in the Export Wizard panel. You must select at least one page. If you fail to select both datasets and pages, an export error is generated and you can not download the
export.zip
file.- Click Finish.
14.2. Importing Dashbuilder data
You can import Dashbuilder data to Business Central from a ZIP file if the archive is structured in the same way as the following example:
dashbuilder/datasets/definitions/dataset-example1.dset dashbuilder/datasets/definitions/dataset-example2.dset dashbuilder/datasets/readme.md dashbuilder/perspectives/page1/perspective_layout dashbuilder/perspectives/page1/perspective_layout.plugin dashbuilder/perspectives/page2/perspective_layout dashbuilder/perspectives/page2/perspective_layout.plugin dashbuilder/perspectives/readme.md dashbuilder/navigation/navigation/navtree.json dashbuilder/navigation/readme.md VERSION
Procedure
In Business Central, select the Admin icon in the top-right corner of the screen and select Dashbuilder Data Transfer.
WarningYou should only import Dashbuilder data to a clean installation of Red Hat Process Automation Manager in order to avoid overwriting data on an existing system.
- On the Dashbuilder Data Transfer page, click the Choose File icon.
- Navigate to the ZIP file you want to import and select the file.
- Click the Upload icon.
- Click Import.
Chapter 15. LDAP connection
Business Central provides a dedicated UserGroupCallback
implementation for LDAP servers with Red Hat Process Automation Manager to enable the user task service to retrieve information on users, groups, and roles directly from an LDAP service.
You can configure the following LDAP UserGroupCallback
implementation properties:
Property | Description |
---|---|
| User name for connecting to the LDAP server. This property is optional if it is not specified and the LDAP server accepts anonymous access. |
| Password for connecting to the LDAP server. This property is optional if it is not specified and the LDAP server accepts anonymous access. |
| Context in LDAP with user information. |
| Context in LDAP with group and role. |
| Context in LDAP with user group and role membership information.
This property is optional if it is not specified and the |
| Filter for searching user information. This property usually contains substitution keys {0} that are replaced with parameters. |
| Filter for searching group and role information. This property usually contains substitution keys {0} that are replaced with parameters. |
| Filter for searching user group and role membership information. This property usually contains substitution keys {0} that are replaced with parameters. |
| Attribute name of the user ID in LDAP.
This property is optional if it is not specified and the |
| Attribute name of the group and role ID in LDAP.
This property is optional if it is not specified and the |
|
User ID in a DN, instructs the callback to query for user DN before searching for roles. This is optional and is |
|
Initial context factory class name; is |
|
Authentication type where the possible values are |
|
Security protocol to be used, for example, |
|
LDAP url (by default |
15.1. LDAP UserGroupCallback implementation
You can use the LDAP UserGroupCallback
implementation by configuring the respective LDAP properties in one of the following ways:
Programmatically: Build a properties object with the respective
LDAPUserGroupCallbackImpl
properties and createLDAPUserGroupCallbackImpl
using the same properties object as its parameter.For example:
import org.kie.api.PropertiesConfiguration; import org.kie.api.task.UserGroupCallback; ... Properties properties = new Properties(); properties.setProperty(LDAPUserGroupCallbackImpl.USER_CTX, "ou=People,dc=my-domain,dc=com"); properties.setProperty(LDAPUserGroupCallbackImpl.ROLE_CTX, "ou=Roles,dc=my-domain,dc=com"); properties.setProperty(LDAPUserGroupCallbackImpl.USER_ROLES_CTX, "ou=Roles,dc=my-domain,dc=com"); properties.setProperty(LDAPUserGroupCallbackImpl.USER_FILTER, "(uid={0})"); properties.setProperty(LDAPUserGroupCallbackImpl.ROLE_FILTER, "(cn={0})"); properties.setProperty(LDAPUserGroupCallbackImpl.USER_ROLES_FILTER, "(member={0})"); UserGroupCallback ldapUserGroupCallback = new LDAPUserGroupCallbackImpl(properties); UserGroupCallbackManager.getInstance().setCallback(ldapUserGroupCallback);
Declaratively: Create the
jbpm.usergroup.callback.properties
file in the root of your application or specify the file location as a system property.For example:
-Djbpm.usergroup.callback.properties=FILE_LOCATION_ON_CLASSPATH
Ensure that you register the LDAP callback when starting the user task server.
For example:
#ldap.bind.user= #ldap.bind.pwd= ldap.user.ctx=ou\=People,dc\=my-domain,dc\=com ldap.role.ctx=ou\=Roles,dc\=my-domain,dc\=com ldap.user.roles.ctx=ou\=Roles,dc\=my-domain,dc\=com ldap.user.filter=(uid\={0}) ldap.role.filter=(cn\={0}) ldap.user.roles.filter=(member\={0}) #ldap.user.attr.id= #ldap.roles.attr.id=
Additional resources
Chapter 16. Database connection
Business Central provides a dedicated UserGroupCallback
implementation for database server with Red Hat Process Automation Manager to enable the user task service. The user task service helps in retrieving information on users and groups (roles) directly from databases.
You can configure the following database UserGroupCallback
implementation properties:
Property | Description |
---|---|
| JNDI name of the data source used for connections |
| Verifies the user existence |
| Collects the groups for a given user |
| Verifies the group existence |
16.1. Database UserGroupCallback implementation
In database UserGroupCallback
implementation, you must create the required database. You can use this implementation by configuring the respective database properties in one of the following ways:
Programmatically: Build a properties object with the respective
DBUserGroupCallbackImpl
properties and createDBUserGroupCallbackImpl
using the same properties object as its parameter.For example:
import static org.jbpm.services.task.identity.DBUserGroupCallbackImpl.DS_JNDI_NAME; import static org.jbpm.services.task.identity.DBUserGroupCallbackImpl.PRINCIPAL_QUERY; import static org.jbpm.services.task.identity.DBUserGroupCallbackImpl.ROLES_QUERY; import static org.jbpm.services.task.identity.DBUserGroupCallbackImpl.USER_ROLES_QUERY; ... props = new Properties(); props.setProperty(DS_JNDI_NAME, "jdbc/jbpm-ds"); props.setProperty(PRINCIPAL_QUERY, "select userId from Users where userId = ?"); props.setProperty(ROLES_QUERY, "select groupId from UserGroups where groupId = ?"); props.setProperty(USER_ROLES_QUERY, "select groupId from UserGroups where userId = ?"); callback = new DBUserGroupCallbackImpl(props);
Declaratively: Create the
jbpm.usergroup.callback.properties
file in the root of your application or specify the file location as a system property.For example:
-Djbpm.usergroup.callback.properties=FILE_LOCATION_ON_CLASSPATH
Ensure that you register the database callback when starting the user task server.
For example:
System.setProperty("jbpm.usergroup.callback.properties", "/jbpm.usergroup.callback.db.properties"); callback = new DBUserGroupCallbackImpl(true); ... db.ds.jndi.name = jdbc/jbpm-ds db.user.query = select userId from Users where userId = ? db.roles.query = select groupId from UserGroups where groupId = ? db.user.roles.query = select groupId from UserGroups where userId = ?
Additional resources
Chapter 17. Configuring Maven using settings.xml file
Java application development uses the Apache Maven build automation tool to build and manage software projects. Maven uses Project Object Model (POM) configuration XML files to define both, the project properties and the build process.
Maven uses repositories to store Java libraries, plug-ins, and other build artifacts. Repositories can be either local or remote. A local repository is a download of artifacts from a remote repository cached on a local machine. A remote repository is any other repository accessed using common protocols, such as http://
when located on an HTTP server, or file://
when located on a file server. The default repository is the public remote Maven 2 Central Repository. Configuration of Maven is performed by modifying the settings.xml file. You can either configure global Maven settings in the M2_HOME/conf/settings.xml
file, or user-level settings in the USER_HOME/.m2/settings.xml
file.
Additional resources
- Configuring an external Maven repository for Business Central and KIE Server
- Packaging and deploying a Red Hat Process Automation Manager project in Maven
- Maven settings and repositories for Red Hat Process Automation Manager
- System integration with Maven
- Welcome to Apache Maven
- Apache Maven Project - Introduction to Repositories
- Apache Maven Parent POMs Reference.
Chapter 18. GAV check management
In Business Central, projects are identified by the Group ID, Artifact ID, and Version (GAV) Maven naming convention. GAV values differentiate projects and project versions as well as identify dependencies with particular projects.
By default, Business Central detects duplicate GAVs. This feature can be disabled by users with the admin role.
18.1. Configuring GAV checks and child GAV edition
This procedure describes how to configure GAV checks in Business Central.
Procedure
- In Business Central, go to Menu → Design → Projects and click the project name.
- In the project window, click the Settings tab.
In the General Settings tab, perform any of the following tasks:
- To enable other projects to have the same GAV, select the Disable GAV conflict check check box.
- To enable child projects to have GAV edition, select the Allow child GAV edition check box.
Click Save.
NoteYou can click Reset to undo all changes.
- Click Save to confirm the changes.
Duplicate GAV detection is disabled for projects in Development Mode. To enable duplicate GAV detection in Business Central, go to project Settings → General Settings → Version and toggle the Development Mode option to OFF (if applicable).
18.2. Configuring GAV checks for all projects
This procedure describes how to configure GAV checks for all projects in Business Central. You can also disable GAV checks at system startup.
Procedures
- In Business Central, select the Admin icon in the top-right corner of the screen and select Projects. The Projects window opens.
In the Advanced GAV preferences tab, perform any of the following tasks:
- To enable other projects to have the same GAV, select the Disable GAV conflict check check box.
- To enable child projects to have GAV edition, select the Allow child GAV edition check box.
- Click Save.
You can also disable the duplicate GAV detection feature by setting the org.guvnor.project.gav.check.disabled
system property to true for Business Central at system startup:
$ ~/EAP_HOME/bin/standalone.sh -c standalone-full.xml -Dorg.guvnor.project.gav.check.disabled=true
Chapter 19. Configuring the environment mode in KIE Server and Business Central
You can set KIE Server to run in production
mode or in development
mode. Development mode provides a flexible deployment policy that enables you to update existing deployment units (KIE containers) while maintaining active process instances for small changes. It also enables you to reset the deployment unit state before updating active process instances for larger changes. Production mode is optimal for production environments, where each deployment creates a new deployment unit.
In a development environment, you can click Deploy in Business Central to deploy the built KJAR file to a KIE Server without stopping any running instances (if applicable), or click Redeploy to deploy the built KJAR file and replace all instances. The next time you deploy or redeploy the built KJAR, the previous deployment unit (KIE container) is automatically updated in the same target KIE Server.
In a production environment, the Redeploy option in Business Central is disabled and you can click only Deploy to deploy the built KJAR file to a new deployment unit (KIE container) on a KIE Server.
Procedure
-
To configure the KIE Server environment mode, set the
org.kie.server.mode
system property toorg.kie.server.mode=development
ororg.kie.server.mode=production
. To configure the deployment behavior for a project in Business Central, go to project Settings → General Settings → Version and toggle the Development Mode option.
NoteBy default, KIE Server and all new projects in Business Central are in development mode.
You cannot deploy a project with Development Mode turned on or with a manually added
SNAPSHOT
version suffix to a KIE Server that is in production mode.
Chapter 20. Git hooks and remote Git repository integration
Git hooks are bash scripts that execute before or after Git events such as git commit
or git push
. In Business Central, you can use Git hooks to configure repositories to trigger specified actions every time events happen. For more information about Git hooks, see Customizing Git Hooks.
You can integrate remote Git repositories with Business Central by using post-commit Git hooks. This enables you to automate content replication between Business Central and remote repositories. For example, you can implement a real-time backup strategy where changes you make to your Business Central projects are replicated to your remote Git repositories.
Business Central only supports post-commit Git hooks.
A post-commit Git hook executes after every commit as a sync operation. Business Central waits for the post-commit bash to complete and no other write operation occurs in the repository.
20.1. Creating post-commit Git hooks
You can create a post-commit Git hook bash script file that executes code contained in that file or execute code from a different file such as a Java program.
Procedure
Create a
post-commit
Git hook file:$ touch post-commit
Set the permissions of the
post-commit
file to755
:$ chmod 755 post-commit
Add
#!/bin/bash
and any required code to thepost-commit
file, for example:To push all changes to a remote repository:
#!/bin/bash git push origin +master
To log a message:
#!/bin/bash echo 'Hello World'
To execute code of another file:
#!/bin/bash java -jar _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks/git-push.jar
NoteTo use post-commit Git hooks that execute Java code, you must use the following Java libraries:
- JGit: Used to interact with internal Business Central Git repositories.
- GitHub API for Java: Used to communicate with GitHub.
For more information about post-commit Git hook and Java code examples, see Business Central post-commit Git Hooks Integration.
20.2. Importing remote Git repositories
You can import a remote Git repository in to Business Central and configure a post-commit Git hook to automatically push changes to that remote repository.
Prerequisites
- Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
- Red Hat Process Automation Manager projects exist in an external Git repository.
- Read access credentials for the external Git repository.
-
(For Windows) Cygwin is installed with the Git package added during installation and the path to the Cygwin
/bin
folder is added to your environmentPATH
variable. For example,C:\cygwin64\bin
. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.
Procedure
- In Business Central, go to Menu → Projects.
- Select or create the space that you want to import the Git projects into.
-
Click
on the right side of the screen and select Import Project.
-
In the Import Project window, enter the URL of your Git repository, for example,
https://github.com/USERNAME/REPOSITORY_NAME.git
, and the credentials for the Git repository. Click Import.
The project is added to the Business Central Git repository and is then available in the space.
ImportantUse the HTTPS or Git protocol instead of a SCP-style SSH URL. Business Central does not support the basic SSH URL and an error appears if you use this URL.
You must have your public ssh key configured in your Git provider.
The Git repository must be a KJAR project, containing only a single KJAR that is compatible with the Red Hat Process Automation Manager version. The KJAR content must be in the root of the repository.
In a command terminal, navigate to the
hooks
folder located in the repository Git folder of the project. For example:$ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
Create a
post-commit
file that pushes changes to the remote Git repository. For example:#!/bin/sh git push origin +master
For more information about creating post-commit Git hooks, see Section 20.1, “Creating post-commit Git hooks”.
Optional: To check that the configuration was successful, create a guided rule in Business Central:
- In Business Central go to Menu → Projects → Add Asset → Guided Rule.
- On the Create new Guided Rule page, enter the required information.
Click Ok.
Business Central automatically pushes all changes to the remote repository.
Additional resources
20.3. Configuring Git hooks for existing remote Git project repositories
If you have an existing remote Git repository project you can create a post-commit Git hook in a remote Git repository of that existing project and integrate the remote Git repository with Business Central.
Prerequisites
- Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
- Red Hat Process Automation Manager projects exist in an external Git repository.
- Read access credentials for the external Git repository.
-
(For Windows operating system) Cygwin is installed with the Git package added during installation and the path to the Cygwin
/bin
folder is added to your environmentPATH
variable. For example,C:\cygwin64\bin
. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.
Procedure
In a command terminal, navigate to the
hooks
folder located in the repository Git folder of the project. For example:$ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
Create a
post-commit
file that pushes changes to the remote Git repository. For example:#!/bin/sh git push origin +master
For more information about creating post-commit Git hooks, see Section 20.1, “Creating post-commit Git hooks”.
Optional: To check that the configuration was successful, create a guided rule in Business Central:
- In Business Central go to Menu → Projects → Add Asset → Guided Rule.
- On the Create new Guided Rule page, enter the required information.
Click Ok.
Business Central automatically pushes all changes to the remote repository.
20.4. Configuring Git hooks as a system property for Business Central
If you do not have an existing Git repository project or if you want to apply post-commit Git hooks to a large number of project repositories you can specify a directory containing a hook file for the value of the org.uberfire.nio.git.hooks
system property. This directory is copied to the Git repositories.
If you specify the org.uberfire.nio.git.hooks
system property, all Business Central internal repositories and project repositories use the post-commit Git hook. You should only use fully qualified paths in your script.
Prerequisites
- Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
-
(For Windows operating system) Cygwin is installed with the Git package added during installation and the path to the Cygwin
/bin
folder is added to your environmentPATH
variable. For example,C:\cygwin64\bin
. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.
Procedure
Create a post-commit Git hook in a directory on your local system.
For more information about creating post-commit Git hooks, see Section 20.1, “Creating post-commit Git hooks”.
To specify the directory with the hook file for the value of the
org.uberfire.nio.git.hooks
system property, do one of the following tasks:Add the
org.uberfire.nio.git.hooks
system property to thestandalone.xml
file. For example:<system-properties> <property name="org.uberfire.nio.git.hooks" value="_EAP_HOME_/hooks"> </property> ... </system-properties>
Use the
-Dorg.uberfire.nio.git.hooks
environment variable when executing Business Central. For example:$ ./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
Start Business Central.
The post-commit Git hook is copied to all Business Central internal repositories and project repositories.
Additional resources
20.5. Integrating remote Git repositories
In the following example, you use a post-commit Git hook and Java code to integrate Business Central with a remote Git repository. For the Java code example, see Business Central post-commit Git Hooks Integration. The example provides the following functionality:
-
Automatic generation of the template
.gitremote
configuration file -
Validation of the
.gitremote
configuration file for required parameters -
Patterns defined in the ignore parameter of the
.gitremote
file are ignored by Git - Message and notification output to users
- Support for GitLab and GitHub token authentication
- Support for GitLab group and subgroup project creation
- Support for GitHub organization repository creation
Prerequisites
- Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
- Java Development Kit (JDK) 8 is installed.
- Maven is installed.
Procedure
In a terminal window, clone the GitHub repository to your system:
$ git clone https://github.com/kiegroup/bc-git-integration-push.git
Navigate to the cloned repository:
$ cd bc-git-integration-push
Execute a Maven clean install:
$ mvn clean install
Create a
/hooks
folder in yourEAP_HOME
directory:$ mkdir -p _EAP_HOME_/hooks/
Copy the
git-push-2.1-SNAPSHOT.jar
to theEAP_HOME/hooks/
folder:$ cp bc-git-integration-push/target/git-push-2.1-SNAPSHOT.jar _EAP_HOME_/hooks/
Optional: To create a template
.gitremote
configuration file, rungit-push-2.1-SNAPSHOT.jar
:$ java -jar git-push-2.1-SNAPSHOT.jar
Example template
.gitremote
configuration file#This is an auto generated template empty property file provider=GIT_HUB login= password= token= remoteGitUrl=https://api.github.com/ useSSH=false ignore=.*demo.*, test.* githubOrg=OrgName gitlabGroup=Group/subgroup
Modify the
.gitremote
configuration file parameters.Table 20.1. Example .gitremote parameters Parameter Description provider
The Git provider. Only two values are accepted: GIT_HUB and GIT_LAB. Required
login
The user name for the Git provider. Required
password
A plain text password. Not required if a
token
is provided.token
A generated token to replace the
username
andpassword
based unsecured connection. Note: If this is not set a warning is displayed that you are using an unsecured connection. Not required if apassword
is provided. Note: GitLab only supports token authentication.remoteGitUrl
A public provider URL or a locally hosted enterprise for any provider. Required. Note: The public GitHub URL should be the API URL. For example, api.github.com.
useSSH
Boolean to allow the SSH protocol to push changes to the remote repository. Optional. Default = false. Note: This parameter uses the local
~/.ssh/
directory to obtain the SSH configuration.ignore
A comma separated regular expressions to ignore project names that match any of these expressions. Optional.
githubOrg
Defines the repository organization if GitHub is used as the provider. Optional.
gitlabGroup
Defines the repository group and subgroup if GitLab is used as the provider Optional.
Create a
post-commit
Git hook file inEAP_HOME/hooks
:$ touch post-commit
Set the permissions of the
post-commit
file to755
:$ chmod 755 post-commit
Add
#!/bin/bash
and code to executegit-push-2.1-SNAPSHOT.jar
to thepost-commit
file:$ echo "#\!/bin/bash\njava -jar $APP_SERVER_HOME/hooks/git-push-2.1-SNAPSHOT.jar" > hooks/post-commit
Start Business Central with the
-Dorg.uberfire.nio.git.hooks
environment variable set. For example:$ ./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
To use post-commit Git hooks that execute Java code, you must use the following Java libraries:
- JGit: Used to interact with internal Business Central Git repositories.
- GitHub API for Java: Used to communicate with GitHub.
For more information about post-commit Git hook and Java code examples, see Business Central post-commit Git Hooks Integration.
20.6. Git hook exit codes
When a Git hook exits an integer value is returned which determines the status of the Git hook execution. This integer value is known as a Git hook exit code. The execution status can be a success (1), warning (2 to 30) or error (31 to 255).
20.7. Customizing Git hook notifications
Business Central provides a mechanism that enables users to receive customized Git hook notifications based on the hook exit codes.
To enable the notification mechanism you must create a *.properties
file containing the custom messages and then specify the path to that file as the value of the appformer.git.hooks.bundle
system property.
Procedure
Create the
*.properties
file and add a line for each exit code with a corresponding message in the following format:<exit_code>=<display_message>
The
<exit_code>
is the Git hook exit code and the<display_message>
is the custom message that is displayed to a user.For example:
0=Success! All working as expected. 1=Warning! Please check the logs and advise your admin. . . 31=Error! Please advise your admin immediately.
NoteIt is not necessary to define all the possible exit codes in the *.properties file. Notifications appear only for the exit codes defined in the *.properties file.
ImportantThe notification service only supports the
ISO 8859-1
(LATIN 1
) character set in the properties file. If you want to use extended characters, please use their escaped Unicode character code sequences.To enable Git hook notifications, specify the path to the file as the value of the
appformer.git.hooks.bundle
system property.See the following example of a
standalone.xml
file with the setting that points to aMessages.properties
file:<system-properties> <property name="appformer.git.hooks.bundle" value="/opt/jboss-as/git-hooks-messages/Messages.properties"> </property> ... </system-properties>
20.7.1. Git hook notifications in Business Central
You can view Git hook notifications in Business Central. There are three Git hook exit code notification types.
Exit code | Customized message | UI notification color |
---|---|---|
| Success! All working as expected. | Green |
| Warning! Please check the logs and advise your admin. | Orange |
| Error! Please advise your admin immediately. | Red |
UNIX machines only support error codes between 0 (success) to 255 (error), any exit code outside of this range will end up being converted into a different code which may cause showing a wrong notification message.
Windows machines don’t have this limitation and support a wide range of exit codes.
20.7.2. Git hook notification internationalization support
You can internationalize notification messages by placing additional properties files in the same path as the original properties file specified as the appformer.git.hooks.bundle
system property.
The name of the different localized files must be <filename>_<lang>.properties
, where the <filename>
is the same as the original. For example, where the system property points to Messages.properties
, you can create Messages_en.properties
for English, Messages_fr.properties
for French, or Messages_it.properties
for Italian.
The notification service will choose the properties file based on the user’s language, if there are no available translations for that language it will use the entries from the original Messages.properties
file.
Chapter 21. Role-based access control for branches in Business Central
Business Central provides the option for users to restrict the access for a target branch for a specific collaborator type. The security check uses both the Security Management screen and contributors sources to grant or deny permissions to spaces and projects. For example, if a user has the security permission to update a project and has write permission on that branch, based on the contributor type, then they are able to create new assets.
21.1. Customizing role-based branch access
You can customize contributor role permissions for each branch of a project in Business Central. For example, you can set Read, Write, Delete, and Deploy access for each role assigned to a branch.
Procedure
- In Business Central, go to Menu → Design → Projects.
If needed, add a new contributor:
- Click the project name and then click the Contributors tab.
- Click Add Contributor.
- Enter user name in the text field.
- Select the Contributor role type from the drop-down list.
- Click Ok.
Customize role-based branch access for the relevant contributor:
- Click Settings → Branch Management.
- Select the branch name from the drop-down list.
- In the Role Access section, select or deselect the permissions check boxes to specify role-based branch access for each available role type.
- Click Save and click Save again to confirm your changes.
Chapter 22. Viewing process instance logs
You can view all the process events of an instance from its Logs tab. The instance logs list all the current and previous process states. Business Central has two types of logs for process instances, Business and Technical logs.
Procedure
- In Business Central, go to Menu → Manage → Process Instances.
- On the Manage Process Instances page, click the process instance whose log you want to view.
Select the Logs tab:
- Click Business to view the business events log.
- Click Technical to view the technical events log.
- Click Asc or Desc to change the order of the log files.
Chapter 23. Business Central system properties
The Business Central system properties listed in this section are passed to standalone*.xml
files. To install standalone Business Central, you can use the listed properties in the following command:
java -jar rhpam-7.8.0-business-central-standalone.jar -s application-config.yaml -D<property>=<value> -D<property>=<value>
In this command, <property>
is a property from list and <value>
is a value that you assign to that property.
- Git directory
Use the following properties to set the location and name for the Business Central Git directory:
-
org.uberfire.nio.git.dir
: Location of the Business Central Git directory. -
org.uberfire.nio.git.dirname
: Name of the Business Central Git directory. Default value:.niogit
. -
org.uberfire.nio.git.ketch
: Enables or disables Git ketch. -
org.uberfire.nio.git.hooks
: Location of the Git hooks directory.
-
- Git over HTTP
Use the following properties to configure access to the Git repository over HTTP:
-
org.uberfire.nio.git.proxy.ssh.over.http
: Specifies whether SSH should use an HTTP proxy. Default value:false
. -
http.proxyHost
: Defines the host name of the HTTP proxy. Default value:null
. -
http.proxyPort
: Defines the host port (integer value) of the HTTP proxy. Default value:null
. -
http.proxyUser
: Defines the user name of the HTTP proxy. -
http.proxyPassword
: Defines the user password of the HTTP proxy. -
org.uberfire.nio.git.http.enabled
: Enables or disables the HTTP daemon. Default value:true
. -
org.uberfire.nio.git.http.host
: If the HTTP daemon is enabled, it uses this property as the host identifier. This is an informative property that is used to display how to access the Git repository over HTTP. The HTTP still relies on the servlet container. Default value:localhost
. -
org.uberfire.nio.git.http.hostname
: If the HTTP daemon is enabled, it uses this property as the host name identifier. This is an informative property that is used to display how to access the Git repository over HTTP. The HTTP still relies on the servlet container. Default value:localhost
. -
org.uberfire.nio.git.http.port
: If the HTTP daemon is enabled, it uses this property as the port number. This is an informative property that is used to display how to access the Git repository over HTTP. The HTTP still relies on the servlet container. Default value:8080
.
-
- Git over HTTPS
Use the following properties to configure access to the Git repository over HTTPS:
-
org.uberfire.nio.git.proxy.ssh.over.https
: Specifies whether SSH uses an HTTPS proxy. Default value:false
. -
https.proxyHost
: Defines the host name of the HTTPS proxy. Default value:null
. -
https.proxyPort
: Defines the host port (integer value) of the HTTPS proxy. Default value:null
. -
https.proxyUser
: Defines the user name of the HTTPS proxy. -
https.proxyPassword
: Defines the user password of the HTTPS proxy. -
user.dir
: Location of the user directory. -
org.uberfire.nio.git.https.enabled
: Enables or disables the HTTPS daemon. Default value:false
-
org.uberfire.nio.git.https.host
: If the HTTPS daemon is enabled, it uses this property as the host identifier. This is an informative property that is used to display how to access the Git repository over HTTPS. The HTTPS still relies on the servlet container. Default value:localhost
. -
org.uberfire.nio.git.https.hostname
: If the HTTPS daemon is enabled, it uses this property as the host name identifier. This is an informative property that is used to display how to access the Git repository over HTTPS. The HTTPS still relies on the servlet container. Default value:localhost
. -
org.uberfire.nio.git.https.port
: If the HTTPS daemon is enabled, it uses this property as the port number. This is an informative property that is used to display how to access the Git repository over HTTPS. The HTTPS still relies on the servlet container. Default value:8080
.
-
- JGit
-
org.uberfire.nio.jgit.cache.instances
: Defines the JGit cache size. -
org.uberfire.nio.jgit.cache.overflow.cleanup.size
: Defines the JGit cache overflow cleanup size. -
org.uberfire.nio.jgit.remove.eldest.iterations
: Enables or disables whether to remove eldest JGit iterations. -
org.uberfire.nio.jgit.cache.evict.threshold.duration
: Defines the JGit evict threshold duration. -
org.uberfire.nio.jgit.cache.evict.threshold.time.unit
: Defines the JGit evict threshold time unit.
-
- Git daemon
Use the following properties to enable and configure the Git daemon:
-
org.uberfire.nio.git.daemon.enabled
: Enables or disables the Git daemon. Default value:true
. -
org.uberfire.nio.git.daemon.host
: If the Git daemon is enabled, it uses this property as the local host identifier. Default value:localhost
. -
org.uberfire.nio.git.daemon.hostname
: If the Git daemon is enabled, it uses this property as the local host name identifier. Default value:localhost
-
org.uberfire.nio.git.daemon.port
: If the Git daemon is enabled, it uses this property as the port number. Default value:9418
. org.uberfire.nio.git.http.sslVerify
: Enables or disables SSL certificate checking for Git repositories. Default value:true
.NoteIf the default or assigned port is already in use, a new port is automatically selected. Ensure that the ports are available and check the log for more information.
-
- Git SSH
Use the following properties to enable and configure the Git SSH daemon:
-
org.uberfire.nio.git.ssh.enabled
: Enables or disables the SSH daemon. Default value:true
. -
org.uberfire.nio.git.ssh.host
: If the SSH daemon enabled, it uses this property as the local host identifier. Default value:localhost
. -
org.uberfire.nio.git.ssh.hostname
: If the SSH daemon is enabled, it uses this property as local host name identifier. Default value:localhost
. org.uberfire.nio.git.ssh.port
: If the SSH daemon is enabled, it uses this property as the port number. Default value:8001
.NoteIf the default or assigned port is already in use, a new port is automatically selected. Ensure that the ports are available and check the log for more information.
-
org.uberfire.nio.git.ssh.cert.dir
: Location of the.security
directory where local certificates are stored. Default value: Working directory. -
org.uberfire.nio.git.ssh.idle.timeout
: Sets the SSH idle timeout. -
org.uberfire.nio.git.ssh.passphrase
: Pass phrase used to access the public key store of your operating system when cloning git repositories with SCP style URLs. Example:git@github.com:user/repository.git
. -
org.uberfire.nio.git.ssh.algorithm
: Algorithm used by SSH. Default value:RSA
. -
org.uberfire.nio.git.gc.limit
: Sets the GC limit. -
org.uberfire.nio.git.ssh.ciphers
: A comma-separated string of ciphers. The available ciphers areaes128-ctr
,aes192-ctr
,aes256-ctr
,arcfour128
,arcfour256
,aes192-cbc
,aes256-cbc
. If the property is not used, all available ciphers are loaded. org.uberfire.nio.git.ssh.macs
: A comma-separated string of message authentication codes (MACs). The available MACs arehmac-md5
,hmac-md5-96
,hmac-sha1
,hmac-sha1-96
,hmac-sha2-256
,hmac-sha2-512
. If the property is not used, all available MACs are loaded.NoteIf you plan to use RSA or any algorithm other than DSA, make sure you set up your application server to use the Bouncy Castle JCE library.
-
- KIE Server nodes and Process Automation Manager controller
Use the following properties to configure the connections with the KIE Server nodes from the Process Automation Manager controller:
-
org.kie.server.controller
: The URL is used to connect to the Process Automation Manager controller. For example,ws://localhost:8080/business-central/websocket/controller
. -
org.kie.server.user
: User name used to connect to the KIE Server nodes from the Process Automation Manager controller. This property is only required when using this Business Central installation as a Process Automation Manager controller. -
org.kie.server.pwd
: Password used to connect to the KIE Server nodes from the Process Automation Manager controller. This property is only required when using this Business Central installation as a Process Automation Manager controller.
-
- Maven and miscellaneous
Use the following properties to configure Maven and other miscellaneous functions:
kie.maven.offline.force
: Forces Maven to behave as if offline. If true, disables online dependency resolution. Default value:false
.NoteUse this property for Business Central only. If you share a runtime environment with any other component, isolate the configuration and apply it only to Business Central.
-
org.uberfire.gzip.enable
: Enables or disables Gzip compression on theGzipFilter
compression filter. Default value:true
. -
org.kie.workbench.profile
: Selects the Business Central profile. Possible values areFULL
orPLANNER_AND_RULES
. A prefixFULL_
sets the profile and hides the profile preferences from the administrator preferences. Default value:FULL
-
org.appformer.m2repo.url
: Business Central uses the default location of the Maven repository when looking for dependencies. It directs to the Maven repository inside Business Central, for example,http://localhost:8080/business-central/maven2
. Set this property before starting Business Central. Default value: File path to the innerm2
repository. -
appformer.ssh.keystore
: Defines the custom SSH keystore to be used with Business Central by specifying a class name. If the property is not available, the default SSH keystore is used. -
appformer.ssh.keys.storage.folder
: When using the default SSH keystore, this property defines the storage folder for the user’s SSH public keys. If the property is not available, the keys are stored in the Business Central.security
folder. -
appformer.experimental.features
: Enables the experimental features framework. Default value:false
. -
org.kie.demo
: Enables an external clone of a demo application from GitHub. -
org.uberfire.metadata.index.dir
: Place where the Lucene.index
directory is stored. Default value: Working directory. -
org.uberfire.ldap.regex.role_mapper
: Regex pattern used to map LDAP principal names to the application role name. Note that the variable role must be a part of the pattern as the application role name substitutes the variable role when matching a principle value and role name. -
org.uberfire.sys.repo.monitor.disabled
: Disables the configuration monitor. Do not disable unless you are sure. Default value:false
. -
org.uberfire.secure.key
: Password used by password encryption. Default value:org.uberfire.admin
. -
org.uberfire.secure.alg
: Crypto algorithm used by password encryption. Default value:PBEWithMD5AndDES
. -
org.uberfire.domain
: Security-domain name used by uberfire. Default value:ApplicationRealm
. -
org.guvnor.m2repo.dir
: Place where the Maven repository folder is stored. Default value:<working-directory>/repositories/kie
. -
org.guvnor.project.gav.check.disabled
: Disables group ID, artifact ID, and version (GAV) checks. Default value:false
. -
org.kie.build.disable-project-explorer
: Disables automatic build of a selected project in Project Explorer. Default value:false
. -
org.kie.verification.disable-dtable-realtime-verification
: Disables the real-time validation and verification of decision tables. Default value:false
.
- Process Automation Manager controller
Use the following properties to configure how to connect to the Process Automation Manager controller:
-
org.kie.workbench.controller
: The URL used to connect to the Process Automation Manager controller, for example,ws://localhost:8080/kie-server-controller/websocket/controller
. -
org.kie.workbench.controller.user
: The Process Automation Manager controller user. Default value:kieserver
. -
org.kie.workbench.controller.pwd
: The Process Automation Manager controller password. Default value:kieserver1!
. -
org.kie.workbench.controller.token
: The token string used to connect to the Process Automation Manager controller.
-
- Java Cryptography Extension KeyStore (JCEKS)
Use the following properties to configure JCEKS:
-
kie.keystore.keyStoreURL
: The URL used to load a Java Cryptography Extension KeyStore (JCEKS). For example,file:///home/kie/keystores/keystore.jceks.
-
kie.keystore.keyStorePwd
: The password used for the JCEKS. -
kie.keystore.key.ctrl.alias
: The alias of the key for the default REST Process Automation Manager controller. -
kie.keystore.key.ctrl.pwd
: The password of the alias for the default REST Process Automation Manager controller.
-
- Rendering
Use the following properties to switch between Business Central and KIE Server rendered forms:
-
org.jbpm.wb.forms.renderer.ext
: Switches the form rendering between Business Central and KIE Server. By default, the form rendering is performed by Business Central. Default value:false
. -
org.jbpm.wb.forms.renderer.name
: Enables you to switch between Business Central and KIE Server rendered forms. Default value:workbench
.
-
Chapter 24. Performance tuning considerations with Business Central
The following key concepts or suggested practices can help you optimize Business Central configuration and Red Hat Process Automation Manager performance. These concepts are summarized in this section as a convenience and are explained in more detail in the cross-referenced documentation, where applicable. This section will expand or change as needed with new releases of Red Hat Process Automation Manager.
- Ensure that development mode is enabled during development
You can set KIE Server or specific projects in Business Central to use
production
mode ordevelopment
mode. By default, KIE Server and all new projects in Business Central are in development mode. This mode provides features that facilitate your development experience, such as flexible project deployment policies, and features that optimize KIE Server performance during development, such as disabled duplicate GAV detection. Use development mode until your Red Hat Process Automation Manager environment is established and completely ready for production mode.For more information about configuring the environment mode or duplicate GAV detection, see the following resources:
- Disable verification and validation of complex guided decision tables
The decision table verification and validation feature of Business Central is enabled by default. This feature helps you validate your guided decision tables, but with complex guided decision tables, this feature can hinder decision engine performance. You can disable this feature by setting the
org.kie.verification.disable-dtable-realtime-verification
system property value totrue
.For more information about guided decision table validation, see Designing a decision service using guided decision tables.
- Disable automatic builds if you have many large projects
In Business Central, when you navigate between projects in the Project Explorer side panel, the selected project is built automatically so that the Alerts window is updated to show any build errors for the project. If you have large projects or frequently switch between many projects that are under active development, this feature can hinder Business Central and decision engine performance.
To disable automatic project builds, set the
org.kie.build.disable-project-explorer
system property totrue
.
Appendix A. Versioning information
Documentation last updated on Wednesday, March 03, 2021.