Work with Articles

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, which will eventually replace articles. Document Hubs are available for public preview starting in 2024.1.

• See Documentation for more about the advantages of Document Hubs and the future of articles.

• See Document Hubs for help using Document Hubs.

An article is a document object in Alation. Articles can be created to record any useful information about your data objects: from extensive descriptions of concepts to procedures or how-to tips. You can share your Articles for the benefit of your colleagues and invite others to collaborate on the content.

To systematize the Articles, you can organize them into a taxonomy.

Viewing

You can find shared Articles using Search. You can also see all shared Articles as a sorted list or as Taxonomy under Articles in the left-hand Navigation Menu. To view a specific article, click its title.

Note

If Articles are mentioned in Conversations, in other Articles, or are added as Field values, you can open them by clicking their title anywhere in Alation.

List

The List view displays Articles sorted either alphabetically or chronologically. To switch between sorting options, click the sorted by value then click the sorting option you prefer: newest or name. In addition to sorting, you can filter the list using the text filter.

Taxonomy

The Taxonomy view displays Articles as taxonomies listed alphabetically by the title of the main parent Article. Taxonomies are created by adding children to a top-level article. Children can be either articles or tables; child articles, in turn, can have children of their own, so that taxonomies can be several layers deep:

Create an Article

Articles can be created by users with any role other than Viewer. To create a new Article:

1. In the left-hand Navigation Menu, go to Articles and click . The new Article page will open on the right.

2. In the Title field, type the title. New Articles are created based on the default Article Template. You may want to create a custom template to structure your content in a better way.

3. Hover over the Properties field on the right to reveal the Wrench icon next to the Template label. Click it to open the list of Article Templates available in your catalog.

   

   Note

   Article Templates define the type and number of Fields that you find on the catalog page of an Article. A Field can be viewed as a “building block” for the Template. The Template is a set of Fields that best suit the type of content you are creating. For example, you might use a “customer segment” template for documenting terms for an article group on a marketing campaign and a different “Best Practices” Template for tips on querying a Data Source.

   Article Templates can be created by users with Server Admin or Catalog Admin roles. For details on creating Article Templates, see Manage Templates.

4. Fill out the Fields on your Article page. For details on types of Fields, see About Templates and Fields.

5. To add to or create a taxonomy, either add a child by clicking in the Children field and selecting a child article from the list that appears, or find the article that you believe would be a good parent for your new article and add your new article as a child to that one. You must have access to the parent article to edit it.

6. Where necessary, save the changes to the Fields by clicking Save in the top right corner of the Field panel.

Formatting Text

For blocks of text, your Article Template will include the Rich Text type of Fields. You will see a panel with basic formatting functions on top of the editable area of Text Fields. You can also embed objects such as the following:

• Links

• Tables

• Emoticons

• Images

• Video files

To customize the basic HTML of the text input, on the formatting panel, click to open the HTML code of the input.

@-mentioning

In an article, you can reference any Alation object, such as a User, a Data Source, or a Query, by @-mentioning it in the text field. To mention an object, type the @ symbol in the text field. The list of objects to select from will open.

For Tables, Views, Queries, and Query results, the preview of the object will be available after you save the Field. To see the preview, click the Expand icon [+] that comes after the title of the mentioned object.

Note

When you @-mention an object in an article, the article will be automatically added to the Relevant Articles field on the catalog page of the mentioned object.

Miscellaneous How-To’s

Insert an Excel Table into an Article

Embed Results in an Article

How to Configure a List of Allowed File Types for Article Attachments

Viewing Table and Query Previews in Articles

You can view previews by clicking the [+] link at the end of the table or query name:

This will expand the table or query for viewing:

Editing

You can edit Articles you created or the Articles you have Edit access to. To edit an article:

1. Open the Article catalog page.

2. Hover over the title of the Field you want to edit to reveal the Edit icon. The image of the Edit icon depends on the type of Field you are editing. For example, it can be Edit for Text, for Object Sets, a list for List Values or a calendar icon for Dates. Click it to edit the field value.

Attachments

You can attach files to your article in the Attachments Field of the Article Template.

Deleting

To delete an article, in the top right corner of the article page, click More and then click Delete. In the Confirm Delete dialog that opens, click Yes to confirm the action. Your article will be deleted from the catalog.

Version History and Restoring Versions

Alation stores Version History for Articles. A version is a saved snapshot of an Article having a saved update to the value of an editable Field. To view Version History:

1. On the catalog page of an Article, in the upper right, click More and then click Version History. The Version History dialog opens. It has information on the user who made the change, time of the change, and the View Snapshot link for each version.

2. Click View Snapshot for a version to open and view its page.

3. To exit the snapshot view, in the Viewing Snapshot panel above the Title, click Exit View.

You can restore an older version of an article and in doing so, override all newer edits. You need to have Edit access to the article to be able to restore. To restore an older version:

1. Open the Version History of the article and click View Snapshot for the version you want to restore. The snapshot view will open.

2. In the Viewing Snapshot panel under the title, click Restore. The version you are viewing will be restored as the current version of the article.

Note

Some older versions cannot be restored. For example, it is not possible to restore a version that uses a different Article Template.

Sharing and Access

You can manage access to Articles you created and to Articles shared with you for editing. All newly created Articles are shared with everyone for editing by default.

To change access privileges:

1. On the Article catalog page, in the upper-right corner, click Share. The Share dialog will open.

2. In the section Everyone at your company…, select a sharing option:

Everyone Can Edit	All Alation users have the Edit access to the article (default)
Editing Restricted	All Alation users have permission to view, but only selected users can edit
Private	No one can view or edit except selected users

3. If you want users with Edit access to share the article, too, leave the checkbox Editors can change access permissions selected. If not, clear it.

4. You can also regulate access for specific users after providing the global setting. Click Invite in the Who Can Access section of the dialog, and in the searchable list that opens, find and select users to manage access for. Selected users and groups will be added to the Who Can Access list.

5. For each user and group, select the access level from the list on the right then click Save to save the changes.

Note

Server Admins do not by default have Edit access to articles that have Editing restricted  or Private  access setting unless they are granted such access by the creator of the article.

Revoking Access

To revoke access to your article from a user, open the Access dialog, find the user and in the access options list in the corresponding row, click Remove. Access to the article will be revoked from this user.

Sharing Articles

If necessary, you can share your article with other users. To share:

1. On the catalog page of the article, in the upper-right corner, click Share. The Sharing dialog will open.

2. In this dialog, hover over section Share With and click Add. The Users searchable list will open.

3. Find and select users to share your article with. Selected users will be added to under Share With list.

4. Click Send. The selected users will receive emails that the article is shared with them.

If necessary, you can update the access to the article right from the Share dialog. To change access:

1. Click the access level icon in the upper-right corner of the Share dialog. The Access dialog will open.

2. Change access to the article then proceed with sharing.

Article Groups

Articles can be organized into collections, or article groups. For more on article groups, refer to the section Work with Article Groups.