Migrating governance artifacts (IBM Knowledge Catalog)

Use cpd-cli commands to export and import governance artifacts within a Cloud Pak for Data cluster or between different clusters.

You can import and export the following governance artifacts:

  • Business terms
  • Categories
  • Classifications
  • Data classes
  • Governance rules
  • Policies
  • Reference data sets
Note: Custom properties definitions can be exported starting with version 4.7.0. For older versions, they must be migrated between installations before you export and import glossary artifacts.

To migrate governance artifacts, you must first export the artifacts and then import them back into the IBM Knowledge Catalog service. When you are done, you can also download the import and export log files.

Prerequisites

The cpd-cli interface and related modules must be installed.

The glossary-api-aux module must be registered. To verify that the module is available, run the following command:

cpd-cli export-import list ${CPD_PROFILE_NAME} aux-module


The module should be listed in the command output.

Required permission
To complete this task, you must be an administrator of the project (namespace) where you deployed the IBM Knowledge Catalog service. In addition, you must have the Manage glossary permission.

Exporting governance artifacts

To export governance artifacts from the IBM Knowledge Catalog service, complete the following tasks:

  1. Prepare a YAML file with the export specification. Create an export.yaml file with the following parameters:

    • parameter: EXPORT_HOST
      value: The hostname of the cluster from which you want to export data
    • parameter: ARTIFACT_TYPES
      value: A comma-separated list of artifact types that you want to export
      Possible values: category, classification, data_class, glossary_term, policy, reference_data, rule, all
    • parameter: CATEGORY_IDS
      value: A comma-separated list of parent category IDs or all_top_level
    • parameter: AUTH_STRING
      value: The access token for the source system. You can specify either a bearer or ZenApiKey token. For more information about generating a ZenApiKey token, see Generating an API authorization token. For more information about generating a bearer token, see Generating a bearer token.
    • parameter: INCLUDE_CUSTOM_ATTRIBUTE_DEFINITIONS
      value: true or false. This mandatory parameter specifies whether to export the custom properties definitions.

    Match the key and indentation with the following example:

    glossary-api-aux:
  EXPORT_HOST: <hostname>
  ARTIFACT_TYPES: all
  CATEGORY_IDS: e39ada11-8338-3704-90e3-681a71e7c839
  AUTH_STRING: Bearer <token> | ZenApiKey <token>
  INCLUDE_CUSTOM_ATTRIBUTE_DEFINITIONS: true

    If the export.yaml file is not provided, the following default values are used during export:

    • EXPORT_HOST: <hostname> - current host
    • ARTIFACT_TYPES: all
    • CATEGORY_IDS: all_top_level
    • AUTH_STRING: - The token is obtained by the cpd-cli for the user defined in profiles specified by the required --profile parameter.
    • INCLUDE_CUSTOM_ATTRIBUTE_DEFINITIONS: true

  2. Go to the directory where cpd-cli is installed and run the export command:

    cpd-cli export-import export create -c <component_name> \
-n <namespace> <export_name> -f <export_yaml_file> ${CPD_PROFILE_NAME}

    Replace the following values:

    • Replace <component_name> with the value glossary-api.
    • Replace <namespace> with the namespace where the IBM Knowledge Catalog service is deployed.
    • Replace <export_name> with the name of the export task.
    • Replace <export_yaml_file> with the path to the YAML file with the export specification.

    Example:

    cpd-cli export-import export create -c glossary-api \
-n wkc export1 -f /root/export.yaml --profile=${CPD_PROFILE_NAME}

    A folder is created for each selected artifact type, and all the artifacts and the relationships between them are exported to a CSV file so that you can share your artifacts. All resulting folders are compressed into a single export package, which you will use to import into your IBM Knowledge Catalog service.

  3. Wait for the export to complete. You can check the export status by using this command:

    cpd-cli export-import export status \
-n <namespace> <export_name> ${CPD_PROFILE_NAME}

    Replace the values as described in step 2.

    Hint: A status of SUCCEEDED indicates only the completion of the export job. If no data was exported despite the success message, check the log files. The export might have failed, for example, due to permission errors.

  4. Download the export result:

    cpd-cli export-import export download \
-n <namespace> <export_name> ${CPD_PROFILE_NAME}

    Replace the values as described in step 2.

    The name of the export package has this format: cpd-exports-<export_name>-<timestamp>-data.tar

Importing governance artifacts

To import governance artifacts to the IBM Knowledge Catalog service, complete the following tasks. If you want to import from an export created on a different cluster, log in to the remote cluster before you follow the steps:

  1. Go to the directory where cpd-cli is installed, and then run the following command to upload the export package:

     cpd-cli export-import export upload \
 -n <namespace> -f <file_data.tar> ${CPD_PROFILE_NAME}

    Replace <file_data.tar> with the name of your export package.

    Example:

    cpd-cli export-import export upload \
-n wkc -f cpd-exports-export1-20221108142513-data.tar --profile=default

  2. Prepare a YAML file with the import specification. Create an import.yaml file with the following parameters:

    • parameter: IMPORT_HOST
      value: The hostname of the cluster to which you want to import data
    • parameter: WAIT_TIME
      value: The interval in seconds in which the import status is checked
    • parameter: MERGE_OPTION
      value: The merge option used for import: all, specified, empty. specified is set as default starting with 4.7.1, earlier versions use all. For more information, see Methods for merging imported and existing artifacts in the IBM Cloud Pak for Data documentation.
    • parameter: AUTH_STRING
      value: The access token for the source system. You can specify either a bearer or ZenApiKey token. For more information about generating a ZenApiKey token, see Generating an API authorization token. For more information about generating a bearer token, see Generating a bearer token.

    Match the key and indentation with the following example:

    glossary-api-aux:
  IMPORT_HOST: <hostname>
  WAIT_TIME: 1
  MERGE_OPTION: all
  AUTH_STRING: Bearer <token> | ZenApiKey <token>

    If the import.yaml file is not provided, the following default values are used during import:

    • IMPORT_HOST: <hostname> - current host
    • WAIT_TIME: 30
    • MERGE_OPTION: specified
    • AUTH_STRING: - The token is obtained by the cpd-cli for the user defined in profiles specified by the required --profile parameter.

  3. Run the following command to import the data to the IBM Knowledge Catalog service:

    cpd-cli export-import import create <import_name> --from-export <export_name> \
-n <namespace> -f <import_yaml_file> ${CPD_PROFILE_NAME}

    Replace the following values:

    • Replace <import_name> with the name of the import task.
    • Replace <export_name> with the name of the export task.
    • Replace <namespace> with the namespace where the IBM Knowledge Catalog service is deployed.
    • Replace <import_yaml_file> with the path to the YAML file with the import specification.

    Example:

    cpd-cli export-import import create import1 --from-export=export1 \
-n wkc -f /root/import.yaml --log-level=debug --verbose --profile=default

  4. Wait for the import to complete. You can check the import status by using this command:

    cpd-cli export-import import status \
-n <namespace> <import_name> ${CPD_PROFILE_NAME}

    Replace the values as described in step 3.

    Hint: A status of SUCCEEDED indicates only the completion of the import job. If no data was imported despite the success message, check the log files. The import might have failed, for example, due to permission errors.

Imported governance artifacts are immediately published.

Downloading log files

You can download the log file for a specific export job by using the following command:

cpd-cli export-import export logs \
-n <namespace> <export_name> ${CPD_PROFILE_NAME}

Replace <export_name> with the name of the export task.

Example:

cpd-cli export-import export logs \
-n wkc export1 --profile=default

You can retrieve a list of imports or download the log file for a specific import job:

  • To list the imports, use the following command:

    cpd-cli export-import import list \
-n <namespace> ${CPD_PROFILE_NAME}

    Replace <namespace> with the namespace where the IBM Knowledge Catalog service is deployed.

  • To download a log file, use the following command:

    cpd-cli export-import import log <import_name> ${CPD_PROFILE_NAME}

    Replace <import_name> with the name of the import task.

Parent topic: Administering IBM Knowledge Catalog