credmkt-cli

Support for market place page where in any kind of feature like report/app/noderedflow can be published. User can visit market place download the Package and install.

• credmkt-cli
  • Installation
  • Commands
    • credmktcli setup
    • credmktcli package:init
    • credmktcli package:add
    • credmktcli package:build
    • credmktcli package:publish
    • credmktcli package:apply
    • credmktcli package:update
    • credmktcli package:revert
  • How to add reports to package
  • How to add datasets to package
  • How to add custom fields to package
  • How to add Node-RED flows to package
  • How to add App Builder apps to package
  • How to add CAPPS apps to package
  • How to update an existing package
  • How to add database migrations to package

Installation

Prerequisites

• Node.js >= v18 (Download Link) installed.

Online Mode

• Run the following command to install.

  $ npm install -g @credenceanalytics/credmktcli@latest

• Test installation by typing following command:

  $ credmktcli --help

Offline Mode

• Extract credmkt-cli.zip.
  • Place the extracted credmkt-cli folder to somewhere safe on your disk.
• Run npm link --force inside credmkt-cli/ folder.
• Test installation by typing following command:

  $ credmktcli --help

Commands

credmktcli setup

Run this command in the credence/ folder.

This command creates a new directory named custom-packages/ in the credence/ folder and initializes configuration including:

• Database connection details
• Application user ID
• Reporting WAR path
• Node-RED API URL (default: http://127.0.0.1:8001)
• App Builder API URL (default: http://127.0.0.1:3004)
• API key (automatically retrieved from database)

Usage

$ credmktcli setup

Folder structure before running the command [dev environment]

credence/
  ├── visualizer-dashpages/
  ├── pages/
  ├── apps/
  └── microservices/

Folder structure after running the command [dev environment]

credence/
  ├── custom-packages/
  ├── visualizer-dashpages/
  ├── apps/
  ├── pages/
  └── microservices/

credmktcli package:init

Run this command in package repository must be a git repo.

This command helps in setting up a new package by creating a cred_package.json file in the specified directory. It prompts the user to enter various details about the package such as name, version, description, author and keywords and writes these details into a newly created cred_package.json file.

Usage

$ credmktcli package:init

Folder structure after running the command

<Package repo>/
  └── cred_package.json

credmktcli package:add

This command is used to add content to an existing package in a Git repository. It supports:

• Visualizer dashboards (file-based)
• Pagebuilder pages (file-based)
• Node-RED flows (API-based, automatically exported)
• App Builder apps (API-based, automatically exported)
• CAPPS apps (file-based, copied from CREDENCE_PATH/apps/)
• Reports (database-based, automatically exported)
• Datasets (file-based, automatically exported)
• Custom fields (database-based, automatically exported)

This command checks if the current directory is a Git repository and contains a cred_package.json file. It then prompts the user to choose what type of content to add.

For Node-RED flows and App Builder apps, the command fetches available items from their respective APIs, lets you select which ones to add, and automatically exports the content.

For Reports and Custom Fields, the command connects to the database, fetches available items, lets you select which ones to add, and automatically exports the content.

For Datasets, the command lists available datasets from the REPORTING WAR path and copies the selected dataset to the package.

Usage

$ credmktcli package:add

Folder structure before running the command

<Package repo>/
  └── cred_package.json

Folder structure after running the command

└── <Package repo>/
    ├── visualizer-dashboard/
    │   └── <Added dashboard>/
    │       └── files
    ├── pages/
    │   └── <Added pages>/
    │       └── files
    ├── jobcenternodered_flows/
    │   └── <Flow_Name>.json
    ├── appbuilder_apps/
    │   └── <app_id>.zip
    ├── capps_apps/
    │   └── <app_name>/
    │       └── <app files>
    ├── reports/
    │   ├── reports.json
    │   └── <report_name>.rptdesign
    ├── datasets/
    │   └── <dataset_name>.js
    ├── migration/
    │   └── <version>/
    │       └── dbscript.sql
    └── cred_package.json

credmktcli package:build

This command updates existing Node-RED flows in a package by fetching the latest versions from the Node-RED API. It's useful when flows have been modified in Node-RED and you want to update your package with the latest changes.

Current support: Node-RED flows only (App Builder apps will be supported in future versions)

Usage

$ credmktcli package:build

When to use this command

Use package:build when:

• You've already added Node-RED flows to your package using package:add
• The flows have been modified in Node-RED
• You want to update the package with the latest flow definitions

Note: This command does NOT commit changes or bump version. After running package:build, use package:publish to create a new version.

How it works

1. Validation: Checks if current directory is a git repository with cred_package.json
2. Discovery: Reads all Node-RED flows listed in packageFolders.jobcenternodered_flows
3. API Fetch: Connects to Node-RED API to get current flow definitions
4. Matching: Matches package flows against API flows by ID
5. Update: Exports latest flow definitions and overwrites JSON files in jobcenternodered_flows/ folder
6. Summary: Displays which flows were updated and which were not found

Example output

$ credmktcli package:build

Building package content from APIs...

Found 3 Node-RED flow(s) in package
Fetching available flows from Node-RED API...
Updating 2 Node-RED flow(s)...

Build Summary:
──────────────────────────────────────────────────
✓ Updated 2 Node-RED flow(s) successfully
⚠ Warning: 1 flow(s) no longer exist in Node-RED:
  - "Old Flow" (ID: abc123)
──────────────────────────────────────────────────

Package content updated. Run 'credmktcli package:publish' to create new version.

Folder structure

Before running the command:

<Package repo>/
  ├── jobcenternodered_flows/
  │   ├── Flow_1.json          (outdated)
  │   ├── Flow_2.json          (outdated)
  │   └── Old_Flow.json        (will show warning - deleted from Node-RED)
  └── cred_package.json

After running the command:

<Package repo>/
  ├── jobcenternodered_flows/
  │   ├── Flow_1.json          (✓ updated)
  │   ├── Flow_2.json          (✓ updated)
  │   └── Old_Flow.json        (unchanged - not in Node-RED)
  └── cred_package.json

credmktcli package:publish

This command is used to update the version of a package, commit and push changes to the Git repository, and create a ZIP archive containing a git.diff file.

The ZIP archive contains only a git.diff file (the diff between the current branch and the release branch), rather than the full package contents. This diff-based approach enables incremental updates when applying packages.

Prerequisite: The package repository must have a release branch that serves as the baseline for generating diffs.

Usage

$ credmktcli package:publish

How it works

1. Version bump: Prompts for version bump type (patch/minor/major) and updates cred_package.json
2. Git commit & push: Commits all changes and pushes to the remote repository
3. Diff generation: Generates a diff between the current branch and origin/release
4. ZIP creation: Creates <package-name>-<version>.zip containing only the git.diff file

Output

The command creates a ZIP file named <package-name>-<version>.zip containing:

<package-name>-<version>.zip
  └── git.diff

credmktcli package:apply

This command installs a package from a ZIP file using a git-based diff approach. Instead of extracting package contents directly, it applies a git.diff file to a target git repository, enabling incremental updates and version tracking via git history.

Usage

$ credmktcli package:apply

How it works

1. Extraction: Extracts the package ZIP to a temporary directory
2. Diff discovery: Locates the git.diff file inside the extracted package
3. Target setup: Sets up custom-packages/<package-name> as a git repository (initializes if new, validates if existing)
4. Clean check: Validates the target repository has no uncommitted changes
5. Diff application: Applies the git.diff to the target repository using git apply
6. Git commit: Commits all changes with the package version as the commit message
7. Content installation: Installs package content (reports, pages, dashboards, Node-RED flows, App Builder apps, database migrations)
8. Version tracking: Records the installed version in the database

Folder structure before running the command [production environment]

└── credence/
    ├── custom-packages/
    ├── visualizer-dashpages/
    ├── apps/
    ├── microservices/
    └── pages/

Folder structure after running the command [production environment]

credence/
  ├── custom-packages/
  │   └── <package-name>/
  │       ├── .git/
  │       ├── visualizer-dashboard/
  │       │   └── <different dashboards>
  │       ├── pages/
  │       │   └── <different pages>
  │       ├── jobcenternodered_flows/
  │       │   └── <flow files>
  │       ├── appbuilder_apps/
  │       │   └── <app files>
  │       ├── capps_apps/
  │       │   └── <app_name>/
  │       │       └── <app files>
  │       ├── migration/
  │       │   └── <version>/
  │       │       └── dbscript.sql
  │       └── cred_package.json
  ├── visualizer-dashpages/
  │   └── dash/
  │       └── <different dashboards>
  ├── pages/
  │   └── <different pages>
  ├── apps/
  │   └── <installed CAPPS apps>
  └── microservices/

Note: Node-RED flows and App Builder apps are installed via their respective APIs, not copied to file system directories. The target directory is a git repository that tracks all applied versions via commit history.

credmktcli package:update

This command applies multiple packages in version order from the updates/packages/ folder. It discovers all package ZIP files in the updates/packages/ subfolder, sorts them by semantic version, and applies them sequentially with comprehensive error handling and recovery.

Run this command in the credence/ folder.

Usage

$ credmktcli package:update

Required folder structure

credence/
  └── updates/
      └── packages/
          ├── mypackage-1.0.0.zip
          ├── mypackage-1.1.0.zip
          ├── anotherpackage-2.0.0.zip
          └── anotherpackage-2.1.0.zip

Package naming convention

All package ZIP files must follow the naming pattern: <package-name>-<version>.zip

Examples of valid names:

• dashboard-reports-1.0.0.zip
• user-analytics-2.1.3.zip
• custom-widgets-1.5.0.zip

How it works

1. Discovery: Scans updates/packages/ folder for ZIP files
2. Validation: Validates package names against naming convention
3. Sorting: Groups packages by name and sorts by semantic version (oldest to newest)
4. Confirmation: Shows the application order and asks for user confirmation
5. Sequential Application: Applies packages one by one with failure recovery
6. Reporting: Provides detailed summary with success/failure counts

Error handling

• Failed packages create .failed files with error details
• Processing continues even if individual packages fail
• Final summary shows all results

Folder structure before running the command [production environment]

└── credence/
    ├── custom-packages/
    ├── updates/
    │   └── packages/
    │       ├── package-a-1.0.0.zip
    │       ├── package-a-1.1.0.zip
    │       └── package-b-2.0.0.zip
    ├── visualizer-dashpages/
    ├── apps/
    ├── microservices/
    └── pages/

Folder structure after running the command [production environment]

credence/
  ├── custom-packages/
  │   ├── package-a/
  │   │   ├── .git/
  │   │   ├── visualizer-dashboard/
  │   │   │   └── <dashboards>
  │   │   ├── pages/
  │   │   │   └── <pages>
  │   │   ├── jobcenternodered_flows/
  │   │   │   └── <flows>
  │   │   ├── appbuilder_apps/
  │   │   │   └── <apps>
  │   │   ├── capps_apps/
  │   │   │   └── <app_name>/
  │   │   │       └── <app files>
  │   │   └── cred_package.json
  │   └── package-b/
  │       ├── .git/
  │       ├── reports/
  │       │   └── <reports>
  │       └── cred_package.json
  ├── updates/
  │   └── packages/
  │       ├── package-a-1.0.0.zip
  │       ├── package-a-1.1.0.zip
  │       ├── package-b-2.0.0.zip
  │       └── package-a-1.0.0.failed (if failed)
  ├── visualizer-dashpages/
  │   └── dash/
  │       └── <applied dashboards>
  ├── pages/
  │   └── <applied pages>
  ├── apps/
  │   └── <installed CAPPS apps>
  └── microservices/

credmktcli package:revert

This command reverts an installed package to its previous version. It uses git history to reset the package directory and updates the database version tracking accordingly.

Usage

$ credmktcli package:revert

How it works

1. Database connection: Connects to the database and retrieves all installed packages with their version history
2. Package selection: Displays packages that have a previous version available and lets you select one to revert
3. Confirmation: Shows the version change (current → previous) and asks for confirmation
4. Git reset: Runs git reset --hard HEAD~1 on the package's git repository to restore the previous state
5. Database update: Deletes the current version record from marketplace_pkg_versions
6. Re-apply content: Re-applies the reverted package content (reports, pages, dashboards, Node-RED flows, App Builder apps)
7. Logging: Records the revert action in marketplace_log

Example

$ credmktcli package:revert

? Enter database password for user@host/sid ********
? Select a package to revert
  my-dashboard-package  1.2.0 → 1.1.0
  report-bundle         2.0.0 → 1.5.0

? Are you sure you want to revert my-dashboard-package from 1.2.0 to 1.1.0? Yes

Resetting git repository to previous version...
Git reset successful
Reports applied successfully
Pages applied successfully
Package my-dashboard-package reverted from 1.2.0 to 1.1.0 successfully

Note: Only packages with at least two installed versions (current and previous) can be reverted. Packages with only one version will not appear in the selection list.

How to add reports to package

Prerequisites

• credmktcli setup command completed (one time only)
• Database connection configured in setup
• REPORTING_WAR_PATH configured in setup

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "Report" from the menu

4. Enter your database password when prompted

5. The command will fetch all available reports from the database and display them

6. Select the report you want to add from the list

7. The report content will be automatically exported to the reports/ folder:

   • .rptdesign file (report design)
   • reports.json file (report metadata merged with any existing reports)

8. The cred_package.json file will be updated with report names:

   {
     "reports": ["Report Name 1", "Report Name 2"]
   }

9. Run credmktcli package:publish command to push changes and create the ZIP file

Package git repository structure:

.
└── <Package git repository>/
    ├── .git/
    ├── reports/
    │   ├── reports.json
    │   ├── Report_1.rptdesign
    │   └── Report_2.rptdesign
    └── cred_package.json

Adding multiple reports

You can add multiple reports by running credmktcli package:add multiple times and selecting "Report" each time. Each new report will be merged into the existing reports.json file.

How to add datasets to package

Prerequisites

• credmktcli setup command completed (one time only)
• REPORTING_WAR_PATH configured in setup

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "Dataset" from the menu

4. The command will list all available datasets from REPORTING_WAR_PATH/plugins/datasets/

5. Select the dataset you want to add from the list

6. The dataset will be automatically copied to the datasets/ folder

7. The cred_package.json file will be updated with dataset names:

   {
     "datasets": ["dataset_name_1", "dataset_name_2"]
   }

8. Run credmktcli package:publish command to push changes and create the ZIP file

Package git repository structure:

.
└── <Package git repository>/
    ├── .git/
    ├── datasets/
    │   ├── custom_dataset_1.xml
    │   └── custom_dataset_2.xml
    └── cred_package.json

Installation behavior

When installing a package with datasets using package:apply:

• Datasets are copied to REPORTING_WAR_PATH/plugins/datasets/
• Existing datasets with the same name will be overwritten

How to add custom fields to package

Prerequisites

• credmktcli setup command completed (one time only)
• Database connection configured in setup
• Custom fields must exist in IWZ_CUSTOM_METADATA or IWZ_CUST_METADATA table
• Custom tables (CUSTOM_<table>) must already exist in the target database

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "Custom Field" from the menu

4. Enter your database password when prompted

5. The command will list all tables that have custom fields

6. Select a table from the list

7. Multi-select the custom fields you want to add (using checkbox)

8. When prompted, choose whether to add custom fields from another table

9. The cred_package.json file will be updated with custom field definitions:

   {
     "custom_fields": {
       "TABLE_NAME": [
         { "COL_NAME": "field_1", "CONTROLTYPE": "Text", ... },
         { "COL_NAME": "field_2", "CONTROLTYPE": "Date", ... }
       ]
     }
   }

10. Run credmktcli package:publish command to push changes and create the ZIP file

Installation behavior

When installing a package with custom fields using package:apply:

• Columns are added to existing custom tables (CUSTOM_<table>) for each field
• Columns are added to existing audit tables (LOG_CUSTOM_<table>)
• For IWZ_CUSTOM_METADATA: columns are also added to RPT_CUSTOM_<table> and HIS_CUSTOM_<table> if they exist
• Metadata is inserted into IWZ_CUSTOM_METADATA or IWZ_CUST_METADATA
• Fields that already exist are skipped

Note: Custom tables must already exist in the target database. This command only adds new columns to existing tables.

How to add Node-RED flows to package

Prerequisites

• credmktcli setup command completed (one time only)
• Node-RED API URL configured in setup
• Node-RED instance running and accessible

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "Node Red Flow" from the menu

4. The command will fetch all available flows from Node-RED and display them

5. Select the flow(s) you want to add from the list

6. The flow content will be automatically exported to the jobcenternodered_flows/ folder

7. The cred_package.json file will be updated with flow metadata:

   {
     "packageFolders": {
       "jobcenternodered_flows": [
         {"id": "flow-id", "name": "Flow Name"}
       ]
     }
   }

8. Run credmktcli package:publish command to push changes and create the ZIP file

Package git repository structure:

.
└── <Package git repository>/
    ├── .git/
    ├── jobcenternodered_flows/
    │   ├── Flow_1.json
    │   └── Flow_2.json
    └── cred_package.json

Installation behavior

When installing a package with Node-RED flows using package:apply:

• The installer fetches all existing flows from Node-RED
• Matches flows by name (not ID)
• If no match found: Creates a new flow
• If 1 match found: Prompts for confirmation before updating
• If multiple matches found: Exits with error (requires unique flow names)

How to add App Builder apps to package

Prerequisites

• credmktcli setup command completed (one time only)
• App Builder API URL configured in setup
• App Builder instance running and accessible

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "Appbuilder App" from the menu

4. The command will fetch all available apps from App Builder and display them

5. Select the app(s) you want to add from the list

6. The app content will be automatically exported as ZIP files to the appbuilder_apps/ folder

7. The cred_package.json file will be updated with app metadata:

   {
     "packageFolders": {
       "appbuilder_apps": [
         {"id": "app-id", "name": "App Name"}
       ]
     }
   }

8. Run credmktcli package:publish command to push changes and create the ZIP file

Package git repository structure:

.
└── <Package git repository>/
    ├── .git/
    ├── appbuilder_apps/
    │   ├── app-id-1.zip
    │   └── app-id-2.zip
    └── cred_package.json

How to add CAPPS apps to package

Prerequisites

• credmktcli setup command completed (one time only)
• CREDENCE_PATH configured in setup
• CAPPS apps exist in CREDENCE_PATH/apps/ directory

Steps

1. Run credmktcli package:init command in your package git repository

2. Run credmktcli package:add command

3. Select "CAPPS App" from the menu

4. The command will list all available CAPPS apps from CREDENCE_PATH/apps/ directory

5. Select the app(s) you want to add from the list

6. The app folder will be automatically copied to the capps_apps/ folder in your package

7. The cred_package.json file will be updated with app names:

   {
     "packageFolders": {
       "capps_apps": ["app-name-1", "app-name-2"]
     }
   }

8. Run credmktcli package:publish command to push changes and create the ZIP file

Package git repository structure:

.
└── <Package git repository>/
    ├── .git/
    ├── capps_apps/
    │   ├── my-capps-app-1/
    │   │   └── <app files>
    │   └── my-capps-app-2/
    │       └── <app files>
    └── cred_package.json

Installation behavior

When installing a package with CAPPS apps using package:apply:

• If the app folder exists in CREDENCE_PATH/apps/, it will be deleted first
• The app folder from the package is then copied to CREDENCE_PATH/apps/
• This ensures a clean installation without leftover files from previous versions

How to update an existing package

Once you have published a package (e.g., mypackage-1.0.0.zip), you may need to update it with new content or modifications.

Steps to update and publish a new version:

1. Navigate to your package git repository

   cd <Package git repository>

2. Make your changes:

   • To add new content: Run credmktcli package:add and select the type of content to add
     • Visualizer dashboards
     • Pagebuilder pages
     • Node-RED flows (fetched from API)
     • App Builder apps (fetched from API)
     • CAPPS apps (copied from CREDENCE_PATH/apps/)
     • Reports (fetched from database)
     • Datasets (copied from REPORTING WAR)
     • Custom fields (fetched from database)
   • To update existing content:
     • For Node-RED flows: Run credmktcli package:build to automatically update all flows from Node-RED API
     • For App Builder apps: Run credmktcli package:add again and select the same item (you'll be prompted to overwrite)
     • For CAPPS apps: Run credmktcli package:add again and select the same app (it will be overwritten)
     • For reports: Run credmktcli package:add again and select the same report (you'll be prompted to overwrite)
     • For datasets: Run credmktcli package:add again and select the same dataset (you'll be prompted to overwrite)
     • For custom fields: Run credmktcli package:add again and select fields from the same table (existing fields will be merged)
     • For dashboards/pages: Manually update files in their respective folders

3. Publish the updated package:

   credmktcli package:publish

4. When prompted, choose version bump type:

   • patch (1.0.0 → 1.0.1) - for bug fixes
   • minor (1.0.0 → 1.1.0) - for new features
   • major (1.0.0 → 2.0.0) - for breaking changes

5. The command will:

   • Update version in cred_package.json
   • Commit changes to git
   • Push to remote repository
   • Generate git.diff (diff between current branch and release branch)
   • Create new ZIP file: <package-name>-<new-version>.zip containing the git.diff

Example workflow:

Example 1: Adding new content

# Start with existing package repository
cd my-dashboard-package

# Add a new Node-RED flow
credmktcli package:add
# Select "Node Red Flow" → choose flow → automatically exported

# Publish new version
credmktcli package:publish
# Choose "minor" → creates my-dashboard-package-1.1.0.zip

Example 2: Updating existing Node-RED flows

# Navigate to package repository
cd my-dashboard-package

# Update all Node-RED flows from API (fetches latest versions)
credmktcli package:build

# Publish updated version
credmktcli package:publish
# Choose "patch" → creates my-dashboard-package-1.1.1.zip

Example 3: Adding reports and custom fields

# Navigate to package repository
cd my-report-package

# Add a report from database
credmktcli package:add
# Select "Report" → enter DB password → choose report → automatically exported

# Add custom fields
credmktcli package:add
# Select "Custom Field" → enter DB password → choose table → select fields

# Publish new version
credmktcli package:publish
# Choose "minor" → creates my-report-package-1.2.0.zip

Version management:

The marketplace tracks installed package versions in the database. When applying updates:

• You can install a higher version (upgrade)
• If you try to install a lower version (downgrade), you'll receive a warning
• Use package:update command to apply multiple versions sequentially
• Use package:revert command to revert to the previous version

How to add database migrations to package

Packages can include database migration scripts that run automatically during package:apply. Migrations are tracked in the marketplace_pkg_migrations table and will only execute once per package version.

Migration folder structure

Place SQL scripts in the migration/<version>/ folder inside your package repository:

.
└── <Package git repository>/
    ├── .git/
    ├── migration/
    │   ├── 1.0.0/
    │   │   └── dbscript.sql
    │   ├── 1.1.0/
    │   │   └── dbscript.sql
    │   └── 2.0.0/
    │       └── dbscript.sql
    └── cred_package.json

SQL file format

SQL statements in dbscript.sql should be separated by ;/ (semicolon followed by forward slash):

CREATE TABLE my_custom_table (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100)
);/

INSERT INTO my_custom_table (id, name) VALUES (1, 'example');/

BEGIN
    -- PL/SQL block
    DBMS_OUTPUT.PUT_LINE('Migration complete');
END;/

How it works

1. During package:apply, the installer checks for a migration/<version>/dbscript.sql file matching the package version being applied
2. Before executing, it checks the marketplace_pkg_migrations table to see if this migration has already been run
3. If not yet executed, the SQL file is parsed and each statement is executed against the database
4. After successful execution, a record is inserted into marketplace_pkg_migrations to prevent re-execution
5. If the migration was already executed (e.g., re-applying the same version), it is skipped

Steps

1. Create a migration/<version>/ folder in your package repository
2. Add a dbscript.sql file with your SQL statements separated by ;/
3. Run credmktcli package:publish to include the migration in the package
4. When the package is applied using credmktcli package:apply, the migration will run automatically