This Playbook describes the benefits of configuring and running the Exception Request Management Process, what it does and how it works. We explain how you can configure and run the process “out of the box”, and how to adapt it to suit your organization.
Table of Contents
Introduction
The Architecture Records Solution includes five different types of architecture records:
Architecture Decision Record
Pattern Description
Compliance Assessment
Approved Architecture Standard
Exception Request
See Architecture Records Metamodel for details of each type. An Exception Request component represents a request for an exception from adherence to an approved architecture standard. It may come from the team leading an initiative, or from a product team. Some exceptions might be permanent - it may be impossible, for example, for a solution to conform to a standard database management system because purchased packaged software is reliant on a particular underlying database. Or it might be temporary. For example, a team may need more time to migrate the solution they support from an out-of-date technology to one that is an approved standard. Maintaining a register of approved exceptions enables an architecture team to keep track of the effectiveness of their architecture standards and compliance across the IT estate.
This Process Playbook shows how the management of exceptions to approved standards can be automated. Whilst this is the only example process included with the Architecture Records Solution, you may wish to develop similar processes for other types of architecture record that you’ve deployed in your organization. So in addition to being a process that can be immediately adopted to manage your exception requests, we hope you will be inspired to develop similar processes with which to govern your architecture.
All of the assets required to configure and run this process are included in the Architecture Records Solution. This is one of a set of Process Playbooks that help you leverage Ardoq’s unique automation capabilities. See Automated Process Playbooks for more inspiration.
Who should use this Process Playbook
This playbook is for Enterprise Architects and governance administrators who want to automate the process of managing exception requests, making it easy to record and track the submission, review and approval of exceptions to approved technology standards.
Why you should configure and run this process
The Architecture Records solution contains five record types that conform to a common metamodel pattern. These can be adapted and new types can be created. See the Architecture Records Configuration Guide for details.
The Architecture Standard component type is used to record your approved standards, linking to your Technology Catalog (which is provided with the Technology Portfolio Management Solution). It allows you to fully articulate your standards and why they have been adopted, providing Live Start and End dates to indicate when the standard is in force.
Good governance practices go beyond just defining and publishing standards. It is not always possible for every IT solution to adhere to approved standards - some teams may need more time to bring their solutions up to standard. It may be impossible for some solutions to be fully compliant with all your standards. For example, a COTS package may have technical dependencies that go against your approved standards, such as requiring a particular supporting operating system or database management system that is not approved.
The Exception Request component type, which is also included with the Architecture Records Solution, allows you to document exception requests so that you can manage and track compliance and agreed non-compliance with your approved standards. The automated process described in this document enables you to implement an automated process to manage exception requests, from the creation of an initial proposal, through its review and approval (or rejection) to triggering necessary actions when the granted life of an approved exception comes to an end.
Ardoq’s Exception Request Management Process
What it is
This automated process, when configured and deployed, begins when a new Exception Request component is created, and runs continuously in the background until the Exception Request is either rejected or has come to the end of its life and has been retired. It engages with members of the Architecture Review Board (ARB) who determine whether to approve the request and decide how long the exception should last. Then a month before the exception expires, it warns the application owner and the Chief Architect that the exception is coming to an end, indicating that they might need to take action, to confirm that the exception is no longer required, or to renew or extend the exception, if necessary and desirable.
A newly created Exception Request is routed to members of the ARB, inviting them to confirm their approval of the request, and the Request’s status is updated to reflect the ARB’s decision (to Approve or Reject the request).
The owners of the Applications that are the subject of the request are notified when the status is changed.
30 days before the expiry of an approved exception the owners of the Applications are warned that the exception is coming to an end
At the same time, the Chief Architect is invited to update the status of the Exception Request. If it is no longer required, the status can be changed to Retired, and the request will no longer be considered “live”. Alternatively, the Chief Architect might grant an extension by changing the Live End Date, or ask the Application Owner to submit a fresh exception request for consideration by the ARB.
Figure 1 below shows the process that is provided with the Architecture Records Solution. Details of how this can be configured and put into operation are provided later in this Playbook.
Figure 1: Ardoq’s Exception Request Management Process
Solution dependencies
As described above, the process makes use of a metamodel that goes a little beyond the metamodel of the Architecture Records Solution. It assumes that Applications have owners, and that People are assigned to Roles (see How to use Roles in Ardoq for more about the Role component type). The full metamodel required by the process is shown in Figure 2 below.
Figure 2: Exception Request Management Process Metamodel
How it works
Just two types of asset combine to produce this process: Surveys and Broadcasts.
Surveys - Forms that gather information from people in different steps of the process. Their answers are used to add information to the model. These may take the form of references (such as creating Approved By links between a Person and an Exception Request), or fields that add detailed information to a particular asset (such as the Live date range that indicates the period for which the exception has been approved).
Broadcasts - Highly configurable messages that can watch for specific situations and, when they occur, trigger a message to a person, for example asking them to complete a survey about a particular asset, or warning them about a situation that has arisen. For example, an invitation to the members of the Architecture Review Board to review a newly submitted Exception Request.
Figure 3 below shows how the Exception Request Management Process of Figure 1 has been implemented with two Surveys and six Broadcasts. An advantage of Ardoq’s distributed workflow capability is that individual Broadcasts can be enabled or disabled so that as much or little of this process can be put into action.
Figure 3: The process in terms of Ardoq assets
The Surveys
Two surveys are used to support the Technical Debt Management Process:
REC - New Exception Request: This survey is used to create a new Exception Request. The Survey questions are:
Exception Request Name.
Category: Select the category in the workspace to which this exception request belongs.
Subject: Select the Application(s) to which this exception request relates. The answer will form a “Has Subject” reference from the Exception Request component to the selected Application(s).
Exception From: Select the Architecture Standard(s) from which the request is seeking an exception. The answer will form a “Refers To” reference from the Exception Request component to the selected Architecture Standard(s).
Considering: a text paragraph describing the situation that has led to this request.
Exception Justification: a text paragraph justifying the need for the exception.
Review Date: a hidden field that will be automatically populated with the date/time of the survey’s submission.
REC - Review Exception: This Survey is used by members of the Architecture Review Board to review an exception request when it is first submitted, and by the Chief Architect when it approaches its end of life. The questions to which a response is invited are:
Exception granted from/to: the start and end dates defining the period for which the exception is being granted.
Approved By: select the person or people who have approved the decision. The answer creates an “Approved By” reference from the Exception Request component to the selected Person component(s).
Status: set the status of the request. The options are:
Proposed
Rejected
Approved
Retired
Review Date: a hidden field that will be automatically populated with the date/time of the survey’s submission.
The remaining fields, whose values were supplied when the Exception Request was first created, are shown for information purposes as read-only fields.
The Broadcasts
Six Broadcasts are used to send the surveys for completion:
1. REC - Review Proposed Exception: this Broadcast invites members of the Architecture Review Board to review a newly created Exception Request using the REC - Review Exception Survey. The Broadcast runs weekly, and will fire for every Exception Request component that has a Decision Status field value that is either empty or equal to Proposed. A gremlin query identifies the target audience, selecting all Person components that have an Assigned To reference to a Role component with the name ARB Member.
hasId(ids).V().hasLabel('Person').filter(__.out('Assigned To').hasLabel('Role'). has('name', 'ARB Member')).path() |
Note that this way of using gremlin to connect components to an audience of people who do not have reference connections to those components will only work well where the number of components and the size of the audience are both small. If you anticipate hundreds or more of components for each broadcast, you should identify the audience in a different way (for example, by selecting them directly from the People workspace or by entering their email addresses).
For as long as the Decision Status field value remains empty or equal to Proposed, members of the ARB will receive this invitation every week.
2. REC - Exception Request Approved: this Message Broadcast will send a message to the owners of Applications that are the subject of an Exception Request that has been recently updated and whose Decision Status is Approved. The broadcast runs hourly. A gremlin query identifies all the Person components that have an Owns reference to Application components that have a Has Subject reference from the Exception Request.
g.V().hasId(ids).out('Has Subject').hasLabel('Application').in('Owns'). hasLabel('Person').path() |
3. REC - Exception Request Rejected: this Message Broadcast will send a message to the owners of Applications that are the subject of an Exception Request that has been recently updated and whose Decision Status is Rejected. The broadcast runs hourly.
4. REC - Exception Request Retired: this Message Broadcast will send a message to the owners of Applications that are the subject of an Exception Request that has been recently updated and whose Decision Status is Retired. The broadcast runs hourly.
5. REC - Exception Expiry Warning: this Message Broadcast will send a message to the owners of Applications that are the subject of an Exception Request warning them when their exception has just 30 days left to run. The broadcast runs daily.
6. REC - Review Expiring Exception: this Broadcast invites the Chief Architect to review Exception Requests that have 30 days or less remaining before they expire using the REC - Review Exception survey. The Chief Architect is identified with a gremlin query that selects Person components that have an Assigned To reference to a Role component with the name Chief Enterprise Architect.
g.V().hasId(ids).V().hasLabel('Person').filter(__.out('Assigned To').hasLabel('Role'). has('name', 'Chief Enterprise Architect')).path() |
Note that this way of using gremlin to connect components to an audience of people who do not have reference connections to those components will only work well where the number of components and the size of the audience are both small. If you anticipate hundreds or more of components for each broadcast, you should identify the audience in a different way (for example, by selecting them directly from the People workspace or by entering their email addresses).
How to configure and run it
This section describes the few steps needed to configure the Surveys and Broadcasts and make the whole process live.
Make sure that your metamodel complies with that shown in Figure 2.
Your Chief Architect should be identified in your model as a Person with an Assigned To reference to a Role component called Chief Enterprise Architect. If that is not the case, you should edit the Broadcast REC - Review Expiring Exception so that it is aligned to your metamodel.
ARB members should be identified in your model as Person components with Assigned To references to a Role component called ARB Member. If that is not the case, you should edit the Broadcast REC - Review Proposed Exception so that it is aligned to your metamodel.
Application Owners should be identified in your model as Person components with Owns references to an Application component. If that is not the cse, you should edit the Broadcasts REC - Exception Request Approved, REC - Exception Request Rejected and REC - Exception Request Retired so that it is aligned to your metamodel.
Your Person components must all contain valid Contact Email field values.
Edit each of the four Surveys and add a suitable contact email address in the General information Section. Save each Survey, ensuring they are made Live.
Edit each of the four Broadcasts and in the Compose message section, add a suitable Sender’s email address and review the message content to ensure that it suits the culture and style of your organization.
Select Launch Broadcast to make each Broadcast live.
That’s it! Your Technical Debt Management Process process is now running.
Adapting the process to fit your organization
This process uses simple gremlin queries to identify the people who should receive Broadcast messages or surveys. We’ve chosen to illustrate different approaches, which you may prefer to change depending on your approach to governance and responsibility.
The Broadcast REC - Review Exception is sent to all Person components that have an Assigned To reference to the Role component called ARB Member. Each recipient will receive the same copy of the same survey. It allows each to add themselves to the set of Person components who have approved the decision, but it also allows each to update the Status and Live date range fields. Each respondent will overwrite any existing values in these fields, so only the input of the last change will count.
It might be argued that it is dangerous to invite approval from multiple people, as this “muddies” the accountability of the decision. An alternative would be to send the Broadcast to a single authority, such as the Chief Architect, who acts as the chair of the ARB and is accountable for its collective decision. See the gremlin code in REC - Review Expiring Exception for an example that picks out the Chief Architect.
If you only make this one change, the REC - Review Exception survey will still allow multiple people to be identified as approving the decision. If you wish to constrain this to just one approver, you should edit the Approved By question in the Survey Builder and set the max number of references that can be created to “1”.
An alternative to selecting recipients via their roles is to select them directly. However, this has the disadvantage that they become “hard-wired” into the Broadcast, and if they change job they will continue to be the recipient of a broadcast that may no longer be applicable to their role in the organization.
You will also note that we chose to limit the fields that can be updated in the two surveys. The survey used to initiate the request does not offer the Live date range, so they are not able to set the start and end dates of the exception (with this design, that is only in the gift of the reviewers). And the reviewers can set the status and the live date range (setting how long the exception lasts), but they cannot update the details of the request. These are design choices, and they are easy to change by adding or removing fields from the two surveys. FIeld-level permissions can be used to underline these design choices.