Resources

Metadata App

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.0.0

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. 

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

Using the Generate Report option of the application, a CSV or XLSX file can be downloaded containing select data from your Assets on the Platform. This functionality can be accomplished by Organization level users as well as Workspace level users, however the functionality will be more limited as a Workspace level users.
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
Upon selecting the Generate Report option from the applications main menu, the first task will be to select the Organization for which you wish to generate a report. Most users will likely only have one Organization to select from, however users can be in multiple Organizations so the selection option is there.
Invalid Organization

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
The final page in this flow has two sections which determine what data from the Platform to include and the format to download it in.
Data Fields

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 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_PUBLIC state, 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).

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 XLSX will 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.
  • There is an option to populate blank entries for attribute columns with a placeholder, otherwise these will be left off the asset in question.

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.

Invalid Organization

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.

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.

Overwrite Metadata

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.

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

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.