Document File Versioning

Purpose

The purpose of this document is to define the process of using File Versions in ClientSpace.

Overview

Files uploaded to ClientSpace as Attachments or assigned to Dataform Fields can now have a hierarchy of several files, all associated with a ‘Primary’ file.  The Primary file is considered the currently in-use file.  Other files associated with this Primary file are considered to be ‘Versions’ or ‘Versioned’ files.  Versioned files can be updated to be the Primary file (a technique called ‘Pinning’).  This will allow for somewhat of an historical record of File Management activity.

On Attachment lists or Dataform Fields, only the Primary file is displayed.  Using the File Management Upload web page, modifications to the hierarchy can be accomplished.

There is no technical limit to the number of files that can be included in the hierarchy, but only one file will be designated as the Primary file at any time.

Protected versus UnProtected

If files are shared over multiple locations in ClientSpace, they can be managed as individual sets of files (Protected) or as a synchronized set (UnProtected).  This implementation in ClientSpace is currently limited to Orgs, Contacts and Activity Attachments. 

See the section “Special Considerations” below for a description of this methodology. 

System Configuration

On the App Settings page, ‘Miscellaneous’ tab, a new “File Versioning” checkbox has been added.  This checkbox sets the default behavior for the installation.  When uploading a file, the File Management Upload page will contain a set of radio buttons labelled “Replace” and “New Version”.  Based on the File Versioning checkbox setting, the appropriate radio button will automatically be selected based on the following convention:

• When unchecked, files uploaded over existing files will ‘Replace’ the existing file (this is how prior versions of ClientSpace operated)
• When checked, files uploaded over existing files will become the Primary file, causing the existing file to become a ‘Version’ of the Primary file

Security

New Security Entities have been added to manage the versioning process:

• FileMan_Ver_Override
  • Allows a user to override the default File Versioning App setting when uploading a file. The user can select either the “Replace” or “New Version” radio button on the File Management Upload page.  Each time the page loads, the default value will be selected
• FileMan_Pin
  • Allows a user to swap files in the versioning hierarchy
• FileMan_Delete
  • Allows a user to delete a version of a file

File Management Upload User Interface Modifications

File Versioning is handled via the File Management Upload User Interface.  Several changes have been made to this interface:

• Existing files (Current File and those in the Versions list) can now be viewed from this interface (click the File Name hyperlink)
• A logical Version Number is displayed next to each file name. The number is derived from the order in which associated files were uploaded to the system, ‘v1’ being the earliest.
• A Versions list appears on the form, ordered by Version Number ascending
• A Help button appears next to each file name. Clicking this button displays information about the file:
  • File Name
  • Version
  • Description
  • Uploaded Date
  • Modified Date
  • Size
• The Versioning radio button set, “Replace” and “New Version” has been added. These buttons define the operation of uploading a file:
  • If “Replace”, uploading a new file will replace the Current File and all its contents with the new file
  • If “New Version”, uploading a new file will cause the Current File to be moved to the Versions list, and sets the new file to be the Primary file
  • On page load, the buttons will default to the File Versioning App Setting described above
  • If the User is not a Global Admin and does not have “FileMan_Ver_Override” entity, the buttons will be disabled and the user can only perform the operation defined by the File Versioning App Setting
• The “Category” value allies to ALL associated files
• The “Description” and “Tags” apply to the specific file
• A ‘Pin’ button appears on each file in the Versions list. Clicking this button:
  • Swaps the Current File for the Versioned file being pinned (must be a global admin or have FileMan_Pin entity)
  • A ‘Delete’ button appears on each file in the Versions list, if:
    • The User is a global admin or has FileMan_Delete entity
    • The file is not in use in another location

Special Considerations

While the process is consistent in use, it is important to recognize the following conditions and how they affect the process:

• Dataform Attachments
  • Uploading a new file takes effect only after Saving the File Management Upload page
  • If a Current File exists, uploading a new file and clicking Save will pin the new file as the Current File and version the existing file
  • Pinning a Versioned file takes effect INSTANTLY, no Save is needed
  • Deleting a Versioned file takes effect INSTANTLY, no Save is needed (a confirmation message is presented before the delete is executed)
• Dataform File Management data types (Dataform fields)
  • Uploading a new file does not take effect until:
    • The File is uploaded and the File management Upload page is Saved, AND
    • The Dataform is Saved
    • The Dataform field File Name will appear in Red type if it has changed and the form is not yet Saved
    • If the Dataform is not saved, no changes will be made and the newly uploaded file will be abandoned
  • Pinning a file does not take effect until:
    • The File Management Upload page is Saved, AND
    • The Dataform is Saved
    • The Dataform field File Name will appear in Red type if it has changed and the form is not yet Saved
    • If the Dataform is not saved, no changes will be made
  • Deleting a Versioned file takes effect INSTANTLY, no Save is needed (a confirmation message is presented before the delete is executed)
• Orgs, Contacts and Activity Attachments
  • Behavior is similar to Dataform Attachments
  • For Orgs and Contacts, pinning will be synchronized
    • Example:
      • Upload File_A to Contact
        • File_A will appear on both Contact and Org
      • Upload File_B to Contact
        • File_B will appear and be pinned on Contact and Org, File_A will be versioned on both
      • Pin File_A on Contact
        • File_A will also be pinned on Org (UnProtected)
        • File_B will be versioned on both
      • Pin File_B on Org
        • File_A will still be pinned on Contact
      • Upload File_C on Org
        • File_C will be pinned on Org
        • File_A will remain pinned on Contact
        • File_C will be in Version list on Contact
      • For Activity Attachments, pinning will not affect Contact/Org (Protected)

The file attachment datatype  (File Upload Manager - database) in NEXT has been enhanced to respect both dataform and File management security rights.  These security rights work in the following way:

Dataform_Field security: View/Add/Edit/Delete controls whether a user can

• View - view the file from the field
• Add - add a new file when the field is empty
• Edit - update or change an existing file (folder icon)
• Delete - Delete a file from the Dataform (trashcan icon).

With field edit rights comes an additional layer of security in the file manager dialog using the File_Man security entities:

• File_Man_Delete - Edit rights provide the ability to delete files in the file manager dialog (under "Manage Versions")
• File_Man_Pin - Edit rights provide the ability to pin a different file (under "Manage Versions") and make it the current file.
• File_Man_Ver_Override - Edit rights provide the ability to override the system default setting of Pin New vs Replace File.