Migrating governance artifacts (IBM Knowledge Catalog)

Prerequisites

The cpd-cli command-line 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.

You can import and export the following governance artifacts:

• Business terms
• Categories
• Classifications
• Data classes
• Governance rules
• Policies
• Reference data sets

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: TOKEN
     value: The access token for the source system. See Obtaining an authorization token.
   • parameter: INCLUDE_CUSTOM_ATTRIBUTE_DEFINITIONS
     value: true or false. This mandatory parameter specifies whether to export custom attribute definitions.

   Make sure the key and indentation are as in the following example:

   glossary-api-aux:
     EXPORT_HOST: <hostname>
     ARTIFACT_TYPES: all
     CATEGORY_IDS: e39ada11-8338-3704-90e3-681a71e7c839
     TOKEN: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IklqSmVFYXlHUUxHU(...)
     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
   • TOKEN: - 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 the cpd-cli command-line interface 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 --log-level=debug --verbose --profile=default
   

   For each selected artifact type, a folder is created, and the artifacts and the relationships between them are exported to a CSV file in that folder. All resulting folders are then compressed into a single export package.

3. Wait for 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 values as described in step 2.

   Example:

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

   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 values as described in step 2.

   Example:

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

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

At any time, 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

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 the cpd-cli command-line interface is installed.

    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.
   • parameter: TOKEN
     value: The access token for the target system. See Obtaining an authorization token

   Make sure the key and indentation are as in the following example:

   glossary-api-aux:
     IMPORT_HOST: <hostname>
     WAIT_TIME: 1
     MERGE_OPTION: all
     TOKEN: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkMwZGtlSkZoRGlPQ(...)
   

   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
   • TOKEN: - 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 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 values as described in step 3.

   Example:

   cpd-cli export-import import status \
   -n wkc import1 --profile=default
   

   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.

At any time, 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.

  Example:

  cpd-cli export-import import list \
  -n wkc --profile=default
  

• 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.

  Example:

  cpd-cli export-import import log import1 --profile=default
  

Learn more

• Obtaining an authorization token

Parent topic: Administering IBM Knowledge Catalog