0 / 0
Importing governance artifacts by type with CSV files

Importing governance artifacts by type with CSV files

You can import governance artifacts and categories with CSV files. You can include values for all properties of the governance artifacts, including relationships with other artifacts. You must have a separate CSV file for each type of governance artifact and for categories.

Prerequisites

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

CSV file

The CSV file must be correctly formatted. See CSV file format for importing governance artifacts.

You can create the CSV file in multiple ways, for example:

  • You can create the CSV file in another software application, such as a spreadsheet program.
  • You can export governance artifacts from the same instance of IBM Knowledge Catalog and then modify the exported file.
  • You can export governance artifacts from a different instance of IBM Knowledge Catalog.
  • You can export artifacts from IBM InfoSphere Information Governance Catalog, and then update the CSV export file to fit to the format required by the CSV import file.

Depending on how the file is encoded, you might need to use a different method to import the file. If the file is encoded with UTF-8, you can import the file through the UI or with an API request. If the file uses a different encoding, you must import it with an API request. See Importing CSV files with encoding other than UTF-8.

Required permissions

The permissions that you need depend on what you plan to import.

Permissions for importing top-level categories

To import top-level categories, you must have the Manage governance categories user permission.

Permissions for importing subcategories

To import subcategories, you must have one of these category collaborator roles in the parent category:

  • Admin
  • Owner
  • A custom role with the permission to create subcategories.

Permissions for importing governance artifacts

You must have permission to manage artifacts in every category that is listed in the CSV file, whether the category is listed in the Category field, the Secondary category field, or as part of a related artifact path. You can manage artifacts in a category if you have one of the following category collaborator roles:

  • Admin
  • Owner
  • Editor
  • A custom role with the permission to import an artifact type.

To import governance artifacts, you must have permission to manage artifacts in the primary category for every governance artifact that is listed in the file.

To import a relationship between two governance artifacts, you must have permission to manage artifacts in the primary categories of both governance artifacts.

To include a secondary category relationship for a governance artifact, you must have permission to manage artifacts in the secondary category.

Preparing to import governance artifacts

Before you can import governance artifacts, all categories and subcategories that are listed in the import file for those artifacts must exist. Otherwise, the artifacts with undefined categories are not imported. For more information, see Solving governance artifacts import problems.

Before you can import a CSV file with category definitions, the higher-level categories must exist, unless you define them in the file.

To create the required categories, you can use either of these methods:

Your import files can include relationships to other types of governance artifacts that you haven't imported yet. The artifacts that are defined in the file are created. However, the relationships to artifacts that don't exist are not created and you receive an error message. You can add the relationships by importing the files that received errors again after you import and publish the other types of governance artifacts.

Importing a CSV file through the UI

To import a CSV file through the UI:

  1. If necessary, create categories. See Preparing to import governance artifacts.
  2. From the navigation menu, open the Governance section and select Categories, Business terms, Classifications, Data classes, Reference data, Policies, or Rules.
  3. Click Add artifact-type > Import from file. If the button is disabled, make sure you have the required permissions.
  4. Add your CSV file.
  5. Set the merge method to resolve conflicts with any existing artifacts:
  6. Click Import. The import process runs asynchronously. If you leave the import window open, you can view the import results. Otherwise, you can close the import window to continue working. However, you are not notified when the import is complete and you can't access the import results.
  7. When the import process is complete, finish your artifacts and categories.

Importing CSV files with an API request

In the API request, you can specify to run parallel import processes or set the content type specification to a different encoding than UTF-8.

To import a CSV file by using the REST API:

  1. If necessary, create categories. See Preparing to import governance artifacts.
  2. Submit a POST /v3/governance_artifact_types/{artifact_type}/import request. Set the query parameters:
    1. Set the merge option parameter to resolve conflicts with existing artifacts:
    2. Optional. Set the async_mode parameter to true if you want to run multiple import process in parallel.
    3. If necessary, include encoding information in the API request. See Importing CSV files with encoding other than UTF-8. See API documentation: Import values from specified CSV file. After the request is submitted, a process ID is provided in the response (process_id parameter).
  3. Optional. You can use the process ID that is provided in the response to check the status of the import. Submit a GET /v3/governance_artifact_types/import/status/{process_id} request to return the status of the import process. See API documentation: Import status.
  4. When the import process is complete, finish your artifacts and categories.

Importing CSV files with encoding other than UTF-8

The content type in the http request must be multipart/form-data and the file type must be text/csv. By default, UTF-8 character encoding is used for CSV files. If the file does not use UTF-8, you must use an API call to import the file. See API documentation: Import values from specified CSV file.

You can enter the encoding type as part of the content type specification.

For example, if the file has windows-1250 encoding, your CURL command might look like this:

curl -X POST "https://{server}:{port}/v3/governance_artifact_types/{artifact_type}/import?merge_option={merge_option}" -H "accept: application/json" -H "Authorization: $AUTHORIZATION_HEADER" -H "content-type: multipart/form-data" -F "file=@\"./import_glossary.csv\";type=text/csv;charset=windows-1250" -k

Finishing your artifacts and categories

The governance artifacts in your CSV file are imported as drafts and subject to workflow. The draft artifacts must follow the workflow for that type of governance artifact. You can view the draft governance artifacts on the Draft tab for the respective artifact type, for example, business terms.

To finish your imported artifacts:

  1. After you import all types of artifacts, publish all the draft artifacts. Go to your Task inbox and start the publishing process. You must have permission to publish the artifacts. See Workflows for governance artifacts.
  2. If necessary, rerun the import for files that received relationship errors with the Replace all values merge method. Then, publish the updated artifacts.

Any categories that you import are published immediately because categories are not subject to workflow. The imported categories have the following collaborators:

  • You are a collaborator in all the categories that you import, with the Owner role.
  • If you import new top-level categories, you are the only collaborator.
  • If you import subcategories to existing categories, the new subcategories inherit all collaborators from their higher-level categories.

For more information, see Solving governance artifacts import problems.

To finish your imported categories, add other collaborators to the new categories. If you add the Public access group to an imported category, it has the Editor category role assigned by default, instead of the Viewer role, which is assigned to this group when you manually create categories.

See Managing category collaborators.

Learn more

Parent topic: Import methods for governance artifacts

Generative AI search and answer
These answers are generated by a large language model in watsonx.ai based on content from the product documentation. Learn more