{"id":21430183,"url":"https://github.com/cuba-platform/admin-tools-addon","last_synced_at":"2025-07-09T13:08:50.014Z","repository":{"id":150931706,"uuid":"127886190","full_name":"cuba-platform/admin-tools-addon","owner":"cuba-platform","description":"Interactive runtime diagnosis for CUBA applications","archived":false,"fork":false,"pushed_at":"2025-01-28T09:40:13.000Z","size":1693,"stargazers_count":7,"open_issues_count":3,"forks_count":7,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-08T07:30:58.142Z","etag":null,"topics":["admin-tools","apache2","cuba-component","cuba-platform"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuba-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-03T09:43:32.000Z","updated_at":"2025-01-14T09:27:16.000Z","dependencies_parsed_at":"2025-01-14T10:35:25.125Z","dependency_job_id":"95ea030d-bcdd-4cb7-9ad5-15adf0060baf","html_url":"https://github.com/cuba-platform/admin-tools-addon","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/cuba-platform/admin-tools-addon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fadmin-tools-addon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fadmin-tools-addon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fadmin-tools-addon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fadmin-tools-addon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuba-platform","download_url":"https://codeload.github.com/cuba-platform/admin-tools-addon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fadmin-tools-addon/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264465872,"owners_count":23612583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin-tools","apache2","cuba-component","cuba-platform"],"created_at":"2024-11-22T22:21:25.482Z","updated_at":"2025-07-09T13:08:50.008Z","avatar_url":"https://github.com/cuba-platform.png","language":"Java","readme":"\u003cp\u003e\n    \u003ca href=\"http://www.apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat\" alt=\"license\" title=\"\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://travis-ci.org/cuba-platform/admin-tools-addon\"\u003e\u003cimg src=\"https://travis-ci.org/cuba-platform/admin-tools-addon.svg?branch=master\" alt=\"Build Status\" title=\"\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Admin Tools\n\n- [Overview](#overview)\n- [Installation](#installation)\n  - [From the Marketplace](#from-the-marketplace)\n  - [By Coordinates](#by-coordinates)\n- [Enabling and Disabling Components](#enabling-and-disabling-components)\n- [Predefined Roles](#predefined-roles)\n- [Add-on Components](#add-on-components)\n  - [Runtime Diagnose Components](#runtime-diagnose-components)\n  - [SQL Script Generator](#sql-script-generator)\n  - [Shell Executor](#shell-executor)\n  - [SSH Terminal](#ssh-terminal)\n  - [Config Loader](#config-loader)\n  - [Console Script Loader](#console-script-loader)\n  - [Auto Import Subsystem](#auto-import-subsystem)\n  - [Tomcat JMX Bean](#tomcat-jmx-bean)\n\n# Overview\n\nThe 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.\n\nYou 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.\n\nKey features:\n\n* Working with console straight from the user interface.\n* Ability to diagnose runtime applications.\n* Working with remote servers with the UI.\n* Downloading/uploading configuration files and scripts.\n* Executing operations on Tomcat server.\n\nSee [sample application](https://github.com/cuba-platform/admin-tools-demo) using this component.\n\n# Installation\n\nThe 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.\nAlso, you can install the add-on by coordinates choosing the required version of the add-on from the table.\n\nIn 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](https://doc.cuba-platform.com/manual-latest/manual.html#app_components_usage).\n\n## From the Marketplace\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n\n ![marketplace](img/marketplace.png)\n\n3. Find the Admin Tools add-on there.\n\n ![addons](img/addons.png)\n\n4. Click *Install* and apply the changes.\nThe add-on corresponding to the used platform version will be installed.\n\n## By coordinates\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n3. Click the icon in the upper-right corner.\n\n ![by-coordinates](img/by-coordinates.png)\n\n4. Paste the add-on coordinates in the corresponding field as follows:\n\n `com.haulmont.addon.admintools:cuba-at-global:\u003cadd-on version\u003e`\n\n where `\u003cadd-on version\u003e` is compatible with the used version of the CUBA platform.\n\n | Platform Version | Add-on Version |\n|------------------|----------------|\n| 7.2.x            | 1.5.0          |\n| 7.1.x            | 1.4.0          |\n| 7.0.x            | 1.3.1          |\n| 6.10.x           | 1.2.1          |\n| 6.9.x            | 1.1.3          |\n| 6.8.x            | 1.0.5          |\n\n5. Click *Install* and apply the changes. The add-on will be installed to your project.\n\n# Enabling and Disabling Components\n\nEach 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](#auto-import-subsystem).\n\nYou can turn on *Auto Import Subsystem* in the middleware block, writing the next property in the file `app.properties`:\n\n```properties\nadmintools.autoImport.enabled = true\n```\n\nYou can enable/disable the other components in the client block,  writing the next properties in the file `web-app.properties`:\n```properties\nadmintools.groovyConsole.enabled = false\nadmintools.sqlConsole.enabled = false\nadmintools.jpqlConsole.enabled = false\nadmintools.diagnoseExecutionLog.enabled = false\n\nadmintools.scriptGenerator.enabled = false\nadmintools.shellExecutor.enabled = false\nadmintools.sshTerminal.enabled = false\nadmintools.configLoader.enabled = false\nadmintools.consoleScriptLoader.enabled = false\n```\n\n# Predefined Roles\n\n- **admin-tools-full-access** - grants full access to the add-on features.\n- **admin-tools-diagnose** - grants an ability to upload diagnose info in admin tools *Diagnose Wizard* dialog window.\n\n# Add-on Components\n\n## Runtime Diagnose Components\nComponents *Groovy Console*, *JPQL Console*, *SQL Console* and *Diagnose Execution Logs* are imported\nfrom the [Runtime Diagnose Component](https://github.com/mariodavid/cuba-component-runtime-diagnose).\n\nThe following enhancements have been made for this component:\n\n* Added an ability to import scripts from ZIP files for *Groovy Console*, *JPQL Console* and *SQL Console*.\n* Added the autocomplete for providing suggestions  while you type JPQL request in *JPQL Console*.\n\n## SQL Script Generator\n\nThis part of the component enables generating SQL scripts for selected project entities.\n\n![generate-scripts-menu](img/gen-scripts-menu.png)\n\nJPQL requests are used for entity selection. Start by specifying a metaclass, view and type of a script to be generated\n(insert, update, insert update). Selecting a metaclass automatically generates a JPQL request:\n\n```sql\nselect e from example$Entity e\n```\n\n![generate-scripts-dialog](img/gen-scripts-dialog.png)\n\nAfter that, SQL scripts of the specified type are generated for the found entities. If no results are found,\nthe system shows a corresponding notification. You can limit the number of entities to be loaded using\nthe *Entity Limit* field.\n\n*Note:* if you cancel the process, it will not be stopped on the middleware.\n\n## Shell Executor\nShell Executor is designed for running shell scripts. It allows you to run various OS commands from the application UI.\nNote that this functionality is available only on Unix-like systems.\n\n![shell_console_menu_item](img/shell-executor-menu-item.png)\n\n![shell_console](img/shell-executor.png)\n\nThe screen consists of two sections: the first section allows a user to input and manage scripts and the second one enables working with results.\n\nWhen scripts are run, the system generates temporary files which are stored in the `tomcat/temp` directory. Note\nthat the component does not remove these files automatically.\n\n## SSH Terminal\n\nSSH Terminal is designed for working with remote servers from the application UI.\n\n ![ssh_console_menu_item](img/ssh-terminal_menu_item.png)\n\nBefore connecting to a remote server, it is required to specify credentials and a hostname in the corresponding section.\nAs 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.\nThe toolbar of *SSH Console* contains also the _Fit_ button, which allows a user to change the size of the terminal.\n\nConnection parameters can be stored in the database (except the password and the passphrase). For saving, removing and loading\nconnection parameters, use corresponding buttons. By default, connection parameters are saved only for the current user\nif the checkbox *Is for everyone* isn't checked. All available connection parameters are shown in the *Saved Sessions* list.\n\n![ssh_console_connected](img/ssh-terminal_connected.png)\n\n### Known Issues\n\n- The `screen` utility does not work in the terminal.\n\n## Config Loader\n\nUsing the Config Loader, it is possible to upload configuration files and various scripts to a [configuration\ndirectory](https://doc.cuba-platform.com/manual-latest/conf_dir.html) from the system UI without stopping the application.\n\n![Load-config-menu-item](img/config-loader-menu-item.png)\n\nThe configuration directory is located at `tomcat/conf`. Additionally, you can specify a relative path\nin the corresponding field.\n\n![load-config](img/config-loader.png)\n\nWhen trying to upload a file that already exists in the configuration directory or if names of two files coincide,\na message requesting to confirm file replacement appears.\n\n![confirm-file-replace](img/confirm-file-replacement.png)\n\n## Console Script Loader\n![console-script-loader-menu-item](img/console-script-loader-menu-item.png)\n\nConsole Script Loader is used to import scripts in the [Groovy, JPQL and SQL consoles](#runtime-diagnose-components).\nUpload ZIP in the corresponding field and it redirects to a necessary console with a script in a text field.\n\n![console-script-loader-menu-item](img/console-script-loader.png)\n\n## Auto Import Subsystem\n\nThe AutoImport subsystem is designed to preconfigure servers and transfer data among servers. The process is launched\nautomatically during the server start/restart.\n\nFor 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\n been processed, then it is not considered by the system and skipped.\n\nThere are several options for exporting various entities:\n\n* 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.\n* Arbitrary entities can be exported using the __Export as ZIP__  or __Export as JSON__ actions available on the *Administration \u003e Entity Inspector* screen.\n\n### Creating an Auto Import Configuration File\n\n1. Example of a configuration file:\n\n     ```xml\n     \u003c?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?\u003e\n     \u003cauto-import\u003e\n         \u003c!--default processor--\u003e\n         \u003cauto-import-file path=\"com/company/example/Roles.zip\" bean=\"admintools_DefaultAutoImportProcessor\"/\u003e\n         \u003cauto-import-file path=\"com/company/example/Groups.json\" class=\"com.company.example.SomeProcessor\"/\u003e\n     \u003c/auto-import\u003e\n     ```\n\n     Where `path` is a path to the data file, `bean`/`class` — a processor.\n\n2. Add the `admintools.autoImportConfig` property to `app.properties` and specify the path to the configuration file.\nFor example:\n\n    ```properties\n    admintools.autoImportConfig = +com/company/example/auto-import.xml\n    ```\n3. Add `admintools.autoImport.enabled=true` property to `app.properties` file.\n\n### Custom Import Processor\n\nA processor is responsible for file processing and can be implemented as a bean or a simple Java class.\nIf necessary, you can provide a custom implementation of a processor for any entity within the project by implementing the\n`AutoImportProcessor` interface.\n\n#### Creating a Custom Import Processor\n\n1. Create a class that implements the `AutoImportProcessor` interface.\n\n     ```java\n     @Component(\"admintools_ReportsAutoImportProcessor\")\n     public class ReportsAutoImportProcessor implements AutoImportProcessor {\n         @Inject\n         protected ReportService reportService;\n         @Inject\n         protected Resources resources;\n\n         @Override\n         public void processFile(String filePath) throws Exception {\n             try (InputStream inputStream = resources.getResourceAsStream(filePath)) {\n                 byte[] fileBytes = IOUtils.toByteArray(inputStream);\n                 reportService.importReports(fileBytes);\n             }\n         }\n     }\n     ```\n\n2. 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,\nspecify its FQN.\n\n     ```xml\n     \u003c?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?\u003e\n     \u003cauto-import\u003e\n         ...\n         \u003cauto-import-file path=\"com/company/example/Reports.zip\" bean=\"admintools_ReportsAutoImportProcessor\"/\u003e\n\t\t \u003cauto-import-file path=\"com/company/example/Reports.json\" class=\"com.company.example.ReportsAutoImportProcessor\"/\u003e\n         ...\n     \u003c/auto-import\u003e\n     ```\n\n### Logging\n\nLogging information is available in the `app.log` file. See examples of the log output below.\n\n#### Successful import\n\n```\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing\n...\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip has been imported\n```\n\n#### Incorrect name of a processor\n\n```\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing\n...\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - org.springframework.beans.factory.NoSuchBeanDefinitionException: No bean named 'autoimport_InvalidAutoImportProcessor' available\n```\n\n```\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing\n...\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - java.lang.ClassNotFoundException: com.example.InvalidAutoImportProcessor\n```\n\n#### Uploaded archive is not found\n\n```\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - file com/company/autoimporttest/Roles.zip is importing\ncom.haulmont.addon.admintools.core.auto_import.AutoImporterImpl - File not found by the path com/example/invalid.zip\n```\n\n### Known Issues\n\nClass `com.haulmont.cuba.core.app.importexport.EntityImportViewBuilder` is extended by class `ExtendedEntityImportViewBuilder`\nto build JSON if ONE_TO_MANY meta property has type ASSOCIATION.\n\n## Tomcat JMX Bean\nTomcat JMX is a management bean which allows you to execute operations on Tomcat server currently running the application.\nIt is supported on Windows and Unix-like operating systems. The bean can be accessed from *Administration → JMX Console* screen.\nStart searching by the object name 'Tomcat' and the domain 'cuba-at' and you will find the *TomcatWeb* MBean.\nIf 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.\n\n![find tomcat jmx](img/find-tomcat-jmx.png)\n\nTomcat JMX bean allows you to execute the following operations:\n\n* `getTomcatAbsolutePath` - returns an absolute path to the Tomcat directory;\n* `shutdown` - shutdowns the Tomcat process;\n* `reboot` - shutdowns the existing Tomcat process and runs a new one;\n* `runShellScript` - runs a script in the Tomcat directory with the following arguments:\n    1. `Path` - path to a script relative to the Tomcat root directory;\n    2. `Arguments` - arguments that should be passed to the script.\n\n![tomcat jmx](img/jmx-tomcat-core.png)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fadmin-tools-addon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuba-platform%2Fadmin-tools-addon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fadmin-tools-addon/lists"}