Get Started

Deliverables / SAP Companion

This guide is for UAs who are creating SAP Companion projects to support BTP products and services. When you follow this guidance, you help us create a consistent in-app help experience for our customers.

SAP Companion is mandatory for all SAP BTP cloud applications. If your product or service includes an SAP application, then make sure to configure SAP Companion.

User Journeys for UAs

Here are some ways that you can use these guidelines:

I want to create a new project. See Get Started>Plan the Development Effort and Plan the UA Effort.
I want to find technical requirements for a project. See Get Started>Plan the Development Effort.
I want to add static help content. See Static Help.
I want to add a guided tour. See Guided Tours.
I want to see the minimum requirements for BTP for SAP Companion content. See Static Help>Minimum Requirements for BTP.
I want to find new features coming for SAP Companion. See Resources>Improvements.
I want to find the tracking spreadsheet to see the progress of my project and other projects in BTP. See Resources>UA Community.
I want to find the Teams channel for the BTP SAP Community. See Resources>UA Community.

Overview

SAP Companion is SAP's in-app help framework for user assistance in web-based applications. It provides access to embedded help content. We currently provide two forms of in-app help:

Static Help: Descriptive explanations of specific screen elements directly in the application.
Guided Tours: Step-by-step process assistance with useful instructions and information for each step.

8.89; 71.44

Question mark icon in the shell bar that opens the in-app help

4.44; 87.44

Formerly called "carousel". Contains tabs for Help Topics, Guided Tours, Learning, and What's New.

48.63; 19.81

Connected to the tile; a question mark that indicates which UI element is going to be explained

56.21; 37.69

Text that opens when you select either a tile in the help panel or if you select a hotspot

53.86; 69.81

Line that connects a bubble to its tile

51.24; 81.81

The part in the help panel that provides a short explanation for the hotspot. Has a one-to-one mapping with a CMS topic

When to Use SAP Companion

In-app help content should complement other forms of assistance, like UI text and SAP Help Portal content. Each type of assistance works together to provider users with a harmonious, contextual, and holistic user experience, with relevant information made available where appropriate.

23.38; 26.94

UI text

56.41; 37.81

In-app help

19.88; 94.92

Link to SAP Help Portal

<div> <div></div> <div>(1) UI Text</div> <div>(2) In-App Help (SAP Companion)</div> <div>(3) SAP Help Portal</div> </div> <div> <div><strong>Definition</strong></div> <div>Necessary information in the UI.</div> <div>Supplemental information that can be activated in the UI.</div> <div>Holistic information available on a separate site.</div> </div> <div> <div><strong>Usage</strong></div> <div>Information user needs immediately.</div> <div> <p>Information that may provide important context for a new or intermediate user</p> <p>Can use to link to help.sap.com content for more in-depth information.</p> </div> <div>Information that is complex, comprehensive, and sufficient to onboard a brand new user.</div> </div> <div> <div><strong>Examples</strong></div> <div>Password parameters, storage limits, error resolution.</div> <div>Multiple uses of a feature, uncommon definitions, tips and tricks.</div> <div>Comprehensive task and feature information.</div> </div> <div> <div><strong>Links</strong></div> <div> <p><a href="https%3A%2F%2Fpages.github.tools.sap%2Fproduct-standards%2Fportal%2Fdocs%2Frequirements%2FUserAssistance%2FUA-060%2F">UA-060 - Product Standard for User Assistance</a></p> <p><a href="https%3A%2F%2Fhelp.sap.com%2Fdocs%2FSNG_FOR_UA%2Fe33c591ae4494a659a3f5f983c9d1161%2F188d673d8c3349ffb9136110e2fe9ed7.html%3Fstate%3DDRAFT">Text on the User Interface – The Basics | SAP Help Portal</a></p> <p><a href="https%3A%2F%2Fexperience.sap.com%2Ffiori-design-web%2Fui-text-guidelines-for-sap-fiori%2F">UI Text Guidelines for SAP Fiori</a></p> </div> <div>Use the SAP BTP guidelines on these pages.</div> <div><a href="https%3A%2F%2Fpages.github.tools.sap%2Fproduct-standards%2Fportal%2Fdocs%2Frequirements%2FUserAssistance%2FUA-070%2F">UA-070 - Product Standard for User Assistance</a></div> </div>

false

Use SAP Companion if you want to give additional, context-specific information, such as:

The meaning of a specific UI element
A guided process with information for each step
Best practices for the user
Useful links

dont

false

Don't use SAP Companion if the UI element is self-explanatory, such as:

Save button
Delete button
Edit button
Add to Favorites button

In-App Help and Built-In Support

If your UI has both Built-In Support and SAP Companion, you must make sure that both tools work together.

Keep these things in mind:

Built-In Support has a headset icon in the UI shell bar. This embedded tool focuses on the product support experience and provides information on that process. Don't put help links and learning links inside the Built-In Support panel.
In-App help has a question mark icon in the UI shell bar. This embedded tool focuses on providing help content directly in the UI from each relevant UI page.

Work with your development team to think about these things:

The Built-In Support search feature pushes customers out to the SAP Help Portal. This conflicts with SAP Companion because the static help is available inside the UI.
More guidance to come...

Plan the Development Effort

Before you start creating content for SAP Companion, you have to work with your development team to add the framework to your UI. Here are some helpful tips.

Determine if your content is going to be part of a standalone project or part of a bigger SAP Companion project. Here's a list of the projects where many UAs are working together in one SAP Companion framework. Make sure you choose the latest version of that page to see the most up-to-date list.
To help your development team estimate their effort, share this link with them. The email template inside this help topic is your first connection with the SAP Companion development team that supports you and your dev team during your project.
Make sure you know the technical requirements! You'll go through this information with your development team.
Give your development team the integration steps to follow.

Plan the UA Effort

There are a few resources that will help you get started.

Look over the general SAP guidelines as defined in Working with SAP Companion Content.
Use the checklist for creating content to help you get started.
Use these best practices to find BTP-specific guidelines and help us provide a consistent in-app help experience.
If you are writing SAP Companion content that appears inside the SAP BTP cockpit, then you are part of a bigger SAP Companion project. You need to complete these setup instructions so that your content is integrated properly.
If you want to know more about SAP Companion tool onboarding, check out Welcome (cloud.sap). This is a nice overview from the SAP Companion team.
If you want to see an overview of how to set up the project in the CCMS, refer to SAP Companion in Continuous Delivery.

Configuration Settings

Here's a list of configuration settings that should apply to your project. Keeping these consistent in our in-app help gives customers a better experience in BTP products and services.

Ask your development team to use these settings in the initialization script when first setting up SAP Companion. If they have any questions about this, they can reach out to the SAP Companion development team contact.

<div> <div>Parameter</div> <div>BTP Value</div> <div>Default Values</div> <div>What it does</div> </div> <div> <div>openImmediately</div> <div> <p>Minimize</p> <p>Let your users decide when they need help.</p> </div> <div>can be set to: full or minimized</div> <div>When set, the help pane opens automatically when the app loads.</div> </div> <div> <div>noHelpMode</div> <div> <p>Don't use the hide option.</p> <p>If you don't have specific content, at a minimum, add a link tile to SAP Help Portal.</p> </div> <div>can be set to: hide button or carousel</div> <div>When no help exists, this controls whether the empty panel opens on the Learning tab or if the help icon is not displayed.</div> </div> <div> <div>showShortDescription</div> <div>True</div> <div>default: true</div> <div> <p>Controls whether the short description for the tile is displayed in the panel.</p> <p>This information helps users quickly preview what's available so they understand where the link takes them.</p> <p>You can add key words to the short description to help users scan your content.</p> <p><strong>If you have more tiles than a user can see at once without scrolling, consider reducing the number of tiles instead of turning off the short description. Tiles can also be dynamically shown only when the UI element is visible to the user on the page, helping reduce clutter of the Companion Help Topics panel.</strong></p> </div> </div> <div> <div>showMinimizeButton</div> <div>True</div> <div>default: true</div> <div>Displays a minimize icon for the panel</div> </div> <div> <div>showCloseButton</div> <div>True</div> <div>default: true</div> <div>Displays a close icon for the panel</div> </div> <div> <div>enableTextBasedRecognition</div> <div> <p>False</p> <p>Most apps consider this an option when they want to improve recognition for elements in their UI. If this is set to true, and your UI supports multiple languages, the UA developer has to repeat hotspot assignments for each language.</p> </div> <div>default: true</div> <div>Display text-dependent recognition as an option during hotspot assignment.</div> </div> <div> <div>hotspotDefaults</div> <div>Use the green question mark for hotspot icons.</div> <div></div> <div>Sets the default hotspot icon type for the application.</div> </div> <div> <div>showHelpLogo</div> <div>False</div> <div>default: false</div> <div>Displays the SAP Companion logo and provides a link to the SAP Companion product page.</div> </div> <div> <div>logoSrc</div> <div>Don't include this</div> <div>SAP Enable Now logo.</div> <div>Makes the SAP Companion/Enable Now brand visible with the SAP Enable Now + SAP Companion logo</div> </div> <div> <div>logoUrl</div> <div>Don't include this</div> <div>URL</div> <div>Makes the SAP Companion/Enable Now brand visible. The logo is linked to the SEN product page/help.</div> </div>

Stable IDs

Before assigning hotspots, align with your developers to provide stable IDs for each UI element where in-app help is needed. Creating stable IDs is a time-consuming process for development so make sure the hotspot aligns with recommendations on when to include SAP Companion.

Why do we need stable UI elements?

Essential SAP Companion features like Guided Tours and Hotspots require reliable recognition of UI elements. SAP Companion analyzes the UI elements and their attributes and recognizes UI elements that have the potential to be a hotspot. If UI elements and their attributes are unstable, hotspots can disappear, features like Guided Tours won't work, and help topics won't be displayed.

How to ensure stable IDs?

To make a UI element stable, a dedicated attribute must be added to it in the code. This attribute ensures recognition. The best practice is to add a unique attribute named to the element. This attribute is specifically used by the SAP Companion.

UI Elements that need to be stable are:

Buttons
Table headers
Field labels
Dropdown menus

Stable ID Indicators

Hotspots should be only assigned to stable elements. The indicator for a stable ID is shown during the hotspot assignment as Excellent. Indicators such as Good or Weak mean that the UI element is unstable.

The status indicator also shows language dependencies. Here's a reference for indicators.

<div> <div>Status</div> <div>Indicator</div> <div>Color</div> </div> <div> <div>Stable</div> <div>Excellent</div> <div>Dark Green</div> </div> <div> <div>Unstable</div> <div>Good</div> <div>Light Green</div> </div> <div> <div>Unstable</div> <div>Weak</div> <div>Orange</div> </div> <div> <div>Unstable</div> <div>Language Dependent</div> <div>Blue</div> </div>

Content Security Policy

If you use images, icons, or videos, check with your developers if they have a content security policy in place. If yes, your content is not displayed, and an exception rule is required for help.sap.com.

DITA Elements

Refer to the Infrastructure Guide section on Elements for SAP Companion.