Enroll Articles into Agile Approval

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.

Agile Approval is a collaboration workflow enabling Alation users to request reviews and provide approvals for Articles, ensuring that these articles are credible sources of information for everyone. Reviewers can monitor the edits made by others and either confirm the changes by approving them or discard them by restoring the last approved version. The catalog page of an article will indicate the review status of its content, so that the readers are informed whether or not the article has been vetted by a subject matter expert and can be trusted.

Agile Approval Workflow Overview:

Turning Agile Approval On

If you want your article to go through the approval cycle, you need to enable Agile Approval for this specific article and assign Reviewers.

Note

Agile Approval workflow can only be enabled for each article.

Turning on Agile Approval enables the approval workflow for the article. This means that the content will have to be approved by the assigned expert, or the Reviewer, before the article receives the status Approved.

Reviewers step in between creators and consumers of articles and sign off on all edits. Any changes to articles with Agile Approval on are monitored and have to be reviewed and approved for the article to become Approved. Reviewers are notified on both new updates to the article and the change of status using their Inbox . For details on Inbox, see Inbox.

You can turn Agile Approval on and off for articles:

• You created

• You have Can Edit access to

• You are assigned as Reviewer of.

To enroll an article in Agile Approval,

1. In the upper-right corner of the article catalog page, click More and in the menu that opens, click Access. The Access dialog will open.

2. In the Agile Approval panel, click the down arrow then toggle Agile Approval on.

   

3. In the Assign Reviewers panel that opens, click Add and find and select users or groups to be Reviewers. These users will be tasked with reviewing and approving all changes to the article. They will receive notifications on edits to the article, will be able to add or remove Reviewers and turn Agile Approval workflow for the given article on and off.

Note

It is possible to leave the article without any Reviewers. In this case users with Can Edit access will see an alert on the article page reminding to assign someone so that the article can start moving through the approval cycle.

Users added as Reviewers will automatically be granted Can Edit access if they have not been given this permission before.

4. In the dialog, click Save. The assigned Reviewers will be listed under the Reviewers field on the right of the article catalog page. The page will also display the Agile Approval status banner under the title:

• Status This Article Contains Edits and Needs Your Review will be displayed to Reviewers.

• Status Pending Review - Your Edits are Saved and Visible will be displayed to non-Reviewer users with access

5. If no Reviewers are assigned, the catalog page of the article will display a reminder. In the Agile Approval status banner, under Awaiting Review By, click assign someone to open the searchable list of users and groups. Find and select users or groups to be Reviewers.

6. Alternatively, you can assign Reviewers by setting values to the Reviewers field on the article catalog page. To add Reviewers, click Add next to the field and in the Users and Groups list, find and select users or groups to be Reviewers.

Turning Agile Approval Off

If Agile Approval is turned off for an article that was previously enrolled in it, Alation stops pulling it through the approval cycle:

• The dedicated Reviewers field is hidden from the article catalog page.

  Note

  The system preserves data on latest Reviewers, and they will be restored if Agile Approval is turned back on.

• Notifications about this article previously triggered by the Agile Approval workflow will be removed from the users’ inboxes.

• Agile Approval status banners will be hidden from the article catalog page

If Agile Approval is turned back on, the Reviewers will be restored, and the article will go to Requires Review state. New review tasks will be sent to Reviewers again.

Note

The user who turns Agile Approval back on will automatically be added as a Reviewer; however, they can remove themselves from the list of Reviewers.

Approving an Article

Reviewers approve articles to confirm that the content is trustworthy.

To approve an article,

1. Open its catalog page.

   

2. Review the content and the field values and in the Agile Approval status banner, click Approve Current Version. The status of the article will change to Approved.

   

Editing an Article with Agile Approval On

Changes to Fields

Users with Can Edit access can make changes to the article. If an article with the Approved status is updated, it will change the status back to Requires Review.

Although most of the field changes will trigger the Requires Review status, there are exceptions. Changes to the following fields will not impact the approval status of the article:

• Reviewers

• Contributors

• Tags

• Children

• Attachments

Adding a Template

Users with Can Edit access can add a new template to the article. Adding a template will cause an Approved article to go to the “Needs Review” state.

Restoring an Older Version

As the Reviewer, you can restore an older version of an article enrolled in Agile Approval and, thus, discard any pending edits.

To restore an older version,

1. Open the catalog page of the article that requires your review. Its status will be This Article Contains Edits and Needs Your Review.

2. In the Approval status banner, click Open Version  History. The Version History dialog will open. It lists all existing versions of the given article, by time and user, newest on top.

3. In Version History dialog, click View Snapshot for a version you want to restore. The snapshot view of the article will open.

4. Click Restore Version. The article will be restored to this particular version.

   

Article Review Tasks and Notifications

Reviewers will receive notifications about all new edits to the articles they are responsible for and tasks to review and approve the changes. Notifications will show up in their Inbox in Alation. Active Review tasks will be filtered into Assigned to Me view of the Inbox.

To view notifications and tasks,

1. Click the Activity button on the main toolbar. Your Inbox will open on the right. New notifications can be found in My Inbox folder.

2. Click any Article Review notification to see the details on the edits that require approval.

3. If you want to review and approve the edits right away, click Go to Page  icon in the review notification to open the catalog page of the article.

4. Alternatively, you can find your active Review tasks under  Assigned to Me on the left. They will be available alongside your Conversation tasks.

5. Click a task to see its details then click Go to Page to open the catalog page of the article directly from the task.

Note

A Review task stays active until the article that triggered it is approved and assigned the Approved status. While the task is active, it receives an update every time the article is edited. All edits waiting for review in one review cycle are accumulated in the task body.

After the article is assigned the Approved status, the corresponding task is deactivated and no longer updates. If new edits are made in the approved article, a new review cycle is kicked off and a new review task is sent to all Reviewers.