The Architecture Records Solution presents a family of component types that conform to a common metamodel pattern. Five record types are included with the solution:

You do not need to use all five types when adopting this Solution, and you may choose to develop your own record types that use the common metamodel pattern differently, to best suit your needs.

This article provides essential guidance on configuring and adapting the Solution. It should be read in conjunction with the Architecture Records Metamodel.

Architecture Records Solution Metamodel

As the above metamodel is a pattern, it retains considerable flexibility concerning the component types that are referenced from the record component. Regarding these component types, and in configuring associated Surveys, you must specify the component type(s) and workspace(s) involved. You will note that Has Subject, Refers To and Is Realized By are all left open regarding the component types that they reference. When implementing the Solution, you will need to review the decisions we’ve made for each of these in the context of each record type, and either accept these or change them to another type of your choosing.

Eleven fields are defined in the metamodel, but none of the record types use all of the fields. When amending the record types, or developing your own, you are free to make your own selection from those provided, and you may choose to add others to tailor them to suit your particular needs.

Note: Two alternative fields are provided to record the actual decision: Decision YesNo and Decision Text. Some decisions demand the recording of a binary decision, for example, “does this solution comply with a particular requirement?”. Decision YesNo can be included in the record type to document the outcome of that binary decision.
​
Many decisions are not binary, but require a paragraph of text to record the decision outcome, which may be more nuanced than a simple “Yes” or “No” outcome. Such decisions can be recorded with the Decision Text field. Given the availability of other supporting text paragraph fields, such as Decision Context, Concern, Rationale, Assumptions and Consequence, it is unlikely that both Decision YesNo and Decision Text would feature in the same record type.

Your organization may use a document management system to store formal documents such as the architecture records covered by this Solution. The advantage of using this Solution is that your decision records will be an integral part of your architecture repository, with connections that can reach across Ardoq's knowledge graph. You may therefore face a choice: switch to just storing such records in Ardoq, or accept a degree of replication. If you choose the latter, you could add a URL field to the record types that will have a “twin” in your document management system. In this way, each record can be represented with a component in Ardoq, and have a clickable URL link to the full document in your document management system.

This guide will step through each of the five record types provided with the Solution, discussing the field and reference choices that have been made, and alternative design choices you may wish to consider. It concludes with consideration of how to develop your own types.

You will see that the metamodel pattern caters for both ownership and approval references to Person components. For Decision Record we’ve chosen to include the Owns reference to a Person, and approval(s) using the Approved By reference, also from Person components. A decision of whether to include or exclude approvals for decision records is a matter of governance style, and will vary significantly from one organization to another. You will need to decide what types of decisions need to be documented formally in a record, and to what extent authority to make or approve decisions is devolved or centralized.

When you wish to record ownership of records, we strongly recommend these references come from a Person component. This reinforces accountability, and allows you to automate notifications and actions using Broadcasts, since people have email addresses. An alternative, that is less specific, would be to have Organizational Units owning decision records. In this situation, it is still possible to link decisions to individuals where people who belong to organizational units have been assigned to roles. For example, it might be reasonable to associate architecture decision records to the member of its owning team who is assigned to the role of “architect”.

If you wish to remove approvals, you must delete the corresponding question in REC - Exception Request.

The Has Subject reference is intended to point to “the thing that is the subject of the decision”. The Survey REC - Decision Record Details has chosen to associate this reference to an Application component. If you wish to associate your decision records to other component types, such as Initiative components, you will need to amend this Survey. One option is to allow users to create Has Subject references to a choice of different component types. To achieve this, you will need to create separate survey reference questions for each type/Workspace combination that you wish to offer your users.

The Refers To reference is also intended to offer flexibility, representing a link to the component(s) that influenced the decision. The Survey REC - Decision Record Details has chosen to associate this reference to a Requirement component, representing a Quality Characteristic in the organization’s quality model. This could also be used, for example, to associate the decision record with architecture guiding principle(s), which would also be represented with Requirement components. You will need to update the Survey question if you wish to change either the component type or workspace. For more information about selecting and defining your corporate quality model, see Technical Debt Management: Solution Configuration Guide.

We recommend using Category components to organize your Decision Record components, as there may be many such components sharing the same Workspace. A starting structure is provided with the Solution, with the following top-level categories:

The most suitable structure of Categories will vary from one organization to another. You should set up a set of Category components in your Decisions Workspace to represent your preferred hierarchy using the core Ardoq application as soon as you’ve decided to make use of the Decision Record component type. The Survey REC - Architecture Decision Record Details contains a Category question that allows survey respondents to select the right category for a new decision record. If you do not wish to use Categories in your Decisions workspace, you should delete the Category components form the Decisions workspace and remove the Category question from the Survey,

You may wish to use Ardoq Discover to publish decision logs. The solution includes a Discover Viewpoint, REC—Decision Logs, to facilitate this. It uses conditional formatting to color decision records according to their Decision Status.

The implementation of the Pattern component type provided with the Solution does not include references to People (owners or approvers). If you would like to include either or both of these, take a look at the implementation of Decision Record described above for an example.

We have included the Live date range field, which, together with the Decision Status field, is used to determine whether a pattern is “live” given today’s date.

The proposed metamodel caters to the use of Is Realized By references to a primary component for each realization of the Pattern. The provided survey, REC - Pattern Details, does not have a corresponding reference question for this, so if you wish to use it in the Survey, you will need to add this question using the Survey Builder.

It is quite common to wish to include a diagram in a pattern description. If you use an external drawing application or document management system and wish to include references in your pattern descriptions, you might choose to add one or more fields of type URL to the component type, and corresponding questions to the Survey.

You may wish to use Ardoq Discover as a means of publishing your pattern libraries. A Discover Viewpoint, REC - Live Patterns, is included with the Solution to facilitate this.

The Compliance Assessment component type uses the List Field Decision YesNo to record the outcome of the compliance assessment. The Live Date Range field is used to indicate the period of validity of the record, and the Live end date can be used to trigger a Broadcast warning interested parties that the assessment is approaching the end of its validity. This automated process, which might be used to start another assessment cycle, is not included with the Solution, but a similar process, dealing with Exception Requests, can be viewed as a working example. See Process Playbook: Automating Exception Requests for more details.

The Has Subject reference is used to point to the component(s) that are the subject of the assessment. The Survey REC - Compliance Assessment Details contains a reference question, SUBJECT:, which invites the user to identify one or more Application component as the subject of the compliance assessment. If you wish to conduct compliance assessments of things that are represented by component types other than Application, you will need to replace or supplement this question with additional reference questions, providing the appropriate Workspace and Component Type names.

The Refers To reference allows for a connection to components that are considerations for the compliance assessment. If you choose to use this, you will need to decide precisely what it means, and which component type and workspace it will point to. The provided Survey contains a reference question, CONSIDERING, that allows the user to point to Control components in the Control Library workspace. An alternative might be to point it to the standard, policy or principle against which the compliance assessment was being conducted. To follow such a path, you will need to change the CONSIDERING: question to point to your chosen component type and workspace.

In the provided example, the Approved By reference is used to indicate the approval of the compliance assessment decision. A process to automate approval can easily be implemented using Surveys and Broadcasts, similar to the one that deals with Exception Request components. See Process Playbook: Automating Exception Requests for more details.

As with other Architecture Record types, you may choose to organize the compliance assessment components using a hierarchical tree of Category components in the workspace. We recommend maintaining this hierarchy using the core Ardoq platform, and once set up, users of the REC - Compliance Assessment Details Survey will be able to select the right category when documenting a new Compliance Assessment.

The Architecture Standard component type follows the same approach as the other record types described above. It uses the reference Has Subject to point to the thing or things that represent the adopted standard. Ideally, this should be a component in the organization’s Technology Catalog. In Ardoq, this is represented with a Technology Product component. It is an abstract, catalog entry component type that, in turn, points to deployed instances of the technology using Deploys To references. The Technology Catalog forms part of the Technology Portfolio Management Solution. The Survey REC - Architecture Standard Details contains a reference question, ARCHITECTURE STANDARD, which implements the reference in this way.

As with other Architecture Record types, a hierarchical tree of Category components can be used to organize your standards within the workspace. We recommend setting up the same structure of categories that you have adopted for your Technology Catalog. The Standards workspace provided with the Solution contains Category components that mirror the top-level structure of the Technology Product Catalog workspace provided with the Technology Portfolio Management Solution. If you prefer a different structure, just replace the provided Category components with a structure that suits your needs.

If you’ve already deployed the Technology Portfolio Management Solution, you will note that the Technology Product component type already contains a date range field called Approved Standard. This provides a very lightweight way to indicate that a catalog entry is an approved standard. However, it does not capture background information, such as the concern and rationale, or cater for approvals. This is provided with the adoption of Architecture Standard components.The additional information captured with the Architecture Standard component makes it easier to communicate with non-architecture colleagues. A Discover Viewpoint, REC - Live Standards, is provided to facilitate this.

When adding this solution to your Technology Portfolio Management Solution, you must decide what to do with the Approved Standard field in Technology Product. If it contains dates that are independent of the Live date range in your Approved Standard components, you will create ambiguity. You might choose to delete the field from Technology Product and just use the Live date range field in the referenced Architecture Record field. Or you could choose to replace the Approved Standard field with a calculated date range field that checks if there is an incoming Has Subject reference from an Architecture Standard component and, if there is, populates itself with the values held in the standard’s Live field.

If you have chosen not to create a Technology Catalog, and have not implemented the Technology Portfolio Management Solution, but still wish to record your standards, you could choose to adapt the metamodel for Architecture Standard by having the Has Subject reference point to a different component type. For example, you might choose to have it directly reference your Application components, to indicate which among your application portfolio represent approved standards. If you choose to do this, you will need to amend the ARCHITECTURE STANDARD question in the Survey REC - Architecture Standard Details. Be aware that adopting this approach can lead to increased complexity as you deploy multiple instances of the same technologies. This will result in more than one Application component needing to contain the Has Subject reference from its corresponding Architecture Standard. This complexity, and the growing maintenance burden it introduces, can be resolved with the adoption of the Technology Portfolio Management Solution, which deploys an abstract Technology Catalog that represents each deployable technology just once.

In the provided example, the Approved By reference is used to indicate the approval of the decision to record a new standard. A process to automate approval can easily be implemented using Surveys and Broadcasts, similar to the one that deals with Exception Request components. See Process Playbook: Automating Exception Requests for more details.

An Exception Request component is used to record a request, that might or might not be approved, to avoid one or more approved Architecture Standard. The Refers To reference indicates which standard or standards the exception is being sought from. The Has Subject reference indicates the component or components that are seeking to avoid adoption of the standard(s). The provided Survey REC - Exception Request Details assumes that the Has Subject destination component type is Application, and has been implemented accordingly. You might reasonably wish to allow Initiatives to be the subject of exception requests, in which case you will need to replace or supplement the SUBJECT question with another that corresponds with your chosen component type and workspace.

An example automated process is provided with the solution, which contains additional surveys and broadcasts that manage the creation, approval and end-of-life management of exception requests. See Process Playbook: Automating Exception Requests for more details.

We provide five Architecture Record types, which cover a wide variety of architecture records that can all benefit from the Alexandrian pattern language format. It is possible to develop your own. If you’ve read the rest of this document, you will have a good understanding of the design considerations and the possible variations that relate to each of the five types included. If you wish to develop your own, follow the same approach, being guided by the Architecture Records Metamodel, which presents you with your starting set of choices. And, you may choose to add some additional fields that are specific to the type of record you have in mind. Good luck!

The following table lists the assets that make up the Solution along with the Workspaces that are referenced. Deploying the Solution will cause all of the relevant components to be created if they are not already present. Other sections of this document indicate how to adapt the solution to work without some component types. If you also choose to delete the corresponding Workspaces, you will need to edit the Assets that reference those workspaces and delete the reference.