Bulk Create or Edit Glossary Terms

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Note

Document Hubs are Alation’s new documentation feature set for glossaries and terms. Document Hubs are available for public preview starting in 2024.1.

  • See Document Hubs for help using Document Hubs.

  • See Documentation for more information about how Document Hubs are related to Glossaries and Terms.

You can use the Bulk Utility to create and edit glossary terms, as well as soft-delete them. An important use of the soft-delete feature is when you want to re-assign terms from one glossary to another. For this case, you need to first soft-delete the terms, then re-create them in the new glossary. You can use the Bulk Utility for both steps.

Bulk Create Glossary Terms

To create a set of glossary terms, do the following:

  1. Ensure that the Feature Flags Glossary Terms GA and Bulk Utility (Beta) are both enabled. See Feature Configuration.

  2. If you don’t have an existing Term Type template for the terms you are creating, create one as described in Manage Templates.

  3. Manually create a single term of the desired Term Type.

  4. Using full-page search, search for your new term.

  5. Filter search results for terms, that is, select the Documentation dropdown and then select Terms.

    ../../../_images/BulkUtility_TermsFilter.png

  6. Under Saved Searches, click the + button (Save as New Search). Remember the name you use to save the search.

  7. Navigate to the Bulk Utility either from the Admin Settings menu or by appending /bulk-utility/ to the catalog base URL. If you already have the Bulk Utility page open, click Reset. Your saved search should appear as a button within the 1-Download field.

  8. Click the button to generate an editable spreadsheet. This file, along with a more human-readable reference version, contains columns for all the fields included in the Term Type. Both files are packaged into a zip file for download. Once the zip file is prepared, it should appear in the 1-Download field as a row in the table at the bottom of the field:

    ../../../_images/BulkUtility_DownloadZip.png

  9. Click the link in the file column to download the zip file.

  10. Unzip the zip file and open the included file with the name beginning “use_this_for_upload”.

  11. Add a row for each Term to be created, using the manually-created Term as a template. Leave the id column blank, to indicate you want new Terms objects to be created.

  12. Delete the row containing the Term you created manually. (This is optional; if you make no changes to it, leaving it in the file should have no effect.)

  13. Save the file.

  14. On the Bulk Utility page, under Attachments, delete any existing attachments by hovering over them one at a time and clicking the X that appears beside them.

  15. Click the + icon to add your saved file.

  16. Click the Upload button in the 2-Upload field. A new browser tab opens, and once the upload is complete you are directed back to the Bulk Utility article.

    Warning

    If the file is large, it may appear that the utility is not working. Do NOT click Upload more than once. If you believe the process is stuck or unresponsive, contact Alation Support before re-uploading to avoid any unwanted side effects.

    Note

    After each upload, download the associated “feedback file” under Attachments in the Bulk Utility article, with a name of the form <first-8-letters-of-username>-<4-random-characters>.xlsx.

Bulk Edit Glossary Terms

To edit a set of glossary terms, do the following:

  1. Navigate to the Alation search bar and press Enter to open the full-page search.

    ../../../_images/BulkUtility_SearchResults.png

  2. Filter search results for Terms, that is, select the Documentation dropdown and then select Terms.

    ../../../_images/BulkUtility_TermsFilter.png

  3. Choose additional filters to limit the export to Terms you’d like to edit, then save your search by clicking the Save Search button (+) in the Saved Searches area of the left sidebar. Remember the name of your Saved Search as you will use it in the Bulk Utility.

    Warning

    If there are typos in your search query, Alation tries to correct for them and will often return results with the corrected spelling. However, the bulk utility does not make this same correction. You should therefore verify that the search results you are seeing are for the term or terms in your search query. Check the top of your search results—if you see a message similar to the following, you should correct your query:

    ../../../_images/Articles_ResultsForDiffTerm.png

  4. Under Saved Searches, click the + button (Save as New Search). Remember the name you use to save the search.

  5. Navigate to the Bulk Utility either from the Admin Settings menu or by appending /bulk-utility/ to the Alation base URL. If you already have the Bulk Utility page open, click Reset. Your saved search should appear as a button within the 1-Download field.

  6. Click the button to generate an editable spreadsheet. This file, along with a more human-readable reference version, contains columns for all the fields included in the Term Type. Both files are packaged into a zip file for download. Once the zip file is prepared, it should appear in the 1-Download field as a row in the table at the bottom of the field:

    ../../../_images/BulkUtility_DownloadZip.png

  7. Click the link in the file column to download the zip file.

  8. Unzip the zip file and open the included file with the name beginning “use_this_for_upload”.

  9. Edit the terms as desired. Do not remove or edit the ID column to ensure the term IDs are preserved during the edit.

    Note

    If your Term Type includes an Object Set with permitted type Article and its column shows article names, replace each name with the article’s ID, formatted as text (that is, with a leading single-quote (‘)). For example, if the article’s ID is 2133, enter it as '2133 in the Object Set column. (The article ID appears before the article title in the article page URL—for example, myalationinstance.com/article/2133/mp1.)

  10. Save the file.

  11. On the Bulk Utility page, under Attachments, delete any existing attachments by hovering over them one at a time and clicking the X that appears beside them.

  12. Click the + icon to add your saved file.

  13. Click the Upload button in the 2-Upload field. A new browser tab opens, and once the upload is complete you are directed back to the Bulk Utility article.

    Warning

    If the file is large, it may appear that the utility is not working. Do NOT click Upload more than once. If you believe the process is stuck or unresponsive, contact Alation Support before re-uploading to avoid any unwanted side effects.

    Note

    After each upload, download the associated “feedback file” under Attachments in the Bulk Utility article, with a name of the form <first-8-letters-of-username>-<4-random-characters>.xlsx.

Soft-Delete Glossary Terms

To soft-delete glossary terms:

  1. Open the file you originally downloaded for bulk creation.

  2. Add a column action containing the word delete for all rows containing glossary terms you want to delete.

  3. Save the file.

  4. On the Bulk Utility page, under Attachments, delete any existing attachments by hovering over them one at a time and clicking the X that appears beside them.

  5. Click the + icon to add your saved file.

  6. Click the Upload button in the 2-Upload field. A new browser tab opens, and once the upload is complete you are directed back to the Bulk Utility article.

  7. Spot check that your action was successful.