Manage Documents

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 how to manage documents in a Document Hub. You can create, edit, and configure documents, add and remove documents from folders, change access to documents, and delete documents.

Create a Document

You must have a Steward role or higher to create documents in a document hub. When you create a document, you become its owner and will have permanent view and edit access to it.

Documents must belong to at least one folder and can belong to multiple folders. You can create a document in two ways:

• Create a Document via a Document Hub. You can select one or more folders during the creation process.

• Create a Document via a Folder. The document will automatically belong to that folder. You can add it to more folders afterward.

Create a Document via a Document Hub

To create a document from a document hub:

1. Navigate to the catalog page of the document hub you want the document to belong to. You can do this through the left navigation or by searching.

2. Click the + Create <Document Name> button on the lower half of the page. The name used on the button is the name Alation admins gave to document objects in this hub’s settings. As an example, if this document hub’s documents are named Metrics, the button will say + Create Metric.

3. Optionally, if you want the document to have a different template than the default, click the drop-down menu under Select an initial template for this <Document> and select a template.

4. Select one or more folders for the document to belong to. Once you select a folder, the Create button is enabled.

5. Click the Create button.

6. If the ability to create documents is controlled by a workflow, the document will open as a pending draft that must be submitted for review. If there is no workflow, the document is created immediately.

7. You can now edit and configure the document.

8. If the document is in the pending draft state, click Submit for Review. The document status changes to Under Review. Click the View Review Status button to see the current status of the review.

1. Navigate to the catalog page of the document hub you want the document to belong to. You can do this through the Apps menu or by searching.

2. Click the + Create <Document Name> button on the lower half of the page. The name used on the button is the name Alation admins gave to document objects in this hub’s settings. As an example, if this document hub’s documents are named Metrics, the button will say + Create Metric.

3. Optionally, if you want the document to have a different template than the default, click the drop-down menu under Select an initial template for this <Document> and select a template.

4. Select one or more folders for the document to belong to. Once you select a folder, the Save button is enabled.

5. Click the Create button.

6. If the ability to create documents is controlled by a workflow, the document will open as a pending draft that must be submitted for review. If there is no workflow, the document is created immediately.

7. You can now edit and configure the document.

8. If the document is in the pending draft state, click Submit for Review. The document status changes to Under Review. Click the View Review Status button to see the current status of the review.

Create a Document via a Folder

To create a document from a folder:

1. Navigate to the catalog page for the folder you want the document to belong to. You can do this through the left navigation or by searching.

2. Click the + <Document Name> button. The name used on the button is the name Alation admins gave to document objects in this hub’s settings. As an example, if this document hub’s documents are named Metrics, the button will say + Metric.

3. Click Create New <Document>. A dialog box appears.

4. Optionally, if you want the document to have a different template than the default, click the drop-down menu under Select an initial template for this <Document> and select a template.

5. Click the Create button.

6. If the ability to create documents is controlled by a workflow, the document will open as a pending draft that must be submitted for review. If there is no workflow, the document is created immediately.

7. You can now edit and configure the document.

8. If the document is in the pending draft state, click Submit for Review. The document status changes to Under Review. Click the View Review Status button to see the current status of the review.

1. Navigate to the catalog page for the folder you want the document to belong to. You can do this through the Apps menu or by searching.

2. Click the + <Document Name> button. The name used on the button is the name Alation admins gave to document objects in this hub’s settings. As an example, if this document hub’s documents are named Metrics, the button will say + Metric.

3. Click Create New <Document>. A dialog box appears.

4. Optionally, if you want the document to have a different template than the default, click the drop-down menu under Select an initial template for this <Document> and select a template.

5. Click the Create button.

6. If the ability to create documents is controlled by a workflow, the document will open as a pending draft that must be submitted for review. If there is no workflow, the document is created immediately.

7. You can now edit and configure the document.

8. If the document is in the pending draft state, click Submit for Review. The document status changes to Under Review. Click the View Review Status button to see the current status of the review.

Edit or Configure a New Document

To edit or configure a new document:

1. Click the default title at the top of the page and enter the document’s title.

2. Click the Edit button to the right of Description and enter a description. This is the main content of the document.

3. To control who can access this document, click the three dots in the upper right, then click Access Settings. Choose the desired access level and assign users if needed. See Document Hub Permissions for more information about access levels.

4. To change which folders the document belongs to, click the three dots in the upper right, then click Membership Settings.

5. Modify any other fields associated with the document as desired. Changes are saved automatically. The fields that are available depend on the document’s template and field-level permissions.

1. Enter the title at the top of the page.

2. Click the Edit button to the right of Description and enter a description. This is the main content of the document.

3. To control who can access this document, click Manage in the upper right, then click Access Settings. Choose the desired access level and assign users if needed. See Document Hub Permissions for more information about access levels.

4. To change which folders the document belongs to, click Manage in the upper right, then click Membership Settings.

5. Modify any other fields associated with the document as desired. Changes are saved automatically. The fields that are available depend on the document’s template and field-level permissions.

Add an Existing Document to a Folder

To add an existing document to a folder, you must be the folder’s creator, a Catalog Admin, a Server Admin, or a Steward, Composer, or Source Admin with edit access to the folder.

Documents can belong to multiple folders within the same document hub.

There are several ways to add an existing document to a folder:

• Add a Document to a Folder via the Document

• Add a Document to a Folder via the Folder

• Add a Document to a Folder via the Document Hub

Add a Document to a Folder via the Document

To add a document to a folder via the document catalog page:

1. Navigate to the document’s catalog page. You can do this through the left navigation or by searching.

2. Click the three dots in the upper right corner and select Membership Settings. The Add / Remove <Folder> dialog opens.

3. Select the checkbox to the left of the folder(s) you want the document to be added to. If needed, use the filter box at the top of the list to search for folders, or use the paging controls at the bottom of the list.

   Note

   If you can’t select a checkbox, that means you only have view access to that folder and won’t be able to add the document to it.

4. Click Save. The document will be added to the folders you selected.

Add a Document to a Folder via the Folder

To add a document to a folder via the folder catalog page:

1. Navigate to the catalog page for the folder you want the document to belong to. You can do this through the left navigation or by searching.

2. Click the + <Document> button. The name used on the button is the name Alation admins gave to document objects in this hub’s settings. As an example, if this document hub’s documents are named Metrics, the button will say + Metric.

3. Click Add Existing <Document>. A dialog box appears.

4. Enter a search term to find the existing document, or scroll through the list to find it.

5. Select the document you want to add. It will immediately be added to the list of documents in this folder.

Add a Document to a Folder via the Document Hub

To add a document to a folder via the document hub catalog page, through the document:

1. Navigate to the catalog page of the document hub you want the document to belong to. You can do this through the left navigation or by searching.

2. Find the document in the list of documents on the lower half of the page. You can do this by entering a search term at the top of the document list or using the paging controls at the bottom of the document list.

3. Click the three dots to the right of the document and select Membership Settings. The Add / Remove <Folder Name> dialog opens.

4. Select the checkbox to the left of the folder(s) you want the document to be added to. If needed, use the filter box at the top of the list to search for folders, or use the paging controls at the bottom of the list.

   Note

   If you can’t select a checkbox, that means you only have view access to that folder and won’t be able to add the document to it.

5. Click Save. The document will be added to the folders you selected.

To add a document to a folder via the document hub catalog page, through the folder:

1. Navigate to the catalog page of the document hub you want the document to belong to. You can do this through the left navigation or by searching.

2. Find the destination folder on the upper half of the page. You can do this by entering a search term at the top of the folder list or using the paging controls at the bottom of the folder list.

3. Click the three dots to the right of the destination folder and select Link <Document> to <Folder>.

4. Enter a search term to find the existing document, or scroll through the list to find it.

5. Select the document you want to add. It will immediately be added to the list of documents in this folder.

Remove a Document from a Folder

Removing a document from a folder disassociates it from that folder. The document may still belong to other folders in the hub and will still belong to the document hub even if it doesn’t belong to any folders.

To remove a document from a folder, you must be the folder’s creator, a Catalog Admin, a Server Admin, or a Steward, Composer, or Source Admin with edit access to the folder.

There are several ways to remove a document from a folder:

• Remove a Document from a Folder via the Document

• Remove a Document from a Folder via the Folder

• Remove a Document from a Folder via the Document Hub

Remove a Document from a Folder via the Document

To remove a document from a folder via the document catalog page:

1. Navigate to the document’s catalog page. You can do this through the left navigation or by searching.

2. Click the three dots in the upper right corner and select Membership Settings. The Add / Remove <Folder> dialog opens.

3. Deselect the checkbox to the left of the folder(s) you want to remove the document from. If needed, use the filter box at the top of the list to search for folders, or use the paging controls at the bottom of the list.

   Note

   If you can’t deselect a checkbox, that means you only have view access to that folder and won’t be able to remove the document from it.

4. Click Save. The document will be removed from the folders you deselected.

Remove a Document from a Folder via the Folder

To remove a document from a folder via the folder catalog page:

1. Navigate to the catalog page of the folder the document belongs to. You can do this through the left navigation or by searching.

2. Find the document in the folder. You can do this by entering a search term at the top of the document list or using the paging controls at the bottom of the document list.

3. Click the three dots to the right of the document and select Remove from <Folder Name>.

Remove a Document from a Folder via the Document Hub

To remove a document from a folder via the document hub catalog page:

1. Navigate to the catalog page of the document hub the document belongs to. You can do this through the left navigation or by searching.

2. Find the document in the list of documents on the lower half of the page. You can do this by entering a search term at the top of the document list or using the paging controls at the bottom of the document list.

3. Click the three dots to the right of the document and select Membership Settings. The Add / Remove <Folder Name> dialog opens.

4. Deselect the checkbox to the left of the folder(s) you want to remove the document from. If needed, use the filter box at the top of the list to search for folders, or use the paging controls at the bottom of the list.

   Note

   If you can’t deselect a checkbox, that means you only have view access to that folder and won’t be able to remove the document from it.

5. Click Save. The document will be removed from the folders you deselected.

Change Access to a Document

To change who has access to a document, you must be the document’s creator, a Catalog Admin, a Server Admin, or a Steward, Composer, or Source Admin with edit access to the document.

1. You can modify permissions from the document hub or the document itself:

   1. From the document hub:

      1. Navigate to the catalog page of the document hub the document belongs to. You can do this through the left navigation or by searching.

      2. Find the document in the list of documents on the lower half of the page. You can do this by entering a search term at the top of the document list or using the paging controls at the bottom of the document list.

      3. Click the three dots to the right of the document and select Access Settings. The access dialog opens.

   2. From the document itself:

      1. Navigate to the document’s catalog page. You can do this through the left navigation or by searching.

      2. Click the three dots in the upper right corner and select Access Settings. The access dialog opens.

2. Choose whether you want the document to inherit its permissions from folders it belongs to:

   1. To inherit permissions, ensure the toggle at the top of the dialog is enabled, then click Save. You are done.

   2. To give this document its own individual permissions and override the folder permissions, disable the toggle and continue with the next step.

3. Choose the level of access:

   1. Public—All Alation users in your organization will have view and edit permissions to this object. This is the default setting.

   2. Editing Restricted—All Alation users in your organization will have view permissions to this object. You can grant edit permissions to specific users. Catalog Admins, Server Admins, the object creator always have view and edit permissions.

   3. Private—You can grant view or edit permissions to specific users. Catalog Admins, Server Admins, the object creator always have view and edit permissions.

4. If Editing Restricted or Private is selected in the previous step, then select specific users or groups to grant access to.

   1. Click + Invite.

   2. Search for or navigate to the users or groups and select the ones you want.

   3. In the list at the bottom of the dialog, select Can Edit or Can View to specify which permissions you want to grant for each user. You can use the paging controls at the bottom of the list to navigate through the list.

5. Click Save.

Delete a Document

Deleted documents are soft-deleted, so they still exist in the Alation database. Deleted documents will not appear in the navigation, search, or the document hub. Most references to a deleted document will no longer appear in the catalog. Direct @-mentions will remain. If you click on an @-mention or use a saved bookmark to visit the document’s old link, the document catalog page will open with a warning that it has been deleted. The document can then be restored from that page.

To delete a document, you must be the document’s creator, a Catalog Admin, a Server Admin, or a Steward, Composer, or Source Admin with edit access to the document.

There are several ways to delete a document:

• Delete a Document via the Document Hub

• Delete a Document via the Document

Delete a Document via the Document Hub

To delete a document via the document hub:

1. Navigate to the catalog page of the document hub the document belongs to. You can do this through the left navigation or by searching.

2. Find the document in the list of documents on the lower half of the page. You can do this by entering a search term at the top of the document list or using the paging controls at the bottom of the document list.

3. Click the three dots to the right of the document name, then click Delete.

4. In the confirmation dialog that appears, click Delete.

Delete a Document via the Document

To delete a document via the document catalog page:

1. Navigate to the document’s catalog page. You can do this through the left navigation or by searching.

2. Click the three dots in the upper right corner and select Delete.

3. In the confirmation dialog that appears, click Delete.

Documents API

You can create, retrieve, update, and delete documents using the Documents API.