Updated: December 8, 2023

SAPUI5 Version 1.120

Message Handling – Processing Multiple Items

Intro

When a user selects multiple items from a table, it might not be possible to process all of the items at once.

Users therefore need clear and user-friendly information on:

The actions available for the selected items
Any issues that prevent items from being processed
Whether or not an action was successful for all items

Scenarios for Processing Results

This guideline outlines the message patterns and recommended message texts for the following scenarios:

Success: All items were processed successfully
Failure: No items can be processed / were processed
Partial Processing: Only some items can be processed. Others can’t be processed or require manual validation.

Enabling/Disabling Actions

Guidelines

Enable an action that:

Always works, regardless of whether or not items are selected
Can be applied to at least one of the selected items

Disable an action that:

Can’t be applied to any of the selected items
Doesn’t correspond to the number of selected items. For example, disable Compare if only one item is selected

For more details, see UI Element States.

After the action is applied, keep the items selected.

Success

When all items were processed successfully, show a message toast.

Message Toast
Text	<number of items> <item name> were <action>.

Message toast

Failure Cases

No items can be processed

When no items can be processed, disable the action button.

For example, if all the selected items are locked, disable the Edit button.

To help users understand why the action button is disabled, use the item states.

Disabled edit button

No items were processed

When no items were processed, show a message view in a dialog.

Message View
Header	Summary
First List Item	No <item names> were <action>.
Next List Items	Specific messages for each unprocessed item.
Button	Close

Message view with errors only

Partial Processing

Backend issues

When one or more of the selected items were processed successfully and one or more were not, due to backend issues, show a message view in a dialog.

Message View
Header	Summary
First List Item	Success Message <number of successful items> of <total number of items> <item name> were <action>.
Next List Items	Specific error messages for unprocessed items Specific warning messages for processed items
Button	Close

Message view with a mix of success, error, and warnings messages

One or more items can’t be processed

Before processing, a warning message asks users whether they want to apply the action to remaining items.
After user confirmation the resulting message depends on the processing results:
- A message toast for successful processing
- A message view for when backend errors occurred during the processing

Messaging sequence for items that can't be processed

Before Processing

If the action cannot be applied to one or more items, a warning message asks the users whether they want to apply the action to the other items.

Warning Message Box
Message Text	<number of items ineligible for the action> of <total number of items> <item name> can’t be <action>. Do you still want to <action> the remaining <number of editable items> <item name>?
Message Details	*Possible Causes* Selected <item names> are excluded if: Somebody is working on the <item name> (a draft exists or changes haven’t been saved). <action> is not allowed on the <item name>.
Buttons	<Primary action>, Cancel

After User Confirmation

After the users confirm the primary action for the remaining items the resulting message depends on the processing results:

When all the remaining items were successfully processed, a message toast is displayed.
When one or more backend errors occurred during the processing, a Summary message view in a dialog is displayed. It includes:
1. Successfully processed items
2. The backend error or errors
3. An information message for each item excluded from the processing

Information message text: The <item name> can’t be <action>

Summary with backend errors and information messages for items excluded from processing

Processing is blocked by items that require manual validation

Some warnings for individual items may require a user decision before processing can continue:

Case 1: Just one warning. The user can ignore the warning and process the item, or skip the item.
Case 2: More than one warning. The user can ignore the warnings and process all the items, or skip all the affected items. Processing is only interrupted once.

Case 1: One Item

When one item requires manual validation, show a warning message box with actions to:

Validate and process the item
Skip the item: When the users skip the item, in the message view in a dialog, show an information message for the skipped item in the message view.

Warning Message Box
Body Text	<item name> <item ID>: <message description> You can <action> this <item name> anyway, or skip it for now.
Show Details	Optional
Buttons	<Primary action>, Skip

For the skipped item, in the Summary message view, add an information message text below the other (success, error, and warning) items.

Message View
Information Message Text	The <item name> was skipped and not <action>.

Manual validation flow for one item (message box)

Case 2: More than One

When more than one item requires manual validation, show a warning message box with actions to:

Validate and process the items
Skip the items: When the users skip the items, in the message view in a dialog, show an information message for each skipped item.

Warning Message View
Header	*Warning*
Body Text	Warnings exist for some of the selected <item name, plural>. You can choose “<primary action>” to ignore the warnings, or skip these <item name, plural> for now.
Buttons	<Primary action>, Skip

For each skipped item, in the Summary message view, add an information message text below the other (success, error, and warning) items.

Message View
Information Message Text	The <item name> was skipped and not <action>.

Manual validation flow for several items (message view)

Action on multiple items with field issues in edit mode

Triggering a mass action can reveal field issues because the mass action also triggers field validation.

List the field related messages among other messages in the summary message view dialog.

Once the dialog is closed, the message popover appears, with a list of only the field issues.