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:

Overview

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:

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

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

  3. 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 p4d, the 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 help.

Architecture

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 architecture

  • Commons provides the browser-based user interface and communicates with the Perforce service through the P4Java API.

  • P4Combine provides the .docx and.pptx file 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:

http://www.perforce.com/documentation

  • Introducing Perforce

  • Perforce System Administrator's Guide

Users

Commons users are Perforce users. Each Commons user has a directory in the commons depot: //commons/user/<userID>. 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 commonsadmin.

  • 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 commonsguest.

In addition, Commons administration requires that there be at least one Perforce super user defined to manage administrative tasks that require 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 commonsmgmt.

For more information about managing Commons users, see Managing Users.

Spaces

Spaces are implemented in part by creating Perforce groups. There is an internal p4 counter called commonsSpaceId that determines the next group to use. It is incremented with each attempt to create a space. Commons groups are named commons_group_n, where 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 commonsSpaceId value of 213, the Space appears in the Perforce service as //commons/spaces/213.

Depot

Commons requires a depot in your Perforce service named //commons.

By default, files are located in //commons/spaces/<SpaceID>/files/... 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 help.

Commons creates empty folders by creating a .commons file in the folder path.

Files

Commons adds a suffix to filenames to indicate file revisions when a file is downloaded. The suffix takes the form pvn, where 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 giants_contract(pv3).docx. The 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 interface.

Workspaces

Each Commons user has a client workspace specification named commons_uclient_<userID>.

Each Commons space is represented by a client workspace specification named commons_sclient_<spaceID>. Do not edit these workspaces! They are not intended to be used outside of Commons.

Following files

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_label_<labelID>. 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 “Email notifications”.

Administrative Tasks

Commons administrators perform the following tasks, covered in this guide:

Hide partial matches
Highlight matches
0 matching pages