Updated: March 19, 2021

Draft Handling

Intro

A draft is an interim version of a business entity that has not yet been explicitly saved as an active version. Drafts are saved automatically in the background whenever users add or change information within a business entity while in edit state (auto-save).

In SAP Fiori, drafts are used as follows:

  • 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 concurrently, 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 (showing additional fields 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. This returns a list of messages. See the article on message handling to find out how to display messages.

While the user is modifying a business entity, a saving indicator shows when a draft is saved implicitly. The implicit save does not make the Save button redundant. Clicking or tapping the Save button is still necessary in order to incorporate the changes into an active business document.

Responsiveness

Sizes M and L offer enough space to display the saving indicator in the toolbar. If there is not enough space available, for example, on a smartphone, do not show the saving indicator. Also note that the text must never be truncated.

Size S

(1) Saving indicator visible; (2) & (3) Saving indicator not visible due to limited screen space
(1) Saving indicator visible; (2) & (3) Saving indicator not visible due to limited screen space

Sizes M and L

Split-screen layout
Split-screen layout

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, or as long as the draft exists, the business entity remains locked for other users until the lock period expires. When the lock expires, other users can either discard the draft, or take over from the previous user and continue editing.

Editing Status

In a draft context, we differentiate between the following editing statuses:

  • Unchanged/active version
    • If all mandatory fields have been filled, and the entries are consistent in the business context, the user can save the entity as an “active” version. In other words, the changes are written into the database in the backend system.
    • “Unchanged” is the default status for a saved entity that no one is working on. There is no special indicator for this status on the screen. However, if you offer Editing Status as a filter, the user can filter for all entities that have no draft available. The filter for that is called Unchanged.
  • 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.

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 activated or saved are known as “create-drafts”.

In scenarios where the object entity does not have a name  or an 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.

Saved business entities that are being processed by someone are known as “edit-drafts”.

Global Edit Flow

In the global edit flow, there is only one Edit button on the main page. This button changes every linked subpage to edit mode. Users can navigate between the main page and subitems, or between individual subitems, without saving the changes explicitly. Navigating between items does not generate a success message confirming that the user’s draft was saved.

When the user switches to edit mode, the main page no longer shows the Edit button. Instead, two buttons are shown prompting the user to either cancel or activate/save the changes.

When the user leaves edit mode, display a success message confirming whether or not the draft was saved.

The saving indicator is placed in the toolbar on the main page and on subitems.

Global edit flow
Global edit flow

Select Multiple Items – Master List

The user can select multiple items in the master 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 buttons for activating and discarding the draft.
  • 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 master list guideline.

Master list – Selecting multiple items
Master list – Selecting multiple items

Navigate

While a user is editing an entity, changes are implicitly auto-saved as a draft. This allows users to navigate cross-contextually without losing any data. If the user makes changes and navigates away, for example, via BackHome, or any other navigation link, display a success message.

Create-draft

If the object entity does not have a name or an ID before the user activates or saves it, use the following format: New [entity] (see 1). If an ID or name is available, show the dedicated information instead (see 2).

When users navigate away from the entity, display one of the following texts as a success message depending on which of the two scenarios above applies:

(1) New [entity] was saved as a draft.

(2) [Entity] was saved as a draft.

Edit-draft

In an edit scenario, the business entity already has an ID or name. Show this information to help users identify what has been saved as a draft.

When users navigate away from the entity, display the following text as a success message: [Entity] was saved as a draft.

Implicit saving – Success message
Implicit saving – Success message

Resume Editing

Once the user returns to the draft, the UI is displayed in edit mode and the user can resume editing. When the user exits the draft, the last modified status is auto-saved and a success message is displayed.

Resume editing
Resume editing

Activate/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, such as Save and Next, place them next to the Save button. For more information, see edit page floorplan.

Saving a draft
Saving a draft

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:

Account cannot be saved. A more recent version is available. Any changes you didn’t save were discarded.

Button: Close

Error message – Saving
Error message – Saving

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:

Account cannot be saved. A more recent version is available. Any changes you didn’t save were discarded.

Button: Close

Error message – Saving
Error message – Saving

Cancel Editing

If the user makes changes and clicks or taps the Cancel 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:

Cancel editing and 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:

Cancel editing and discard all changes?

Button: Discard

 

When the user clicks Discard, display the following message:

Message text:
Changes discarded

Cancel popover
Cancel 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 at any one time. 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 document.

The object remains locked until the user has finished editing. In some use cases, the lock should expire automatically, for example, when the user who is blocking the object has been idle for a certain time.

If the lock time expires but the draft is still available, other users see that the object has been modified by someone else but not saved. Other users can then take over editing, which results in the changes or draft of that user being discarded.

The graphic opposite shows how the draft concept helps users to work together asynchronously on a business entity 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 or tapping 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, object header, or object page 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, set the MarkLocked property of the object list item or object page header to true.

The status Unsaved changes can also be displayed in the object page header.

There is no generic option available for the object header and object page header.

(1) & (1.1.) Specification for draft and unsaved changes; (2) & (2.1) Specification for locking
(1) & (1.1.) Specification for draft and unsaved changes; (2) & (2.1) Specification for locking

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.

(1) Responsive table ; (2) non-responsive table
(1) Responsive table ; (2) non-responsive table

Editing Status Popovers

Trigger

When the user clicks or taps the editing status, a responsive popover appears and displays draft-related administrative information.

Popover trigger: (1) responsive table; (2) non-responsive table; (3) object page header; (4) object page header (locked)
Popover trigger: (1) responsive table; (2) non-responsive table; (3) object page header; (4) object page header (locked)

Dimensions

The popover has a minimum height and width to ensure that the size of the dialog does not vary too much between the initial load and the display of information.

Draft popover – Dimensions
Draft popover – Dimensions

Types

When the user clicks or taps the editing status, a popover will appear with information on who has locked an object or who has unsaved changes.

If the user’s name is not available or cannot be retrieved, replace the user’s actual name with “another user”.

The images on the right show the different use cases.

Popovers
Popovers

The quick view for an employee is shown when information about the person who has locked an object is available and clickable. When a quick view is opened from a dialog, it appears on top of the dialog and not in place of it.

Quick view
Quick view

The quick view for an employee is shown when information about the person who has locked an object is available and clickable. When a quick view is opened from a dialog, it appears on top of the dialog and not in place of it.

Quick view
Quick view

Which Information Is Shown

If the user edits an entity, update the changed information immediately in the corresponding lists, such as the work list or the object list item. All other users will see the active or most recently saved data of the entity.

Graphic displaying which information is shown, for example on a worklist
Graphic displaying which information is shown, for example on a worklist

Saving Indicator

When a user adds or changes information within a business entity, an indicator shows the user that these changes have been saved as a draft.

If no changes have been made, nothing is shown.

If not enough space is available, do not show the saving indicator. Also note that the text should not be truncated.

States

There are two different states:

State 1: Saving draft …

Display state 1 after every content change that triggers a background save (draft). State 1should be shown for at least 1.5 seconds.


State 2:
Draft saved

Display state 2 after the draft has been saved. State 2 should also be shown for at least 1.5 seconds.

Without messaging icon: (1) split-screen layout; (2.1) full screen layout. With messaging icon: (1) split-screen layout; (2.1) full screen layout.
Without messaging icon: (1) split-screen layout; (2.1) full screen layout. With messaging icon: (1) split-screen layout; (2.1) full screen layout.
Saving indicator – Dimensions
Saving indicator – Dimensions

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

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 saved state will be displayed in edit mode. If the user clicks or taps 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 chooses 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

Bookmarking an active entity
Bookmarking an active entity
Bookmarking an active entity with draft
Bookmarking an active entity with draft

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 is not accessible, 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].

Bookmarking a draft
Bookmarking a draft
Bookmarked draft no longer availalble
Bookmarked draft no longer availalble

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 saved state will be displayed in edit mode. If the user clicks or taps 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

Deep linking
Deep linking

Sorting, Filtering, and Grouping

Sorting

The table in a work list 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.

Sorted by Rate
Sorted by Rate

Filtering

The table in a work list 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:

Active Version
Draft
Locked
Unsaved Changes

Filtered by editing status
Filtered by editing status

Grouping

The table in a work list 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.

Grouped by rate
Grouped by rate

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 Never update; error Deletion allowed; warning
Unsaved Changes (draft by another user) Editing allowed; warning Update allowed; warning Deletion allowed; warning
Information
The message patterns below are intended to offer guidance on the information that your messages should include. The exact format will depend on the available messaging controls and infrastructure.

Message Patterns – Actions for a Single Item

User attempts to DELETE …

… a locked item

Type: Error

Title: Error

Message text:

User name known:

[entity] cannot be deleted. It is currently locked by:
[clickable user name]

User name unknown:

[entity] cannot be deleted. It is currently locked by another user.

Button: Close

… 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

… own draft/active item

Type: Warning

Title: Delete

Message text:

Delete [entity]?

Buttons: Delete | Cancel

User attempts to EDIT …

… a locked item:

Type: Error

Title: Error

Message text:

User name known:

[entity] cannot be edited. It is currently locked by:
[clickable user name]

User name unknown:

[entity] cannot be edited. It is currently locked by another user.

Button: Close

… 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

User attempts to UPDATE …

… a locked item

Type: Error

Title: Error

Message text:

User name known:

[entity] cannot be [action]. It is currently locked by:
[clickable user name]

User name unknown:

[entity] cannot be [action]. It is currently locked by another user.

Button: Close

… 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

… own draft 

Type: Error

Title: Error

Message text:

[entity] cannot be [action]. Save your changes to the [entity] first.

Button: Close

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

User attempts to DELETE …

… items that can be deleted 

Type: Warning

Title: Delete (n)

Message text:

Delete the selected [entities]?

Buttons: Delete | Cancel

… items with unsaved changes by other users and items that can be deleted

Type: Warning

Title: Delete (n)

Message text:

Short text:

Delete the selected [entities]?

[checkbox] Also delete [entities] with unsaved changes

Long text:

The following [entities] have been edited by other users, but not saved (n):[entity]
Unsaved changes by: [clickable user name]

Buttons: Delete | Cancel

… items with unsaved changes by other users

Type: Warning

Title: Delete (n)

Message text:

Short text:

Other users have edited the selected products without saving the changes.

Delete anyway?

Long text:

The following [entities] have been edited by other users, but not saved (n):
[entity]
Unsaved changes by: [clickable user name]

Buttons: Delete | Cancel

… locked items and items that can be deleted

Type: Warning

Title: Delete (n)

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:

The following [entities] are currently locked by other users (n):
[entity]
Locked by: [clickable user name]

Buttons: Delete | Cancel

… locked items and items with unsaved changes

Type: Warning

Title: Delete (n)

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:

The following [entities] are currently locked by other users (n):
[entity]
Locked by: [clickable user name]

The following [entities] have been edited by other users, but not saved (n):
[entity]
Unsaved changes by: [clickable user name]

Buttons: Delete | Cancel

User attempts to UPDATE …

The following section does not show any example pictures. Please refer to the section before for examples.

… items that can be updated

Type: Confirmation

Title: [action] (n)

Message text:

[action] the selected [entities]?

Buttons: [action] | Cancel

… items with unsaved changes by other users and items that can be deleted

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:

The following [entities] have been edited by other users, but not saved (n):
[entity]
Unsaved changes by: [clickable user name]

Buttons: [action] | Cancel

… items with unsaved changes (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:

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].

Button: Close

… items with unsaved changes (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]?

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].

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

Implementation