Embedded Help planning

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Embedded Help planning

    Embedded Help in ServiceNow allows you to provide contextual assistance directly within UI pages, improving user experience by delivering relevant guidance based on page, role, and other criteria. Proper planning ensures your custom help topics appear on the correct pages and are accessible to the right users.

    Show full answer Show less

    Key Details for Planning Embedded Help

    • Page: Identify the exact UI page name from the URL where the help will appear. Include any special characters like a leading dollar sign if present.
    • Modifier: Choose between Normal (visible to users with appropriate roles) and Setup (visible during Guided Setup). You can repurpose Setup content for Normal use.
    • Qualifier: Use qualifiers to customize help for common pages used across multiple applications, such as homepage modules, enabling tailored content per context.
    • Role: Specify the lowest role required to view the help topic. Users with higher roles that include this role will also see the content unless more specific content exists for their role.
    • Product: Write content primarily for the Enterprise product version. Express topics can be copied and modified if needed.
    • Version: Base system content usually targets the current software version. For custom applications or organizational processes, select “All” to apply broadly.
    • Domain: When using domain separation, assign the help content to the appropriate domain.
    • ServiceNow Help: Base system topics are read-only. To customize, create copies for your own content.
    • Content Formatting: Use available formatting tools but note that images are not supported, and videos must be embedded via source code with supported platforms like YouTube or Vimeo. Related links require full URLs, and highlight text usage is discouraged due to theme variability.

    Additional Considerations

    • Changes to embedded help are not automatically deployed across instances and are excluded from update sets to prevent unintended overwrites.
    • Qualifiers enable administrators to tailor help content on shared pages for different contexts.
    • Role targeting ensures users see only relevant help content based on their access privileges.
    • Internationalization support allows localization of embedded help content in multiple languages to serve global users effectively.

    Practical Benefits for ServiceNow Customers

    By carefully planning embedded help topics with attention to page names, roles, and qualifiers, you can deliver precise, role-specific guidance within the ServiceNow UI. This improves adoption, reduces user confusion, and supports organizational processes. The ability to localize content and embed multimedia enhances accessibility and engagement globally. Understanding the constraints around content deployment and formatting ensures you maintain control over updates and presentation quality.

    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 correct 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 Service Catalog home page
    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.

    Qualifier
    Identify pages you want custom help for that are used in many applications. For example the home.do page opens for every homepage module and for many dashboard modules. The embedded help administrator can use qualifiers to customize content for a common page in the instance.
    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.
    Domain
    If your organization uses domain separation and customizes help content, specify the domain the content applies to.
    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 in embedded help content.
    • To embed video, you must code the video information in the source code <<>> view. Video content from YouTube and Vimeo are supported.
    • 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.
    • Any changes you make to embedded help are not automatically deployed to another instance.
    • Changes to the embedded help table are not captured in update sets, update_sync=false is set intentionally.