Welcome to Commons
This chapter provides an overview of Commons, its architecture, and how it works with the Perforce versioning service. It also provides an outline of the primary tasks you can perform as a Commons administrator. This chapter includes the following topics:
Commons is a browser-based file versioning application that enables users to share files while keeping track of revision history. It is built on top of the Perforce versioning service.
Commons is based on the concept of spaces, which are collections of files. Spaces can be closed and restricted to members only, oropen and accessible to any authenticated Commons user for viewing, downloading, and uploading of files.
A typical workflow for Commons could include the following:
Sally logs into the Commons browser interface, opens a space, finds a file, views the file history to see who worked on it most recently and what kinds of changes were made, and downloads the file for editing.
After making her own edits, Sally logs back into Commons and uploads the revised file by dragging and dropping it. She writes a brief description of the changes she made, and sends an email invitation to Vikas asking him to review her changes.
Vikas clicks the link to the file in the email, downloads the file, makes some edits, uploads it, and sends an email to Sally informing her that his edits are ready for her to view.
In a more complex scenario, Sally makes her edits and discovers that Fernanda has uploaded her own revision of the file while Sally was working on it. When Sally attempts to check in her revision, Commons prompts her to view a visual comparison of the file revisions, and asks her if she wants to merge the two versions into a single version that contains both her edits and Fernanda's, accept Fernanda's edits alone, or reject Fernanda's edits and upload only her own.
The file versioning functionality and metadata management are handled
by the Perforce service (an instance of
Perforce Server). The browser interface, preview, comparison, and conflict
merge functionality are provided by Commons web services. For more
information about the Commons user interface and workflow, see the Commons
Commons consists of four web applications that work with the Perforce versioning service to provide a single browser-based user interface that enables users to share, search, view, download, upload, track revision histories, preview, compare revisions, and merge conflicting revisions of files:
Figure 1. Commons architecture
Commons provides the browser-based user interface and communicates with the Perforce service through the P4Java API.
P4Combine provides the
.pptxfile compare and merge services. It communicates with the Commons web service over http.
P4Preview provides file previews in the Commons user interface. It communicates with the Commons web service over http.
pdfcompare provides all non-txt, non-image, and non-docx file comparisons in the Commons user interface. It communicates with the Commons web service over http.
P4Search provides file and metadata search services. It communicates with the Commons web service over http and with the Perforce service through the P4Java API.
The Perforce service (p4d) stores all of the data used by the four Commons services, including versioned files and metadata.
The five Commons web applications should be deployed in separate web containers. If Commons is installed as a virtual machine image using the Commons OVA (Open Virtual Appliance), the web applications are deployed in separate Jetty web containers.
Commons and the Perforce service
Commons is built on top of the Perforce service and uses the Perforce service to manage files, spaces, users, and other metadata.
This section assumes that you are familiar with basic Perforce concepts and administrative tasks. If you are administering a trial installation of Commons, you do not need to understand all of these concepts. But if you are administering a production Commons installation and you are not familiar with Perforce, you might want to refer to the following Perforce documentation at:
Perforce System Administrator's Guide
Commons users are Perforce users. Each Commons user has a directory
in the commons depot:
This directory includes an
icon.jpg file for the
image that is displayed for the user in Commons.
Commons uses two Perforce user accounts to perform certain tasks behind the scenes.
The Commons administrator account is used by Commons to create spaces and perform other tasks. The default Commons administrator user account is
The Commons guest user account is required for normal operation, and enables users who are not members of a closed space to view, download, and upload a file, if a space member sends them a link to the file. The default Commons guest user account name is
In addition, Commons administration requires that there be at least
one Perforce super user defined to manage administrative tasks that
super access to the Perforce service. Only
super users can access the Commons User Management console. If Commons
is installed as a virtual machine image using the Commons OVA, the
default Perforce super user for access to the User Management console is
For more information about managing Commons users, see Managing Users.
Spaces are implemented in part by creating Perforce
groups. There is an internal p4
determines the next group to use. It is incremented with each attempt to
create a space. Commons groups are named
n is the value of the
commonsSpaceId counter at the time of space
creation. Space creation fails if Commons cannot create or modify the
next assigned group. Each time a member is added to a space, the member
is added to the group.
Spaces are represented in the
//commons depot by
the value of
commonsSpaceId. For example, if the
space "Federal contracts" has the
213, the Space appears in the Perforce
Commons requires a depot in your Perforce service named
By default, files are located in
You can, however, map any depot location to an existing space by using
the "Include New from Depot" setting in Space properties. For more
information about mapping Perforce depot locations to spaces, see the
Commons creates empty folders by creating a
.commons file in the folder path.
Commons adds a suffix to filenames to indicate file revisions when a
file is downloaded. The suffix takes the form
n is the version number of the file. For
example, if you download version 3 of the file
giants_contract.docx, it will appear on your
local machine as
suffix is visible only on the user's local machine. The version number
is listed under or next to the filename in the Commons browser
Each Commons user has a client workspace specification named
Each Commons space is represented by a client workspace
Do not edit these workspaces! They are not intended to be used outside
When a user follows a file, the file is tracked using labels and the
Reviews: field of the user's Perforce user account.
These labels are named
Commons generates user notifications by using the Perforce service's
p4 reviews capability. These notifications are
internal to Commons. To enable email notifications as well, a Commons
administrator can set up a review daemon. For more information, see
Commons administrators perform the following tasks, covered in this guide:
Install and upgrade Commons and Perforce services
Add and manage Commons users
See Managing Users
Back up and recover versioned files and metadata
Start and stop services, manage Commons virtual machines, enable email notification, and monitor logs