Data source asset

A data source contains tabular data that can be selectively loaded and filtered in a configurator with a table component.

Supported File Types

A data source can be created or updated with files of these types:

• Microsoft Excel .xls or .xlsx

• CSV files .csv

• JSON files .json

While you can create a single data source asset from such a file, we strongly recommend that you instead upload the file as a file asset first. This will allow you to create multiple data sources based on it and update them all at once whenever you upload a newer version of your file. We will walk you through this process in the next section.

Create a new data source

1. Create a new file asset
   Upload the file that contains the data for your data source as a file asset (make sure that the Asset Type is set to “File”). It must be a file with one of the supported file types.

2. Select the file asset, click on Create data source and enter a name for your new data source.

   

You now have a data source that is linked to the file asset and will be updated automatically when you update the file asset.

Now we have to configure which data will be extracted from the file. The asset manager will analyze the file and tries to create a starting point for you to work with. The exact process depends on the type of file: a CSV file already contains tabular data and should result in a faithful representation. The same is true for an Excel file, provided that it also contains tabular data – the asset manager will use the first worksheet it finds, but you can choose which one to use in the import configuration, which we will look at next.

Adjust the Import Configuration

The import configuration describes which part of the raw data should be read and how it should be interpreted. When you create a new data source, an initial import configuration will be created automatically as a starting point.

While some parts of the import configuration are the same for all data sources, other parts depend the type of file that is used as source. For instance, an Excel-based data source allows you to choose the worksheet from which to load data. JSON-based data sources require more setup and are explained in a separate article, but the following general points also hold true for it.

Each import configuration contains a list of column definitions, which allow you to describe the columns that you want your data source to have. If the underlying file contains tabular data, then these can be a close match to the columns found in there, but they don’t have to be. You may only be interested in a subset of the data, or may want to interpret it differently – for instance, you can indicate that the texts found in one column are actually URLs or a list of values separated by a specific character.

• Each column must have a unique name, which you can freely choose. Keep in mind though that the name must be a valid Hive identifier, since you will use it to access the data in your configurator. This name can be identical to the column name found in the underlying file (if it contains tabular data and column names), but it doesn’t have to be – though it’s usually a good idea to keep the names the same.

• The column type indicates what kind of data it holds. The asset manager will try to convert the raw file contents so that they fit the column type and displays an error if a column value cannot be used.

• The default value of the column will be used when the underlying file doesn’t contain a value for it (e.g. if an Excel cell is empty).

Other settings of the import configuration depend on the underlying file. For CSV files, you can e.g. choose the character that is used to separate column values. Both CSV- and Excel-based data sources allow you to ignore conversion errors and use the column’s default value instead, e.g. if a Number column contains letters.

You can change the import configuration at any time to alter how data is read and interpreted. Each time you do, the contents of the underlying fille will be read again and interpreted according to the updated import configuration. This process also happens automatically when the underlying file comes from a file asset that has just been updated. If there are any conversion errors, they will be displayed prominently in the asset manager.

Advanced Topics

Linked Asset Columns

There is a convenient way to associate a data source column with other assets by using one of the LinkedAsset column types. Let’s say you have a products data source: you can link each product with a thumbnail, 3D model, material or PDF document so that you can easily access them in your configurator. To do so, place all assets that can be linked to in an asset folder and create a LinkedAsset column. Configure the column to use your asset folder and optionally select one of the assets as a fallback, which will be used if a linked asset is missing.

The column values in the underlying file must be of type Text, specifically they must be the names of the assets in your asset folder. When the data source is imported, the asset manager will look for an asset with that name and use the configured fallback asset if none can be found. A hint will be displayed to inform you about the missing asset.

The data source will be linked to each folder and fallback asset that is used in a Linked Asset column. If the folder is moved or deleted, it will result in an error to notify you about the compromised data source.

Interaction with linked file asset

• There is no limit on how many data sources you can link to a file asset

  • Each data source can only be linked to 1 file asset though.

• If linked, you cannot update the contents of a data source directly; you have to update the file asset instead (which will update all linked data sources).

• You can copy a linked data source. The copy will be linked to the same file asset but has an independent import configuration that you can change (e.g. select a different Excel worksheet).

  • When you copy a file asset, any linked data sources will not be copied, nor will the new file asset be linked to any data sources.

• If you delete a file asset, all links from it to data sources will be removed. The data sources still function, but cannot be updated until you upload a new file into each data source separately.

  • There is currently no way to re-create a data source link, which is why we do not recommend you delete a file asset with data source links.

  • You can delete a data source that is linked to a file asset without affecting the file asset or any other linked data source. Only the deleted data source and its link will be removed.

Automation

You can update the contents of data sources automatically, e.g. by loading data from an external service on a fixed schedule, by using a workflow.