Skip to main content

Providing Status Information

Most modules that operate in the gateway scope are long running, and therefore should provide easy access to status information. There are a variety of ways to provide status in Ignition, and the requirements of your module will dictate which, or which combination, you use.

Gateway Homepage Panels​

The homepage panels are the sections displayed when the Ignition gateway is first accessed. These panels usually indicate to the end user that a particular module is up and running and give some basic information that should be useful at a glance. For example, the SQLBridge module shows the number of running, errored, and stopped groups- information that is fundamental for that module.

A module can provide any number of homepage panels. The panels are defined in the module's GatewayModuleHook by implementing the getHomePagePanels() function. That function returns a HomepagePanelDescriptor, which defines various properties of the panel, such as the name, title, help bubble text, and more. The core body of the panel is generated by the call to newPanel on the descriptor, which uses Wicket to serve up a React web panel.

For Ignition 7.9, 8.0, and 8.1, we provide React and Redux as part of our Gateway API (marked as 'externals' in the webpack config), but as a module developer, you are free to use whatever client-side technologies you'd like to build the javascript that gets mounted for your pages. The components used in the Ignition Gateway Status section (such as Tables, Charts, etc) are implemented as reusable React components through the 'ignition-react' javascript package, so it may be easier for you to maintain a consistent appearance with the rest of Ignition's web components through their reuse.

Gateway Homepage Panel Example

For this example, the status page itself is assembled using the React javascript library, and the webpack bundling tool. The webpack process outputs a homeconnectstatus.js file that is referenced in the GatewayModuleHook. By placing it in the appropriate resource directory, it is included in the module when the mvn command is executed.

If you want to alter homeconnectstatus.js, you need to change the source in src/main/javascript, then run webpack before building your module. To do so, you will need Node and the Node Package Manager (npm) installed. See the instructions for installing node and npm if you don't have them installed on your development machine. We suggest using the current LTS version, though any LTS from version 12 up should work.

Once installed, follow these instructions at the command line, in the javascript folder:

  1. (Optional) Install the yarn package management tool to make use of its faster resolution and dependency locking features:

    npm i -g yarn@1.22.11

  2. Navigate to the source javascript directory:

    gateway-webpage-gateway/src/main/javascript

  3. Install the local dependencies using yarn or npm:

    npm install
    # or alternatively, if using yarn
    yarn install

  4. Use the provided node scripts to build the javascript (defined in the 'scripts' section of the package.json):

        npm run build:dev # builds 'development' versions, with additional tools for debugging

        npm run build:prod # builds the higher-performing 'production' version, which should be used for production modules

        # yarn alternatives
        # yarn run build:dev
        # yarn run build:prod

Note When installing this example module for the first time, the above steps must be performed in order to build homeconnect.js. If it is not built, the module file size will only be around 15kb after running mvn-package and the status page will not appear. Correctly built, the module size will be around 75kb after running mvn-package.

Webpack transpiles this React source code into a javascript file which is located in hce-gateway/src/main/resources/mounted/js. That transpiled javascript is what is ultimately mounted and served by Ignition.

Status Panels​

Status panels are similar to the homepage panels in how they're created and delivered, but they are shown on the status page. They are suitable for showing in-depth information that would be appropriate for troubleshooting and performance monitoring. They are implemented through the INamedTab interface, though you would extend the AbstractNamedTab class.

Using Wicket to Create a React Component
private static final INamedTab HCE_STATUS_PAGE = new AbstractNamedTab(
            "homeconnect",
            StatusCategories.SYSTEMS,
            "HomeConnect.nav.status.header") {


        @Override
        public WebMarkupContainer getPanel(String panelId) {
            // We've set  GatewayHook.getMountPathAlias() to return hce, so we need to use that alias here.
            return new BasicReactPanel(panelId, "/res/hce/js/homeconnectstatus.js", "homeconnectstatus");
            }

System Map Components​

The system map is a visual representation of the full system. It allows users to see at a glance the overall state, and is shared with redundant nodes in order to provide a complete overview.

To add components to the system map, the module should implement the updateSystemMap(SystemMap) function in the GatewayModuleHook. This function is called each time the map should be updated, and the module will create a SystemMapElement to add to the map provided to the function. Actual status information is added in the form of StatusItems on the SystemMapElement. In other words, a SystemMap consists of multiple SystemMapElements, each with multiple StatusItems.