0 / 0
Importing all governance artifacts from an instance with a ZIP file
Importing all governance artifacts from an instance with a ZIP file

Importing all governance artifacts from an instance with a ZIP file

You can import all the governance artifacts from a Watson 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 Watson 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. The exception is a relation 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.

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

You can avoid duplicate prefined data classes and classifications with one of the following methods:

  • Delete the existing predefined data classes and classifications from the target Watson Knowledge Catalog instance before you import artifacts. See Deleting published artifacts of the same type.
  • Exclude the [uncategorized] category when you create the ZIP file by exporting artifacts. Replace the artifact identifiers for predefined data classes and classifications in the Classifications, Data Classes, Parent Classification, and Parent Data Class columns with the equivalent predefined artifact names and category paths.
  • Edit the CSV files for data classes and classifications to remove the predefined artifacts. Also, replace the artifact identifiers for predefined data classes and classifications in the Classifications, Data Classes, Parent Classification, and Parent Data Class columns with the equivalent predefined artifact names and category paths in all affected CSV files.

For more information, see Solving governance artifacts import problems.

The predefined reference data sets in the Locations category have the same artifact ID values across all Watson 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:

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.

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