Relationships between Moderation (Approval) status, Scheduling, Versions and Workflows

  • Article

Recently, while working on a WCM project, I realized that many developers don't know that various properties of a list item (especially document library) are inter dependent and may change based on each other's values. These properties are: Moderation (Approval) status, Scheduling status, Versions Numbers. So I thought, I'd put up this write-up that would demystify some of the underlying concepts.

 

FACTS:

Before starting on this let's get some facts clear:

  1. Item Scheduling (ability to schedule or expire an item) is ONLY available on document libraries. You cannot enable it on lists.

  2. SharePoint does not rely on Scheduling Start Date (or Publish date) and Scheduling End Date (or Expiry Date) to find if an item needs to be shown or not to unauthorized users. In fact, it relies on "Moderation Status" (the value shown in "Approval Status" field). When you enable Item Scheduling on a document library, SharePoint makes use of event receivers and timer job to change the moderation status as per Scheduling Start and End Dates.

  3. This is what happens to moderation status as per Scheduling Start and End Dates.

    1. Before Scheduling Start Date: if someone "approves" an item (from different options available, more on that below), the moderation status changes to "Scheduled".
    2. On Scheduling Start Date: if moderation status was "Scheduled" earlier, it changes to "Approved". Version number is changed from Minor to next Major. No change happens if moderation status was "Draft" or "Pending" earlier.
    3. On Scheduling End Date: if moderation status was "Approved" earlier, it changes to "Draft". Version number is changed from Major to previous Minor

  4. If you are setting the moderation status manually (through Object Model) from a custom application or Workflow, you need NOT worry about checking Scheduling Start and End Dates and change the status to "Scheduled" or "Approved" according to these dates. You can always, change the status to Approved (as shown below). SharePoint would ensure that it gets the correct status as per Scheduling Dates.

    Item.ModerationInformation.Status = SPModerationStatusType.Approved  

APPROVING AND PUBLISHING ITEMS

SharePoint provides multiple ways to approve or publish items that can vary based on item's moderation status and version numbers. This section explains that. Note that the following explanation is only for "Pages" library in "Publishing Sites". However, the behavior should be same for other document libraries also, though Page Editing Toolbar would not be available.

 

The options to approve based on moderation status are:

 

  1. Item status - "Draft"
    1. Page Editing Toolbar: two buttons are visible: Submit For Approval, Publish
    2. ECB menu: "approve/reject" is not available. Instead, "Publish a Major Version" is available
    3. "View item properties" page: "Approve/Reject" button is available, which takes to the approval page. But on the approval page only the following two options are available:
      1. Draft
      2. Pending
  2. Item status - "Pending"
    1. Page Editing Toolbar: two buttons are visible: Approve, Reject - these button change the status directly
    2. Context menu: approve/reject menu is available and takes to approval page with all three options:
      1. Approved
      2. Rejected
      3. Pending

 

The behavior of various options is described below. To make it simpler to understand, I've provided the following categories for each behavior:

  1. Visibility: where and when "this" option is available
  2. Versions: how does "this" option impacts version numbers
  3. Moderation: how does "this" option impacts moderation status
  4. Scheduling: how does "this" option impacts scheduling

 

The behavior for options is:

  1. Submit for Approval

    1. Visibility: Appears when the approval status is "draft"
    2. Versions: Checks-in the current minor version
    3. Moderation: Changes the approval status to "Pending"
    4. Scheduling: If item is schedule and scheduled start time comes before item is approved, nothing happens

     
     

  2. Publish

    1. Visibility: Appears on Page Editing Toolbar when the approval status is "draft", version could be checked-in or out
    2. If the item Scheduled Start Date is in PAST (item is active)
      1. Versions: Checks-in (if checked out) and changes the current "Minor Version" (e.g. 4.1) to next "Major version" (e.g. 5.0)
      2. Moderation: Changes the approval status to "Approved"
      3. Scheduling (when scheduled start time comes): NA
    3. If the item Scheduled Start Date is in FUTURE (item is not active)
      1. Versions: Checks-in (if checked out), keeps the current "Minor Version"
      2. Moderation: Changes the approval status to "Scheduled"
      3. Scheduling (when scheduled start time comes):

        1. Changes the approval status to "Approved"

        2. Converts the latest Minor version to Next Major version

           

  3. Publish a Major Version (It's not same as Publish on Page Editing Toolbar)

    1. Visibility: In ECB Menu, only when the status is draft and item is checked-in
    2. Versions: Interestingly, this does not change version. It changes only moderation status. If item version is 0.1, it remains 0.1 even afterwords.
    3. Moderation: Changes the approval status to "Pending"
    4. Scheduling (when scheduled start time comes): No Change

 

HTH