Articles, Blogs, Videos, Podcasts, Share projects - Experiences from the field

Hi there,

While exploring Instance Scan, I encountered several undocumented parts. Several parts which I have been writing articles and blogs on, though one part is still unknown: the Scores table and score* fields on Checks and Suite Checks which have been added with the Quebec release.

In this article I'll describe what I found on the Scores table.

Data model

When looking at the Instance Scan data model which I described in a previous Community article, you'll notice the "Scores" table and score* fields on "Checks" and "Suite Checks". These are all not made visible in the Instance Scan application, not in Application Module, not on List Layouts, not on Form Layouts, etcetera. So let's unwrap this part! First, a snipped of the data model involved:

Scores table

When opening the Scores table, you will notice records will have been created for each category of Scan Result records. For example:

Interesting! Though, where does this come from? How are these scores being calculated?

Calculation rules

Rules

"Rules" that I found out while testing the Scores calculation:- Max Scorable Findings can be left empty, this will be interpreted as 1;- Min Scorable Findings can be left empty, this will be interpreted as 0;- Scoring Scale can be left empty, this will be interpreted as 1;- Scoring Scale of 2 or higher will ignore Max Scorable Findings;- Max Scorable Findings, Min Scorable Findings, and Scoring Scale have a blanc default value for new records;- Score Weight can be left empty, this will be interpreted as 1;- The Score is calculated based on the sum of Count for Scan Findings, not based on the Finding count field which you'll find on the Scan Result table;

- The Count field on Scan Findings represents the actual count for the Check concerned, this is simply the outcome of how you've defined your Check;

Be aware:

- Even if you deactivate Checks, if they are still present on the Suite Check table, they will be counted as 100%. This could influence your Score!

Scorable Findings

If you'll leave the Max/Min Scorable Findings fields default, the calculation will be very basic. If there is a Scan Findings sum for Count of 1 or higher for a certain Check, the score would be 0%. You can influence this behavior by using the Max Scorable Findings. Setting this field for example to 100 and having a Scan Findings sum for Count of 10 for a certain Check, the score would be 90%.

In the same way, you can also define a Min Scorable Findings. When setting this field for example to 10 and having a Scan Findings sum for Count of 10 or less for a certain Check, the score would be 100%. The score will only be calculated when the sum for Count is higher than the value set.

Scoring Scale

When leaving the Scoring Scale field on Checks default or setting it to 1, the calculation according to the Scan Finding as described above will be applied. When for a certain Check using any higher value than 1 on the Scoring Scale field though, the score for that particular Check will either be 0% or 100%. For example using the Max Scorable Findings the score for a Check could be 50%, if you would also have a Check with a score of 100%, the calculated score will be 75% (assuming the Score Weight used is equal for the Checks). Though when for the previous example where the Check scored 50% a Scoring Scale of 2 (or higher) would be used, this would actually result in 0%. So using the Scoring Scale field seems to override the usage of Max Scorable Findings. This feels a bit odd, though maybe someone has a perfectly explainable use case for this.

Score Weight

By default, each Check has the same weight. So if you have two Checks within one category where one Check scores 100% and one scores 0%, obviously the calculated score for that category will be 50%. You can influence the weight using the Score Weight field on the Suite Check table. For example for Priority 1 Checks, you might want a higher weight as for Priority 5 Checks. Or you might give Security Checks a higher weight than User Experience Checks. So for the same example, if you have two Checks within one category where one Check has a Score Weight of 2 and scores 100% and one Check has a Score Weight of 1 (or blanc) and scores 0%, the calculated score for that category will be 66,67%.

Score

In the previous paragraphs, the calculation for Score for each category has been described. The only one left… the Score for category "Overall". The Score for Overall is calculated based on the average Score of all categories, taking into consideration the Scan Findings sum for Count and the Score Weight.

Scan Statistic

You might have noticed the Scan Statistic table. Is this also part of what I described already in this article? No. Or… don't know?! I haven't found any relation between the Scores table, score* fields on Checks and Suite Checks, and the Scan Statistics table. So the Scan Statistics table remains one of the undocumented pieces of Instance Scan.

Recap

Out-of-the-box the Instance Scan does come with a score functionality. It's just not visually applied anywhere and undocumented. Also, there are several possibilities to make the calculation smarter/more specific to your Checks. Looks really nice.

Do need to mention… I'm just digging around for the undocumented. I don't know if what I found out is supported, if it's development left-overs and being deprecated in a future release, or that is still in development and might be updated and added in a future release.

---

And that's it. Hope you like it. If any questions or remarks, let me know!

Kind regards,

Mark Roethof

ServiceNow Technical Platform Architect @ Quint Technology

2x ServiceNow Developer MVP

2x ServiceNow Community MVP

---

LinkedIn