CSV file format for importing governance artifacts

Limitations

The maximum recommended size of the CSV import file is 50 MB.

Some IBM Knowledge Catalog plans have limits on the number of governance artifacts of a specific type you can create. The first imported draft is not counted separately but any further drafts that you import are counted. For example, if the published term A has one update draft, the published term and the draft are counted as one term. However, if the published term A has two draft updates, the published term and the drafts are counted as two terms. You can avoid double counting by publishing your imported artifacts before you reimport them.

Header row

The header row of the CSV file represents which properties are imported for the artifacts.

Follow these guidelines for the header row:

• The header row must be the first row in the file and must not be repeated.
• Separate column names with a comma. If you create the file in a spreadsheet editor, the commas are added automatically when you save the file in CSV format.
• The header row must include the mandatory columns for the artifact type.
• You can omit any optional columns.
• Use the exact column names in the header row, except for custom attribute and custom relationship columns. Some columns have alternative names. Column names are case-sensitive.
• Make sure the column names do not include extra white space characters. White space characters might be added by a spreadsheet or text editor, but not be visible. If you receive an import error that the column names are incorrect, even though your columns are spelled and capitalized correctly, check for white spaces. For more information, see Solving governance artifacts import problems.

Column delimiters

To delimit values for different columns, use a comma. If you create the file in a spreadsheet editor, the commas are added automatically when you save the file in CSV format.

To omit a value for a column, use a comma directly after the previous comma and without any other characters. For example, two consecutive commas indicate that the second column is empty.

To include a comma in a value, surround the value in double quotation marks. For example, to import a value of test,, use the following format:

"test,"

Category paths

You must specify the full category path for categories and relationships to artifacts. If you do not specify the category, the default category is [uncategorized].

To delimit the category path, use two greater-than (>>) symbols between each level of the category hierarchy and between the category path and the artifact name.

myCategory1 >> myCategory2 >> myCategory3

myCategory1 >> myCategory2 >> myCategory3 >> artifactName

>> artifactName
artifactName

Artifact property values

The values for the governance artifact properties that you import are case-sensitive. For example, the tags number and NUMBER are treated as two distinct labels, not one.

Name,Artifact Type,Category,Tags,Related Terms
businessterm1,glossary_term,myCategory1,tag1,myCategory1 >> rel_term1
,,,tag2,myCategory1 >> rel-term2
businessterm2,glossary_term,myCategory1,tag3,myCategory2 >> rel-term3
,,,tag4,myCategory2 >> rel-term4

GIM00015E: Artifact Average balance in column Related Terms is not found in the specified hierarchy.

Character encoding

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 your CSV file does not use UTF-8, you must import the file with an API call and include the encoding type as part of the content type specification. See Importing CSV files with encoding other than UTF-8.

Name (Mandatory)

Alternative column name

name

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The name of the artifact.

The name of a governance artifact is associated with its primary category, which you must include in the Category field. This is why the list of business terms, for example, might show business terms with identical names, but with different primary categories.

Format

The name of the artifact must be unique for the artifact type in its primary category. Names are case-sensitive. For example, the names "Confidential" and "confidential" are considered as different names.

The name must contain 1 - 255 characters. A name cannot include Unicode control characters, start or end with a white space, or any greater-than (>) symbols.

Default value

None. You must supply a value for the artifact name.

Example

To add a business term named Blue, specify:

 Name,Artifact Type,Category
 Blue,glossary_term,Colors

Artifact Type (Mandatory)

Alternative column name

artifact_type

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The name of one type of governance artifact.

Format

You can import data for only one type of governance artifact at a time. Use the following values to specify the artifact type:

Default value

None. You must supply an artifact type.

Example

To add a business term artifact, specify:

 Name,Artifact Type,Category
 Blue,glossary_term,Colors

Category (Mandatory)

Alternative column name

category

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The primary category of the artifact or the category to create.

Format

Specify the full hierarchy path, starting with a top-level category, such as: myCategory1 >> myCategory2 >> myCategory3. See Category paths.

Unless you are importing categories, the specified categories must exist. If you are importing subcategories, the higher-level categories must exist, unless you define them in the same file.

Default value

Leave this field blank in the following situations:

• To import top-level categories.
• To add imported artifacts to the [uncategorized] category.

Example

To add a business term to the Colors top-level category, specify:

 Name,Artifact Type,Category
 Blue,glossary_term,Colors

To import a new top-level category, named myCategory1, specify:

Name,Artifact Type,Category
myCategory1,category,

To add a category, named myCategory2, as a subcategory to an existing category, named myCategory1, specify:

Name,Artifact Type,Category
myCategory2,category,myCategory1

To add a category, named myCategory3, in an existing category hierarchy of myCategory1 >> myCategory2, specify:

Name,Artifact Type,Category
myCategory3,category,myCategory1 >> myCategory2

Description

Alternative column name

description

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

Description

A description for the artifact.

Format

A description can contain up to 15000 characters.

Secondary Categories

Alternative column name

secondary_categories

Artifact types

Business terms, classifications, data classes, reference data sets, policies, governance rules

Description

A secondary category for an artifact.

Format

The category must exist. You can't specify the [uncategorized] category as a secondary category. Specify the full hierarchy path, starting with a top-level category. See Category paths.

To import multiple secondary categories for an artifact, add multiple rows for that artifact, with a different secondary category value in each row.

Stewards

Alternative column name

stewards

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

For categories, the steward is not displayed in the UI. To check the values, you can use the REST API call GET /v3/categories/{guid}. For more information, see the API documentation.

Description

The user ID for the person who is responsible for the artifact.

Format

An IBMid that consist of alphanumeric values. As an IBM Cloud account owner, you can view all users in your account. To find out a user's IBMid, go to Administration > Access (IAM) > Users. Open the entry for that user and click Details.

The format of the values of Stewards is not compatible between Cloud Pak for Data as a Service and Cloud Pak for Data 3.5 or 4.x.

Steward Groups

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The steward user group responsible for the artifact.

Tags

Alternative column name

tags

Artifact types

Categories, business terms, classifications, data classes, reference data sets, policies, governance rules

For categories, tags are not displayed in the UI. To check the values, you can use the REST API call GET /v3/categories/{guid}. For more information, see the API documentation.

Description

A string that can simplify retrievability of the artifact.

Format

A string of up to 255 characters. It can contain spaces, letters, numbers, underscores, dashes, and the symbols # and @.

If the tag does not yet exist, a new tag is created. To import multiple tags for an artifact, add multiple rows for that artifact, with a different value for a tag in each row.

Classifications

Alternative column name

classifications

Artifact types

Categories, business terms, data classes, reference data sets, policies, governance rules

For categories, the classification is not displayed in the UI. To check the values, you can use the REST API call GET /v3/categories/{guid}. For more information, see the API documentation.

Description

The classification that is assigned to the artifact.

Format

The classification must exist. Specify the classification with its full category hierarchy path. See Category paths.

To import multiple classifications for an artifact, add multiple rows for that artifact, with a different value for a classification in each row. Note that the Classifications column is supported in categories import, but it is not exported.

Example

Name,Artifact Type,Category,Classifications
Account,glossary_term,Insurance >> Business Area >> All Accounts,Insurance >> concept

Business Start

Alternative column name

business_start

Artifact types

Business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The effective date for when the published artifact becomes active. You can import artifacts with a business start date that is in the past.

The effective start date is set as follows:

• Import of a new artifact with an effective start date in the past: when you publish the draft, the effective start date is set to the date and time of publishing.
• Import of a new artifact with an effective start date in the future: when you publish the draft, the effective start date that is specified in the import is used.
• Import of updates to an existing artifact that has an effective start date in the past: when you publish the draft, if you imported with the Replace empty values merge method, then the original start date is preserved. Otherwise, the start date is changed to the publish date.
• Import of updates to an existing artifact that has an effective start date in the future: when you publish the draft, the effective start date that is specified in the import is used unless that date is in the past. In this case, it is set to the date and time of publishing.

Format

Specify the start date, time, and the Coordinated Universal Time time offset, in the format yyyy-mm-dd hh:mm±hh:mm, for example, 2020-10-07 16:00+00:00. Specifying the time offset is optional. If you omit that part, Coordinated Universal Time is assumed.

Business End

Alternative column name

business_end

Artifact types

Business terms, classifications, data classes, reference data sets, policies, governance rules

Description

The effective date for when the published artifact becomes inactive.

Format

Specify the start date, time, and the Coordinated Universal Time time offset in the format yyyy-mm-dd hh:mm±hh:mm, for example, 2021-10-07 17:00+00:00. Specifying the time offset is optional. If you omit that part, Coordinated Universal Time is assumed.

Related Terms

Alternative column name

related_terms

Artifact types

Business terms, classifications, data classes, reference data sets, policies, governance rules

Description

A business term that is related to the artifact.

Format

The business term must exist. Specify a related term with its full category hierarchy path. See Category paths.

To import multiple terms for an artifact, add multiple rows for that artifact, with a different value for a term in each row.

Example

Name,Artifact Type,Category,Classifications,Related Terms
Account claim tracking,glossary_term,Insurance >> Business Area >> Claim,Insurance >> property,Insurance >> Business Area >> Account >> Account

Custom property values

Column name

custom_attribute-name

The column name for such a value is the name of the custom property that is prefixed with custom_.

Artifact types

Categories, business terms, data classes, policies, governance rules

Description

A value for any type of custom property except for custom property of type Relationship.

Format

The custom attribute must exist.
For the custom property of type USER_GROUP the supported format is:

• "user_id:user", for example "1000330999:user"
• "group_id:group", for example "10000:group"

Both users and user groups can be defined for one CP of type USER_GROUP (if it supports multi values).

Custom relationships

Column name

custom_directed_relationshipname

The column name for a relationship is the name of the custom relationship that is prefixed with custom_directed_. For example, custom_directed_Is Analyzed By.

Artifact types

Categories, business terms, data classes, classifications, policies, governance rules

Description

Custom attributes of type Relationship.

Format

The custom relationship and the target artifact must exist. You must specify the directed relationship. The reversed relationship is created automatically. Specify the custom relationship with its full category hierarchy path. See Category paths.

Specify the information in the following format: contextPath:Type

Part of Terms

Alternative column name

part_of_terms

Artifact types

Business terms

Description

Adds a part relationship between two business terms:

• Is a part of: Specifies a relationship in which a term is a component of, a part of, an attribute of, or a member of another term.
• Has a part of: Specifies a relationship in which another term is a component of, a part of, an attribute of, or a member of the first term.

Format

The target business term must exist or must be defined in the same CSV file. In the row for the business term that has an Is a part of relationship, list the target business term. The Has a part of half of the relationship is added automatically.

Specify a part relationship with its full category hierarchy path`. See Category paths. A part relationship must always be defined as an Is a part of relationship.

To import multiple relationships for a term, add multiple rows for that term.

Example

For example, Fixed Rate, Hybrid Rate, and Variable Rate are attributes of the term Interest Rate, which in turn is an attribute of the term Home Loan. In this case, each of the terms Fixed Rate, Hybrid Rate, and Variable Rate has the Is a part of relationship to the term Interest Rate. The term Interest Rate has the Has a part of relationship to those terms but also the Is a part of relationship to the term Home Loan.

The rows for these terms look similar to this sample:

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Related Terms,Part of Terms,Abbreviations
Interest Rate,glossary_term,myCategory1,,,,,,myCategory1 >> Home Loan,,
Fixed Rate,glossary_term,myCategory1,,,,,myCategory1 >> Interest Rate,,
Hybrid Rate,glossary_term,myCategory1,,,,,myCategory1 >> Interest Rate,,
Variable Rate,glossary_term,myCategory1,,,,,myCategory1 >> Interest Rate,,

Type of Terms

Alternative column name

type_of_terms

Artifact types

Business terms

Description

Shows type relationships:

• Is a type of: Specifies a relationship in which a term is an instance of the concept that is expressed by another term typically broader in scope.
• Has a type of: Specifies a relationship in which the concept that is expressed by a term has one or more subtypes that are expressed by other terms. For example, the term Loan might be specified as having the Has a type relationship to the terms Home Loan, Car Loan, and Student Loan.

Format

The target business term must exist or must be defined in the same CSV file. In the row for the business term that has an Is a type of relationship, list the target business term. The Has a type of half of the relationship is added automatically.

Specify a type relationship with its full category hierarchy path. See Category paths. A type relationship must always be defined as an Is a type of relationship.

To import multiple relationships for a term, add multiple rows for that term.

Example

For example, Home Loan, Car Loan, and Student Loan are different types of loan. In this case, each of the terms Home Loan, Car Loan, and Student Loan has the Is a type of relationship to the term Loan. The term Loan has the Has a type relationship to those terms.

The rows for these terms look similar to this sample:

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Related Terms,Part of Terms,Type of Terms
Home Loan,glossary_term,myCategory1,,,,,,,myCategory1 >> Loan,
Car Loan,glossary_term,myCategory1,,,,,,,myCategory1 >> Loan,
Student Loan,glossary_term,myCategory1,,,,,,,myCategory1 >> Loan,

Synonyms

Alternative column name

synonyms

Artifact types

Business terms

Description

A relationship to another business term that has the same meaning.

Format

The target business term must exist or be defined in the same CSV file. Specify the synonym with its full category hierarchy path. See Category paths.

To import multiple synonyms for a term, add multiple rows for that term, with a different synonym in each row.

Data Classes

Alternative column name

data_classes

Artifact types

Business terms

Description

Any data classes that are assigned to a term.

Format

The data class must exist. Specify the data class with its full category hierarchy path. See Category paths.

To import multiple data classes for a term, add multiple rows for that term, with a different data class in each row.

Abbreviations

Alternative column name

abbreviations

Artifact types

Business terms

Description

An abbreviated form of the business term name.

Format

The abbreviation for a term.

To import multiple abbreviations for a term, add multiple rows for that term, with a different value for an abbreviation in each row.

Parent Classification

Alternative column name

parent_classification

Artifact types

Classifications

Description

The main classification to which this classification belongs.

Format

The parent classification must exist or be defined in the same CSV file. Specify the parent classification with its full category hierarchy path. See Category paths.

Example :

Name,Artifact Type,Category,Parent Classification,Related Terms
financial,classification,Insurance >> Business Area >> Claim,Insurance >> property

Parent Data Class

Alternative column name

parent_data_class

Artifact types

Data classes

Description

Specifies the relationship within a hierarchy of data classes.

Format

The parent data class must exist or must be defined in the same CSV file. Each data class can have only one parent data class. The parent and child data classes must be in the same category. Specify the parent data class with its full category hierarchy path. See Category paths.

Example :

Name,Artifact Type,Category,Description,Classifications,Related Terms,Parent Data Class
Georgia State Driver's License,data_class,Driver's License >> US License,A string representing a driver license of US state Georgia.,,,Driver's License >> US License >> Southeastern Driver's License

Enabled

Alternative column name

enabled

Artifact types

Data classes

Description

Indicates whether a data class is enabled for data matching.

Format

Possible values are TRUE or FALSE. This column is optional but if you add it, it must contain a value for each data class in the CSV file.

Reporting Authorized

Alternative column name

reporting

Definition

Alternative column name

definition

Artifact types

Data classes

Description

The data class definition.

Format

XML code surrounded by double quotation marks. Create this XML code by exporting an existing data class.

This column is optional but if you add it, it must contain a value for each data class in the CSV file.

Example :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><DataClasses xmlns="http://www.ibm.com/infosphere/ia/classification/DataclassesDefinition"><DataClass id="AddressLine1" name="Address Line 1" description="Address Line 1 of a multi-line address." priority="12" active="true" provider="IBM"><JavaClassifier scope="column" className="com.ibm.infosphere.classification.impl.AddressLineClassifier"/><DataTypeFilter><LogicalDataType>string</LogicalDataType></DataTypeFilter><DataLengthFilter minLength="4" maxLength="100"/><ColumnNameFilter><ColumnNameRegularExpression>addr.{0,15}(1|one)$</ColumnNameRegularExpression></ColumnNameFilter></DataClass></DataClasses>

Data Set Type (Mandatory for reference data sets)

Alternative column name

type

Artifact types

Reference data sets

Description

The data type of the reference data set. This property is mandatory if you import a reference data set.

Format

Supported values are text, date, number.

Parent Reference Data Sets

Alternative column name

parent_rds

Artifact types

Reference data sets

Description

Specifies the relationship within a hierarchy of reference data sets.

Format

The parent reference data set must exist or must be defined in the same CSV file. A reference data set can have any number of parent reference data sets. Specify the parent reference data set with its full category hierarchy path. See Category paths.

To import multiple parent reference data sets, add a separate row for each one.

Example :

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Related Terms,Business Start,Business End,Data Set Type,Parent Reference Data Sets,Secondary Categories,Custom Columns
RDS1,reference_data,cat1,Test RDS,tag1,Confidential,1000330999,cat1 >> term1,6/15/2021 13:08,7/31/2021 21:59,TEXT,cat1 >> RDS2,Information Governance,TEXT||CUSTOM COLUMN1||test
,,,,,,,,,,,,Business Information,NUMBER||CUSTOM COLUMN2||test2
RDS2,reference_data,cat1,,,,,,6/15/2021 13:13,,TEXT,,,

Custom Columns

Alternative column name

custom_columns

Artifact types

Reference data sets

Description

Map columns in a reference data set to existing custom columns. When importing new reference data sets, you can define new custom columns. See Custom columns.

Format

Specify the information in the following format:

type (TEXT/NUMBER/DATE)||name||description (optional)||composite-key/normal-column (optional, default: normal-column)||mandatory/optional (optional, default: optional)||max characters number (optional, default: 2000 for normal-column, 200 for CK column)||validator as path>>name (optional)

• If the column is defined as composite key, then it must be mandatory.
• Only a published referece data set of type TEXT can be a validator.
• Only custom columns of type TEXT can have a validator.
• Maximum number of composite key columns per a set is 5.

Examples :

NUMBER||Digit Count||Number of digits of the prime
TEXT||Additional information

Parent Policy

Alternative column name

parent_policy

Artifact types

Policies

Description

Specifies the parent policy of a policy.

Format

The parent policy must exist. Specify the parent policy with its full category hierarchy path. See Category paths.

A policy can have only one parent policy.

Examples :

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Secondary Categories,Rules,Parent Policy
policy7,policy,PolicyDef,test policy7,Tag1,,,,,PolicyDef >> policy1

Parent Policies

Alternative column name

parent_policies

Artifact types

Governance rules

Description

Specifies the parent policy of a governance rule.

Format

The parent policy must exist. Specify the parent policy with its full category hierarchy path. See Category paths.

Examples :

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Related Terms,Business Start,Business End,Type,Secondary Categories,Rules,Reference Data Sets,Parent Policies,custom_Rule_text_0
rule2,rule,cat1,,,,,,6/15/2021 13:17,,Governance,,cat1 >> rule1,,cat1 >> pol1,
rule1,rule,cat1,test description,tag1,Confidential,1000330999,cat1 >> term1,6/15/2021 13:16,8/31/2021 21:59,Governance,Business Information,cat1 >> rule3,cat1 >> RDS2,cat1 >> pol2,example CA value
,,,,,,,,,,,,cat1 >> rule2,cat1 >> RDS1,cat1 >> pol1,
rule3,rule,cat1,,,,,,6/15/2021 13:20,,Governance,,cat1 >> rule1,,cat1 >> pol1,

Rules

Alternative column name

rules

Artifact types

Policies, governance rules

Description

For a policy, a governance rule that is governed by this policy.

For a rule, the governance rules that are related in some way to this rule. The relationship is symmetrical. If you specify that rule A is related to rule B, then rule B is related to rule A.

Format

The governance rule must exist. Specify the governance rule with its full category hierarchy path. See Category paths.

To import relationships with multiple rules, add a separate row for each one.

Example :

Name,Artifact Type,Category,Description,Tags,Classifications,Stewards,Related Terms,Business Start,Business End,Secondary Categories,Rules,Parent Policy,custom_policy_text_0
pol3,policy,cat1,,,,,,6/15/2021 13:16,,,,,
pol2,policy,cat1,,,,,,6/15/2021 13:14,,,cat1 >> rule1,cat1 >> pol1,
pol1,policy,cat1,test descritpion,tag1,Confidential,1000330999,cat1 >> term1,6/15/2021 13:11,7/31/2021 21:59,Information Governance,cat1 >> rule3,cat1 >> pol3,example CA value
,,,,,,,,,,,cat1 >> rule1,,
,,,,,,,,,,,cat1 >> rule2,,

Reference Data Sets

Alternative column name

rds

Artifact types

Governance rules

Description

A reference data set that is related to the governance rule.

Format

The reference data set must exist. Specify the reference data set with its full category hierarchy path. See Category paths.