- Latest Version 1.126
- SAPUI Version 1.124
- SAPUI5 Version 1.120
- SAPUI5 Version 1.118
- SAPUI5 Version 1.116
- SAPUI5 Version 1.114
- SAPUI5 Version 1.112
- SAPUI5 Version 1.110
- SAPUI5 Version 1.108
- SAPUI5 Version 1.106
- SAPUI5 Version 1.104
- SAPUI5 Version 1.102
- SAPUI5 Version 1.100
- SAPUI5 Version 1.98
- SAPUI5 Version 1.96
- SAPUI5 Version 1.94
- SAPUI5 Version 1.92
- SAPUI5 Version 1.90
- SAPUI5 Version 1.88
- SAPUI5 Version 1.86
- SAPUI5 Version 1.84
- SAPUI5 Version 1.82
- SAPUI5 Version 1.80
- SAPUI5 Version 1.78
- SAPUI5 Version 1.76
- SAPUI5 Version 1.74
- SAPUI5 Version 1.72
- SAPUI5 Version 1.70
- SAPUI5 Version 1.68
- SAPUI5 Version 1.66
- SAPUI5 Version 1.64
- SAPUI5 Version 1.62
- SAPUI5 Version 1.60
- SAPUI5 Version 1.58
- SAPUI5 Version 1.56
- SAPUI5 Version 1.54
- SAPUI5 Version 1.52
- SAPUI5 Version 1.50
- SAPUI5 Version 1.48
- SAPUI5 Version 1.46
- SAPUI5 Version 1.44
- SAPUI5 Version 1.42
- SAPUI5 Version 1.40
- SAPUI5 Version 1.38
- SAPUI5 Version 1.36
- SAPUI5 Version 1.34
- SAPUI5 Version 1.32
- SAPUI5 Version 1.30
- SAPUI5 Version 1.28
- SAPUI5 Version 1.26
- Latest Version 1.126
- SAPUI Version 1.124
- SAPUI5 Version 1.122
- SAPUI5 Version 1.120
- SAPUI5 Version 1.118
- SAPUI5 Version 1.116
- SAPUI5 Version 1.114
- SAPUI5 Version 1.112
- SAPUI5 Version 1.110
- SAPUI5 Version 1.108
- SAPUI5 Version 1.106
- SAPUI5 Version 1.104
- SAPUI5 Version 1.102
- SAPUI5 Version 1.100
- SAPUI5 Version 1.98
- SAPUI5 Version 1.96
- SAPUI5 Version 1.94
- SAPUI5 Version 1.92
- SAPUI5 Version 1.90
- SAPUI5 Version 1.88
- SAPUI5 Version 1.86
- SAPUI5 Version 1.84
- SAPUI5 Version 1.82
- SAPUI5 Version 1.80
- SAPUI5 Version 1.78
- SAPUI5 Version 1.76
- SAPUI5 Version 1.74
- SAPUI5 Version 1.72
- SAPUI5 Version 1.70
- SAPUI5 Version 1.68
- SAPUI5 Version 1.66
- SAPUI5 Version 1.64
- SAPUI5 Version 1.62
- SAPUI5 Version 1.60
- SAPUI5 Version 1.58
- SAPUI5 Version 1.56
- SAPUI5 Version 1.54
- SAPUI5 Version 1.52
- SAPUI5 Version 1.50
- SAPUI5 Version 1.48
- SAPUI5 Version 1.46
- SAPUI5 Version 1.44
- SAPUI5 Version 1.42
- SAPUI5 Version 1.40
- SAPUI5 Version 1.38
- SAPUI5 Version 1.36
- SAPUI5 Version 1.34
- SAPUI5 Version 1.32
- SAPUI5 Version 1.30
- SAPUI5 Version 1.28
- SAPUI5 Version 1.26
Draft Handling
Intro
A draft is a temporary version of a business entity that has not yet been explicitly saved as an active version.
Drafts are used:
- To keep unsaved changes if an editing activity is interrupted, allowing users to resume editing later.
- To prevent data loss if an app terminates unexpectedly.
- As a locking mechanism to prevent multiple users from editing the same object at the same time, and to make users aware when there are unsaved changes by another user.
When a user starts creating a new business entity or edits an existing one, a draft is created in parallel in the background to enable field validation and dynamic field control based on user interaction, and to provide default values for fields based on recent data entry. A draft can be validated for consistency and completeness at any time using the different message types and controls described in the message handling article.
While the user is modifying a business entity, the draft is saved every 20 seconds. Clicking the Save button is still necessary in order to incorporate the changes into an active business entity, which is called the saved version.
Responsiveness
Types
Draft Types
Drafts can differ in terms of their visibility to different users and the interactions allowed. SAP Fiori currently employs an exclusive draft scenario. In this type of scenario, one user is the owner of the draft. As long as a user is working on an object, the business entity remains locked for other users until the lock period expires. When the lock expires, other users can discard any unsaved changes and start editing.
Editing Status
In a draft context, we differentiate between the following editing statuses:
- Saved version
- If all mandatory fields have been filled, and the entries are consistent in the business context, the user can save. When a draft entity is saved, the changes are transferred to the saved version. After saving, the draft is deleted.
- Draft
- A user’s own draft is tagged as Draft. The editing status to filter for a user’s own drafts is called Own Draft.
- Locked
- If a user is editing a business entity, it is locked for other users. The object remains locked until the user has finished editing or until the locking time has passed. The editing status to filter for locked entities is called Locked by Another User.
- Unsaved changes
- If the locking time has expired, other users can see that there are unsaved changes by the person who edited the object The editing status to filter for unsaved entities by other users is called Unsaved Changes by Another User.
The sap.m.objectMarker was developed to express the technical status of an object. The user name cannot be represented with the object marker.
For more information about the sap.m.objectMarker, see the article on object display elements.
Behavior and Interaction
When a user creates a new business entity or edits an existing one, it remains in Draft state until the user saves it.
The following interaction flow shows how the draft concept helps users to create and edit new business entities.
Create and Edit
In a create scenario, drafts belong to a single user. No other user has access to the draft while the object is being created.
New business entities that have not been explicitly created (activated) are known as “create-drafts”.
In scenarios where the object entity does not have a name or ID, use the format New [entity| as a placeholder in tables, lists, or messages. If an ID or name is available, use this information instead.
In an edit scenario, when a user is actively editing an object, no other user has access to the edit mode of that object. In parallel, a draft is created, which is a deep copy of the business document. As soon as the user starts editing, the editing status of the object changes to Draft.
Saved versions of business entities that are edited by someone are known as “edit-drafts”.
The ist report reflects the information of the “edit-draft”. If the document is unchanged, the list report reflects the information of the saved version.
Create Flow
Edit Flow
Draft/Saved Version Switch
When the user changes to edit mode, the main page no longer shows the Edit button. Instead, a draft/saved version switch is shown next to the title of the page that allows the user to switch between the draft version and the current saved version of the business entity.
Select Multiple Items – List in a List-Detail Layout
The user can select multiple items in the list as follows:
- Display first or last item (default): Either the first or last (default) selected item remains visible in the details area. If the first or last selected item is a draft, show the object in edit mode and enable the Save and Discard buttons.
- Display aggregate: The details area displays a summary of the selected items and offers some added value or functionality. If the selection includes a draft, use the data that is currently displayed in the draft, and not the last activated or saved data.
For more information about multiple selection of items, see the Mass Edit guideline.
Save
If all mandatory fields have been filled and the entity has a consistent state independently and also within its business environment and business processes, users can incorporate the edits into an active business entity.
Saving an entity executes all necessary application logic and saves a consistent state. If errors occur that prevent the entity from being saved, users must first resolve these issues.
For more information, see messaging and form field validation.
If your use case requires further buttons apart from Save (for existing objects) or Create (for new objects), place them next to the Save or Create button. Examples might be Save and Next or Create and Next. For more information, see Manage Objects.
Save action – outdated draft
If the lock time expires due to a user’s inactivity, and another user starts editing in the meantime, display the following message:
Type: Error
Title: Error
Message text:
[Object] cannot be saved. A more recent version is available. Any changes you didn’t save were discarded.
Button: Close
Discard Draft
If the user makes changes and clicks the Discard button, display a popover (sap.m.Popover) to confirm that the draft should be deleted. The user must click outside the popover to close it.
If the user has not made any changes, the draft should be deleted, even if fields were already prefilled. To do so, use the CreatedAt and ChangedAt timestamps of the administrative data to check whether changes have been made to the draft entity.
Create-draft
For a create-draft, show the following message text:
Message text:
Discard this draft?
Button: Discard
When the user clicks Discard, display the following message:
Message text:
Draft discarded
Edit-draft
For an edit-draft, show the following message text:
Message text:
Discard all changes?
Button: Discard
When the user clicks Discard, display the following message:
Message text:
Changes discarded
Discard Popover
Guidelines
When to Show Which Editing Status
When multiple users work on the same work list, there is always a chance that more than one user will try to edit the same object simultaneously. This can lead to important edits being lost when multiple users submit their changes without informing one another. Therefore, a draft for a business entity acts as an edit lock, which forces object information to be changed sequentially.
In an edit scenario, when a user actively edits an object, no other user has access to the edit mode of that object. In parallel, a draft is created, which is a deep copy of the business entity.
The object remains locked until the user has finished editing. When the user who is blocking the object has been idle for 30 minutes, the lock expires automatically. Other users can then take over editing, and the draft of the previous user is discarded.
This graphic shows how the draft locking concept works and when to display which message.
How to Display the Editing Status
In most controls the editing status is clickable and provides access to additional information related to the draft, such as when the draft was created or who the owner of a draft is. Clicking the status opens a responsive popover that displays all relevant information.
Controls That Display the Editing Status
Object list item, object header, and object page header
If an object has a certain editing status, use one of the status properties of the object list item or object header. Do not overwrite existing status properties. Instead, use an additional status line to ensure that no information gets overwritten.
If an object is locked, has unsaved changes or is in draft state, set the ShowMarkers property of the object list item or object header to true and use the sap.m.objectMarker.
Tables
If you need to indicate the editing status of a business entity in a responsive table, place a link below the key information. Use sapUiTinyMarginTop to align the information in a responsive table.
If you need to indicate the editing status of a business entity in a non-responsive table, such as an analytical table, tree table, or grid table, provide an extra column for that information and place a transparent button inside. Name the column header Editing Status. The column should be placed after the main information on the table.
The editing status has different visualisations, such as icon only, icon and text, or text-only. Choose the one that is the most appropriate. Draft should always be displayed as text-only.
Upload Set
The upload set control uses sap.m.objectMarker to display the editing status. The default behavior for the editing status is as follows:
On L/M size:
- Locked and Unsaved Changes are displayed as icons and text, while Draft is displayed as text.
On S size:
- Locked and Unsaved Changes are displayed as icons, while Draft is displayed as text.
Which Information Is Shown
If the user edits an entity, update the changed information immediately in the corresponding lists, such as the list report, worklist, or object list item. All other users will see the most recently saved version of the entity.
Bookmarking and Deep Linking
A page of an application that is not its entry page can be bookmarked or shared as a deep link. Ideally, the full UI state of the page will be retrieved. Technically this includes every part that is represented in the URL. For more information, see the article on deep linking.
Bookmarking an entity in active status
If a bookmark is called for an active entity for which no draft exists, open the entity in display mode.
If a bookmark is called for an active entity for which a draft exists, display a dialog asking the user whether he or she wants to resume editing or discard the draft.
The dialog contains the following information:
Type: Confirmation
Title: Resume Editing
Message text:
We saved a draft of your changes to [entity] on August 8, 2015 17:35.
Do you want to resume editing or discard the changes?
Buttons: Resume | Discard
If the user resumes editing via Resume, the last implicitly updated draft state will be displayed in edit mode. If the user clicks the Back button, the active entity will not be displayed. Instead, the previous entry before the user navigated to the active instance will be displayed. Navigation to the draft does not create an entry for back navigation.
If the user chooses Discard, show the original saved version in display mode and the following message informing the user that the draft was deleted:
Message text:
Changes discarded
Bookmarking a draft
If a bookmark is called for an entity that was bookmarked while in draft state, open the entity in edit mode.
If the bookmark relates to an entity that no longer exists due to an action that triggered its deletion, such as Save or Discard, or if it cannot be accessed, display an empty page.
Message text:
The [entity] is no longer available.
[App name as link]
If a user shares a link to an entity with another user, the other user will be taken to the display view of the entity. If a different user’s draft exists, the page shows the appropriate editing status, such as Locked by [user name].
Deep Linking
When one user navigates from one application to an entity in another application, and this entity has a draft created by that particular user, display a dialog asking whether the user wants to resume editing or discard the draft.
The dialog contains the following information:
Type: Confirmation
Title: Resume Editing
Message text:
We saved a draft of your changes to [entity] on August 8, 2015 17:35.
Do you want to resume editing or discard the changes?
Buttons: Resume | Discard
If the user resumes editing via Resume, the last implicitly updated draft state will be displayed in edit mode. If the user clicks the Back button, the active entity will not displayed. Instead, the previous entry before the user navigated to the active instance will be displayed. Consequently, navigation to the draft does not create an entry for back navigation.
If the user selects Discard, the page will show the original (active) document in display mode, and the following message informing the user that the draft was deleted:
Message text:
Changes discarded
Sorting, Filtering, and Grouping
Sorting
The table in a list report is sorted by a property defined either by the app (default sorting) or by the user, such as a key identifier, date, or status.
Draft entities are sorted by the same criteria. If the property is empty in the draft entity, the item appears at top. The table can also be sorted by Draft. In an ascending order, the entities that are in draft state or locked appear at the top. In a descending order, these items appear at the bottom.
Filtering
The table in a worklist is filtered by the properties defined by the app (by default) or by the user. Draft objects are filtered by the same criteria. If those properties are empty in the draft entity, the item will not match the criteria and will not be shown.
The table can also be filtered by Editing Status with the following values:
Editing Status | Description |
All | Displays all entities |
Own Draft | Displays a user’s own draft only |
Locked by Another User | Displays all entities that are currently in progress by someone |
Unsaved Changes by Another User | Displays all entities with unsaved changes (lock expired, draft of someone is still available) |
Unchanged | Displays all entities that have no draft |
Grouping
The table in a list report is grouped by the properties defined by the app (by default) or by the user. Draft entities are grouped accordingly. If the property is empty in the draft entity, this creates a group of its own, which appears at the top of the table.
Follow this guideline for empty properties:
[Filter criteria]: Not Defined
Actions and Messaging
The editing status of an entity also has implications for any actions the user executes:
- Locked items can never be edited, updated, or deleted.
- Update actions cannot be applied to a user’s own draft.
- Users can delete their drafts and any objects for which the lock expired.
If your app offers mass actions with multiple selection, you may also need to consider potential conflicts – some actions may not be feasible if only some of the selected items can be processed. The sections below outline the different use cases and corresponding user messages.
Message Handling
We distinguish between edit, update, and delete actions:
- Edit: Open an object in edit mode.
- Update: Trigger changes to the latest active version, such as Post and Approve.
- Delete: Remove from the database.
Editing Status/Action | Edit | Update | Delete |
Active Version (actively saved, no draft or unsaved changes exist) | Editing allowed; no message | Update allowed; no message | Deletion allowed; warning |
Locked (draft locked by another user) | Never allow editing; error | Never update; error | Never delete; error |
Draft (user’s own draft) | Editing allowed; no message | Use case-dependent | Deletion allowed; warning |
Unsaved Changes (draft by another user) | Editing allowed; warning | Update allowed; warning | Deletion allowed; warning |
- Type: Warning Message Box
- Title: Warning
- Message text: You’ve made changes to this object. What would you like to do?
- Option 1: Save: Apply changes to the saved version.
- Option 2: Keep Draft: Changes are only visible to you and have no effect on dependent processes and functions.
- Option 3: Discard Draft: All changes will be lost.
- Buttons: OK | Cancel
… an item with unsaved changes by another user
Type: Warning
Title: Delete
Message text:
User name known:
Another user edited this [entity] without saving the changes:
[clickable user name]
Delete anyway?
User name unknown:
Another user edited this [entity] without saving the changes. Delete anyway?
Buttons: Delete | Cancel
User attempts to EDIT …
… an item with unsaved changes by another user:
Type: Warning
Title: Warning
Message text:
User name known:
Another user edited this [entity] without saving the changes:[clickable user name]
If you take over, those changes will be lost.
User name unknown:
Another user edited this [entity] without saving the changes. If you take over, those changes will be lost.
Buttons: Edit | Cancel
… an item with unsaved changes by another user
Type: Warning
Title: Warning
Message text:
User name known:
Another user edited this [entity] without saving the changes:
[clickable user name]
If you [action] this [entity], those changes will be lost.
User name unknown:
Another user edited this [entity] without saving the changes. If you [action] this [entity], those changes will be lost.
Buttons: [Action] | Cancel
Message Patterns – Actions for Multiple Items
The following message patterns apply to multi selection cases. In case the user selects one item of one type show the entity name instead, e.g.
Locked items + 1 item with unsaved changes:
Message text:
2 of 3 sales orders are currently locked by other users and cannot be deleted.
Sales order 12345 has unsaved changes. Delete anyway?
Buttons: Delete | Cancel
Locked items + 2 or more items with unsaved changes:
Message text:
2 of 4 sales orders are currently locked by other users and cannot be deleted.
2 sales orders have unsaved changes.
Do you still want to delete the sales orders with unsaved changes?
Buttons: Delete | Cancel
… locked items and active/draft items
Type: Warning
Title: Delete
Message text:
Short text:
X of Y [entities] are currently locked by other users and cannot be deleted.
Do you still want to delete the remaining n [entities]?
Long text:
Grouped list with entity information, e.g. ID and Description plus information who locks each item.
Buttons: Delete | Cancel
… locked items and items with unsaved changes
Type: Warning
Title: Delete
Message text:
Short text:
X of Y [entities] are currently locked by other users and cannot be deleted.
n [entities] have unsaved changes.
Do you still want to delete the [entities] with unsaved changes?
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item/ has unsaved changes.
Buttons: Delete | Cancel
… locked, unsaved changes and active/ draft items
Type: Warning
Title: Delete
Message text:
Short text:
X of Y [entities] are currently locked by other users and cannot be deleted.
Do you still want to delete the remaining n [entities]?
[checkbox] Also delete [entities] with unsaved changes
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item/ has unsaved changes.
Buttons: Delete | Cancel
… items with unsaved changes
Type: Warning
Title: Delete
Message text:
Short text:
Other users have edited the selected products without saving the changes.
Delete anyway?
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item/ has unsaved changes.
Buttons: Delete | Cancel
… items with unsaved changes and active/ draft items
Type: Warning
Title: Delete
Message text:
Short text:
X of Y [entities] are currently locked by other users and cannot be deleted.
n [entities] have unsaved changes.
Do you still want to delete the [entities] with unsaved changes?
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item/ has unsaved changes.
Buttons: Delete | Cancel
User attempts to UPDATE …
The following section does not show any example pictures. Please refer to the section before for examples.
… active items
Type: Confirmation
Title: [action]
Message text:
[action] the selected [entities]?
Buttons: [action] | Cancel
… items with unsaved changes by other users and active items
Type: Warning
Title: Warning
Message text:
Short text:
Some of the [entities] you selected have been edited by other users, but not saved. These changes will be lost.
[checkbox] Also [action] [entities] with unsaved changes
Long text:
Grouped list with entity information, such as ID and description, as well as information on who has unsaved changes.
Buttons: [action] | Cancel
… user’s own draft and locked items
Type: Error
Title: Error
Message text:
Short text:
The selected [entities] cannot be [action]. They are currently locked, or exist as draft versions.
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item and user’s own draft.
Button: Close
… items with unsaved changes and locked items
Type: Warning
Title: Warning
Message text:
Short text:
X of Y [entities] cannot be [action]. They are currently locked, or exist as draft versions.
Do you still want to [action] the remaining n [entities]?
Long text:
Grouped list with entity information, such as ID and description, as well as information on who is locking each item.
Buttons: [action] | Cancel
… items with unsaved changes by other users, user’s own draft and locked items
Type: Warning
Title: Warning
Message text:
Short text:
X of Y [entities] cannot be [action]. They are currently locked, or exist as draft versions.
Do you still want to [action] the remaining n [entities]?
[checkbox] Also [action] [entities] with unsaved changes
Long text:
The following [entities] are currently locked by other users (n):
[entity]
Locked by: [clickable user name]
You have edited the following [entities] without saving the changes (n):[entity]
Save your changes before [action] the [entities].
The following [entities] have been edited by other users, but not saved (n):[entity]
Unsaved changes by: [clickable user name]
Buttons: [action] | Cancel
Resources
Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.
Elements and Controls
- Dialog (guidelines)
- Messaging (guidelines)
- Object Display Elements (guidelines)