Skip to main content

Asset Import for glossaries
App

The Asset Import app loads metadata for glossaries, categories, and terms from a CSV file into Atlan. It's designed to support large-scale enrichment and migration of business glossary metadata without manual entry.

CSV files can be provided either by uploading them directly from your local machine or by fetching them from a cloud object store. Supported object storage systems include Amazon S3, Google Cloud Storage (GCS), and Azure Data Lake Storage (ADLS).

This reference provides complete configuration details for glossary imports, including input handling rules, options for updates versus creation, and behavior when working with hierarchical structures like parent categories or anchors.

You can also use the same Asset Import app to import other types of metadata, such as Assets, Tags and Data Products. See their respective references for details.

Access​

The Asset Import app isn't enabled by default. To use this app, contact Atlan support and request it be added to your tenant. Once enabled, glossary imports can be set up and run by admins or users with workflow permissions.

Source​

This section defines how the input CSV file for glossary metadata is provided and identified in Atlan.

Workflow name​

Specifies the display name for the workflow in Atlan. This name is used to identify the import job in the UI and logs. Choose a name that clearly reflects the purpose or scope of the glossary import.

Example: If you're importing glossary terms for a specific domain, you might set:

Business glossary import

Import metadata from​

This property defines how the CSV file containing glossary metadata is provided to the workflow. The file format must match the CSV file format for glossaries.

There are two ways to provide the file:

  • Direct file uploads: Upload a CSV file directly from your local machine. This is useful for smaller files or ad-hoc imports. See Direct file uploads.
  • Object storage: Fetch the CSV file from a supported cloud object store (S3, GCS, or ADLS). This is recommended for larger files or recurring imports. See Object storage.

Direct file uploads​

Upload a CSV file directly from your local machine. This option is best for smaller files or ad-hoc imports that are run manually.

File size limit

Direct file uploads are limited to ~10 MB. Only one file can be uploaded per run. For larger or recurring imports, use object storage.

Object storage​

This option imports the glossary CSV file from a cloud object store rather than a local upload. It's recommended for large files and for recurring imports. Supported providers are Amazon S3, Google Cloud Storage (GCS), and Azure Data Lake Storage (ADLS). When this option is selected, additional storage-specific properties such as bucket, project ID, or container become available.

Amazon S3 enables you to store and retrieve objects at scale. You can use this option when the glossary CSV file is stored in an S3 bucket.

AWS access key​

The access key for your AWS account. You can find this in the AWS Management Console > IAM > Users > Security credentials tab.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or role-based.

Example:

AKIAIOSFODNN7EXAMPLE

AWS secret key​

The secret key that pairs with your access key. This is generated when you create an access key in IAM. You must download it at creation time or rotate and generate a new one if lost.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or role-based.

Example:

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS role ARN​

The ARN of the AWS role to use to access S3. You must set this up separately in AWS, and grant permissions for Atlan to assume this role.

  • Must have a value if you are using role-based authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or access/secret key based.

Example:

arn:aws:iam::123456789012:role/roleName

Region​

The AWS region in which your bucket is located (for example, us-east-1). You can find this in the S3 service dashboard when selecting your bucket.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank in all other scenarios, where the region is inferred from the tenant or role.

Example:

ap-southeast-1

Bucket​

The name of the S3 bucket that contains your glossary CSV file. The bucket name is listed in the S3 service dashboard.

  • Must be blank to use the tenant-backed object store's bucket.
  • Must have a value in all other scenarios.

Example:

my-company-glossary

Glossaries file​

This property is available only when the Direct file uploads option is selected under Import metadata from. It defines the CSV file that contains glossary metadata for import into Atlan.

The glossary CSV follows a structured format with columns for glossaries, categories, and terms. Each row in the file represents a single glossary object and its attributes, while parent–child relationships (such as categories under glossaries, or terms under categories) are encoded in specific columns.

You can upload one CSV file per workflow run. The file must follow the Glossary CSV format, and only CSV files are supported, formats such as JSON or Excel aren't accepted.

Duplicate entries cause errors

Duplicate glossary, category, or term entries in the same file cause errors and workflow failure. The file is processed in parallel for maximum speed, so duplicates result in backend collisions rather than precedence.

For detailed information on the required structure and field definitions, see the Glossaries CSV format.

Prefix (path)​

This property is available only when the Object storage option is selected under Import metadata from. It specifies the directory or path within your selected cloud object store where the glossary CSV file is located.

If left blank, the system searches from the root of the bucket or container.

  • With prefix: Only files under the specified path are processed.
  • Without prefix: System searches from the root of the storage location.
  • Format: Use forward slashes (/) as path separators.
  • Trailing slash: Not required, Atlan appends automatically if missing.

Example: If your glossary file is stored in a folder called finance inside the glossaries directory of your bucket, set the prefix to:

glossaries/finance

Object key (filename)​

This property is available only when the Object storage option is selected under Import metadata from. It specifies the exact CSV file to import from your chosen cloud object store. The value entered here is combined with the optional Prefix (path) to form the complete location of the file.

The object key must include the file name and extension. Only one file can be provided per configuration. If you have multiple CSV files, the Object key (filename) property can only reference one file at a time. A new workflow run is required for each file, even if they're stored in the same prefix or folder.

  • Single file: Only one CSV file per workflow configuration
  • Multiple files: Requires separate workflow runs for each file
  • File extension: Must include the .csv extension
  • Path combination: Object key + prefix = complete file location (within the bucket)

Example: If your glossary file is stored under a folder called finance in your object store, you can configure:

Prefix:

glossaries/finance

Object key:

terms.csv

Complete path: {{bucket}}/glossaries/finance/terms.csv

Input handling​

The Input handling property defines how the workflow processes glossary metadata from the CSV file when matching it with existing assets in Atlan. It controls whether new glossaries, categories, and terms are created or only existing ones are updated.

Glossary matching rules

Glossary objects use different matching rules than regular assets:

  • Glossaries: Matched only by name; the qualifiedName field is ignored.
  • Terms: Matched by the unique combination of name and anchor; the qualifiedName field is ignored.
  • Categories: Matched by the unique combination of name, parentCategory, and anchor; the qualifiedName field is ignored.

This means you can't use qualifiedName to control updates, so you can't use this app to change the names of existing glossaries, terms, or categories.

Create and update​

This option creates new glossary assets from the CSV file and updates any that already exist in Atlan. With this configuration, the workflow reads each row in the CSV and either:

  • Creates a glossary, category, or term if it doesn't already exist, or
  • Updates the corresponding glossary, category, or term if it's already present.

This option is commonly used when loading a glossary into Atlan for the first time, or when expanding an existing glossary with additional terms while refreshing the details of existing entries.

Update only​

This option updates only glossary assets that already exist in Atlan. With this configuration, the workflow applies changes from the CSV file to matching glossaries, categories, or terms, but doesn't create any new assets.

This option is useful when enriching or correcting existing glossaries with additional metadata, descriptions, or attribute values.

Options​

The Options property defines how the workflow interprets and applies data from the glossary CSV file. These settings control error handling, attribute overwrites, and how multi-valued fields like tags or custom metadata are managed.

When Default is selected, the following behaviors apply:

  • Blank fields in the CSV are ignored and don't overwrite existing values.
  • Any invalid value in a field causes the import to fail.
  • Comma (,) is used as the field separator.
  • Up to 20 records are processed in each API request.
  • Custom metadata attribute values are merged with any existing values.
  • Links are updated if their URL is the same, otherwise new links are added.
Atlan tags behavior

If the atlanTags column exists in your CSV, it always overwrites existing tags completely, regardless of the selected handling option. This is different from regular assets where tags can be appended or merged.

Glossaries CSV file​

The glossary CSV file defines the metadata for glossaries, categories, and terms to be imported. Each row represents one glossary object and its attributes. Parent–child relationships are encoded using specific columns such as anchor (for terms) and parentCategory (for categories).

Required fields​

Glossaries​

  • typeName: Must be AtlasGlossary for glossaries.

  • name: The name of the glossary.

    Example: Concepts (creates a glossary called "Concepts")

Terms​

  • typeName: Must be AtlasGlossaryTerm for terms.

  • name: The name of the term.

    Example: Customer ID (creates a glossary term called "Customer ID")

  • anchor: The glossary this term belongs to (must match the glossary name exactly).

    Example: Concepts (places the term "Customer ID" in the "Concepts" glossary)

  • categories: Optional list of categories in which to organize this term. Separate multiple categories by a newline within the cell.

    Example: this organizes the term into both a "Finance" subcategory in the "Business Units" category, and a "General" category (both in the "Concepts" glossary)

    Business Units@Finance@@@Concepts
    General@@@Concepts

Categories​

  • typeName: Must be AtlasGlossaryCategory for categories.

  • name: The name of the category.

    Example: Business Units (creates a category called "Business Units")

  • anchor: The glossary this category belongs to (must match the glossary name exactly).

    Example: Concepts (places the category "Business Units" in the "Concepts" glossary)

Subcategories​

  • typeName: Must be AtlasGlossaryCategory for subcategories.

  • name: The name of the subcategory.

    Example: Financial Data (creates a category called "Financial Data")

  • anchor: The glossary this category belongs to (must match the glossary name exactly).

    Example: Concepts (places the category "Financial Data" in the "Concepts" glossary)

  • parentCategory: The parent category in which this subcategory belongs (uses @ as a delimiter).

    Example: Business Units@Finance@@@Concepts (places "Financial Data" under the "Finance" category inside the "Concepts" glossary)

Matching behavior​

  • Glossaries: only name is used for matching
  • Terms: unique combination of name and anchor is used
  • Categories: unique combination of name, parentCategory, and anchor is used
Case sensitivity and matching rules

All identifiers are case-sensitive and must match exactly:

  • No leading or trailing space trimming
  • No fuzzy matching
  • Invisible characters (for example, zero-width spaces) may break matching

The qualifiedName field is completely ignored, so you can't use this app to change the names of existing glossaries, categories, or terms.

Common fields​

You can use these common fields on glossaries, categories, and terms.

  • userDescription: Description or definition of the asset.

    Example: A party (individual or organization) to whom the company delivers goods and/or services. (gives the definition of a term)

Certificates​

  • certificateStatus: Optional certificate on the asset. Must be one of (case-sensitive):

    • VERIFIED
    • DRAFT
    • DEPRECATED
    • or empty.

  • certificateStatusMessage: Optional message to associate with the certificate. Atlan only shows this if the certificateStatus is non-empty.

    Example: Confirmed by reviewing the description and readme.

Announcements​

  • announcementType: Optional type of announcement on the asset. Must be one of (case-sensitive):

    • information
    • warning
    • issue
    • or empty.

  • announcementTitle: Optional heading line for the announcement. Atlan only shows this if the announcementType is non-empty.

    Example: Unconfirmed quality

  • announcementMessage: Optional detailed message that can be associated with the announcement. Atlan only shows this if the announcementType is non-empty.

    Example: The quality of this asset has not been validated by either automated or manual checks. Use at your own risk.

Owners​

  • ownerUsers: Optional list of individual users who are owners of the asset. Separate each username by a newline within the cell.

    Example: this assigns both "jane" and "joe" as individual owners of the asset

    jane
    joe

  • ownerGroups: Optional list of groups who are owners of the asset. Separate each group name by a newline within the cell.

    Example: this assigns both "finance" and "marketing" as group owners of the asset

    finance
    marketing

Atlan tags​

  • atlanTags: Optional list of the tags to assign to the asset. Separate each tag by a newline within the cell, and format as one of the following:

    • Tag Name to directly assign the tag to the asset but not propagate it.

    • Tag Name>>FULL to directly assign the tag to the asset and propagate it both down the hierarchy and through lineage.

    • Tag Name>>HIERARCHY_ONLY to directly assign the tag to the asset and only propagate down the hierarchy (not through lineage).

    • Tag Name<<PROPAGATED to indicate the tag has been propagated to the asset.

      Propagated tags are ignored

      Any tag marked propagated (Tag Name<<PROPAGATED) is ignored by an import. Only those tags that are directly applied are imported, though of course any tags applied up-hierarchy or upstream that are marked to propagate are still propagated accordingly.

    For source tags (with values), you can extend the tag name portion as follows:

    • Tag Name {{connector-type/Connection Name@@sourceTagLocation??key=value}}, where:
      • connector-type is the type of the source tag (snowflake, dbt, etc)
      • Connection Name is the name of the connection for the source the tag is synced from
      • sourceTagLocation is the path within that connection where the source tag exists
      • key is an optional key for the associated value for the tag
      • value is the value for the associated tag

    Example: this associates the Confidential Atlan tag, which is synced with the CONFIDENTIAL Snowlfake tag in the DEMO database's CUSTOMER schema as part of the Production Snowflake connection. It has a value of Not Restricted in Snowflake, and the tag itself is fully-propagated in Atlan.

    Confidential {{snowflake/Production@@DEMO/CUSTOMER/CONFIDENTIAL??=Not Restricted}}>>FULL

  • links: Optional list of the links to assign to the asset. Separate each link by a newline within the cell, and format as embedded JSON.

    • typeName: set to Link
    • attributes: containing a substructure of
      • name: the name (title) to give the link
      • link: the URL of the link

    Example: this creates 2 links for the asset, one named Example and the other named Google

    {"typeName":"Link","attributes":{"name":"Example","link":"https://www.example.com"}}
    {"typeName":"Link","attributes":{"name":"Google","link":"https://www.google.com"}}

Readmes​

  • readme: Optional HTML-formatted contents to use as the README for the asset. (You can limit this to only what's inside the <body></body> HTML tags.)

    Example: this sets the README to include a heading of "Overview" with some descriptive content underneath

    <h1>Overview</h1>
    <p>
      Some descriptive content about this asset,
      including <a href="https://example.com">links</a>
      and other rich HTML content.
    </p>

Starred details​

  • starredDetails: Optional list of the users you want to star the asset for. Separate each entry by a newline within the cell, and format as embedded JSON.

    • assetStarredBy: set to the username
    • assetStarredAt: set to the (epoch-style) timestamp of when to star it for them

    Example: this ensures the asset is starred for two users, "Jane" and "Joe"

    {"assetStarredBy":"joe","assetStarredAt":1698769268966}
    {"assetStarredBy":"jane","assetStarredAt":1698769268966}

Associated terms​

You can link terms to other terms in a number of ways, each with slightly different meanings. In all cases, you specify the related term using the format Term Name@@@Glossary Name. To relate multiple terms, separate each by a newline within the cell.

Example: this assigns the asset to 2 terms, Customer in the Concepts glossary and Revenue in the Metrics glossary

Customer@@@Concepts
Revenue@@@Metrics
  • antonyms: Optional list of terms whose meaning is the opposite of this term's meaning.
  • synonyms: Optional list of terms whose meaning is the same as this term's meaning.
  • seeAlso: Optional list of terms to assign as related terms.
  • classifies: Optional list of terms that define this term in greater detail. (Mutually-exclusive with isA.)
  • isA: Optional list of terms that are more abstract explanations of this term. (Mutally-exclusive with classifies.)
  • preferredTerms: Optional list of terms that are recommended instead of this term. (Mutally-exclusive with preferredToTerms.)
  • preferredToTerms: Optional list of terms that this term is recommended to be used in place of. (Mutually-exclusive with preferredTerms.)
  • replacedBy: Optional list of terms that this term is superceded by. (Mutually-exclusive with replacementTerms.)
  • replacementTerms: Optional list of terms that this term replaces. (Mutually-exclusive with replacedBy.)
  • translatedTerms: Optional list of terms that translate this term into other langauges. (Mutually-exclusive with translationTerms.)
  • translationTerms: Optional list of terms for which this term is a translation. (Mutually-exclusive with translatedTerms.)
  • validValues: Optional list of terms that define valid values for this term. (Mutually-exclusive with validValuesFor.)
  • validValuesFor: Optional list of terms that this term defines a valid value for. (Mutually-exclusive with validValues.)

Custom metadata​

You can also manage custom metadata attributes through the app. For these, use the name of the custom metadata and attribute as the name of the column in the CSV in the format Custom Metadata Name::Attribute Name.

Example:

  • Data Quality::Completeness: this column sets values for the Completeness attribute in custom metadata named Data Quality.

For any attribute that supports multiple values, separate each value by a newline within the cell.

Sample CSV file​

Download a sample CSV file to understand the required structure:

📥 Download sample glossary CSV
Sample file disclaimer

This sample file shows the structure and format only. It may not import as-is and is merely a template for creating your own CSV files.

See also​