Building custom dashboard widgets

Red Hat Process Automation Manager 7.0

Red Hat Customer Content Services

Abstract

This document describes how to build custom pages including dashboards and reports in Red Hat Process Automation Manager 7.0.

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.

Prerequisite

You must 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, in memory, and so on. A data set definition instructs Business Central how 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, which will define where the data set is stored, how it can be accessed, read, and parsed, and what columns it contains.

Note

The Data Sets page is visible only to users with admin role.

1.1. Adding data sets

You can create a new data set to fetch data from an external data source and use that data for the reporting components.

Procedure

  1. Log in to Business Central and click the gear icon.
  2. Click Data SetsData Set ExplorerNew Data Set.
  3. Select one of the following the 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

      Note

      KIE Server must be configured with this option.

  4. Complete the Data Set Creation Wizard and click Test.

    Note

    Depending on the provider you chose, the configuration steps will differ.

  5. 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

  1. Log in to Business Central, click the gear icon, and then click Data Sets.
  2. In the Data Set Explorer pane, search for the data set you want to edit and click Edit.
  3. In the Data Set Editor pane, use the appropriate tab to edit the data as required. The tabs will 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:

  4. After making the required changes, click Validate.
  5. 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 result in a data set, the caching technique will determine 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 size. 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, Business Central engine caches the data set. This reduces the number of requests to the remote storage system. All data set operations are performed in the Business Central 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.

Note

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 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

  1. Go to MenuDesignPages.
  2. In the Pages panel, click New. Alternatively, click New Page on the Page Editor pane.
  3. In the New Page dialog box, enter a value in the Name field and select the required style.
  4. Click Ok. The new page opens in the Page Editor.
  5. In the Components pane, expand the components and drag the required component types to the editor canvass.
  6. After placing the components on the page, edit its properties from the Properties pane.
  7. 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

  1. Go to MenuDesignPages.
  2. Select a page from the Pages panel. The page opens in the Page Editor.
  3. 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

Save

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.

Note

The Workbench tree, which appears by default in the Navigation panel, is the main Menu of Business Central.

2.3.1. Creating a navigation tree

You can create as many custom navigation trees as required. A custom navigation tree differs from the default Workbench navigation tree in one aspect. The custom navigation trees can be deleted but the default tree can not be removed from Business Central. They can contain the default groups and entries from the Workbench tree as well as user created groups and trees.

Prerequisites

  • Ensure your role has adequate permissions for creating a navigation tree.

Procedure

  1. Log in to Business Central and go to MenuDesignPages.
  2. Select the Navigation panel and then click New.
  3. Enter the name of the new navigation tree and click the check mark icon or, press Enter.
  4. Click Save.

2.3.2. Editing a navigation tree

You can use the Navigation panel from the Pages perspective to edit the custom navigation trees. You can further customize the trees by adding groups, dividers, and page entries, deleting the specific entries of the tree, and reordering, renaming, or deleting them.

Prerequisites

  • Ensure your role has adequate permissions for editing a navigation tree.

2.3.3. Adding groups, dividers, and page entries to a navigation tree

You can add groups, dividers, and page entries to a navigation tree.

Procedure

  1. Go to MenuDesignPages.
  2. Click the Navigation panel and then select the navigation tree you want to add the entries to.
  3. Click the gear icon of the tree and then select New Group, New Divider, or New Page.
  4. Enter the name of the new group or page and click the check mark icon or press Enter.

    Note

    Divider entries do not have a name property.

  5. Click Save.

2.3.4. Reordering a navigation tree

In the Navigation panel you can reorder the navigation trees as well as its entries.

Note

The reordering options of tree entries will differ according to their position in the tree hierarchy.

Reordering navigation trees

Procedure

  1. Go to MenuDesignPages.
  2. Click the Navigation panel and then select the navigation tree you want to reorder.
  3. Click the gear icon of the tree and then move up or down as required.

    Note

    First and last entries of a navigation tree have only two reordering options available.

  4. Click Save.
Reordering the entries of a navigation tree

Procedure

  1. Go to MenuDesignPages.
  2. Click the Navigation panel and then expand the navigation tree.
  3. Click the gear icon of the entry you want to reorder and then move up or down as required.
  4. If desired, click Goto Page to view the selected page.
  5. Click Save.

2.3.5. Renaming a navigation tree

You can rename all navigation trees except the Workbench tree.

Procedure

  1. Go to MenuDesignPages.
  2. Click the Navigation panel and then select the custom navigation tree you want to rename.

    Note

    To rename an entry of a tree, expand the tree and select the entry that you want to rename.

  3. Click the edit icon of the tree or the tree entry.
  4. Enter the new name of the tree and click the check mark icon.

    Note

    You cannot rename divider entries.

  5. Click Save.

2.3.6. Deleting a navigation tree

You can delete any navigation tree except the Workbench tree from the Navigation panel of the Pages perspective.

Procedure

  1. Go to MenuDesignPages.
  2. In the Navigation panel, select the navigation tree that you want to delete, then click the delete icon.
  3. Click Save.

2.3.7. Deleting the entries of a navigation tree

You can delete the entries of a navigation tree.

Procedure

  1. Go to MenuDesignPages.
  2. Click the Navigation panel.
  3. Expand the tree that contains the entries you want delete.
  4. Click the delete icon of the entry.
  5. Click Save.

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.

Table 2.1. Core component sub-types

Core component sub-typesDescription

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.

Note

Core components are not mandatory.

  • Navigation components: Used for navigating between pages. There are six types of navigation components.

Table 2.2. Navigation component sub-types

Navigation component sub-typesDescription

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.

Note

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.
Note

HTML components also have additional text properties to customize component Alignment, Decoration, Color, Size, and Weight properties.

Chapter 3. Security management

You can perform security and permission management tasks from the Security page. To access the Security page, click Roles, Groups, or Users on the Settings page. Depending on which icon you click, the Security page opens on 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.

3.1. Creating users

You can create as many Business Central users as you require. User privileges and settings are controlled by the roles assigned to a user and the groups that a user belongs to.

Procedure

  1. Click the gear icon, and then click Users.
  2. Click New user, enter a user name, and then click Next.
  3. If desired, click the Groups tab, click Add to groups, and then select the groups that you want this user to belong to. Then click Add to selected groups.
  4. Click the Roles tab, click Add roles, and then select the roles that you want to give this user. Then click Add to selected roles.
  5. Click Create.
  6. Click Yes to set a password for the user and click Change.
Note

The user must have at least one role to access Business Central.

3.2. Creating groups

Groups enable you to control privileges and settings for a collection of users. You can create as many groups as you require.

Procedure

  1. Click the gear icon, and then click Groups.
  2. Click New group, enter a group name, and then click Next.
  3. Select the users that you want to belong to this group, and then click Add selected users.

3.3. 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

  1. Click the gear icon, and then click Roles or Groups.
  2. Select a role or group.
  3. In the Permissions section, click the arrow next to the item that you want to change.

    The list of current permissions appears.

  4. Make any desired changes.
  5. Click Add Exception to add an item not listed, and then set the permissions as required.
  6. Click Save.
Note

Any changes you make to roles or groups affect all of the users associated with that role or group.

3.4. Changing the home page

The home page is the page that appears after you log on to Business Central. By default, the home page is set to Home. You can change the home page for roles and groups.

Procedure

  1. Click the gear icon, and then click Roles or Groups.
  2. Select a role or group.
  3. Select a page from the Home Page list.
  4. Click Save.

    Note

    The role or group must have read access to a page before you can make it the home page.

3.5. 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.

Procedure

  1. Click the gear icon, and then click Roles or Groups.
  2. Select a role or group.
  3. Select a priority from the Priority menu, and then click Save.
Note

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 a user enjoys when working on Business Central. For more information, see Security settings.
Note

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: Friday, August 31, 2018.

Legal Notice

Copyright © 2018 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.