The Enterprise Architecture Workspace offers a feature to file and manage architectural artifacts (like Architectural Decision Records). In the context of enterprise architecture and technical governance best practices, the respective business functions might want to review new ADRs first and file an approval accordingly. The product documentation describes this feature but the following common questions are often asked:
- How are the approvers configured and assigned?
- How can the OOTB approval flow be configured and changed?
- Which other assets need to be configured or taken into consideration?
Enterprise Architecture Group
From a configuration point of view, we first need to understand that a default assignment group, named Enterprise Architect Group is introduced and OOTB available. The purpose is to assign all users in their function as enterprise architects:
All group members will inherit the EA Analyst role (for details refer to the product documentation). Notice that this group is not just used to manage also approvers for an ADR. Members of this group will also get approval requests for other Enterprise Architecture related processes and requests, in particular:
- Architecture review requests
- TRM product or product lifecycle requests
- Modeling diagram requests
- Digital integration requests
All approvals being created follow the common platform standards. An approval task is created per approver and a mail notification will be sent (can be freely configured and layouts / content changed).
How to request and perform an ADR approval
Assure there is at least one active user member of the Enterprise Architect Group. Now follow the sample steps below to file an ADR (and a concrete example for an architectural artifact), submit it for approval and work on the approval from an enterprise architecture function:
- Access the Enterprise Architecture Workspace
- Navigate to Portfolio > Information Portfolio > Architectural Decision Records
- Create a new architectural artifact
- File your new ADR
Notice that all artifacts are versioned by default and remain initially in the Draft state. Once filed notice that you can issue an approval request via Request Approval button. - Click the Request Approval button
The submission will be confirmed via popup dialog and the record move into the Submitted state.
You may review via Approval Details button all approvers being notified. These are OOTB all active users within the Enterprise Architect Group. - As approver access the Enterprise Architecture Workspace homepage
Within the Needs Attention section, we will find all active approval tasks for the current user and hereby our recently issued approval request for the ADR. You may now either access the ADR record for review first or directly work on the approval task to either approve or reject. - Complete the approval request and revisit the ADR
Once the approval task has been completed, the ADR author and approver will find the status of the ADR being updated to Approved accordingly.
Flows, notifications and related assets
Now let us have a look what is triggered in the backend, creating the approval tasks, notifications and other assets of interest. This will help us to understand better how to customize and change the OOTB process if needed:
- The Request Approval button is a simple UI action, which changes the state to Submitted and shows the confirmation message:
- The architectural artifacts (like the ADR or other similar records) are stored in a central table, along with their versions in a second table (keeping a reference to the main artifact record). Notice that the tables within the data model derive their functionality from the ServiceNow Document Management application:
Architectural Artifacts (sn_apm_architectural_artifact)
extends Documents (ds_document)
Architectural Artifact Versions (sn_apm_architectural_version)
extends Versions (ds_document_version) - Once the state has been set to Submitted, an OOTB flow (Approve Architectural Architect Version) will be triggered:
- The flow logic is straight forward and updating the state and triggering notifications. For the actions creating the (group) approval tasks, notice that the Enterprise Architect Group is pre-configured here:
- The flow will also trigger pre-configured notifications, for example for an approval or rejection scenario. Namely the following notifications are of interest and can be modified (for example to tailor your mail notification standards and company branding):
A sample for a sent notification (beside the created approval tasks) can be seen here: - Once the approval is completed (approved or rejected) the flow ends and the architectural artifact reflects the approval state. From here on a new version can be created if needed and re-submitted.
Traps and pitfalls
Besides the above mentioned flow (creating and managing the approvals and notifications), there are other assets of interest to keep in mind in case we intend to modify for example the approval flow which is only taking the hard-coded user group into account:
- Reader permissions for EA (Business Rule)
An OOTB business rule is triggered anytime a new architectural artifact is created. This business rule basically grants all members of the Enterprise Architect Group read access to the document itself (which is technically stored in the Document Management application). Notice that also here the group name is hard-coded. You might adjust this as well along with your changes to ensure read access remains available across the architectural artifacts in the workspace: - Access Control Lists (ACLs)
With a simple code search we can also quickly identify plenty of ACLs which also check the hard-coded Enterprise Architect Group record for its members. These apply to the TRM capabilities:
Conclusion
Understanding the approval mechanisms, involved OOTB group configurations and the flow steering the process helps to adjust the behavior if needed. While the central group is intended to summarize all users in the role of the enterprise architect and involve them in reviews and approval of architectural artifacts (like ADRs), it also assumes that there is a single group responsible for all aspects and scenarios. In practice, you might look for a different approach in a more complex organization, with dedicated enterprise architecture teams more focusing on specific enterprise architecture capabilities and business applications. You might also want to avoid that all (as per current OOTB configuration) enterprise architects get involved in any kind of architectural review and be more specific in terms of which artifacts should be routed to dedicated enterprise architecture groups.
Notice that architectural artifacts can be associated with any number of entities (for example a specific ADR might be related to a business application). Those relationships are stored in an internal table (sn_apm_related_entities) which can be useful if you want to use those relationships to determine an approval group or target audience being responsible for a review and approval process - a common scenario for a more specialized and organized setup from an enterprise architecture teams perspective.
With this knowledge at hand you can freely adopt the OOTB flow and notifications at hand or configure / implement a different approach tailored to your needs. However, changing the meaning or usage of the OOTB group (Enterprise Architect Group) usually also results in additional configuration changes being required for other assets using this group definition (like business rules and / or ACLs).
