Updated: February 23, 2023

Situation Handling Framework – UI Text Guidelines

Intro

This guideline applies to the texts that you can define for Situation Handling. The guidelines apply to the standard framework and the extended framework. The goal of this guideline is to provide you with formulation patterns and best practices to support you when creating text.

In general, there are two categories:

Configuration texts:

Configuration texts describe technical objects defined by extensibility specialists and key users. Meaningful names and proper descriptions support the user in modeling situations using these apps:

  • Manage Situation Types
  • Manage Situation Types – Extended
  • Manage Situation Scenarios
  • Manage Situation Objects

End user texts:

End user texts describe the business situation displayed to the users who are responsible for solving a situation. A precise description and recommendations on how to solve a situation support the user and ultimately optimize the business process. The user texts are displayed through various channels:

  • My Situations
  • My Situations – Extended
  • SAP Fiori launchpad notifications
  • Email notifications
  • Related business apps

Configuration Texts

You configure Situation Handling in a layered approach:

  • Standard framework: situation templates and situation types
  • Extended framework: situation objects, situation scenarios, situation templates, and situation types

Configuration texts describe these objects and their elements. The items and elements are visible throughout the various layers. Therefore, they should be meaningful and consistent to help extensibility specialists and key users choosing the relevant elements.

There are three types of configuration text:

These elements are often used in combination. Make sure that they complement each other.

Don’t use the terms “object”, “scenario”, “situation”, “situation handling”, or “notification” (or abbreviations or variants thereof, such as “sit” ). The use is already implicit from the context of the object.

Example of configuration texts:<br />
(1) ID<br />
(2) Name<br />
(3) Description
Example of configuration texts:
(1) ID
(2) Name
(3) Description

ID

Use

IDs are non-translatable unique object IDs in the system (such as situation object or situation scenario) and their elements (such as structures or events).

Guidelines

  • Use a combination of a prefix and a descriptive name.
  • Ensure that the prefixes are meaningful and used consistently.
  • Avoid abbreviations in descriptive names unless needed because of length limitations.

IDs for Situation Objects, Situation Scenarios, Situation Templates, and Situation Types

  • Use a prefix that is commonly known to SAP experts and represents the business area or industry it’s used for. For example, you want to clearly distinguish between Sales Order, Purchase Order, and Service Order.
  • If required, you can also combine prefixes to express subareas, such as FIN_APM for Advanced Payment Management in Finance.

Example

Prefixes for business areas Prefixes for industries
CA_ for Cross Applications
ENG_ for R&D / Engineering
FIN_ for Finance
MAN_ for Manufacturing
PROC_ for Procurement
SD_ for Sales…
ISA_ for Automotive
ISAD_ for Defense
ISPRS_ for Professional Services
PSM_ for Public Sector…


  • After the prefix, use a descriptive name.


  • Situation object: SD_SALES_QUOTATION
  • Situation scenario: SD_QUOTATION_VALIDITY
  • Situation template: SD_OBSOLETE_SALES_QUOTATION


IDs for Elements in Situation Objects

  • The elements you define in situation objects are used in all other Situation Handling configuration apps. Therefore, use the naming pattern of prefix and meaningful name as described above.
  • The IDs used in situation objects are local IDs, which means they’re not unique. We recommend that you use the following prefixes:


Element Prefix Example
Value Help Service ID VH_ VH_SALES
Structure ID CDS_ for CDS views
MEM_ for in memory structures
CDS_SALESORDERITEM
MEM_SYSTEMMESSAGES
Event ID EV_ EV_CHANGED
Navigation ID NAV_ NAV_MANAGE_SALESORDER
Callback ID CB_ CB_DELETE_SALESORDERITEM
Action ID ACT_ ACT_MANAGE_SALESORDER

Name

Use

In most cases, names describe the object IDs in the system and their elements in a short and human-readable way. Like IDs, they are visible in all Situation Handling configuration apps. Names are not unique.


Guidelines

  • Use nouns.
  • Use title case.
  • Explain the object referring to the ID. You can use the same structure you used in the ID without the business area or industry prefix: Example ID: WLF_FCADOC, corresponding name: Freight Cost Allocation Document.
  • Remember not to mention the terms “object”, “scenario”, “situation”, “situation handling”, or “notification” (or abbreviations or variants thereof, such as “sit”).
  • Use a meaningful text that will help the user find the right object in the subsequent configuration steps. Don’t just copy the ID.
  • Be as concise as possible to save space. Leave out unnecessary articles or verbs.
  • Don’t end with a period.

Examples

  • Situation object: Sales Quotation
  • Situation scenario: Sales Quotation Validity
  • Situation template: Obsolete Sales Quotation

Name for Trigger

A special case is the trigger name because it describes an action that has already been performed. Additionally, the trigger refers to the object on which the action has been performed. There are two types of triggers:


  • Event-based trigger name
    • Use a noun to name the corresponding trigger object, for example: Contract
    • Use a participle to describe the action that has happened, for example: Created

Example

  • Contract Created



  • Batch-based trigger name
    • Because batches are periodically performed checks, use the pattern: Periodical – object – Check

Example

  • Periodical Contract Check

Description

Use

The description provides additional details about objects in the system and their elements, mostly to enhance an ID and name. Descriptions are visible in the various Situation Handling configuration apps.


Guidelines

For guidelines about the Button Description and Situation Text Description fields, refer to End User Texts > Buttons or End User Texts > Situation Display.

  • Don’t just copy the name.
  • Start with a verb.
  • If there are similar objects, make sure you provide a description that clearly distinguishes them and emphasize the differences.
  • End with a period.

Examples

  • Situation object: Describe how this object is used in Situation Handling and which of its features are relevant. Example name: Collector, corresponding description: Contains all system messages that are relevant for Financial Accounting.
  • Situation scenario: Describe the business scope, which is covered by the scenario: Covers all application jobs in Financial Accounting and its associated system messages that can be used to monitor occurring messages.
  • Situation template: Describe the specific use case: Inform the financial accounting specialist if there are issues in payment dunning runs.

End User Texts

There are three types of text that you can create and that are displayed to end users:

  • Situation Display: information about the situation displayed in apps, such as notifications, or in public channels, such as email.
  • Buttons: texts in buttons that help end users solve a situation.
  • Labels: texts for columns and sections that help end users to better understand the context of a situation.

Situation Display

In the Situation Display section of the Manage Situation Types or Manage Situation Types – Extended app, you can specify the texts with which users are informed about situations. This includes the following texts:

  • Situation texts displayed in the My Situations app (when defined in the Manage Situation Types app) and My Situations – Extended app (when defined in the Manage Situation Types – Extended app)
  • Situation texts displayed directly in the corresponding business app
  • Notification texts shown on SAP Fiori launchpad
  • Notification texts shown in public channels, such as email

The texts, except public notification channels, can embed variables that contain information from the anchor object, the trigger object, or from the event.

Title


Use

The title summarizes the situation. It helps end users to see, at a glance, what the situation is about. Text fields have different labels in the configuration apps of the standard framework and the extended framework of Situation Handling.

In the Manage Situation Types app, the same title is used for both in-app messages and notification texts on SAP Fiori launchpad.

In the Manage Situation Types – Extended app, the same title is used for the situation and the notification, but it can also be changed.

In the template, you can see a preview as it appears in an app or notification.

Extended Framework: Title, Notification Title
Extended Framework: Title, Notification Title
Standard Framework: Short Description
Standard Framework: Short Description

Guidelines

  • Phrase the text with the end user in mind. This may differ from the template name you defined.
  • Use title case.
  • Don’t end with a period, even if your text is a (short) sentence.
    Reason: The short descriptions can also appear in a list (table), so a consistent format is required. Most short description texts will not be a complete sentence.

Examples

  • Staffing Request Updated Soon
  • Digital License Nearly Used Up
  • Blocked Invoice Overdue Soon
  • Ticket Sales Low
  • Overbooked Flight

Details Text

Use

The details text describes the situation with additional details to help business users respond to the situation.

The text fields have different labels in the configuration apps of the standard framework and the extended framework for Situation Handling.

In the template, you can see a preview as it appears in an app or notification.

Extended Framework: Description, Notification Text, Public Text
Extended Framework: Description, Notification Text, Public Text
Standard Framework: Message Details, Secure Notification Details, Public Notification Details
Standard Framework: Message Details, Secure Notification Details, Public Notification Details

Guidelines

  • Don’t just repeat the short description or title.
  • Start with describing the condition or facts that have happened.
    • Present: Delivery date of item <item> of purchase requisition <requisition> is about to expire.; The flight <airline> <connection> on <date> has a critical eco index of <index>%.
    • Past: An error occurred while requesting market data.
    • Future: The purchase contract <contract> will expire soon.
  • Continue with a call to action: Check the inconsistencies. Only use “please” if it’s absolutely necessary.
  • Write full sentences in sentence case.
  • End with a period.
  • You can use a maximum of 15 variables. If you include variables, ensure that their meaning is clear in your context.

Texts for public notification channels do not allow variables because they appear outside the SAP Fiori launchpad (for example, email notifications). They are not allowed to contain sensitive information.


Examples

  • The project manager has updated the staffing requirements in the resource request. Check the staffed resources in the Resource Management app.
  • You have used 80% of your digital access entitlement. Please renew the license if you want to continue using this service.
  • A staffing request was updated. Check the staffed resources in the Resource Management app.
  • You have nearly used up your digital access entitlement. Please renew the license if you want to continue using this service.

Buttons

Use

You can configure the buttons for the My Situations – Extended app that are displays on the situation page for solution proposals and navigation to related business apps. The configuration takes part in the Manage Situation Objects app. A button consists of a name and a description.

You can see a preview of the button in the Manage Situation Objects app.

Definition of buttons in the Manage Situation Objects app
Definition of buttons in the Manage Situation Objects app

Callback Actions

Use

Callback actions are transactions that close situations. The buttons for callback actions are displayed in the My Situations – Extended app under “Solution Proposals”.

Buttons under
Buttons under "Solution Proposals"

Callback Action: Button Name

Guidelines

  • Use title case.
  • Start with a verb describing which action is triggered followed by a noun.
  • Don’t end with a period.

Examples

  • Cancel Bookings
  • Release Collective Settlement Document

Callback Action: Button Description

Guidelines

  • Don’t just repeat the button name.
  • Describe in detail which action is performed.
  • Don’t end with a period.

Examples

  • Set flight status to unscheduled
  • Change bookings to the next flight with the same airline and connection ID
  • Upgrade economy passengers to business class

Navigation Targets

Use

Navigation targets lead to business apps that help end users resolve a situation. The buttons for navigation targets are displayed in the My Situations – Extended app under “Related Apps”.

Navigation targets under
Navigation targets under "Related apps"

Navigation Targets: Button Name

Guidelines

  • Use the app name in title case.

Example

  • Manage Purchase Contracts

Navigation Targets: Button Description

Guidelines

  • Don’t just repeat the button name.
  • Provide additional information such as the specific page that opens in the target app or which specific item is displayed.
  • Use sentence style.
  • Don’t end with a period.

Examples

  • Maintain flight booking details
  • Check the key fields of the freight cost allocation document

Labels

Use

In the Manage Situation Scenarios app, you customize the layout for the My Situations – Extended app. This includes the labels for columns and sections. They help end users to better understand the context of a situation. You can find more information about where the labels are displayed in the documentation on SAP Help Portal.

Guidelines

  • Use title case.
  • Use nouns.
  • Don’t end with a period.

Columns and sections that refer to anchor object data should be labeled with the same name as the object, for example: Sales Order, Material, Supplier.

Columns and sections that refer to the trigger object should have a generic label if the scenario configuration includes more than one situation trigger, for example: Additional Information.

Resources

Elements and Controls

Implementation