Solution Health Check: Configuration guide

The Technical Debt Management Solution is designed to interact with components that are part of other Solutions. Solution Heath Check components can interact with Initiative components from the Strategy to Execution Solution, Debt Items from the Technical Debt Management Solution and Risks from the Compliance Assurance and Application Risk Management Solutions.

But it would be wrong to assume that use of all of these component types, and the Solutions where they originate, are prerequisites for the adoption of the Solution Health Check Solution. As a minimum, this Solution expects to have a set of Application components whose solution architectures can be the subject of a review. Connection to all of the other component types listed above, and shown in the metamodel diagram, is optional, but a few changes will need to be made to remove reference to those that are not in use.

This document will guide you through the simple process of adjusting the Solution Health Check Solution on initial deployment to accommodate the component types you have in your metamodel. Guidance is also given on which Broadcasts to enable should you wish to automate the process of keeping your key business systems under regular review. You have choices to make here depending on which Quality Model or Models you are using, and whether you wish to create a new Solution Health Check component for each review, or alternatively overwrite the last Solution Health Check component when a new review of the same application is conducted. Guidance is also provided if you wish to replace the use of a quality model with your Architecture Guiding Principles, or some other set of requirements that might act as a checklist for conducting solution health checks.

Solution Health Check Metamodel

The metamodel diagram indicates that Solution Health Check components can have an Refers To reference to any of the following technology component types:

These allow you to make a record of what a Solution Health Check has uncovered and triggered, giving you the ability to identify, for example, which Risks were first recorded as a consequence of a given Solution Health Check. The link to Initiative is of particular value if you want to track what action is being, or has been, taken to address the recommendations contained within the Solution Health Check. An Initiative component might be directly connected to a Solution Health Check, indicating that it was created as a consequence of conducting the review, or it might be connected via an Impacts reference to a Debt Item which, in turn, has a Refers To reference from the Solution Health Check, Being able to identify a connected Initiative is an indication that action is being taken to implement the recommendations. A Solution Health Check that raised serious concerns yet has not connected initiatives might indicate that nothing is being done to address the review team’s recommendations. As you might expect, the Solution Health Check solution contains a report and dashboard widget that call attention to this situation. This report and dashboard widget will still work correctly, even if you have not deployed the Technical Debt Management or Strategy to Execution Solutions. But without these additional solutions, the Action column of the report will not contain any useful information.

If you have deployed the Application Risk Management or Compliance Assurance Solutions, we recommend that you add a Reference Question to the Survey SHC - Assessment Survey that invites the respondent to add a reference to an existing or new Risk. This allows you to demonstrate the value being created from your Solution Health Check process by highlighting which Risks were identified in the course of a Solution Health Check evaluation.

You might also choose to add a corresponding report and dashboard widget that could identify those Solution Health Check components that contain a Refers To reference to a Risk component.

If you have deployed the Technical Debt Management Solution, we recommend that you add a Reference Question to the Survey SHC - Assessment Survey that invites the respondent to add a reference to an existing or new Debt Item. This allows you to demonstrate the value being created from your Solution Health Check process by highlighting which Debt Items were identified in the course of a Solution Health Check evaluation.

You might also choose to add a corresponding report and dashboard widget that could identify those Solution Health Check components that contain a Refers To reference to a Debt Item component.

If you have deployed the Strategy to Execution Solution, we recommend that you add a Reference Question to the Survey SHC - Conclusions that invites the respondent to add a reference to an existing or new Initiative. This allows you to demonstrate the value being created from your Solution Health Check process by highlighting which initiatives were identified in the course of a Solution Health Check evaluation.

You might also choose to add a corresponding report and dashboard widget that could identify those Solution Health Check components that contain a Refers To reference to an Initiative component.

Under the heading Live Solution Health Checks the dashboard displays Live Solution Health Checks with urgent concerns. This widget is sourced from the report SHC - Live Solution Health Checks with Urgent Concerns. If you have extended our solution to connect Solution Health Checks to Initiatives and Debt Items, you can extend the dashboard and underlying report to show which of those Solution Health Checks have associated Initiatives (and more importantly, which do not).

The code to add a new column to the report to achieve this is already included with the Solution. You just need to “uncomment” the report gremlin and update the Dashboard widget to enable it.

You will also want to update the dashboard widget so that it shows this new column in the report.

You might wish to use this report to draw particular attention to those Solution Health Checks that have urgent concerns but no associated Initiative (direct or indirect). These are the items in the report with “None” in the Action column. Consider adding a further chart to your dashboard that can draw attention to these Health Checks, as there is a risk that the Health Check was conducted but no action has been taken to address serious concerns raised. A Number Chart using the same report, but with a filter applied, is one way to achieve this.

The Solution Health Check contains a Quality Models workspace that includes three example Quality Models: the Ardoq Quality Model, ISO 25010 and the GOV.UK Service Standard. This workspace is also included with the Technical Debt Management Solution.

If you wish to use either the Ardoq Quality Model or ISO 25010 as the source evaluation criteria for your Solution Health Checks, then you do not need to make any changes to the provided surveys. However, it is a good idea to take a look at how the surveys have been designed, and you will need to change them if you wish to point them to a different quality model.

Unlike many uses of Surveys in Ardoq, the questions that form the scoring criteria for each Health Check are not “hard coded” into the survey as fields. Rather, the criteria are chosen by establishing Depends on references from the Solution Health Check component, to each selected Requirement component that belongs to the chosen Quality Model, and the scores are stored as fields (Importance and Level of Concern) on each reference.

The Ardoq Quality Model

The Ardoq Quality Model consists of two levels of Requirement components contained within an Information Artifact component. Altogether it has 44 Requirement components (10 in Level 1, 34 in Level 2). The ISO 25010 Quality Model has a similar structure (9 Requirements in Level 1, 40 in Level 2).

A set of six surveys starting with the name SHC - New Solution Health Check has been provided to support different approaches to setting up a new Solution Health Check. The distinction between them can be found, in each case, in the Reference Question Quality characteristics to be assessed. They each use an Advanced Search to constrain the list of Reference components offered to the user as possible criteria. All of them contain a constraint rule that selects the Quality Model in use.

The reason for offering three different surveys for each Quality Model is to allow for three variants of the Solution Health Check for each Quality Model. A ‘Lite’ Health Check involves a set of criteria chosen from among just the top level of Requirements (the Quality Characteristics). A ‘Full’ Health Check involves a set of criteria chosen from among the lower level of Requirements (the Quality Sub-characteristics). For the Ardoq Quality Model, the former will offer a selection from among 10 requirements, whilst the latter will offer a choice of 34 requirements. A third, ‘Mixed’ option allows the user to choose a mix of Quality Characteristics and Sub-characteristics. This might happen, for example, if the team want to conduct a 360 degree review, but focus in particular on certain qualities (e.g. Reliability). They could choose all the Quality Characteristics apart from Reliability, for which they would then select all the Sub-characteristics. The disadvantage of this last approach is that the survey will ask the user to select their criteria from among 44 Requirements (both levels of requirements). Having separate surveys avoids forcing all users to select from this mixed list of 44 Requirements.

The three different surveys for each Quality Model have names that end with Lite, Full or Mixed. The ‘advanced search’ rules for the question Quality characteristics to be assessed are given below for each of the three:

This rule ensures that the user is presented with only the top level Quality Characteristics that belong to the desired Quality Model.

These rules ensure that the user is presented with only the lower level Quality Sub-characteristics that belong to the desired Quality Model. Note that the Component Level field, which is a calculated field that automatically determines the level of a component in its parent/child hierarchy, is being tested for the value of 3. Whilst we are looking for the second tier of requirements (the sub-characteristics), there is a parent Information Artifact component that sits above the level 1 Requirements. So the Quality Characteristics in the Ardoq Quality Model will have a Component Level of 2, and the Sub-characteristics will have a Component Level of 3.

This rule uses the Model Name field to select all the Requirements that are part of the desired Quality Model, irrespective of their level.

One advantage of having a quality model represented as sets of components in the knowledge graph is that they can be extended or changed without triggering the need to make changes to the Solution Health Check Surveys. If you maintain the overall structure of the quality models, you can add, change or remove Quality Characteristics or Sub-characteristics to either Quality Model and not need to change anything else in the Solution.

However, if you change the name of either Quality Model, or wish to add a different quality model or equivalent (e.g. a set of Architecture Guiding Principles), then you will need to make a few changes. If you’ve just changed the name of a Quality Model, you will need to make the following changes:

If you wish to add a new Quality Model (or equivalent), you should:

The bubble chart uses a Perspective to color each bubble according to the Quality Characteristic it is representing. Where a “full” model has been used, bubbles will represent Sub-characteristics, which may share a common parent Characteristic. This is where the conditional formatting comes into play - all Sub-Characteristic bubbles that share the same parent will share the same color, making it easy to see their association. Because the coloring is specific to the Characteristics in the Quality Model, there is a separate Perspective for each Quality Model that is supported by this Solution “out of the box”: the Ardoq Quality Model and the ISO 25010 Quality Model. The example bubble chart in SHC - Solution Health Check Presentation uses the Ardoq Quality Model. If you choose to adopt the ISO 25010 Quality Model, you should switch to its corresponding Perspective to display the bubble chart correctly.

If you develop your own Quality Model, or use your Architecture Guiding Principles instead, you need to create a new Perspective that reflects your model.

The solution contains a set of six Message Broadcasts that can be used to automatically message the Application owner to renew a Solution Health Check for their Applications when the end date of the Live date range of the last Solution Health Check approaches. If you do not wish to use this feature, just leave all Broadcasts in their unpublished state. Configuring and launching these Broadcasts will cause the process to operate as follows.

A month before the Live end date, the Application Owner will receive a message containing a link that will open a fresh New Solution Health Check survey with which they can set up a new Solution Health Check. This will create a new Solution Health Check component that will be additional to any previous ones used to record past Health Checks. All previous Solution Health Check components will remain in the graph as historic records. When the Live end date passes, their Live Status will automatically change to “Recently Retired”, and when the end date goes beyond 90 days ago, it will change to “Long Retired”.

When a Solution Health Check is first created, the user chooses one of six New Solution Health Check Surveys, depending on which of two Quality Models they wish to use, and whether they want to set up a ‘Lite’, ‘Full’ or ‘Mixed’ Health Check. When it comes to end of life and renewal, the system has to know which of these six Surveys it should send to the Application Owner, and the message in the Broadcast needs to contain a link to the Survey that will create a new component (and not a link to the Survey of an existing Health Check component, as we don’t want to overwrite a previous Health Check record).

When the New Solution Health Check Survey is first submitted, it uses a Hidden Field question to automatically write the name of the Quality Model and the type of Health Check to the field SHC Model (e.g. “Ardoq Lite”). Each of the six Broadcasts is set up to trigger a month before the LIVE end date for each of the six combinations of Quality Model and Health Check type using that field. If you plan to use both Quality Models, and all three types of Health Check (‘Lite’, ‘Full’ or ‘Mixed’) you will need to configure and launch all six Broadcasts.

The solution has six Message Broadcasts, each named Renew but with a suffix that indicates which of the two Quality Models they refer to, and whether they represent renewals of ‘Lite’, ‘Full’ or ‘Mixed’ Health Checks. Each of these has a corresponding Survey: for example, the Message Broadcast SHC - Renew (Ardoq Lite) is associated with the Survey SHC - New Solution Health Check (Ardoq Lite). But note that these are not Survey Broadcasts, but Message Broadcasts. This is because they are not used to re-present a previously completed survey, but rather used to present a new survey that will initiate a new Solution Health Check. This means that the messages have to be updated with Survey URLs before the Broadcasts can be launched using the process described below.

You should configure and launch only those combinations that you are using. The following instructions describe how to configure and launch one Broadcast: SHC - Renew (Ardoq Lite). You should repeat these tasks for all the Broadcasts you wish to use.

Repeat steps 1 to 10 for each of the Broadcast / Survey pairs you wish to launch. Remember that each Survey is different and will have its own unique URL, so be careful to paste the right Survey URL into the right Broadcast message.

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.