SmartDbManager – Node package for managing SmartDBs
SmartDbManager – Node package for managing SmartDBs
This document describes the functionality and configuration of the SmartDB Manager Node.js web tool. This tool provides a local web UI for viewing SmartDB copies, comparing them to Git branches and initializing SmartDBs for the currently checked-out Git branch.
Tool Description
SmartDB Manager is a lightweight Node.js web application distributed as an npm package.
SmartDB Manager:
Detects SmartDB branch copies from the configured SmartDB branches folder.
Detects the currently active SmartDB.
Detects the currently checked-out Git branch.
Displays whether the active SmartDB and the checked-out Git branch are in sync.
Shows matching Git branch information and last commit dates.
Allows deletion of SmartDB copies.
Allows initialization of a SmartDB for the currently checked-out Git branch.
Optionally allows export and import of repository data when the corresponding scripts are present.
Opens a local browser UI when started.
Requirements
Node.js version 18 or higher
Access to the private Consultingwerk npm registry https://npm.consultingwerkcloud.com
Progress OpenEdge installation
Windows operating system
Instructions
Using SmartDB Manager in a workspace where it is configured
There are a few steps that need to be taken individually by all developers working with a workspace in which SmartDB Manager is configured for it to be functional for them:
Go to https://npm.consultingwerkcloud.com and register an account with your company email address. Make sure the username you provide only has lower case letters.
Open a command prompt.
Configure the Consultingwerk npm package registry.
npm config set @consultingwerk:registry <https://npm.consultingwerkcloud.com>Log in to the Consultingwerk package via CLI. When prompted provide your configured username and password.
npm login --registry <https://npm.consultingwerkcloud.com>Open the workspace in which SmartDB Manager is configured.
Start SmartDB Manager using the configured wrapper script or by running the package manually from a shell where the required environment variables are already set.
When the tool starts successfully, it should open your default browser and display the SmartDB Manager UI.
Configuring SmartDB Manager for a Project
The goal of this step is to allow SmartDB Manager to be executed via a CLI command inside a project.
Go to https://npm.consultingwerkcloud.com and register an account with your company email address. Make sure the username you provide only has lower case letters.
Open a command prompt.
Configure the Consultingwerk npm package registry.
npm config set @consultingwerk:registry <https://npm.consultingwerkcloud.com>Log in to the Consultingwerk package via CLI. When prompted provide your configured username and password.
npm login --registry <https://npm.consultingwerkcloud.com>Add a configuration file in the target project root titled
smartdb-manager-config.json.
Config Fields
smartDbBranchesRoot (required)
Absolute or environment-variable-based path to the folder containing SmartDB branch folders.
port (optional)
Port used by the local web server. When omitted, the OS assigns a free port automatically and the assigned URL is printed to the console on startup.
scriptsPath (required unless all individual script paths are provided)
Absolute or environment-variable-based path to the folder containing SmartDB scripts. When set, the tool resolves scripts from this directory. Individual script path fields (see below) take precedence over scriptsPath when both are specified.
initBranchScriptPath (optional when scriptsPath is provided)
Absolute or environment-variable-based path to the script that initializes the SmartDB for the currently checked-out Git branch. Overrides the path derived from scriptsPath.
Note: The init-branch script is mandatory. The tool will refuse to start if the script file cannot be found at the resolved path.
exportRepositoryDataScriptPath (optional)
Absolute or environment-variable-based path to the script that exports repository data. Overrides the path derived from scriptsPath. When this script is not present on disk, the Export Repository Data action is hidden in the UI.
importRepositoryDataScriptPath (optional)
Absolute or environment-variable-based path to the script that imports repository data. Overrides the path derived from scriptsPath. When this script is not present on disk, the Import Repository Data action is hidden in the UI.
jira (optional)
Configuration block that enables Jira integration in the UI. When present, SmartDB Manager displays Jira ticket information for branches whose names contain Jira issue keys. All three sub-fields are required when the jira block is included:
url– Base URL of the Jira instance (e.g.<https://mycompany.atlassian.net).>email– Email address of the Jira account used for authentication.apiToken– Jira API token for the configured account. Generate one at https://id.atlassian.com/manage-profile/security/api-tokens.
Examples
Using scriptsPath with absolute paths
{
"smartDbBranchesRoot": "C:\\development\\databases\\branches",
"scriptsPath": "C:\\development\\scripts",
"port": 3000
}Using scriptsPath with environment variables
{
"smartDbBranchesRoot": "%SCL-DATABASES%/branches",
"scriptsPath": "%SCL-WORKSPACE%/Scripts"
}Using individual script paths
{
"smartDbBranchesRoot": "C:\\development\\databases\\branches",
"initBranchScriptPath": "C:\\development\\scripts\\init-branch.cmd",
"exportRepositoryDataScriptPath": "C:\\development\\scripts\\export-repository-data.cmd",
"importRepositoryDataScriptPath": "C:\\development\\scripts\\import-repository-data.cmd",
"port": 3000
}With Jira integration enabled
{
"smartDbBranchesRoot": "%SCL-DATABASES%/branches",
"scriptsPath": "%SCL-WORKSPACE%/Scripts",
"port": 3000,
"jira": {
"url": "<https://mycompany.atlassian.net>",
"email": "developer@mycompany.com",
"apiToken": "your-api-token-here"
}
}Running SmartDB Manager
SmartDB Manager should be run from a shell with the required environment variables set or through a wrapper script that sets the required environment first.
Run the tool from the Git repository whose checked-out branch should be inspected and whose SmartDB should be initialized.
npx --yes @consultingwerk/dev-smartdb-manager --config smartdb-manager-config.jsonIf the configuration relies on environment variables such as %SCL-DATABASES% or %SCL-WORKSPACE%, run the command in a shell where those variables are already set, or use a wrapper script that sets them first.
Example wrapper script
@echo off
set SCRIPTPATH=%~dp0
call %SCRIPTPATH%\openedge-version.cmd
cd "%~dp0..\ABL"
npx --yes @consultingwerk/dev-smartdb-manager --config smartdb-manager-config.jsonStart the wrapper script. SmartDB Manager should open a local browser window showing the SmartDB overview.