Admin Tools

• Overview
• Installation
  • From the Marketplace
  • By Coordinates
• Enabling and Disabling Components
• Predefined Roles
• Add-on Components
  • Runtime Diagnose Components
  • SQL Script Generator
  • Shell Executor
  • SSH Terminal
  • Config Loader
  • Console Script Loader
  • Auto Import Subsystem
  • Tomcat JMX Bean

Overview

The add-on extends the capabilities of CUBA applications with runtime diagnostics and management tools. Using console you can interactively inspect the running application, interact with the database and generate SQL scripts.

You can also send OS commands (only for Unix-like systems) and connect to remote servers. Auto Import Subsystem provides preconfiguring servers and transferring data among servers automatically during the server start/restart.

Key features:

• Working with console straight from the user interface.
• Ability to diagnose runtime applications.
• Working with remote servers with the UI.
• Downloading/uploading configuration files and scripts.
• Executing operations on Tomcat server.

See sample application using this component.

Installation

The add-on can be added to your project in one of the ways described below. Installation from the Marketplace is the simplest way. The last version of the add-on compatible with the used version of the platform will be installed. Also, you can install the add-on by coordinates choosing the required version of the add-on from the table.

In case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in CUBA Platform documentation.

From the Marketplace

1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
2. Go to CUBA -> Marketplace in the main menu.

3. Find the Admin Tools add-on there.

4. Click Install and apply the changes. The add-on corresponding to the used platform version will be installed.

By coordinates

1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
2. Go to CUBA -> Marketplace in the main menu.
3. Click the icon in the upper-right corner.

4. Paste the add-on coordinates in the corresponding field as follows:

com.haulmont.addon.admintools:cuba-at-global:<add-on version>

where <add-on version> is compatible with the used version of the CUBA platform.

Platform Version	Add-on Version
7.2.x	1.5.0
7.1.x	1.4.0
7.0.x	1.3.1
6.10.x	1.2.1
6.9.x	1.1.3
6.8.x	1.0.5

5. Click Install and apply the changes. The add-on will be installed to your project.

Enabling and Disabling Components

Each part of the add-on can be enabled or disabled. It can be turned on or off explicitly or by using a corresponding application property. By default, all components are enabled, except Auto Import Subsystem.

You can turn on Auto Import Subsystem in the middleware block, writing the next property in the file app.properties:

admintools.autoImport.enabled = true

You can enable/disable the other components in the client block, writing the next properties in the file web-app.properties:

admintools.groovyConsole.enabled = false
admintools.sqlConsole.enabled = false
admintools.jpqlConsole.enabled = false
admintools.diagnoseExecutionLog.enabled = false

admintools.scriptGenerator.enabled = false
admintools.shellExecutor.enabled = false
admintools.sshTerminal.enabled = false
admintools.configLoader.enabled = false
admintools.consoleScriptLoader.enabled = false

Predefined Roles

• admin-tools-full-access - grants full access to the add-on features.
• admin-tools-diagnose - grants an ability to upload diagnose info in admin tools Diagnose Wizard dialog window.

Add-on Components

Runtime Diagnose Components

Components Groovy Console, JPQL Console, SQL Console and Diagnose Execution Logs are imported from the Runtime Diagnose Component.

The following enhancements have been made for this component:

• Added an ability to import scripts from ZIP files for Groovy Console, JPQL Console and SQL Console.
• Added the autocomplete for providing suggestions while you type JPQL request in JPQL Console.

SQL Script Generator

This part of the component enables generating SQL scripts for selected project entities.

JPQL requests are used for entity selection. Start by specifying a metaclass, view and type of a script to be generated (insert, update, insert update). Selecting a metaclass automatically generates a JPQL request:

select e from example$Entity e

After that, SQL scripts of the specified type are generated for the found entities. If no results are found, the system shows a corresponding notification. You can limit the number of entities to be loaded using the Entity Limit field.

Note: if you cancel the process, it will not be stopped on the middleware.

Shell Executor

Shell Executor is designed for running shell scripts. It allows you to run various OS commands from the application UI. Note that this functionality is available only on Unix-like systems.

The screen consists of two sections: the first section allows a user to input and manage scripts and the second one enables working with results.

When scripts are run, the system generates temporary files which are stored in the tomcat/temp directory. Note that the component does not remove these files automatically.

SSH Terminal

SSH Terminal is designed for working with remote servers from the application UI.

Before connecting to a remote server, it is required to specify credentials and a hostname in the corresponding section. As an alternative, use a private key and a passphrase for a connection instead of a password. After that, use action buttons to connect to a server. The toolbar of SSH Console contains also the Fit button, which allows a user to change the size of the terminal.

Connection parameters can be stored in the database (except the password and the passphrase). For saving, removing and loading connection parameters, use corresponding buttons. By default, connection parameters are saved only for the current user if the checkbox Is for everyone isn't checked. All available connection parameters are shown in the Saved Sessions list.

Known Issues

• The screen utility does not work in the terminal.

Config Loader

Using the Config Loader, it is possible to upload configuration files and various scripts to a configuration directory from the system UI without stopping the application.

The configuration directory is located at tomcat/conf. Additionally, you can specify a relative path in the corresponding field.

When trying to upload a file that already exists in the configuration directory or if names of two files coincide, a message requesting to confirm file replacement appears.

Console Script Loader

Console Script Loader is used to import scripts in the Groovy, JPQL and SQL consoles. Upload ZIP in the corresponding field and it redirects to a necessary console with a script in a text field.

Auto Import Subsystem

The AutoImport subsystem is designed to preconfigure servers and transfer data among servers. The process is launched automatically during the server start/restart.

For importing data, specify a path to a ZIP archive or a JSON file in the configuration file. If an archive with the same name has already been processed, then it is not considered by the system and skipped.

There are several options for exporting various entities:

• Security roles and access groups can be exported using the Export as ZIP or Export as JSON actions available on the Roles and Access Groups screens.
• Arbitrary entities can be exported using the Export as ZIP or Export as JSON actions available on the Administration > Entity Inspector screen.

Creating an Auto Import Configuration File

1. Example of a configuration file:

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <auto-import>
       <!--default processor-->
       <auto-import-file path="com/company/example/Roles.zip" bean="admintools_DefaultAutoImportProcessor"/>
       <auto-import-file path="com/company/example/Groups.json" class="com.company.example.SomeProcessor"/>
   </auto-import>

   Where path is a path to the data file, bean/class — a processor.

2. Add the admintools.autoImportConfig property to app.properties and specify the path to the configuration file. For example:

   admintools.autoImportConfig = +com/company/example/auto-import.xml

3. Add admintools.autoImport.enabled=true property to app.properties file.

Custom Import Processor

A processor is responsible for file processing and can be implemented as a bean or a simple Java class. If necessary, you can provide a custom implementation of a processor for any entity within the project by implementing the AutoImportProcessor interface.

Creating a Custom Import Processor

1. Create a class that implements the AutoImportProcessor interface.

   @Component("admintools_ReportsAutoImportProcessor")
   public class ReportsAutoImportProcessor implements AutoImportProcessor {
       @Inject
       protected ReportService reportService;
       @Inject
       protected Resources resources;
   
       @Override
       public void processFile(String filePath) throws Exception {
           try (InputStream inputStream = resources.getResourceAsStream(filePath)) {
               byte[] fileBytes = IOUtils.toByteArray(inputStream);
               reportService.importReports(fileBytes);
           }
       }
   }

2. If a processor is implemented as a Spring bean, specify the bean name in the configuration file. If a processor is implemented as a simple class, specify its FQN.

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <auto-import>
       ...
       <auto-import-file path="com/company/example/Reports.zip" bean="admintools_ReportsAutoImportProcessor"/>
       <auto-import-file path="com/company/example/Reports.json" class="com.company.example.ReportsAutoImportProcessor"/>
       ...
   </auto-import>

Logging

Logging information is available in the app.log file. See examples of the log output below.

Successful import

com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing
...
com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip has been imported

Incorrect name of a processor

com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing
...
com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - org.springframework.beans.factory.NoSuchBeanDefinitionException: No bean named 'autoimport_InvalidAutoImportProcessor' available

com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing
...
com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - java.lang.ClassNotFoundException: com.example.InvalidAutoImportProcessor

Uploaded archive is not found

com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing
com.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - File not found by the path com/example/invalid.zip

Known Issues

Class com.haulmont.cuba.core.app.importexport.EntityImportViewBuilder is extended by class ExtendedEntityImportViewBuilder to build JSON if ONE_TO_MANY meta property has type ASSOCIATION.

Tomcat JMX Bean

Tomcat JMX is a management bean which allows you to execute operations on Tomcat server currently running the application. It is supported on Windows and Unix-like operating systems. The bean can be accessed from Administration → JMX Console screen. Start searching by the object name 'Tomcat' and the domain 'cuba-at' and you will find the TomcatWeb MBean. If the middleware block is running on the same Tomcat, you will see also the TomcatCore MBean. In this case, you can use either of them.

Tomcat JMX bean allows you to execute the following operations:

• getTomcatAbsolutePath - returns an absolute path to the Tomcat directory;
• shutdown - shutdowns the Tomcat process;
• reboot - shutdowns the existing Tomcat process and runs a new one;
• runShellScript - runs a script in the Tomcat directory with the following arguments:
  1. Path - path to a script relative to the Tomcat root directory;
  2. Arguments - arguments that should be passed to the script.