Embedded Help - An underutilized hero
ServiceNow is a platform with vast capabilities, where every opportunity of feature rich expansion is only a mouse-click away. The most common issue: How do companies keep up with documentation?
This blog article will introduce you to one of the most underutilized, yet impactful features of ServiceNow. I know, I know, documentation is not the most exciting topic. Nor is it revolutionary or even new. But what if you could:
- Document everything(!) directly in ServiceNow
- Make documentation visible & available exactly where it is needed - on custom/configured records
- Use build in versioning
And probably the best thing ever:
Document everything in-style & in the same place as ServiceNow does ootb - with every feature and function.
What if - as with configuration & customization - documentation for everything would just be one mouse-click away?
Excited? Welcome to the party.
The unsung hero-icon
Forget the Superman-S, the Batman-Bat or even the ServiceNow logo. Let me introduce you to the actual unsung hero-icon you've always seen but never noticed:
What's that? This, ladies and gentlemen, is the access to unlimited knowledge. Welcome to embedded help.
What this icon does is - wherever you are in the instance (this includes any workspace) - list embedded help. All of the embedded help linked to wherever you are at this very moment.
You read that correctly. This does not just list random advice. Or tips & tricks (although you could use it for that). It only lists embedded help records which are linked to where you are at this very moment. Looking at the workspace? Workspace help. Some property page? Property help. A specific record - any specific record? Help linked to that exact record. Every time. For everyone.
For everyone? Well, not exactly. Because you can restrict embedded help records per role! Your admin should see the technical documentation? Sure. ITIL users should have the process documentation? Yes! You can do this!
Seems like it is just getting better and better? Welcome on board! But before we all get too excited, let me introduce the one limitation.
Limited availability
In some parts of the platform this feature is not always available. Namely whenever you are using one of the Builders (UI Builder, Flow designer etc.). In these cases you won't have direct access to embedded help. But there is a solution for this as well, as embedded help as a foundational layer, which you should be using already.
The foundation layer - my approach to documentation
It would be kind of cumbersome, if you would now need to replicate all the documentation you already have. Especially if that documentation is already versioned. Kind of pointless introducing yet another area where you can store documentation content. Don't we have the knowledge base for this already?
Well, good news (they just keep on coming):
The foundation layer of embedded help is (or at least can be) the knowledge base. So if you have been documenting processes, technical definition and implementations there already: You are so close.
So how can you close the gap?
Closing the gap
And here we are. All of this leading to the one part of this article, where I actually go into the embedded help. Because closing the gap is as easy as creating embedded help. Starting with what you already have and moving forward with setting a new standard.
Let's start by looking at the currently available embedded help:
Huh? Over 3000 records? Yes! Because ServiceNow is already using this. Remember when I said (or wrote, whatever) that you can use this in the same way ServiceNow does? This is all ServiceNow documentation. Every single time you open some random page in ServiceNow it likely has an embedded help content. Lets look at a common example to highlight how this works:
I will just run through the most important parts:
- Page: Specific page within ServiceNow, where this should be available (where to show it [before the ".do" part in the URL])
- Qualifier: Where should it be shown? (add an embedded help qualifier to boil down to a handful of records - or just a single one)
- Mode: Guided Setup or "Normal" (use "Normal" at all times)
- Content: The content of the Embedded Help
- Version: Linked version (you can leave this empty)
- Role: Limit the embedded help to a role (for technical documentation I always recommend a developer/admin role)
But hold on? Where is my knowledge base linkage?
Now, what you are looking at is an html formatted content page. You can do whatever you want here (with the exception of pictures for some reason) - even videos. But looking at the way ServiceNow utilizes this, all of these are very short text. This becomes more relevant, when we actually click on our hero icon:
Yes, you are seeing this correctly. Even embedded help has embedded help!
These entries are for user guidance. Not for the actual documentation. So how do we actually close the gap?
Links. Just use a short text and link to the knowledge base article (note: in knowledge base articles there are 2 links: One which always shows the view of published content (the one we want) and another one, which only shows the current version).
And thats it! That is all.
Want embedded help for whenever someone looks at incidents? Set the page to "incident".
Want embedded help to show the documentation of your embedded help properties? Create an embedded help qualifier to filter the URL to the specific properties page & set the page to "system_properties_ui".
Want to link to one specific knowledge base article for one single property you've created? Set the page to "sys_properties" and create an embedded help qualifier to link to just one record.
Want an example for embedded help qualifiers?
Embedded Help Qualifiers
This one qualifier is used whenever a "pa_indicators" record (see path) is opened with the additional query parameter "sys_id=-1&sysparm_view=Automated" (see Query Parameter). It applies to any embedded help where the qualifier value is set to "new_automated_indicator". Overall, the resulting embedded help will only show whenever someone creates a new automated performance analytics indicator.
You can use qualifiers to reference just one specific script include, or business rule, or UI page record, or catalog item. Or anything you would want to document.
That's it folks
And that's it. Now your hero-icon will link to the knowledge base - with the versioning benefits of the knowledge base. Or it will guide users & fellow developers alike (then link to the knowledge base). Or both. That closes the gap. Sure, you will have to add some generic content message so the links don't just look empty. But thats what you have templates for. You know about templates, right? You do use them? You use them for your development? Right? ... Maybe that's going to be my next article...
Wait, that's not it. Why do I use this for technical documentation? Because - and hold on to your chairs now - this all is tracked AUTOMATICALLY in update sets. You - yes you - can implement this into your development routine. No more word files. Well, you can just link to word files if you wanted to.
Did I cover everything? Probably not. But let's get started. Let's document ServiceNow in ServiceNow as ServiceNow would:
One mouse-click away. Role based. Linked down to the smallest accurate entity. Versioned. Tracked in Update sets. Release-Depended (optional). Making the world of work work better, not just for you, but for everyone else, too.
