The VNTANA Metadata App simplifies the process of managing your metadata on the VNTANA Platform. This application covers two key functions: the generation of reports containing various information and metadata for your VNTANA Assets, and the uploading of metadata to your VNTANA Assets.
The application is designed to cover a multitude of use-cases when it comes to managing your data on the Platform. In doing so, there may be a few subtleties to how the data is handled and this resource is intended to ensure proper usage.
v1.2.0
Release Notes
Report Generation
- Added Version Number and Last Editor to list of fields when generating a report.
- When Version Number is requested, the resulting report will contain a separate row for each version available for an asset.
Metadata Upload
- Added a Version Number type to allow the assignment of the included data to specific Versions.
- Treatment of this column will differ based on upload type selected. See below for more info.
- Added Thumbnail option to Report Generation.
- Fixed an issue where downloaded templates weren’t revealed in the folder on MacOS.
- Fixed an issue where Amazon Template downloads didn’t complete.
- Added the ability to set the API URL to match Sony XYN platform.
Quality of Life
- Added additional cleanup on entered data to remove newlines, tabs, and return carriages before upload.
Bug Fixes
- Fixed issue where certain empty cells were not read as such resulting in a value of undefined set on Platform.
- Fixed an issue where Workspace users could not complete the Upload data flow.
- Fixed an issue where Number values for certain data types could break cleanup steps and prevent upload.
Settings
- Added a Settings panel accessible via the menu in the upper right corner.
- Allows setting of a custom VNTANA API URL.
- This should only be changed from the default if VNTANA have provided your organization with a private instance.
This release provides some minor QoL updates to address areas of confusion with the Integration data upload.
- Integration Upload
- The downloadable template has been updated to simplify the information returned.
- Dimensions columns were removed. Dimensions can still be passed, however the platform will auto-generate these so they should only be passed if you wish to manually set them.
- A new settings modal was added upon clicking the ‘Download Template’ button, allowing users to specify which workspaces and Amazon marketplaces are included.
- The upload type text has been updated to better reflect the behavior of each option as it pertains to integration data.
- A warning has been added to the data confirmation page when any dimension related column is found/assigned, indicating any values passed for these will prevent the auto-generation of dimensions.
- The downloadable template has been updated to simplify the information returned.
- Bugfixes
- Fixed an issue preventing generation of a report with Attributes
- Fixed messaging when report generation fails
- Fixed toggling of ‘Select All’ button in report generation
- Fixed an issue with data validation when changing the source file during upload/integration flows
- Metadata Upload
- Added the ability to bulk rename Asset’s using the Apps upload functionality.
- Requires Asset Name column with new name and Asset UUID column as identifier.
- Added the ability to bulk rename Asset’s using the Apps upload functionality.
- Integration Data Upload
- Added Workspace Slug to the data generated for the template report.
- Report Generation
- Improved handling of large report requests to prevent timeouts.
- Added additional report fields related to the Amazon Integration.
- Reports can now be generated with information on an asset’s Amazon Publish Status, Amazon ASIN’s, and Asset Dimensions.
- The Publish Status and ASIN’s will be returned on a per-marketplace basis, i.e. the United States and Canada marketplaces will be represented by separate columns.
- A new Report Preset feature has been added which will allow you to store selections for a report as well as share the preset with teammates.
- A default Amazon preset is provided which will pull info on that integration.
- You can save a preset containing common report fields and the export format to avoid having to select the all of these every time.
- A preset can be exported as a json file and shared with teammates who can in turn import the file and have the same preset stored.
- Metadata Upload
- Added upload fields for pipelineUuid and pipelineName to allow you to set an Optimization Pipeline for your assets.
- Integration Upload
- A new upload method has been introduced related to integrations and can be accessed from the Menu page via the Integration Data button.
- This is a separate process to the regular Upload method as the data has to be handled differently.
- Currently, this allows the upload of Amazon ASIN’s on a per-marketplace basis (i.e. separate columns of data per marketplace).
- Uploading Amazon data via this method will also automatically trigger the generation of the needed Asset Dimensions.
Downloading
The application is available on Windows and MacOS and can be downloaded here.
Windows
Download and run the vntana_{version}_setup.exe file. The setup process will be automatic and a start menu shortcut as well as a Desktop shortcut will be created. The application can be run from either of these.
MacOS
Apple Silicon (arm64)
Intel Chips (x64)
Download and run the dmg file. This will prompt you to move the app into your applications directory, from which the application can be started.
Whitelisting
The VNTANA Metadata App makes use of HTTPS requests to the VNTANA Admin API and as such the VNTANA domain may need to be whitelisted for GET/POST requests to the *.vntana.com domain.
Updating
When an update is available, the app will notify you with a button in the upper right corner after authenticating. Clicking this button will bring you to this page to download the new version.
Updating is the same as installing for the first time, the setup file will handle the process for you.
Settings
New in version 1.1.4, there is a Settings panel available from the menu in the upper right corner.
Currently, there is only one setting related to the API Configuration of the app. This should only be changed if VNTANA has provided your organization with a private environment.
Sign-in Page
There are two options for sign-in with the Metadata application: email/password and authentication key.
Email/Password Sign-in
This option requires a valid account on the VNTANA Platform and refers specifically to the email and password used here. This does not include the Google / Microsoft authentication credentials, for users that access the Platform using one of these methods you will have to use your Authentication Key.
Authentication Key
For users that use Google or Microsoft credentials to access the Platform or users that wish to enable quicker sign-in with the application, the Authentication Key option is the route to choose. To learn how to generate this key, see this guide.
With the Authentication Key, upon entering a valid key and successfully authenticating, it will be encrypted and stored locally for use the next time you open the Application.
Report Generation
Quick Tips
- Selecting no Workspaces on the Workspace select page will produce a report covering all Workspaces.
- Workspace level users can only select one Workspace at a time and thus cannot leave the Workspace selection empty.
Organization Selection
If the application is unable to authenticate your credentials with the Organization you’ve selected, the selection box will have a red border and an ‘Invalid Organization’ message will appear. The possible reasons for this include:
-
The selected Organization does not have a valid subscription.
-
The attempt to authenticate to the selected Organization wasn’t able to complete due to network issues.
-
Authenticating into an Organization shouldn’t be confused with signing in with email/password or authentication key. This is a part of the API’s auth flow which requires generating a separate token for individual Organizations. If there is an issue with your credentials you would be prevented from getting past the sign-in page.
-
Workspace Selection
The next screen will allow you to select the Workspaces you wish the report to encompass. Simply check the Workspaces to include in the report. You can leave this selection empty if you just wish the report to include all Workspaces.
Report Configuration
There are a number of fields available including Asset name and UUID, tags, attributes, and preset UUID’s. Select All will return all data or you can pick and choose specific ones. There are a number of quirks to how the data may be returned, you can refer to this list to explain each field and how they may behave with or without other fields.
One important facet of the fields to remember is that the rows that are created are always based on some Asset on the Platform. this means if you generate a list that just returns tags or attributes, but don’t indicate Asset Name or UUID, the spreadsheet may appear strange with large gaps as it does still include rows for Assets that don’t contain tags or attributes.
Asset Name: This is simply the current Name of the Asset being reported on Platform.
This or Asset UUID are used to determine the row of data that is returned. If neither are requested, the data returned may seem disjointed as the data always contains rows representing all Assets in a Workspace, regardless of if the Asset Name/UUID is included.
Asset UUID: This is simply the UUID of the Asset being reported on Platform.
This is the best way to identify a specific Asset when attempting to interact with it via the API as it is always Unique and never changes for the life of the Asset.
- Asset Version Number: This will result in a separate row for each version available for a given asset, with a column indicating the Version Number for each row.
- If this is not included, the data returned will be for the ‘current’ version.
- Last Editor: This will indicate who the last user was to edit the given version. If Version Number is not requested, then this pertains to the ‘current’ version of the Asset.
- Asset Thumbnail: Either the thumbnailBlobId (for CSV format) or actual thumbnail image (for Excel) in the downloadable report.
Asset Status: The current ‘publish’ status of the Asset.
Asset Type: The type of Asset.
Original File Name: The name of the file that is currently uploaded to the Asset.
While this is called the Original file name, if the file on an Asset was changed at any point this will reflect the current name, not the first file name that was ever uploaded to the Asset.
Embed Link: The shareable viewer link allowing others to see your Asset. This can be entered in an iFrame to embed the viewer in a web page.
These links will be returned for all assets in the report, even if the Asset is not in the
LIVE_PUBLICstate, meaning the links won’t work unless the Asset is published.The link does not change based on Publish state, so if you generate these links on non-LIVE_PUBLIC Assets, then change these Assets to LIVE_PUBLIC, you will not need to re-generate these links.
Description: If an Asset has a description, it will be returned in this column.
Workspace Slug: The slug of a Workspace.
This is a unique identifier for your Workspace and is based on the original name of the Workspace. While Workspace names can be changed, this cannot and is used to identify the Workspace of an Asset in embed links.
Workspace Name: The name of the Workspace an Asset is in.
This is not unique and is generally not a great way to identify Assets via the API.
Workspace UUID: The UUID of the Workspace an Asset is in.
This is a unique identifier and like the slug an easy way to guarantee you’re accessing the right Workspace via the API.
Asset Created Date: The date the Asset was first created.
This does not necessarily correlate to the date when a file was uploaded to the Asset.
Asset Updated Date: The last date the Asset was updated.
While this can correlate to when a file was uploaded, it doesn’t necessarily refer to this. Even reconverting will produce a new updated value.
Tags: A ‘|’ separated list of all tags currently applied to an Asset.
Due to the way tags exist on the Platform, there is no way to present tags in their own columns without producing unreadable sheets.
Attributes: All attributes will be returned in their own columns with the column header being the attribute key.
Ex: If the attribute width exists in a Workspace, there will be a column for width returned with each row containing its value (if it has one).
Project UUID: Returns a ‘|’ separated list of all Project UUID’s the Asset is in.
This only contains the UUID of a Project if the asset is a direct child of the Project, it will not contain the UUID’s of any child or parent Projects.
Project Name: Returns a ‘|’ separated list of all Project Names the Asset is in.
Like with the UUID’s, this only contains Projects the Asset is a direct child of.
Original File Size: The file size of currently associated file.
Despite being labeled original, this will always reflect the most recently uploaded file for the Asset.
Optimized File Size: The file size of the Optimized file.
This will return three columns of data: the optimized file size of the output GLB, FBX, and USDZ.
Original Poly Count: The poly count of the original file.
Refers to the most recently uploaded file.
Optimized Poly Count: The poly count of the Optimized file.
This will return three columns of data: the optimized poly counts for the output GLB, FBX, and USDZ.
Original Vertex Count: The vertex count of the original file.
This will always refer to the most recently uploaded file.
Optimized Vertex Count: The vertex count of the Optimized file.
This will return three columns of data: the optimized vertex counts for the output GLB, FBX, and USDZ.
Optimization Preset: The preset UUID and name (separated by ‘|’) of the Optimization preset for the Asset (if one is applied).
Viewer Preset: The preset UUID and name (separated by ‘|’) of the Viewer preset for the Asset (if one is applied).
- Amazon Publish Status: The current status of the asset in the Amazon Integration.
- Amazon Asins: The marketplace specific Asins stored on the asset within the Amazon Integration.
- Asset Dimensions: The dimensions stored on the asset in the Amazon Integration.
File Format
The final setting for the generated report is the format the file should be provided as. The options are CSV or XLSX, with an additional option to separate each selected Workspace into a separate sheet if the XLSX option is selected.
Uploading Data
The second core feature of this application is the ability to bulk create and/or update the Assets on the Platform with metadata using a CSV or XLSX file. There are a number of caveats to how data upload may work, so be sure to read the following sections to understand the relationships between the various fields and parameters you can set when uploading.
Metadata can be uploaded for multiple Workspaces at a time, however if you are a Workspace level user, you can only operate on one Workspace at a time.
Quick Tips
- Setting up your data with our accepted prefixes will speed up the process.
Mult-sheet
XLSXwill only process the first sheet.- Creating assets requires assetName and either workspaceSlug or workspaceUuid.
- Updating assets requires either assetName or assetUuid and either workspaceSlug or workspaceUuid.
- workspaceSlug and workspaceUuid can be retrieved using the Report functionality.
- workspaceSlug can also be extracted from the url of a workspace: https://platform.vntana.com/org-slug/workspace-slug/products
There is an option to populate blank entries for attribute columns with a placeholder, otherwise these will be left off the asset in question.
- Renaming Assets: it is possible as of version 1.1.1 to use the upload function to rename Assets. In order to do this, you must include both the Asset Name column (with the new names) and the Asset UUID column which will be used to identify the Assets. Using either update type this will set the name to whatever is found in the name column.
- Note: If no UUID is entered for a row this will be treated the same as if the ‘Create Missing Assets’ option is selected, regardless of whether that is deselected.
CSV Template
The first step of the Upload Metadata flow is to download our CSV template. This is optional, however it is recommended if you wish to learn how you can set up your data before loading it in so the application can auto-detect how the data should be used. These prefixes will be explained below in relation to the Data Format step.
Organization Select
Like with the Report Generation flow, you must indicate the Organization you wish to work with.
If the application is unable to authenticate your credentials with the Organization you’ve selected, the selection box will have a red border and an ‘Invalid Organization’ message will appear. The possible reasons for this include:
-
The selected Organization does not have a valid subscription.
-
The attempt to authenticate to the selected Organization wasn’t able to complete due to network issues.
-
Authenticating into an Organization shouldn’t be confused with signing in with email/password or authentication key. This is a part of the API’s auth flow which requires generating a separate token for individual Organizations. If there is an issue with your credentials you would be prevented from getting past the sign-in page.
-
Workspace Select
This step will only be present if you are signed in as a Workspace level user. Due to limitations these users have, you can only upload metadata for a single Workspace at a time and as such must select a single Workspace to work with.
Upload Type
The ‘Upload Type’ will determine how your data is handled upon receipt by the API. There are three main scenarios that an upload can execute which largely boil down to what data is created and what data is retained.
Create Empty Assets
This option will only act to create Assets on the Platform and apply any included metadata such as tags and attributes. This operation requires the Asset Name field to be included in the data so the API will know what the newly created Assets should be called, as well as either the Workspace Slug or Workspace UUID which will be used to identify which Workspace the newly created Assets will be placed in.
A couple of notes on this Operation:
If this option is selected, it will never update existing Assets. Even if an Asset of the same name exists it will ignore it and simply create a new one.
If you wish to set an Optimization and / or Viewer Preset on the created Assets, you can pass either their UUID’s or Name’s with the uploaded data.
Preset Name’s are unique and can be used to identify them, however keep in mind that some may be unique to a specific Workspace (depending on how they were created) so UUID is generally the better option.
Preset UUID’s can be pulled via the Report Generation functionality, but only if there already exist some Assets with these presets applied.
- Versions: The behavior of this upload type is unchanged with relation to versions, a new asset is always created.
Add or Update Metadata
This option and the next (Overwrite) are update methods. Selecting Add or Update will ingest your data and apply it to matching Assets while maintaining old data. This can manifest in a couple ways:
-
Data in the spreadsheet is added to what already exists on the Assets.
-
Tags are simply added.
-
Attributes are added if the key is new, otherwise the previous value of a key is overwritten with what is in the spreadsheet.
-
Single entities like description or presets are overwritten if present in the new data.
-
-
Any data that doesn’t appear in the spreadsheet remains as it was before the update.
-
Old tags are retained on the Asset.
-
Attributes with a key not present in the new data remain.
-
Single entities like description or presets are retained.
This option will update the metadata on the Asset, but it will overwrite the Asset first. This means that only the data present in the uploaded file will exist on the Asset after the update.
-
Tags that don’t exist in the uploaded data will be removed.
-
Attributes which don’t exist in the uploaded data will be removed.
Versions with Add or Update / Overwrite
When including a Version Number column in the data to upload, there are different behaviors to account for based on the Upload Type selection and what exists on Platform.
- Version Exists: The specified version is updated.
- Version Doesn’t Exist: An error is generated for the row.
- Product Not Found: Ignores version value and creates a new version (if user selected creation was permitted).
- Version cell is blank: Creates a new version for review.
If the Version Column is not provided, the behavior of these two upload types is technically the same, it is just executing the updates on the ‘current’ version.
Creating Mismatches
If either of the update options are selected, there is another optional setting you can select which will indicate to the API that you wish for any rows of data (Assets) that do not match an existing Asset on Platform to be created with the metadata provided.
| assetName_Name | workspaceSlug_Workspace | tag_Example Tag |
|---|---|---|
|
File01_01.glb |
samples |
Blue |
|
File01_02.glb |
samples |
Green |
Using the above data as an example, if File01_01.glb matches an Asset on the Platform but File01_02.glb does not, by indicating to create mismatches File01_01.glb will be updated with the tag Blue, while a new Asset called File01_02.glb will be created with the tag Green.
File Select
Once you’ve selected the process for your data, you need to import the data. You can select a CSV or XLSX file for processing. The platform will not process anything but the first sheet in multi-sheet XLSX files. From here, the app will read the data and pull out the column headers for mapping on the next page.
Data Confirmation
The final step in the upload process is to confirm your data. This page will present the headers from your selected file with options for the columns data type. If you’ve made use of the prefixes in your file, the application will pick these up and pre-populate the columns with their prefix-determining data type. Simply add/remove any that you need, and you can begin the upload process when everything is set.
Required Data Types
Depending on your selection for the Upload Type, there will be some requirements for the headers you’ve indicated. Refer back to those sections of this document to see these requirements.
Attribute Placeholders
If you’ve indicated any columns are to be used as an Attribute, an option will show up below the table. This option asks whether you wish to auto-populate any empty values for the Attribute in question, meaning if a row of data in your file doesn’t have a value set for that column then the Attribute will be populated with a placeholder of ‘-‘ on the Platform. If this option is not selected, then the Attribute in question will simply be left off the Asset that row corresponds to.
Completed Page
Once you press the ‘Upload’ button, your file will be uploaded and you will be shown the Completed Page. This page signifies that the file has been uploaded, however your data is still being processed. You will be able to see a status for the processing and if there are any errors, an error report will become available to download. This report will contain an error for any row that wasn’t processed successfully, indicating the row number and error. These errors may not necessarily be obvious as to their cause, so don’t hesitate to reach out to our support with the file and we can investigate why they happened.
Possible States
Success
Completed with Errors
Not Completed
Integration Data
Though this is a separate workflow in the Metadata app, it shares a lot of the same expectations and behaviors as the regular Upload workflow. Using this will allow you to bulk add data to your assets specific to integrations.
Quick Tips
- Workspace isn’t important unless you only have Workspace level user access.
- Unless you wish to manually enter the dimensions for your assets, do not include the dimension columns in your data. The presence of any values for any one of these columns will indicate to the BE for that row that the dimensions shouldn’t be auto-generated.
- The columns in question are for Units, Height, Width, and Length.
- The only required columns are assetUuid, integrationType, and at least one integrationAsin column.
- Currently integrationType should just have AMAZON for each row, the downloadable template pre-fills this for you.
- The auto-generation of dimensions will not necessarily be seen on all assets as quickly as any uploaded ASIN’s. This is a cloud process similar to optimization that will be queued up for each of the assets. It is a very quick process, but depending on how many rows of data you are running, you will likely see a delay from the first to the last completion.
- Just like the regular upload flow, there is a row count of 1000 on the uploaded data. Please break you spreadsheet up into more than one upload if you need to process more than 1000 rows.
Organization Select
As with the regular Upload, you must select the organization you wish to upload your data to.
Workspace Select
Unlike with the regular Upload, Workspace is generally irrelevant to this process and therefor is only needed if you only have Workspace level access. This also means that if you have workspace level access, then the only data that’ll be impacted with your upload would be the data contained in the workspaces you can access.
Generate Template Report
It is highly recommended that you utilize the template report functionality to save time when creating you spreadsheet to upload ASINs. This feature will download a report to your machines downloads folder containing the following data:
- Asset Name
- Asset Uuid
- Workspace Slug
- Integration Type – this should contain the value AMAZON for every row of data you are uploading.
- Integration ASINs – a separate column for each Amazon marketplace, i.e. United States or Canada.
The Asset Name and Workspace Slug columns are not necessary for the upload to work but are just meant to help when mapping your ASINs in this file.
When generating the report, you will have the ability to select which workspaces and marketplaces you’d like to include.
The ASIN columns require exact column headers for the marketplace the ASINs are associated with. The downloadable template will include a column for all available marketplaces with the correct column headers. You do not need to leave in the ASIN columns you aren’t setting ASINs for.
An example header for ASINs is integrationAsin_United States where integrationAsin_ is optional and indicates to the app what data the column contains (w/o this you have to manually set it to an ASIN column), and United States is the exact name of the marketplace as recognized by Amazons API.
| Asset Name | assetUuid_UUID | Workspace Slug | integrationType_Type | integrationAsin_United States |
| Asset 1 | 1234 | demo | AMAZON | B00000000 |
| Asset 2 | 4321 | demo | AMAZON | B00000000 |
The above example shows the data used for uploading ASINs to the United States marketplace.
Upload Type
Unlike the regular upload process, this workflow requires your assets already exist, and as such there are only two options for the upload type.
- Add or Update – RECOMMENDED This option will simply update the asset’s integration data without overwriting any data that isn’t passed.
- Overwrite – This option will wipe the asset of integration data and is only used when you want to clean an asset’s integration data and only apply new data. For example, if in your organizations Amazon integration, you have two marketplaces linked: Canada and United States. If an asset has an ASIN assigned for both of these and
Overwriteis selected where only an ASIN is passed for Canada, the updated asset would only have the new Canada ASIN. The United States marketplace would be empty. (Dimensions would also regenerate, but unless the model changed these should be the same as before).
File Select
This is the same as the regular upload flow, you can select a CSV or XLSX file containing your data. The template that is downloaded is a CSV.
Data Confirmation
Just like in the regular data upload flow, you must confirm the data you are uploading. This page will present the columns in your spreadsheet with any pre-determined data types assigned depending on whether any prefixes are utilized. Double check each column is assigned to the correct data type or assign them manually.
Keep in mind that if you are not utilizing prefixes or the column headers provided by the template, the ASIN columns must have the exact name as the header, i.e. United States.
Completed Page
This behaves the same as the regular upload completed page. The status of the upload will be shown, if there are any errors with any rows of data, at the end an error report will be available to download which reflects these.