Shelf Knowledge Management System: Gem Edit and Draft Mode Overview Guide



Document version history 

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

16 July 2024

Expired

1.1

Shelf

The document has been updated to include the description and images of the Gem’s Preview feature.

13 August 2024

Active




















Introduction

This document’s target audience is Content Editors and the document’s goal is to familiarize them with the new content creation and editing flow that now unifies the creation and editing experiences, as well as introduce to the audience our new Save as Draft feature that streamlines the way you work with Gems. This approach—standardizing the Gem creation and editing processes—has been introduced by Shelf to minimize discrepancies in Shelf KMS’s User Interface and improve the User Experience in content creation and editing. 

After reading this guide, you will be familiar with the following capabilities: 
  • Enhanced Gem creation flow
  • Enhanced Gem editing flow
  • Saving Gems as drafts.

If you have any questions regarding this document or if you need any assistance or support in its relation or in regards to the Shelf App and its settings, please contact Shelf’s Technical Support at support@shelf.io, within the Shelf App, or via your account’s CSM. 


     

Prerequisites 

For the purpose of this document and its target audience,  the following preconditions must be met prior to creating, updating or saving Gems as draft:
  • You have permissions to edit a Gem
  • The Content Publication Workflow (CPW) feature is disabled for your account (Figure 1) or the CPW bypass is enabled for your account (Figure 2).
    Figure 1. Disabling CPW in Admin Panel > Customize

    Figure 2. Enabling CPW Bypass for a user

 



Gem creation flow

If the above prerequisites are met, you can start creating a content item (Gem), following the below steps, after logging in to your Shelf KMS account:
  1. On the Shelf KMS Home Dashboard, find and click the ADD button in the upper part of the page. 
  2. From the dropdown menu that opens, select the Create Content option.

    Figure 3. Creating content in Shelf - Start

  3. In the next window that appears, select the needed content—Gem—type.
    Figure 4. Creating content in Shelf - Selecting content type

  4. You are next redirected to the standardized Edit Gem page as shown in the figure below.
    Figure 5. Creating content in Shelf - Working with the Edit Gem page

On the Edit Gem page, when creating a Gem, you can see the following Gem fields:
  1. Gem type icon - not editable
  2. Gem title - required, up to 255 characters
  3. Gem description - optional, up to 500 characters
  4. Gem’s Rich Text Editor - optional, allows you to enter and format text, add graphics etc.
  5. Gem location - required, the default location is (a) user’s Private library, if the user is on Home Dashboard, Gem page, or in this library, (b) any library where the user is at the moment of the Gem creation; if the Gem in Multiple Locations (GIML) capability is enabled for your account, multiple selection is possible, otherwise only one location can be selected at a time
  6. Gem language - required; if you create the Gem from Home Dashboard, than the Gem’s default language will be the language selected on Home Dashboard, and if you create the Gem from within a library, then the Gem’s default language is the language selected in that library’s search results
  7. Category - optional, single or multiple selection is supported depending on the account settings
  8. Tags - optional (if you have permissions to edit tags)
  9. Custom preview image - optional, editable, allows you to add any desired preview image for your Gem; JPG, GIF or PNG formats are allowed, with the recommended image size 400x400px and the file size not more than 1MB
  10. Template (if Templates are enabled for the account) - selectable, allows you to choose and apply a needed Gem template.
Once the needed fields are populated and the content is added to the Gem, you can click PREVIEW (12) to see how the content you have added looks like.

Figure 6. Previewing the Gem’s content

If everything is okay with the content, you can click SAVE AND PUBLISH (11) to save changes and publish your Gem in the location you have indicated.

Figure 7. Creating content in Shelf - Saving and publishing the Gem

5. When the Gem is published, you are redirected to the Gem View page where you can see the newly created Gem with all the information added by you.  

Figure 8. Creating content in Shelf - Viewing the created Gem
Though the images above show the Wiki type Gem creation process, the same approach applies to other Gem types, excluding the Decision Tree type of Gems. 
For example, if you create a Video type Gem, you can add content to it either by the URL link to the needed online video or by uploading it from your local device.

Figure 9. Creating a Video Gem

Figure 10. Creating a Video Gem - video uploaded

However, if you create an Audio, Image or a Document type Gem, you can add content to it only by uploading the respective audio, image or document from your local device.

Figure 11. Creating an Audio Gem - uploading the audio

Figure 12. Creating a Document Gem - uploading the document

Figure 13. Creating an Image Gem - uploading the image

If you need to create a Decision Tree (DT) type Gem, then after clicking Create Content and selecting the Decision Tree option in the Gem Type selection window, you are redirected to the DT-specific Edit Gem page where you can continue creating the Gem either in the half-size mode or enable the full-size mode.

Figure 14. Creating content in Shelf - Creating Decision Tree Gems
When creating a DT Gem, you can also preview its content as in the case of the Wiki type Gem, by clicking the Preview button and viewing the Preview page.

Figure 15. Previewing DT Gem’s content


Gem editing flow

  1. Once you have logged in to your Shelf KMS account and found the Gem you need to update, click it to open the Gem page shown in the figure below.

    Figure 16. Visiting the Gem page in Shelf

  2. That is where the introduction of the new standardized Edit Gem page starts to be seen and changes your actions on the Gempage:
    • You are NOT ABLE to edit the Gem content in place on the Gem page
    • You can see Gem’s content and the Details, Optimization, Connections, Recommendations on the Gem page
    • If you have permissions to edit Gems, you are able to update some of the Gem’s metadata directly on the Gem page: tags, categories, source language, rating, and owner. You can also autotranslate the Gem if needed and if the autotranslation capability is enabled. You can change the Gem’s source language here as well.
    • New, more accurate and logical, context menu for the Gem page, where the content updating/editing options—Custom Preview Image and Manage Locations—have been removed for ALL types of Gems; for those types of Gems which operate attachments—Audio, Video, Image, Document types—the context menu now also does not allow changing the attachment: the Change attachment option is now part of the Edit Gem page.

      Figure 17. Old context menu on View Gem page

      Figure 18. New context menu on the Gem page
      If you want to edit the Gem itself, you need to enter the Gem editing mode. This approach was introduced to make your work with content more logical and more consistent: you will no longer enter the content editing mode by mistake if you have permissions to edit content (if your user role is Admin, Collaborator, or Member).
  3. If you have permissions to edit Gems, click the Edit icon as shown in Figure 16 above. 
  4. Once clicked, you get to the Edit Gem page where you can work with Gem content and metadata.

    Figure 19. Viewing the Edit Gem page after entering the content editing mode

  1. Gem type icon - not editable
  2. Gem title - required, up to 255 characters
  3. Gem description - optional, up to 500 characters
  4. Gem Rich Text Editor (RTE) - optional, Shelf’s Rich Text Editor set of tools which allows you to enter and format text, add graphics, links etc.
  5. Gem location - required, the default location is (a) user’s Private library, if the user is on Home Dashboard, Gem page, or in this library, (b) any library where the user is at the moment of the Gem editing; if the Gem in Multiple Locations (GIML) capability is enabled for your account, multiple selection is possible, otherwise only one location can be selected at a time
  6. Gem language - required; if you create the Gem from Home Dashboard, than the Gem’s default language will be the language selected on Home Dashboard, and if you create the Gem from within a library, then the Gem’s default language is the language selected in that library’s search results
  7. Category - optional, single or multiple selection is supported depending on the account settings
  8. Tags - optional (if you have permissions to edit tags)
  9. Custom preview image - optional, editable, allows you to add any desired preview image for your Gem; JPG, GIF or PNG formats are allowed, with the recommended image size 400x400px and the file size not more than 1MB.
However, when updating your Gem and on the Edit Gem page, you are not able to see the following data on your Gem:
  • Gem metadata (except Tags, Category)
  • Recommendations
  • Connections
  • Optimize Content section
  • Comments tab
  • Change History tab
  • Views tab
For attachment- or link-based types of Gems (Document, Video, Audio, Image, Link), you can also replace or upload the attachments by clicking the Replace button and uploading the attached content from your local device. For Video type Gems, you can additionally change the link to replace the video.

Figure 20. Editing the Document type Gem - replacing the document by uploading

Figure 21. Editing the Video type Gem - replacing the video by link and by uploading

Once you have finished editing the Gem, you can use one of available actions: SAVE AND PUBLISH, SAVE AS DRAFT, and BACK.

Figure 22. Viewing Gem actions on the Edit Gem page

The SAVE AND PUBLISH action works as follows:
  • The Gem is published with all the changes you have made to its content and you are redirected to the Gem page where you can immediately check the changes
  • The changes you have made to the Gem can be viewed in the Gem Change History tab of the Gem page.

Figure 23. Viewing the changes published and merged into Gem
The SAVE AS DRAFT action is described in detail in its dedicated chapter below, so please refer to it for more information.
If you click the BACK button in the left upper corner of the Edit Gem page:
  • The confirmation modal window pops up where you can either discard changes and go back to the Gem page by clicking YES or click NO to go back to the Edit Gem page and continue updating your Gem

Figure 24. Confirming the Back action from the Edit Gem page


Saving Gem as Draft

Understanding Gem Draft feature and its purpose

Content managers and content editors often face a situation when they need to make changes and updates to content items (Gems) but keep them invisible for general viewers until such updates are reviewed and ready to be published for the public. 
For such a case, Shelf has implemented the Save as Draft feature for Gems, which is described and explained in detail in this section.

Let’s walk through the process of updating a Gem in Shelf and see how the Save as Draft feature works and what needs it fulfills. 
  1. Open the Edit mode for the needed Gem.
  2. On the Edit Gem page that appears, you want to update the Gem by adding its Custom Preview Image, that is the image to be displayed on the Shelf Home Dashboard instead of the generic preview image.  Find the relevant section in the Gem Details panel and click the Add button. Upload the needed image in the popup modal window and click Save.

    Figure 25. Adding the custom preview image for the Gem

  3. The image is added and is shown in the respective section of the Gem Details panel. 
    Figure 26. Viewing the added custom preview image
  4. Now you need to save the Gem as Draft because you don’t want anybody to see it until other updates are made. 
To do so, click the SAVE AS DRAFT button on top of the Edit Gem page. The toast message is displayed reading that your Gem was successfully saved as draft. And you remain on the Edit Gem page.

Figure 27. Saving Gem as draft

It means that the update you have just made is saved to the draft Gem version and not to the published Gem. Therefore, this update is not displayed in the Gem Change History tab if you click Back and return to the Gem page.

Figure 28. Viewing the Gem Change History tab on the Gem page

At the same time, this update is displayed on the Draft Change History page which you can access from the context menu of the Edit Gem page.

Figure 29. Accessing the Draft Change History page

Figure 30. Viewing the Draft Change History page and updates saved to Gem Draft

See more details about the Draft Change History feature in the respective section below. 
If for some reason, the attempt to save your Gem as Draft was unsuccessful, the error modal window is displayed titled as Saving as draft failed and showing the error text underneath. You can close that window and stay on the Edit Gem page.
When you have made changes to the Gem, saved the Gem as draft, and returned to the Gem page without publishing the new version of the Gem, you will see the Unpublished Changes label on it indicating that you have some updates to the Gem which are not visible for other viewers.

Figure 31. Viewing the Unpublished Changes label on the Gem
In this case, you can re-enter the Gem editing mode and use the SAVE AND PUBLISH action to publish your changes to the Gem and make them visible to all the viewers. These changes are now displayed in the Change History tab of the Gem page.

Figure 32. Viewing the published changes in the Change History tab


       

Viewing Draft Change History 

The new Draft Change History feature allows content editors to view the entire history of changes on the Gem draft and find out who and when made what changes. 

To start using the Draft Change History feature, the following preconditions must be met:
  • Change History is enabled in the Admin Panel > Customize > Gem tab
  • You must have permissions to edit the specific Gem
  • The Gem’s content has been modified (updated) and saved at least once, that is the Gem has been updated and saved as draft at least once
  • You are on the Edit Gem page.

Access the feature via the Draft Change History option of the Edit Gem page’s context menu.

Figure 33. Accessing and viewing the Draft Change History page with various draft changes 
The Draft Change History page that opens allows you to see the following information:
  • Informational message: Please note that any recent unsaved changes to the draft are not yet visible on this page
  • Name of the draft change author and time of the change
  • Field: shows what field was affected by the draft change
    • Title (all Gem types)
    • Description (all Gem types)
    • Attachment (Audio, Document, Image, Video types of Gems)
    • [CUSTOM_FIELD_NAME] - custom field (all Gem types, if custom fields are added)
    • Decision Tree (Decision Tree type)
    • Settings (Decision Tree type)
    • Question (FAQ type)
    • Answer (FAQ type)
    • Link (Link, Organization types)
    • Wiki Content (Wiki, Organization, Person, Post types)
    • Tags (all Gem types)
    • Category (all Gem types)
    • Image (custom preview image, all Gem types)
  • Original and New: shows the affected field values before and after the change 
    • If the change affected the Attachment or Image field, not-clickable filename is shown 
    • If the change affected the Decision Tree, Answer or Wiki Content field, not-clickable text reading Version from DDMMYYYY:HHMM (in format February 19, 2024 8:14 PM) is shown 
    • If any other field is affected, the value is displayed
    • If there are no values for the Original or New field, then you will see “-” in the Draft Change History grid. 

Once you publish the changes to the Gem, the records in the Draft Change History grid are cleared, and the Draft Change History window is empty if you reopen it from the Edit Gem page.

Figure 34. Viewing Draft Change History after publishing all changes


                        

Discarding Gem drafts 

In certain cases, you may want to delete the Gem draft and restore the Gem’s original version. 
To do that, open the Edit Gem page and then using the context menu icon in the upper right corner of the page, select the Discard draft option from the menu.

Figure 35. Accessing the draft discarding option

Following that, confirm your choice to discard the Gem draft. Note that this will delete all changes made since the time you have last published the Gem.

Figure 36. Confirming the Discard draft action

Once the page is refreshed, go back to the context menu of the Edit Gem page and open the Gem Draft Change History page to verify that the drafts have been discarded.

Figure 37. Viewing the Draft Change History page after discarding the Gem drafts