Manage Document Hubs¶
Alation Cloud Service Applies to Alation Cloud Service instances of Alation
Customer Managed Applies to customer-managed instances of Alation
Available in public preview from Alation version 2024.1
Important
You are viewing documentation for Classic Alation.
This page has information about best practices for Document Hubs and how to manage Document Hubs.
For help with other Document Hub tasks, see the following pages:
Best Practices for Document Hubs¶
This section describes best practices for using Document Hubs.
Define Types of Content¶
Document hubs should be based on a type of content rather than business units. Basing your hubs on content type ensures that hubs are broadly applicable across your business and helps limit the number of hubs that appear in the catalog navigation. If you have too many document hubs, the navigation and search experience become too crowded, making it harder to find relevant content and making the catalog harder to use.
Once you’ve defined your content types, you can use folders to separate documents by business unit and govern who has access to specific folders based on their business unit.
For example, you may need to document definitions for your company’s metrics. Since metric definitions could be useful to all your business units, you create a document hub and name it Metrics. Within the Metrics document hub, you create a folder for each business unit that needs to define metrics—Finance Metrics, R&D Metrics, and so forth. If desired, you can restrict the visibility of each folder to user groups belonging to the appropriate business unit. Within their respective folders, each business unit can now create documents defining their own metrics.
As another example, you may need documentation for business practices. In this context, you might label folders as Business Plans, Go To Market Plans, or Data Applications. These documentation types could be used across multiple business units.
Make Names Meaningful¶
Document hubs all work the same, but you can assign customized names to your hubs, folders, and documents based on your business needs. These custom names appear in the Alation navigation and search features. Ensure that:
Names are meaningful for your organization
Names are unique across all document hubs
For example, if a document hub is meant to hold metric definitions, you could name your document hub Metrics. Your folders could be named after business units like Finance Metrics or R&D Metrics, or they could be named after lines of business or other categories that you define.
Create a Document Hub¶
You must be a Catalog Admin or Server Admin to create document hubs. Document hubs are created in a draft state and aren’t visible to regular users until you publish them. Document hubs can’t be deleted, but they can be unpublished (starting in 2024.1.2) or renamed and repurposed.
To create a document hub:
Click on the Settings icon in the top right corner.
Catalog Admins: A dropdown menu appears. Click Customize Catalog.
Server Admins: The Admin Settings page appears. Under the Catalog Admin section, click Customize Catalog.
Click the Custom Templates tab. The Document Hubs section will appear on the left. You may have to scroll down to see it.
Click the plus icon next to the Document Hubs title.
In the Create Document Hub dialog box, enter the document hub’s Name.
Click the Create button. The document hub editor appears, and a preview of the hub is shown at the bottom of the page. The hub is in a draft state at first and won’t be visible to regular users until you publish it.
Customize the names of the hub’s folder and documents. Click on the pencil icon next to the default folder and document names, then enter a singular and plural version of the name.
Note
These names appear in the left navigation and search. As a best practice, they should be unique and meaningful for your organization and match the intended purpose of the document hub. For example, you could call folders groups, applications, categories, or projects. You could call documents metrics, policies, or help topics—whatever helps your users understand their purpose.
Customize the folder and document templates for this document hub. You can add custom fields and rearrange the fields to suit your needs. Folder and document templates are configured in a similar manner to data object templates. You can add, rearrange, and remove fields, but the template is only associated with this specific document hub.
You can add multiple document templates to your hub by clicking the plus icon next to the Document Templates heading.
Once you’ve added more templates, you can change the default document template if desired. Click the drop-down menu next to Default document template to choose a default template for new documents.
You can preview Document Hub by clicking the Visit Hub link. With the hub page open, you can create folders and documents. At this point, when a Document Hub is not yet published, only admins can view it from this link.
When you’re ready for your users to see the document hub, click the Publish button.
Important
In 2024.1.1 and earlier, publishing is permanent. You can’t unpublish a published document hub, but you can repurpose the hub by renaming it.
Starting in 2024.1.2, you can unpublish a document hub.
The document hub will become visible to all users in Alation as long as the Document Hubs 2: Show Glossary Hub feature flag has been enabled. See Enable Document Hubs, Glossaries, and Terms for more information on feature flags.
Once the document hub is published, you can adjust the default table view and create folders as desired. Then users with the Steward role can edit folders and create documents in the new document hub.
Once the document is published, Stewards can now create folders and documents in the new document hub.
Set the Default Table View¶
You can set the default view for the documents table in your document hubs. As part of the default view, you can choose which columns are visible by default, along with their order. Settings for each document hub must be configured separately.
You must have a Catalog Admin or Server Admin role to set the default view for document tables.
To set the default view for the document table:
Open a document hub catalog page.
Add, remove, and reorder columns on the document table as desired. See Add, Remove, and Rearrange Columns for help doing this.
Above the documents table, a Save Table View for Everyone section will appear. You can now save your settings as the default for the document hub catalog page, the hub’s folder catalog pages, or both.
To apply your column settings as the default for the document hub catalog page, click Save.
To apply your column settings as the default for all the folders in the document hub, click Apply view for all Folders.
Rename a Document Hub¶
You must have a Catalog Admin or Server Admin role to rename a document hub.
To rename a document hub:
Click on the Settings icon in the top right corner.
Catalog Admins: A dropdown menu appears. Click Customize Catalog.
Server Admins: The Admin Settings page appears. Under the Catalog Admin section, click Customize Catalog.
Click the Custom Templates tab. The Document Hubs section will appear on the left. You may have to scroll down to see it.
Click the name of the hub you want to rename. The hub details will appear on the right.
Edit the name of your hub in the Hub & Navigation Name field.
Click Save.
Unpublish a Document Hub¶
Starting in 2024.1.2, you can unpublish a document hub after it’s been published. You must have a Catalog Admin or Server Admin role to unpublish a document hub. You can’t unpublish the built-in Glossary document hub.
Unpublishing a document hub removes it from the catalog navigation, the full search page, and anywhere else it was available. It will still be visible in draft mode to users with a Catalog Admin or Server Admin role on the Custom Templates tab of the Customize Catalog page.
To unpublish a document hub:
Click on the Settings icon in the top right corner.
Catalog Admins: A dropdown menu appears. Click Customize Catalog.
Server Admins: The Admin Settings page appears. Under the Catalog Admin section, click Customize Catalog.
Click the Custom Templates tab. The Document Hubs section will appear on the left. You may have to scroll down to see it.
Click the name of the hub you want to unpublish. The hub details will appear on the right.
Click the Unpublish button near the top right. The hub will be unpublished immediately and go into draft mode. You can continue configuring the hub as needed and publish it again later.