Chapter 2. Business Central Configuration

Each splash page and its corresponding HTML file are located in the EAP_HOME/standalone/deployments/business-central.war/plugins/ directory. The files contain information about the images and the text to be displayed. For example, the authoring_perspective.splash.js splash page points to the authoring_perspective.splash.html file, which contains the names, captions, and location of all the image files that appear in the splash help pop-up windows of the Business Central Authoring perspective.

Deployment descriptors allow the user to configure the execution server on multiple levels:

The granular configuration items specified by the deployment descriptors take precedence over the server level ones, except in case of configuration items that are collection based, which are merged. The hierarchy works like this: deploy time configuration > KJAR configuration > server configuration.

For example, if the persistence mode (one of the items you can configure) defined at the server level is NONE but the same mode is specified as JPA at the KJAR level, the actual mode will be JPA for that KJAR. If nothing is specified for the persistence mode in the deployment descriptor for that KJAR (or if there is no deployment descriptor), it will fall back to the server level configuration, which in this case is NONE (or to JPA if there is no server level deployment descriptor).

Can You Override this Hierarchal Merge Mode Behavior?

Yes. In the default way, if there are deployment descriptors present at multiple levels, the configuration properties are merged with the granular ones overriding the coarse values, and with missing configuration items at the granular level being supplied with those values from the higher levels. The end result is a merged Deployment Descriptor configuration. This default merge mode is called the MERGE_COLLECTIONS mode. However, you can change it (see Section 2.4.2, “Managing Deployment Descriptors”) if it does not suit your environment to one of the following modes:

Deployment Descriptors from dependent KJARs are placed lower than the actual KJAR being deployed, but they still have higher hierarchy than the server level.

Do I Need to Provide a Full Deployment Descriptor for All Kjars?

No, and this is where the beauty of the merge between different files can help you. Providing partial Deployment Descriptors is possible and recommended. For example, if you want to only override the audit mode in a KJAR, then you just need to provide that and the rest of the values will be merged from server level or higher level KJARs.

It is worth noting that when using OVERRIDE_ALL merge mode, all configuration items should be specified since the relevant KJAR will always use them and will not merge with any other deployment descriptor in the hierarchy.

What Can You Configure?

High level technical configuration details can be configured via deployment descriptors. The following table lists these along with the permissible and default values for each.

How Do You Provide Values For Collections-Based Configuration Items?

In the table of valid configuration items earlier, you would have noticed that the valid values for the collection based items are either ObjectModel or NamedObjectModel. Both are similar and provide a definition of the object to be built or created at runtime, with the exception that the NamedObjectModel object details name the object to be looked. Both these types are defined using an identifier, optional parameters and resolver (to resolve the object).

As an example, if you have built a custom marshaling strategy and want your deployments to use that strategy instead of the default, you will need to provide that strategy as an ObjectModel, with the identifier being com.mycompany.MyStrategy, resolver being reflection (the easiest and the default) and any parameters that are required for your strategy to work. Reflection will then be used to create an instance of this strategy using the fully qualified class name that you have provided as the identifier.

<marshalling-strategy>
 <resolver>reflection</resolver>
 <identifier>com.myCompany.MyStrategy</identifier>
 <parameters>
    <parameter xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">
      param
    </parameter>
  </parameters>
</marshalling-strategy>

In the case that reflection based on resolver is not enough (as demonstrated in the previous example), you can use a resolver based on MVEL expression as the identifier of the object model. While evaluating expressions, you can substitute out-of-the-box parameters. For example:

<marshalling-strategy>
  <resolver>mvel</resolver>
  <identifier>new com.myCompany.CustomStrategy(runtimeManager)</identifier>
</marshalling-strategy>

The Spring based resolver allows you to look up a bean by its identifier from a Spring application context. Whenever JBoss BPM Suite is used with Spring, this resolver helps in deploying KJARs into the runtime. As an example (note that the identifier in this case is a named bean in the Spring context):

<marshalling-strategy>
 <resolver>spring</resolver>
 <identifier>customStrategy</identifier>
</marshalling-strategy>

Deployment Descriptors can be edited via the Business Central in one of two ways. Either graphically (by clicking on Authoring → Project Authoring → Deployment Descriptor or by clicking on Authoring → Administration menu and then clicking through to the META-INF folder in the File Explorer. Click on the kie-deployment-descriptor.xml file to edit it manually.

Every time a project is created, a stock kie-deployment-descriptor.xml file is generated with default values as described earlier.

Overriding Hierarchical Merge Mode Behavior

To change the default mode of MERGE_COLLECTIONS to one of KEEP_ALL, OVERRIDE_ALL, or OVERRIDE_EMPTY, you can use the following methods, depending on the requirement.

Restricting Access to the Runtime Engine

One of the configuration items discussed earlier, required-roles, can be edited via the Deployment Descriptors. This property restricts access to the runtime engine on a per KJAR or per server level by ensuring that access to certain processes is only granted to users that belong to groups defined by this property.

The security role can be used to restrict access to process definitions or restrict access at runtime.

The default behavior is to add required roles to this property based on repository restrictions. You can of course, edit these properties manually if required, as described above by providing roles that match actual roles defined in the security realm.

You access the Plugin Management screen by clicking on Extensions → Plugin Management. This brings up the Plugin Explorer screen that lists all the existing plugins under their respective categories:

Open any of these, and you will see the existing plugins in each category, including the uneditable system generated ones.

Let us create a new plugin that echoes "Hello World" when users visit the screen for that plugin. In general, the steps to creating a new plugin are:

Adding a New Screen

Click the button and select New Screen. You will be prompted to enter the name of this new screen. Enter "HelloWorldJS" and press the OK button. The Screen plugin editor will open, divided into 4 sections: Template, CSS, JavaScript and Media.

Template is where your HTML goes, CSS is for styling, JavaScript is for your functions and Media is for uploading and managing images.

Since we are making a simple Hello World plugin, enter the following code in the Template section: <div>My Hello World Screen</div>. This can be any HTML code, and you can use the supplied Angular and Knockout frameworks. For the purposes of this example, we are not using any of those frameworks, but you can choose to by selecting them from the drop down in the Template section.

Enter your JavaScript code in the JavaScript section. Some common methods and properties are defined for you, including main, on_close and on_open. For this demo, select the on_open and enter the following: function () { alert('Hello World'); }

Click the Save button to finish creating the screen. After you save the screen, refresh business central so that the Screen Plugin is listed in the Screen Component of Perspective plugin.

Adding New Perspective

Once a screen has been created, you need to create a perspective on which this screen will reside. Perspectives can also be created similar to the way a screen is created by clicking on the New button and then selecting New Perspective. You can now provide a name for this perspective, say HelloWorldPerspective. This will open the Perspective plugin editor, similar to the Screen plugin editor.

The Perspective Editor is like a drag and drop grid builder for screens and HTML components. Remove any existing grids and then drag a 6×6 grid on the right hand side to the left hand side.

Next, open the Components category and drag a Screen Component on the right hand side to the left hand side (in any grid). This will open the Edit Component dialog box that allows you to select the screen created in the previous step (HelloWorldJS). Click the OK button and then click Save to save this perspective. To tag your perspective, enter Home in the tag name field and click Tags. Click OK and save the changes.

You can open this perspective again from the Perspective plugins listed on the left hand side.

Adding New Menu

The final step in creating our plugin is to add a dynamic menu from where the new screen/perspective can be called up. To do so, go to Extensions → Plugin Management and then click on the New button to select New Dynamic Menu. Give this dynamic menu a name (HelloWorldMenu) and then click the OK button. The dynamic menu editor opens up.

Enter the perspective name (HelloWorldPerspective) as the Activity Id and the name for the drop down menu (HelloWorldMenuDropDown). Click OK and then Save.

This new menu will be added to your workbench the next time you refresh Business Central. Refresh it now to see HelloWorldMenu added to your top level menu. Click on it to reveal HelloWorldMenuDropDown, which when clicked will open your perspective/screen with the message Hello World.

You have created your first Plugin!

Working with Apps (Optional)

If you create multiple plugins, you can use the Apps directory feature to organize your own components and plugins, instead of having to rely on just the top menu entries.

When you save a new perspective, you can add labels (tags) for them and these labels (tags) are used to associate a perspective with an App directory. You can open the App directories by clicking on Extensions → Apps.

The Apps directory provides an alternate way to open your perspective. When you created your HelloWorldPerspective, you entered the tag Home. The Apps directory by default contains a single directory called Home with which you associated your perspective. This is where you will find it when you open the Apps directory. You can click on it to run the perspective now.

You can create multiple directories and associate perspectives with those directories depending on functional and vertical business requirements. For example, you could create an HR directory and then associate all HR related perspectives with that directory to better manage Apps.

You can create a new directory by clicking the button.

The extensibility of Business Central is achieved by an underlying JavaScript (JS) API which is automatically loaded if it is placed in the plugins folder of the Business Central webapp (typically: INSTALL_DIR/business-central.war/plugins/), or it can be loaded via regular JavaScript calls.

This API is divided into multiple sets depending on the functionality it performs.