此内容没有您所选择的语言版本。
Building custom dashboard widgets
Abstract
Preface
As a business analyst or business rules developer, use the Page Editor tool to design and define your page and specify the information to be displayed on it. You can decide which components are a part of your page. You can also customize the component properties of a page according to your requirements. Optionally, before creating a page, you can define a data set to feed the reporting components of the page.
Prerequisites
- You have sufficient permissions for creating pages.
Chapter 1. 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.
1.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.
1.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 1.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.
1.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.
1.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 2. Page authoring
Pages, also known as perspectives, are collections of following components:
- Core components
- Navigational components
- Reporting components
Also, a page can have none or any number of components. The Page Editor tool is used to edit the pages.
A page has either the Fluid style or the Page style. The Fluid style is a classical web page with a vertical scroll bar, when the page exceeds the available height. The Page style is a web page that will always fit to the windows height.
2.1. Creating pages
You can use the Pages perspective to create a page that consists of different types of components. After a page has been created and all the components in it defined, use the Page Editor to save, delete, rename, or copy pages as required.
The following procedure describes how to create a page and add the required components to it:
Procedure
- In Business Central, go to Menu → Design → Pages.
- In the Pages panel, click New. Alternatively, click New Page on the Page Editor pane.
- In the New Page dialog box, enter a value in the Name field and select the required style.
- Click Ok. The new page opens in the Page Editor.
- In the Components pane, expand the components and drag the required component types to the editor canvass.
- After placing the components on the page, edit its properties from the Properties pane.
- Click Save and then click Save again.
2.2. Saving, deleting, renaming, or copying pages
After you have created and defined a page, use the Page Editor to save, delete, rename, or copy pages as required.
Procedure
- In Business Central, go to Menu → Design → Pages.
- Select a page from the Pages panel. The page opens in the Page Editor.
- Perform the desired operation and select Save, Delete, Rename, or Copy from the upper right corner of the Page Editor.
Figure 2.1. Save, delete, rename, or copy pages
2.3. Navigation tree
The Workbench navigation tree contains the entries that are displayed in Business Central’s Main menu. Changes to this navigation tree structure will be reflected in the Main menu on the Home page. Such mechanism can be used, for example, to publish new pages.
Also, additional navigation trees can be created. These custom trees can be used to configure the navigation components within a page. You cannot delete the Workbench tree from the Navigation panel but you can edit the Workbench tree hierarchy to suit your requirements. This feature helps users customize the Main menu of Business Central with new pages.
The Workbench tree, which appears by default in the Navigation panel, is the main Menu of Business Central.
2.4. Components
A page contains different types of components. You can use the following component types in a page:
- Core components: Used to specify custom HTML information or display existing pages. There are two types of core components.
Core component sub-types | Description |
---|---|
HTML | This component opens a HTML editor widget. This can be used to create HTML pages using text, images, tables, links, colors, and so on. You can customize the page as per your requirements. |
Page | This component allows you to add previously created pages to a new dashboard. You can use this component to nest custom pages you have already created in your dashboard. |
Core components are not mandatory.
- Navigation components: Used for navigating between pages. There are six types of navigation components.
Navigation component sub-types | Description |
---|---|
Target Div | This component is used by the Tab list, Menu bar, and the Tree navigator components to display their entries and keep track of the last item clicked. |
Menu Bar | This component displays the entries of a navigation tree in the form of a menu bar. There is no limit to the number of levels supported by Business Central. |
Tile Navigator | This component displays the navigation group in the form of tiles. Groups are displayed as folders but for single entries, its content is displayed instead when selected. |
Tree | This component displays the entries in a vertical tree structure format. |
Carousel | This component displays or cycles through the selected pages like a carousel or a slide show. |
Tab List | This component displays selected menu pages as tabs at the top of the component. |
The target div setting is not needed for non-target div components such as Carousel or Tile navigator.
Reporting components: Used for displaying data from data sets (see Data sets authoring section) in the form of graphs, tables, maps, and so on. There are ten types of reporting components. The reporting components can be configured using the New Displayer widget, which has the following three tabs:
- Type: Choose how to display custom data graphically.
- Data: Choose a data set from the list of custom data sets that you had created from the Data Sets section available in the Settings menu.
- Display: Edit and customize how the content is displayed by adding titles, changing colors, size, and so on.
2.4.1. Placing components on the page editor to create a page
To create pages, you must drag the components to the Editor canvas of the Pages perspective. After placing all of the required components on the page, click Save.
2.4.2. Using the Preview tab to preview pages
While creating or editing pages, click the Preview tab on the Page Editor to preview a page before saving it.
2.4.3. Component properties
The components used in a page have different properties associated with them. The Properties panel enables you to customize a component by editing the following properties:
- Panel properties: Used to customize component panel properties such as Width, Height, and Background Color.
- Margin properties: Used to customize component margin properties such as Top, Bottom, Left, and Right.
- Padding properties: Used to customize component padding properties such as Top, Bottom, Left, and Right.
HTML components also have additional text properties to customize component Alignment, Decoration, Color, Size, and Weight properties.
Chapter 3. Security management
Security management is the process of managing users, groups, and permissions. You can control access to Business Central resources and features from the Business Central Security management page.
Business Central defines three types of entities for security management: users, groups, and roles. You can assign permissions to both roles and groups. A user inherits permissions from the groups and roles that the user is a member of.
3.1. Security management providers
In the context of security management, a realm restricts access to different application resources. Realms contain information about users, groups, roles, and permissions. A concrete user and group management service implementation for a specific realm is called a security management provider.
If the built-in security management providers do not meet the requirements of your application security realm, then you can build and register your own security management provider.
If the security management provider is not installed, the user interface for managing the security realm is not available. After you install and configure a security management provider, the user and group management features are automatically enabled in the security management user interface.
Business Central includes the Red Hat JBoss EAP security management provider which supports realm types based on the contents of the application-users.properties
or application-roles.properties
property file.
3.1.1. Configuring the Red Hat JBoss EAP security management provider based on property files
You can build and register your own Red Hat JBoss EAP security management provider. To use the Red Hat JBoss EAP security management provider based on property files, complete the steps in this procedure.
Prerequisites
- Red Hat JBoss EAP is installed.
Procedure
To use an existing users or roles property file from the Red Hat JBoss EAP instance, include the following system properties in the
EAP_HOME/standalone/configuration/application-users.properties
andEAP_HOME/standalone/configuration/application-roles.properties
files, as shown in the following example:<property name="org.uberfire.ext.security.management.wildfly.properties.realm" value="ApplicationRealm"/> <property name="org.uberfire.ext.security.management.wildfly.properties.users-file-path" value="/standalone/configuration/application-users.properties"/> <property name="org.uberfire.ext.security.management.wildfly.properties.groups-file-path" value="/standalone/configuration/application-roles.properties"/>
The following table provides a description and default value for these properties:
Table 3.1. Red Hat JBoss EAP security management provider based on property files Property Description Default value org.uberfire.ext.security.management.wildfly.properties.realm
The name of the realm. This property is not mandatory.
ApplicationRealm
org.uberfire.ext.security.management.wildfly.properties.users-file-path
The absolute file path for the users property file. This property is mandatory.
./standalone/configuration/application-users.properties
org.uberfire.ext.security.management.wildfly.properties.groups-file-path
The absolute file path for the groups property file. This property is mandatory.
./standalone/configuration/application-roles.properties
Create the
security-management.properties
file in the root directory of your application. For example, create the following file:src/main/resources/security-management.properties
Enter the following system property and security provider name as a value in the
security-management.properties
file:<property name="org.uberfire.ext.security.management.api.userManagementServices" value="WildflyUserManagementService"/>
3.1.2. Configuring the Red Hat JBoss EAP security management provider based on property files and CLI mode
To use the Red Hat JBoss EAP security management provider based on property files and CLI mode, complete the steps in this procedure.
Prerequisites
- Red Hat JBoss EAP is installed.
Procedure
To use an existing users or roles property file from the Red Hat JBoss EAP instance, include the following system properties in the
EAP_HOME/standalone/configuration/application-users.properties
andEAP_HOME/standalone/configuration/application-roles.properties
files, as shown in the following example:<property name="org.uberfire.ext.security.management.wildfly.cli.host" value="localhost"/> <property name="org.uberfire.ext.security.management.wildfly.cli.port" value="9990"/> <property name="org.uberfire.ext.security.management.wildfly.cli.user" value="<USERNAME>"/> <property name="org.uberfire.ext.security.management.wildfly.cli.password" value="<USER_PWD>"/> <property name="org.uberfire.ext.security.management.wildfly.cli.realm" value="ApplicationRealm"/>
The following table provides a description and default value for these properties:
Table 3.2. Red Hat JBoss EAP security management provider based on property files and CLI mode Property Description Default value org.uberfire.ext.security.management.wildfly.cli.host
The native administration interface host.
localhost
org.uberfire.ext.security.management.wildfly.cli.port
The native administration interface port.
9990
org.uberfire.ext.security.management.wildfly.cli.user
The native administration interface username.
NA
org.uberfire.ext.security.management.wildfly.cli.password
The native administration interface user’s password.
NA
org.uberfire.ext.security.management.wildfly.cli.realm
The realm used by the application’s security context.
ApplicationRealm
Create the
security-management.properties
file in the root directory of your application. For example, create the following file:src/main/resources/security-management.properties
Enter the following system property and security provider name as a value in the
security-management.properties
file:<property name="org.uberfire.ext.security.management.api.userManagementServices" value="WildflyCLIUserManagementService"/>
3.2. Permissions and settings
A permission is an authorization granted to a user to perform actions related to a specific resource within the application. For example, a user can have following permissions:
- View a page.
- Save the project.
- View a repository.
- Delete a dashboard.
You can grant or deny a permission and a permission can be global or resource specific. You can use permissions to protect access to resources and customize features within the application.
3.2.1. Changing permissions for groups and roles in Business Central
In Business Central, you cannot change permissions for an individual user. However, you can change permissions for groups and roles. The changed permissions apply to users with the role or that belong to a group that you changed.
Any changes that you make to roles or groups affect all of the users associated with that role or group.
Prerequisites
-
You are logged in to Business Central with the
admin
user role.
Procedure
- To access the Security management page in Business Central, select the Admin icon in the top-right corner of the screen.
Click Roles, Groups, or Users on the Business Central Settings page.
The Security management page opens on the tab for the icon that you clicked.
- From the list, click the role or group you want to edit. All details are displayed in the right panel.
- Set the Home Page or Priority under the Settings section.
Set the Business Central, page, editor, space, and project permissions under the Permissions section.
Figure 3.1. Setting the permissions
- Click the arrow next to a resource type to expand the resource type whose permissions you want to change.
Optional: To add an exception for a resource type, click Add Exception and then set the permissions as required.
NoteYou cannot add an exception to the Business Central resource type.
- Click Save.
3.2.2. Changing the Business Central home page
The home page is the page that appears after you log in to Business Central. By default, the home page is set to Home
. You can specify a different home page for each role and group.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Roles or Groups.
- Select a role or group.
- Select a page from the Home Page list.
Click Save.
NoteThe role or group must have read access to a page before you can make it the home page.
3.2.3. Setting priorities
A user can have multiple roles and belong to multiple groups. The Priority setting determines the order of precedence of a role or group.
Prerequisites
-
You are logged in to Business Central with the
admin
user role.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Roles or Groups.
- Select a role or group.
- Select a priority from the Priority menu, and then click Save.
If a user has a role or belongs to a group that has conflicting settings, the settings of the role or group with the highest priority applies.
Chapter 4. Creating a custom dashboard widget
In order to create custom dashboards, users must combine some of the features of the Business Central (like data sets, pages, navigation trees, and permissions) together and publish them. Dashboards are pages containing at least one reporting component.
There are four stages in the creation of a custom dashboard:
- Data set authoring - In this stage, you define a data set for accessing the data and displaying it through the pages. For more information, see Adding data sets.
- Page authoring - In this stage, you create the pages which are used to display the data from the data sets, among other things. For more information, see Creating pages.
- Publication - In this stage, navigation between pages are defined when you create the custom navigation trees or modify the existing default one (Workbench tree). For more information, see Creating a navigation tree or Editing a navigation tree.
- Security management - In this stage, role and group permissions are set which defines the privileges that are granted to a user when the user is working on Business Central. For more information, see Security management.
You will have to follow the stages listed above if you plan on migrating your dashboards from previous versions of Business Central to the latest one. Note that there is no automatic migration path or tooling to assist you in that regard. You must recreate all your dashboards from scratch.
Appendix A. Versioning information
Documentation last updated on Wednesday, April 28, 2021.