Skip to main content

Asset Import for tags
App

The Asset Import app loads metadata for tags from a CSV file into Atlan. It's designed to support the design and deployment of tag definitions without manual pointing and clicking through the user interface.

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 tag definitions.

You can also use the same Asset Import app to import other types of metadata, such as Assets, Data Products and Glossaries. 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, tag imports can be set up and run by admins or users with workflow permissions.

Source​

This section defines how the input CSV file for tag 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 tag import.

Example: If you're importing tags for the data governance domain, you might set:

Data governance tags import

Import metadata from​

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

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. When the Direct file upload option is selected, only properties relevant to local file handling are available in the Tags section.

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 property imports the tag 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 assets 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 tags 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:

tags

Tags 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 tag metadata for import into Atlan.

The tag CSV follows a structured format with columns for tag names, descriptions, colors, and source system relationships. Each row in the file represents a single tag and its characteristics.

You can upload one CSV file per workflow run. The file must follow the Tags CSV format, and only CSV files are supported, formats such as JSON or Excel aren't accepted. Duplicate tag entries in the same file cause errors and workflow failure.

For detailed information on the required structure and field definitions, see the Tags 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 tag 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 tag file is stored in a folder called governance inside the tags directory of your bucket, set the prefix to:

tags/governance

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 tag file is stored under a folder called tags/governance in your object store, you can configure:

Prefix:

tags/governance

Object key:

governance-tags.csv

Complete path: {{bucket}}/tags/governance/governance-tags.csv

Options​

The Options property defines how the workflow interprets and applies data from the tag CSV file. These settings primarily control error handling.

When Default is selected, the following behaviors apply:

  • Any invalid value in a field causes the import to fail.
  • Comma (,) is used as the field separator.

Tags CSV file​

The tag CSV file defines the metadata for tags to be imported. Each row represents one tag and its attributes.

Required fields​

  • Atlan tag name: The name of the tag. Must be unique.

    Example: Sensitivity (creates a tag called "Sensitivity")

  • Color: The color to use for the tag. Must be one of (case-sensitive):

    • Gray
    • Green
    • Yellow
    • Red

  • Icon - The icon to use for the tag. Can either be a URL to an image (svg or png), or the name of a Phosphor icon in CamelCase.

    Example: PhShieldStar

Matching behavior​

When importing, tags are matched strictly by their name.

Can't update tag names

Note that name controls updates, so you can't use this app to change the name of existing tags.

Source tag fields​

If you want a tag to also capture a value, you need to configure it as a source-synced tag. You need to define these additional fields to create a source-synced tag.

  • Synced connection name: Name of the connection in which the tag exists.

    Example: Production

  • Synced connector type: Type of connector for the connection in which the tag exists.

    Example: custom

  • Allowed values for tag: Optional list of allowed values when associating this tag with an asset in the user interface. Separate each value by a newline within the cell.

    Example: this configures the tag so users can only specify one of the following four values when associating the tag with an asset

    Public
    Internal
    Confidential
    Restricted

  • Tag ID in source: Optional unique string for how the tag is identified in the source system.

    Example: sensitivity-123 or 3bf2a3b7-aa75-4353-8bbd-be64b04746f1

Sample CSV file​

Download a sample CSV file to understand the required structure:

📥 Download sample tags 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​