Developing a plug-in by using the plug-in toolkit

Edit online

Use the IBM® Guardium® Cryptography Manager plug-in toolkit to create, validate, test, and package a plug-in that integrates external systems with Guardium Cryptography Manager.

Before you begin

Ensure that the following requirements are met:
  • You have downloaded the plug-in toolkit binary from the IBM Passport Advantage® portal for your operating system.
  • You have access to a terminal or command prompt.
  • You have credentials and connectivity details for the source system that the plug-in integrates with (required for functional testing).
  • You have permissions to upload plug-ins to GCM.
  • Add the toolkit binary to your system path and verify the installation: 
    

 #Add the toolkit binary export PATH=<path-to-toolkit-binary>:$PATH
#verify the installation plugin-toolkit-<platform> --help
Replace <platform> with your OS-specific binary name, such as:
  • plugin-toolkit-linux-amd64
  • plugin-toolkit-darwin-arm64
  • plugin-toolkit-windows-amd64.exe

About this task

The plug-in toolkit is a command-line utility that helps you develop Guardium Cryptography Manager plug-ins by providing standardized templates, validation checks, testing utilities, and packaging capabilities. This task guides you through the end-to-end workflow to build a deployable plug-in.

Procedure

  1. Initialize a new plug-in template by using the toolkit. 
    plugin-toolkit init -i ./my-plugins
    This command creates a standardized plug-in directory structure.
  2. Customize the plug-in as follows:
    Navigate to the generated plug-in directory and update the plugin content:.
    1. Edit manifest.json to define plug-in metadata such as name and version.
    2. Update configuration files with connection parameters.
    3. Modify playbooks in the src/ directory to implement discovery and integration logic.
    4. Define data mappings in the transformation/ directory.
  3. Run lint validation to ensure that the plug-in follows required conventions and schemas. 
    plugin-toolkit plugin lint ./plugin-template-1.0.0

    The validation checks the manifest schema, folder structure, file naming conventions, playbook syntax, and transformation definitions.

  4. Verify transformation logic by using sample input data. 
    plugin-toolkit test transformations \ 
-i <path-to-sample-input> \ 
-t plugin-template-1.0.0/transformation/discovery/transform_discover.json \  
-o ./dest-reports
    Review the following generated reports:
    • data_report.html to verify transformed data.

    • data_quality_report.csv to identify data quality issues

  5. Complete the following sub-steps to test the plug-in with real data.
    Note:

    Before starting with the functional test feature of the development toolkit, ensure you have the following installed on your machine:

    - **ansible-core=2.20.3**

    - **Molecule 25.12.0**

    - **Python 3.14**

    1. To initialize the functional test environment, run the following command. 
      plugin-toolkit test functional init <action-name> -i ./plugin-template-1.0.0
      Example action names:
      • integration.test_connection
      • discovery.discover
    2. Update the generated <action-name>.env.json with required connection details.
    3. Run the functional test as follows. 
      plugin-toolkit test functional <action-name> -i ./plugin-template-1.0.0
      This test connects to the source system, retrieves data, applies transformations, and validates the output.

  6. Build the plug-in package after all tests complete successfully, create a deployable plugin package.
    Note: Before running the build command, ensure to remove credentials or connection details added in playbooks or configuration files such as <action-name>.env.json.
    plugin-toolkit build -i ./plugin-template-1.0.0 -o ./dist

    The toolkit generates a Guardium Cryptography Manager-compatible ZIP file in the output directory.

Results

A deployable plug-in package is created in the specified output directory. The file is named using the plug-in name and version, for example: <plugin-name>-<version>.zip.

The ZIP file is generated only after all checks pass. Review and resolve any warnings or errors displayed in the console.

What to do next

Install the create plug-in on Guardium Cryptography Manager. For more information, see Installing plug-ins.