Health Tracker FAQ

Integration with HealthScan for ServiceNow Customers and

Partners
Table of Contents
About this document................................................................................................................................. 2
Disclaimer .................................................................................................................................................... 2
FAQs – Before Installing ............................................................................................................................. 3
What is HealthScan? .............................................................................................................................. 3
What is Health Tracker?.......................................................................................................................... 3
What are the key features of Health Tracker? .................................................................................... 3
Why should I use Health Tracker? ......................................................................................................... 4
Who can use Health Tracker? ............................................................................................................... 5
What are the pre-requisites for using Health Tracker? ....................................................................... 5
Do I need additional licenses or subscriptions? .................................................................................. 5
Application Components ...................................................................................................................... 5
How do I get access to HealthScan?................................................................................................... 5
How do I get the latest version of Health Tracker? ............................................................................. 5
How is Health Tracker supported and maintained? ........................................................................... 6
How do I get help? ................................................................................................................................. 6
What API communications take place? .............................................................................................. 6
Is the “Scaled Agile Framework (essential)” app compatible? ........................................................ 6
FAQs – Install and Configure Health Tracker........................................................................................... 7
What are the first steps with Health Tracker? ...................................................................................... 7
How do I use and obtain an authentication token?.......................................................................... 7
Can I modify the Health Tracker app? ................................................................................................ 8
How do extension points work? ............................................................................................................ 8
What are the settings for Health Tracker? ........................................................................................... 8
FAQs – Reporting and Work Process ........................................................................................................ 9
Why does the dashboard focus on “Act” findings? ........................................................................... 9
Can I import older scans for insightful trending? ................................................................................ 9
How should I assign findings to stories ? ............................................................................................... 9
When should scans be run and findings fixed?................................................................................. 10
FAQs – Miscellaneous .............................................................................................................................. 11
I have an issue; how can I move forward (troubleshooting)? ........................................................ 11
What are the future plans for Health Tracker? .................................................................................. 12
How can I contribute? ......................................................................................................................... 12
Release Notes ........................................................................................................................................... 13
About this document
This document serves to support common questions and queries when using the Health Tracker
application. HealthScan support is not covered here.
Further resources and up-to-date information can be found here:
https://developer.servicenow.com/app.do#!/share/contents/4953204_health_tracker

Disclaimer
The FAQs serve as a guide to aid in troubleshooting efforts. Some FAQs may become out of date.
Health Tracker is an application that is constantly evolving. Always thoroughly test features and
updates on a non-production instance first. There is no warranty or guarantee from ServiceNow or
the Health Tracker developers and contributors.
Although Health Tracker is well encapsulated, it is the responsibility of the ServiceNow customer or
partner using the application to verify it’s use in a production environment.
Customization of the Health Tracker application is not supported and should be avoided.
Exceptions may exist for certain configuration requirements. Seek professional advice before
attempting any customization of the application.
Install at your own risk. Use best practice test and deployment approaches.

2
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
FAQs – Before Installing
What is HealthScan?
ServiceNow© HealthScan is a tool that helps you better understand and improve your instance
health. Built on best practice definitions from thousands of instances, it quickly scans your
ServiceNow platform and provides data points across five key categories: security, upgrades,
performance, ease of management and user experience. Each scan runs through a list of
definitions and generates “Findings” (results) as applicable for further follow up and review.
Direct access is not available to non-ServiceNow personnel. ServiceNow Customer Outcomes or
Customer Success must be engaged to run scans.
What is Health Tracker?
Health Tracker is an application to help optimize the process of managing HealthScan results.
Starting a scan and importing the results are key features. Once imported, results can be easily
assessed, tracked, prioritized and assigned to teams to work on and remediate. This streamlined
approach encourages reduction of technical debt and overall higher configuration health.
The focus is on continual improvement and not one-off “scan and fix” sessions.
What are the key features of Health Tracker?
• Run “Sprint Scans“ (where access has been granted)
• Import findings from scans
• Report on findings (Dashboard with ~5 tabs and ~15 reports)
• Assign findings to stories
• Ignore findings (with reason)

Additionally:
• Manage user access via 2 provided roles (additional “admin” & “user” roles)
• Extend the Application (via pre-defined extension points)

3
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
Why should I use Health Tracker?
Scanning instances to assess configuration health is an on-going activity. There is a never ending
flow of “findings” to address. A streamlined approach to reviewing and assigning developers to
address findings is required.
Implementation teams without Health Tracker have a reasonable overhead and manual effort to
constantly process findings. Health Tracker improves transparency and efficiency in reducing the
number of findings and reduces manual effort at every stage of the process.
Below is a list of activities that show where Health Tracker adds value.

Activity/Process Health Tracker Benefit Comment

Sprint scan and custom

Contacting ServiceNow scan (for update sets)
personnel and requesting a Scan at will supported provided
scan ServiceNow is engaged in
a project.

Requesting results from scan Automated Import

Massaging the data (excel)

Automated Import with
and/or Importing and
appropriate fields
processing

Reporting: identifying what to Pre-configured dashboard

work on focusing on “Act” findings

Dashboard shows findings

scheduled into
Planning into sprints past/present/future sprints.
Findings can be easily allocated
to stories.

Dashboard provides overview

Track status of findings based on finding state (and
story)

Future feature to sync the

Consolidated list of ignored
Ignoring findings ignore state back to
findings transparently tracked
HealthScan system

Import logic detects if previous

findings are no longer present
Confirm remediated findings
and tracks this against the
previous finding.

Obtain overview of scan

Import older scans at will
history

4
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
Who can use Health Tracker?
The application can be installed by anyone but usage is restricted. Starting a scan and
automatically importing findings requires an authentication token which is only available from
ServiceNow via:
• Customer Outcomes
• Customer Success

See also the pre-requisites & license sections below.

What are the pre-requisites for using Health Tracker?
• London patch 6 or greater
• *Agile Development v1+ (for reporting and management of imported findings)
• Active ServiceNow Customer Outcomes engagement or Customer Success package
• Allowed inbound and outbound connections to the HealthScan instance

* Scans can be started and findings still imported without needing Agile Development.
Do I need additional licenses or subscriptions?
The application is supporting the Agile Development process and leverages the story table to
remediate findings. An impact on licensing is to be expected as the application requires ITBM &
Platform App Engine SKUs. Please consult with your ServiceNow account representative before
installing the application to avoid license compliance issues.
Note: In addition, be aware that the application requires an active ServiceNow Customer
Outcomes or Customer Success engagement to be used properly.
Application Components
The Health Tracker scoped application consists of:
• 2 roles (x_snc_ht.admin and x_snc_ht.user)
• 5 tables (1 of which is an import table)
• Inbound and outbound REST configuration
• Dashboards and reports

How do I get access to HealthScan?

Access to the HealthScan system is currently restricted to ServiceNow staff including:
• Customer Outcomes
• Customer Success

The Health Tracker application can be used to start a scan and obtain results from the HealthScan
system. An authentication token is required which can only be generated and provided by
ServiceNow.
How do I get the latest version of Health Tracker?
The latest version is available on Share:
https://developer.servicenow.com/app.do#!/share/contents/4953204_health_tracker

5
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
Before applying the latest version, please backup any Local customization you have made on
the app.
Always test the upgrade on a non-production instance.

How is Health Tracker supported and maintained?

There is no guarantee of support, fixes, patches or updates. Use the discussion mechanism that
the share site provides.
How do I get help?
Please use the discussion option on the Share website:
https://developer.servicenow.com/app.do#!/share/contents/4953204_health_tracker

Please note that customizations are not supported, however any issue encountered with the
native application code can be mentioned in the discussion section. Also consider posting to the
community.
What API communications take place?
Inbound
• Webhook to inform that scan has completed
• Run definition (HealthScan instance automated task)

Outbound
• Start scan
• Send definition result back (standard HealthScan instance automated task)
• Get findings
• Ignore and un-ignore finding (future topic)
• Renew Token

Is the “Scaled Agile Framework (essential)” app compatible?

SAFe is not yet supported but future plans to support this are in the works.
Currently the “Parent” field on the finding could be used to link to SAFe stories.

6
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
FAQs – Install and Configure Health Tracker
What are the first steps with Health Tracker?
1. Install the app (see pre-requisites above)
a. See troubleshooting section if any error is encountered.
2. Create a record in the provided instances table for each instance that should be scanned
3. Request an access token for each of the instances you have defined (see below)
4. Enter the token information for the appropriate instances
5. Populate the system property “x_snc_ht.main_instance” with the instance (URL) name where
users will start scans from.
6. Click on “New Scan“ and select the instance/token to use to start the scan
7. When ready, click “Start Scan”
8. When the scan has completed the results are available via the Health Tracker dashboard or
findings list (e.g. the “All” module)
9. Find a finding to address, open the record and choose a story to assign it to. Tip: Assign multiple
findings to one story via list edit mode from any findings list.
10. Add the existing related list to the story form to show all findings that will be addressed as
part of that story.

Note: If requesting new tokens it is likely that permission to export results from the scan is not yet
granted. The scan will run and complete properly but an one-time approval will need to be
obtained from ServiceNow to export the results. Subsequent scans will not require this approval.
See also “I have an issue; how can I move forward (troubleshooting)?”
How do I use and obtain an authentication token?
A ServiceNow representative/consultant assigned to your project will be able request a token on
your behalf provided you meet the minimum requirements. Ensure you provide a list of instances
to be scanned. A token will be generated for each instance.
Follow the steps below once a token and expiry date (per instance) has been obtained:
1. In the Health Tracker application create a new or locate an existing ServiceNow instance
record
a. For new records, saving the record reveals the tokens related list
2. Click the “New” button on the tokens related list and fill out the form:
a. Token (the authentication key)
b. Expiry (the default expiry when the token will stop working)
c. Owned By (optional but will help with token maintenance)

Tokens expire after 5 days by default. Tokens can be renewed on demand which will generate a
new token string. A scheduled job runs daily to auto-renew tokens prior to expiry date. Tokens can
only be renewed a maximum of 5 times. This is a HealthScan constraint.
Note: do not use the same token on multiple instances where the Health Tracker is present. This will
cause the additional instances to invalidate the token present on the other instances.
Note: as per above, ensure that post-clone activities remove tokens from the target instance.

7
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
Can I modify the Health Tracker app?
There are some safe customizations and not so safe customizations that can be made. Various
settings have been exposed to help reduce the need to modify the app. Additionally, extension
points can be used to enhance or modify certain values and processes. Modify at your own risk.
It is favorable to suggest ideas or contribute your solutions on the share discussion page. Also
consider providing a community post.
https://developer.servicenow.com/app.do#!/share/contents/4953204_health_tracker

How do extension points work?

One of the key advantages of the Health Tracker application is the ability to work on findings by
associating them to stories. This link with Agile Development helps the implementation team plan
work into sprints and track the progress on the remediation of findings. A mapping exists between
story state value and the finding state value to update the finding state when the story state
changes. This mapping can be overwritten with custom logic using the pre-defined extension
point.
The solution provides an extension point FindingStorySynchronizer and an instantiation
FindingStorySynchronizerInstance of that point (de-activated) in the default package. This
instantiation point serves as a template to be copied and used for customization purposes. Simply
duplicate the sample record into the global scope and define the appropriate logic.
See also:
• https://docs.servicenow.com/bundle/london-application-
development/page/build/applications/concept/extension-points.html
• https://community.servicenow.com/community?id=community_blog&sys_id=f68a4308db88a
b40200f0b55ca96191a

What are the settings for Health Tracker?

To access all system properties and view their usage navigate to the below address:
<instance>/sys_properties_list.do?sysparm_query=nameSTARTSWITHx_snc_ht
A properties module exists in the Health Tracker app for convenience.

8
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
FAQs – Reporting and Work Process
Why does the dashboard focus on “Act” findings?
Findings currently have a rating of either “Act”, “Recommend” or “Discuss”. Findings with the “Act”
rating are the most critical findings and should therefore be addressed first. It is still possible to see
and access stats on non-act findings. Custom reports can also be created as needed.
Note that the HealthScan team is constantly developing new definitions (aka rules) and some
may provide more results than expected when released. Focusing on “Act” findings generally
limits exposure to “false positives” and confusing metrics.
Can I import older scans for insightful trending?
It is possible to import older scans providing that newer scans are not already imported. I.e., import
all scans starting from oldest to newest. Importing in a different order will result in findings being
unintentionally marked as “absent from scan” and “confirmed closed by scan”.
To import an existing scan, ensure that the fields “External scan ID” and “External number” on the
scan record are filled with the appropriate values before clicking “Start Scan”. These values can
be obtained from the HealthScan system via an authorized user. Note that scans can only be
accessed where the scan requester is the same as the authentication token owner. Scans started
by any other user than what the token is authorized for will not be accessible.
How should I assign findings to stories ?
There are various options that can be evaluated on a case by case basis.
1. Consider assigning findings by developer that last worked on the affected record (“source
updated by”). They may have the most insight and therefore provide the quickest turnaround
time.
2. Assign based on criticality using the “rating” value starting with the act stories. Consider starting
with security or performance findings first.
3. Assign based on application area. E.g., assign all incident management related findings to 1+
stories.
4. Assign based on technical solution. E.g., if a custom integration exists that overlaps cross-
product, rating or category then assign these together.

It’s a good idea to group similar findings together by assigning them to the same story. Consider
grouping by category or developer. Create stories for future sprints and aim to invest >=10% of
developer capacity working on these stories each sprint.

9
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
When should scans be run and findings fixed?
Consider the following options and choose a solution that best matches the maturity of the team.
A combination of all 3 will provide the highest level of assurance.
a) Prior to release (low level of maturity)
When approaching the release readiness phase (prior to a deployment), conduct a
scan of the instance and attach all relevant/critical findings to a story like “Pre-release
health improvements”. The story should be completed prior to UAT.
b) Post-sprint (medium level of maturity)
After the sprint end date is reached, run a scan and assess and remediate the findings as
part of the next sprint. Each sprint will require 1 or more placeholder stories like “Address
improvements for previous sprint”. Estimate 10% of the sprint capacity (minimum 6 hours)
for this activity. This has the advantage of combining enhancements or feedback from
the previous sprint with technical improvements.
c) During story development (high level of maturity)
Prior to moving on from “work in progress” and conducting a peer review, initiative a
custom scan of the update set related to the story/sprint work. The scan output can be
used to improve the implementation or analyzed as part of the peer review.
Remediation takes place as part of story development. Complex or time consuming
changes can still be assigned to a new story for the next sprint.

10
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
FAQs – Miscellaneous
I have an issue; how can I move forward (troubleshooting)?
Use the following troubleshooting process to first determine the route cause.
If app installation related, then test the following:
a. If the error is related to sys_ui_list entries for the x_snc_ht_findings table (image below)
then: Skip all remote update

If scan related, then test the following:

b. Is there a failure reason in the “Notes” field on the scan instance?
c. Is the authentication token still active or has it expired? Does the “renew token”
button on the token work?
d. Did a recent clone take place which causes tokens on one instance to become
invalidated during auto-renewal?
e. Is the scan being created on the HealthScan instance? Confirm the “External
number” and “sys ID” with ServiceNow personnel.
f. Did the scan complete? Scans that don’t complete are due to an issue on the
HealthScan system, not the Health Tracker app.
g. Do the logs show any errors or warnings?*
h. If using a scan type of “custom”, ensure that the update set sys_id provided is valid
and exists with updates on the target instance. It may have already been merged to
another update set. Also confirm that the access token in use has been granted by a
user that has the role to execute custom scans.

If finding import related then test the following:

a. Is there a failure message in the scan record “Notes” field?**
b. Do the logs show any errors or warnings?*
c. Are there import records in the table x_snc_ht_findings_import?
d. Try changing the import property to allow duplicate findings to be imported.+

11
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
 e. Is there a reason the findings on the HealthScan instance and the imported number
of findings do not match? Eg, no new findings or definitions incorrectly generating
duplicate findings. ++

If reporting/dashboard related then test the following:

a. Confirm (via click through to the list) the queries and record data (Eg. active + state
values).
b. Try creating the report you expect to see if the underlying data is accurate or not

* Hint, change the debug level for the Health Tracker system property. All Health Tracker info and
debug messages will be prefixed with “[x_snc_ht]”.
** The retrieval of results for the first time (per instance) will require a one-time approval (per
token per instance) from the Engagement Manager and representatives assigned to the
customer project. This is a semi-automated process which a ServiceNow consultant must start
from the HealthScan instance scan dashboard ("Request Export” button).
+ See the settings list for available options.
The Health Tracker app tries to solve some issues that the HealthScan instance may have
++

when generating findings. Do not expect the numbers to match up!

Finding state not changing as expected:

a. Check if the story state field has custom values other than those provided in the
baseline configuration for Agile Development.
b. Check for custom extension points that may have been added which would override
the sync between stories and findings.
c. Confirm if business rules have been disabled. Eg BRs that fire when a story changes
state or a story is assigned to a finding. Also ensure that if stories are being updated
via script that the setWorkflow(false) is not being used.

What are the future plans for Health Tracker?

A simple backlog exists to add features and attend to edge cases. There is no commitment to
updates or release schedule. Keep up-to-date by checking for new versions on the Share site.
As of May 2019 there are currently 10 features on the backlog.
How can I contribute?
Contribution is highly encouraged. Feedback on all levels including ideas, documentation, bugs,
technical changes and solutions will be whole heartedly accepted and reviewed.
Start with raising awareness on the discussion page in the Share site:
https://developer.servicenow.com/app.do#!/share/contents/4953204_health_tracker

12
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
Release Notes
v1.08 (in development)

v1.07 (2020-01-22)
Additions:
• Custom scan: Update set scans are now using the sprint scan + scorecard + automated scan
portfolios instead of scorecard only. The porftolios are defined in the new system property:
x_snc_ht.scan.custom.default_portfolios
• Scorecard scan: Possibility to run scorecard scans. From the scan record the Scorecard type
can be selected.
• Automated Weekly scans: Health Tracker is now launching a Weekly scorecard scan
automatically! The scan is created on the default instance (Instance related to the default
token). If no default token is present, no scan is launched.
• Access remote dashboard (on health scan system): This feature is mainly designed for
scorecard scans (since categories score cannot be fetched by API) but can be used for all
types of scan.
On any scan record one can Right Click -> Open Remote Scan

Fixes:
• Duplicate scan: When scan is duplicated, the “notes” field is now cleared.

13
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
v1.06 (2019-06-04)
Additions:
• Restrict schedule job that renews tokens to only run on the “main” instance
o See new required property “x_snc_ht.main_instance”
• Reports updated: improves reporting on last scan
• New Watchlist fields on instance and scan records. The watchlist value on the scan record is
by default fetched from the instance watchlist. (see also the system property alternative:
x_snc_ht.scan.notify_emails)
• New button on the scan record to send a scan summary to the (new) watchlist
• Ux: added scan retry UI action for failed scan
o Should help with issues where export from the HS system first requires approval. After
the one-time approval is obtained, click the retry button.
• Ux: added module link to access HT system properties
• Allow multiple update sets to be entered in one scan record

Fixes:
• Access: better restrict the app and module with HT roles
• Update token renew logic to only renew just before the token expires
o Helps reduce the frequency of new token requests due to the HS renew limit.
• The HT prop for logging level no longer show INFO messages when set to "NONE"
• De-activate/remove links to legacy HT instance

v1.0.5 (2019-04-12)
Additions:
• Work note added to story when finding is closed
• Reports:
o Add a flag "most recent" to support reporting on the most recent sprint scan
o Added/changed reports on "Trend" and "Scans" tabs (feedback welcome... run lots
of scans over time first)
• Improve Ux (auto-complete) when searching for stories from the finding form
• Improve Ux (slushbucket) when finding findings to add to a story (the dashboard tab "Needs
Review" is still a much better Ux)
• Added related lists to improve Ux and assigning stories:
o Findings Related by same definition
o Findings Related by same update set
o Findings Related by same source record
o Findings Related by same developer
o All active Findings (on the scan record)
Fixes:
• Clear closed_on field when finding is un-ignored
• Historical import UI action missing "scan start" confirmation message
• Improved stability to auto-closing existing findings when applicable

14
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.
v1.0.4 (2019-04-03)
Additions
• Improved ignore support with "ignore reason" field
• Save HealthScan finding sys_Id for later use with API to ignore findings
• Add link to view finding in HealthScan instance (for ServiceNow personnel)

Fixes
• Ensure findings that are ignored are not included in future scans

v1.0.3 (2019-04-01)
Additions
• Reload scan form when scan completes or fails
• Form Ux improvements
• Added guided tours and improved support
• Added embedded help

v1.0.2 (2019-04-01)
• Extension points

v1.0.1 (2019-03-21)
• Enhancing scanning API
• Data model improvements

v1.0.0 (2019-03-14)
• Core functionalities
o Scan API
o data model (token, findings and instance)

15
© 2019 ServiceNow, Inc. All rights reserved.

ServiceNow, the ServiceNow logo, Now, and other ServiceNow marks are trademarks and/or registered trademarks of ServiceNow, Inc., in the United States
and/or other countries. Other company names, product names, and logos may be trademarks of the respective companies with which they are associated.