Embedded help planning

Before writing custom embedded help, plan the content and note the information used in the Embedded Help form. Careful planning ensures that the topic appears for the right page and role.

Each UI page can display embedded help, specified in the Page field as shown in the following example.

Figure 1. Embedded help topic for the Catalog Items list view
Page name in URL pointing to page name in form

In planning for embedded help topics, consider how the following fields are used and note the values that you need for your custom topics.

Page
Identify and note the UI page name which is found in the URL when the page is displayed as shown. If the page name begins with a dollar sign, such as $mid_server_user, include the dollar sign in the page name. Before you write an embedded help topic for the page, search for the page name to locate a file you can copy.
Modifier
  • Normal content appears for any user with the appropriate role who navigates to the page.
  • Setup content appears when the page is accessed from a link in Guided Setup.

Many embedded help topics in the base system are for Guided Setup. You can copy Setup content and change the Modifier to Normal to quickly provide help for all users.

Role
Specify the lowest level role to provide access to this embedded help topic. All roles that contain the role also see the content, unless another topic targeted to their role exists for the same page.

For example, if you add embedded help content for the itil role that describes your business process for entering incidents, the itil_admin role also sees the content. If you write a different topic with the itil_admin role, the itil_admin sees that content instead of the itil content.

Product
Write content only for the Enterprise topic. You can copy an Express topic and change this field to Enterprise if appropriate.
Version
Base system content is typically specified to the current software version. If you are editing the content for a custom application or to provide information relevant to your organization business process, select All.
ServiceNow Help
If the check box is selected, this field indicates a base system topic. You cannot edit a base system topic, but you can create a copy to add custom content.
Content
You can use the formatting tools to format the content. The following list describes the limitations.
  • You cannot include images or videos in embedded help content.
  • To add a related information link, you must use a full URL, not a relative URL.
  • Best practice is not to use the highlight text tool, as the color may make text unreadable depending on the theme the user has selected.