Importing all governance artifacts from an instance with a ZIP file (IBM Knowledge Catalog)

You can import all the governance artifacts from a IBM Knowledge Catalog instance with a ZIP file that you created by exporting the artifacts.

This task describes how to import governance artifacts from a ZIP file using the API. You can also use the command cpd-cli for the same purpose as described in Migrating governance artifacts in the IBM Software Hub documentation.

You can use this method to move governance artifacts from one IBM Knowledge Catalog instance to another or to edit governance artifact properties with an external tool. All the imported artifacts are published immediately without workflow.

Prerequisites

Before you import governance artifacts with a ZIP file, create the file with the correct format and ensure that you have the required permissions.

ZIP file

You must have a ZIP file of exported artifacts that you created with the GET /v3/governance_artifact_types/{artifact_type}/export API request. The maximum size of the ZIP file is 2 GB. See Exporting all governance artifacts to a ZIP file.

Permissions

You must have the Manage glossary user permission.

You do not need to be a collaborator in any of the categories that are created or affected by the import process.

Editing the contents of the ZIP file

The exported ZIP file contains a separate folder for each artifact type with a CSV file that contains that type of artifact.

You can modify contents of the exported ZIP file manually. Follow these guidelines:

  • Do not create additional folders, for example, a parent folder.
  • Do not change the folder names. The folders for each artifact type in the ZIP file must have the following names: category, classification, data_class, glossary_term, policy, rule, and reference_data.
  • Maintain the correct format of each CSV file. See CSV file format for importing governance artifacts.
  • Do not remove or rename the Artifact ID column in each CSV file. This column specifies the identifier of the artifact in addition to the name of the artifact.
  • Define a relationship between two governance artifacts for only one of the artifacts. There are two exceptions:
    1. The relationship is between a policy and a governance rule. In this case, define the relationship for both artifacts in both CSV files. In the CSV file with policies, add the relationship in the Rule column. In the CSV file with governance rules, add the relationship in the Parent Policies column.
    2. You are using all merge option. In this case, you must ensure that all CSV content is consistent regarding relationships between artifacts. For example, if the ZIP import file contains both a term and a data class connected together with a relationship, then this relationship must be present in both data classes CSV and terms CSV. Otherwise the relationship import behavior is unpredictable, the relationship may be imported or not.

Preparing to import a ZIP file

Before you import a ZIP file, you must complete the following tasks:

  • Perform the appropriate action to avoid missing or duplicate predefined artifacts
  • Create any custom properties and relationships

Avoid duplicate or missing predefined artifacts

Artifacts in exported ZIP files are identified with artifact identifiers in the Artifact ID column, instead of by the artifact name and category path. However, artifact identifiers for predefined data classes and classifications differ between each IBM Knowledge Catalog instance. Therefore, imported predefined data classes and classifications are not recognized as being the same as existing predefined data classes and classifications. As a result, the import process creates duplicate artifacts. When a parent category is not imported due to conflicting ID, the artifacts under this category might be missing.

You can avoid duplicate prefined artifacts with one of the following methods:

  • Delete the existing predefined artifacts from the target IBM Knowledge Catalog instance before you import artifacts. See Deleting published artifacts of the same type.

  • For predefined data classes and classifications:

    1. Exclude the [uncategorized] category when you create the ZIP file by exporting artifacts.
    2. Edit the CSV files for data classes and classifications and replace the artifact identifiers for predefined data classes and classifications in the Parent Classification and Parent Data Class columns with the equivalent predefined artifact names and category paths.
    3. Edit the CSV files for other artifacts and replace the artifact identifiers for predefined data classes and classifications with the equivalent predefined artifact names and category paths in the Classifications and Data Classes columns, for any artifacts that have relationships to the predefined artifacts.

    When you import the artifacts, relationships to the exisiting target predefined artifacts are created.

Create custom properties and relationships

You must create each custom property or relationship definition manually before you import the ZIP file. Otherwise, custom property and relationship values are not imported.

For more information, see Custom properties and relationships.

Merge options

The following merge options are available when running the ZIP import:

all
Replace all values. Imported values replace existing values in a catalog.
specified
Replace with defined values. Imported values that are not empty replace existing values in a catalog.
empty
Replace empty values. Imported values replace only empty values in a catalog.

specified is used as default.

When importing files that contain reference data values, you must always use merge_option=all.

For more information on the merge options, see Methods for merging imported and existing artifacts

Importing a ZIP file

To import a ZIP file of governance artifacts:

  1. If necessary, delete existing predefined artifacts or edit relationships to predefined artifacts. See Preparing to import a ZIP file.
  2. Submit the POST /v3/governance_artifact_types/import request. Include the merge option and the path to the ZIP file. See API documentation: Import values from specified ZIP file. All artifacts are published immediately without workflow.
  3. When the import process is complete, add other collaborators to the new categories. See Managing category collaborators.

You must wait until the import process completes, or you clean up the stalled process, before you can start a new import process.

Monitoring the import process

After you submit the request to import the ZIP file, a process ID is provided in the response (process_id parameter). You can use the process ID to check the status of the import. Submit a GET /v3/governance_artifact_types/import/status/{process_id} request to query the import status. See API documentation: Import status.

You can see a separate status for the import process and the synchronization process. The status for the synchronization process is displayed when the synchronization phase starts. The imported data might not be displayed on the target environment until the synchronization finishes, even when the status of the import is "Succeeded".

When you run a large import and the synchronization process is interrupted, it is restarted automatically from the moment it failed after approximately 15 minutes. The synchronization might be interrupted because the pod where it runs is shut down. The process is restarted on another pod. If the process fails for 24 hours, it is no longer restarted and is marked as failed.

Cleaning up a stalled import process

Tech preview This is a technology preview and is not yet supported for use in production environments.

If the import stalls, you can clean up the import process and then import the ZIP file again. You can't start a new import process until the previous one completes or you clean up the stalled process. All import processes are cleaned automatically after 24 hours of inactivity.

You can check the status of the import process by submitting a GET /v3/governance_artifact_types/import/status/{process_id} request. The process is stalled if the status is IN_PROGRESS, but artifacts are not being imported.

To clean up a stalled or failed import process, submit the POST /v3/governance_artifact_types/import/cleanup/{process_id} request.

See API documentation: Clean up ZIP import process.

Learn more

Parent topic: Import methods for governance artifacts