Importing all governance artifacts from an instance with a ZIP file

Last updated: Dec 13, 2024

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

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
Editing the contents of the ZIP file
Preparing to import a ZIP file
Merge options
Importing a ZIP file
Monitoring the import process
Cleaning up a stalled import process

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 duplicate predefined artifacts
Create any custom properties and relationships

Avoid duplicate 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 business terms, data classes and classifications differ between each IBM Knowledge Catalog instance. Therefore, imported predefined business terms, data classes and classifications are not recognized as being the same as existing predefined business terms, data classes and classifications. As a result, the import process creates duplicate artifacts.

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.
For predefined business terms:
1. Exclude the Knowledge Accelerator Sample Personal Data category when you create the ZIP file by exporting artifacts.
2. Edit the CSV files for business termsa and other artifacts and replace the artifact identifiers for predefined business terms with the equivalent predefined artifact names and category paths in the Related terms column and in any other columns defining business term relationships.
When you import the artifacts, relationships to the exisiting target predefined artifacts are created.

The predefined reference data sets in the Locations category have the same artifact ID values across all IBM Knowledge Catalog instances.

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:

If necessary, delete existing predefined artifacts or edit relationships to predefined artifacts. See Preparing to import a ZIP file.
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.
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.

Cleaning up a stalled import process

Experimental This is an experimental release 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