Usage

This guide provides comprehensive instructions for using the Excel Add-in to interact with the Data Catalog, import assets, enrich metadata, and synchronize updates.

Authentication

Once the add-in has been properly configured and installed (see Installation Guide), access the Data Catalog Excel Add-in and perform login by entering the Data Catalog credentials. Upon successful login, you'll see your profile information in the Profile page.
You can logout at any time from this panel.

Pull Assets Metadata

The Pull Assets page allows you to import metadata from the Data Catalog into your Excel worksheet.

Search and Import

• Search Bar: Use the search functionality to find specific assets in the Data Catalog. The search returns System of Records (SoRs) and Tables present in your Data Catalog. Enter keywords in the search bar to find relevant assets.
• Checkbox Selection: Select individual assets or multiple assets using checkboxes
• Import: Click the Pull Assets button to import selected metadata. Each asset appears as a row in your Excel worksheet with all associated metadata

Worksheet structure

Once imported, each row that represents an asset contains various metadata fields as columns.

Read-Only Fields (Values in these columns cannot be modified):

• assetType - Type of asset (SoR, Table, Column)
• catalogName - Data Catalog name (if present, depending on the provider type of the asset)
• schema - Database schema name (if present, depending on the provider type of the asset)
• sorName - System of Record name
• tableName - Table name
• columnName - Column name

Editable Fields (Values in these columns cannot be modified):

• description - Asset description
• tags - Asset tags
• relatedTerms - Business Glossary terms associated to the asset, as a comma-separated list of <Term type>/<Term> pairs
• Custom properties (customProp1, customProp2, etc.) - Each custom property configured in the Data Catalog appears as a separate column in the worksheet, maintaining its specific data type as defined in the Data Catalog. For more information about custom properties, see the Custom Properties documentation.

Asset Navigation

Once navigating in the Pull Assets page, it is possible to click on an element of the search list in order to enter its detail page.

System of Records Details:

• Click on any SoR to view detailed information
• General Tab: Shows basic information and metadata
• Tables Tab: Lists all tables within that SoR
• Import Options:
  • Pull all tables: Imports all tables within the SoR
  • Pull all columns: Imports all columns within the SoR
  • Pull tree: Imports the SoR, all its tables, and all columns within those tables

Table Details:

• Click on any table to view detailed information
• General Tab: Displays table-specific information
• Columns Tab: Shows all columns within the table
• Import Options:
  • Pull all columns: Imports all columns within the table
  • Pull tree: Imports the table, and all columns within the table

Paste URL

For advanced use cases, you can import assets, or Business Glossary terms, based on Data Catalog search URLs:

1. Perform an advanced search in the Data Catalog interface, either among assets or among Terms
2. Copy the URL from your browser
3. Paste the URL in the Paste URL section of the add-in
4. Click Pull to import all assets or terms matching that search criteria

This feature is particularly useful for importing assets or terms with specific metadata, tags, or other advanced search conditions.

Push Assets Metadata

The Push Assets functionality synchronizes your enriched metadata back to the Data Catalog.

Pre-Push Configuration

Rows Selection

• Select specific rows if you only want to sync a subset of assets
• Leave unselected to sync all rows in the worksheet

Columns Selection

Once the rows have been chosen, you can also select which metadata to synchronize back to the Catalog. The column selection feature allows you to choose which metadata columns will be synchronized, with hidden columns in Excel being automatically unchecked. You have the flexibility to manually deselect any columns you want to exclude from the synchronization process.

relatedTerms is selectable among these columns as well, allowing to synchronize back to the Data Catalog the Business Glossary terms associated to the selected assets.

Validation Process

Once the Push Assets action is triggered from the proper button, the add-in begins a pre-push validation process that ensures data integrity before synchronization. The system performs structure validation by verifying column names and formats, checking for required asset identifiers, and validating custom property types and values to ensure compatibility with the Data Catalog schema.

Synchronization

Once validation passes, row-by-row the synchronization begins. A progress feedback is provided throughout the process, and a completion notification confirms successful synchronization.

Generated Errors and Backup Sheets

During the push process, two additional sheets are automatically created:

Error Logs Sheet: The Error Logs Sheet documents all errors encountered during synchronization and provides specific row references with detailed error descriptions. This guides users toward resolution of any issues that may arise.

Backup Sheet: The Backup Sheet contains the original state of assets before synchronization, serving as a valuable reference for comparison and rollback purposes if needed. This sheet helps users identify what changes were made during the synchronization process.

Business Glossary Terms

Similarly to data assets, Business Glossary terms can be pulled into, enriched within, and pushed back from an Excel worksheet, using the same Pull metadata ribbon group.

Pull Business Glossary Terms

Click the Select Terms button to open a panel listing the terms defined in the glossary, searchable by name; each entry also shows its Term Type. Select one or more terms and click Pull terms to import them into the worksheet. Alternatively, terms matching an advanced search performed in the Data Catalog interface can be imported via Paste URL.

Terms Worksheet Structure

Once imported, each row represents a term and contains the following editable columns:

• Term type - the term's Term Type
• Term - the term's name
• Description - the term's description
• Tags - the term's tags
• Mark for delete - checkbox column; ticking it will delete the term from the Data Catalog on the next push
• Related terms - comma-separated list of related terms, each expressed as <Term type>/<Term>
• Custom properties (CP1, CP2, etc.) - each custom property applicable to Terms appears as a separate column, maintaining its specific data type as defined in the Data Catalog

caution

A term is uniquely identified by the combination of Term type and Term. As a consequence, modifying either of these two fields on an already pulled row before pushing will not rename the existing term: it will instead result in the creation of a brand new one. To rename an existing term, use the Data Catalog UI instead.

Push Business Glossary Terms

Once terms have been enriched, the Push Metadata button starts the same Validation Process and Synchronization flow already described for assets. The Push metadata panel lets you choose which columns to synchronize, including Related terms.

info

During a single push, new terms are created first, terms marked via Mark for delete are deleted next, and finally the remaining rows are updated. This fixed order (create, then delete, then update) ensures that, should an error occur on a specific row, the outcome remains consistent for every other row.

Tips on Worksheet Arrangement

Given that the term relations are always bidirectional, some worksheet arrangements are handled correctly by the push even though they might look inconsistent at first glance:

• Referencing a term before its own creation row: if a term listed further down the worksheet (e.g. row 10) is already referenced in the Related terms column of a term listed higher up (e.g. row 3), the push still succeeds. Since new terms are created first, every new term referenced anywhere in the worksheet already exists by the time relations are applied.
• Declaring a relation on only one side: if term A's Related terms value includes B, but B's own row does not list A back, this is not an error and nothing needs to be fixed. Relations between terms are always bidirectional: after the push, pulling the terms again will show A among B's related terms as well, even though it was never explicitly set on B's row.
• Deleting a term that is still referenced elsewhere in the worksheet: if term A is marked via Mark for delete, and another row in the same worksheet (term B) lists A as a related term, the push still succeeds. A is deleted before the remaining rows are updated, and it is automatically removed from B's related terms as well, without requiring B's row to be changed.

Working with CSV Exports

The add-in is fully compatible with CSV files previously exported from the Data Catalog see Export documentation. Thus, in case stakeholders need to work offline or prefer to use CSV files for metadata enrichment, they can follow this workflow:

1. Import CSV: Load previously exported CSV files into Excel
2. Compatible Format: The CSV structure matches the add-in's pull format
3. Enrich Data: Perform bulk enrichment on the imported data
4. Push Updates: Use the add-in to synchronize changes back to the Data Catalog

When offline work is complete, ensure you follow the data integrity rules to allow push validation to pass when synchronizing back to the Data Catalog from the Excel add-in.

Best Practices and Recommendations

During Import

• Avoid making changes to the worksheet while assets are being imported
• Wait for the import process to complete before beginning enrichment

Data Integrity

• Never modify read-only columns - Changes will not be synchronized and may cause errors
• Don't add extra columns - This will cause synchronization failures
• Avoid empty rows - Remove any blank rows from your worksheet

You can reorder rows, but avoid leaving gaps

During Synchronization

• Don't start multiple sync processes simultaneously
• Avoid worksheet changes while synchronization is in progress
• Review error logs carefully if synchronization fails

Custom Property Management

• Ensure custom property types match the values you're entering
• If changing custom property types, update them in the Data Catalog first
• Use the Data Catalog interface to modify custom property definitions before bulk updates

Troubleshooting Common Issues

Synchronization Errors

Asset Not Found:

• Occurs when read-only identifier fields are modified
• Solution: Restore original asset identifiers or remove invalid rows

Type Mismatch:

• Happens when cell values don't match custom property types
• Solution: Correct the cell value or update custom property type in Data Catalog

Invalid Format:

• Cell format does not comply with expected data type
• Solution: Adjust cell format to match custom property requirements

Term Treated as New:

• Occurs when Term type or Term of an already pulled row is modified before pushing, since these two fields together uniquely identify a term
• Solution: To rename an existing term, use the Data Catalog UI instead; only edit the other columns from Excel