Streams Applied: Document Management Workflow

Streams & Branches

Streams are an exciting new feature in Perforce. In order to understand streams – what they are and how they can make your work more productive – it helps to look at some concrete applications. In this article, the first of a series, I'll look at a simple yet useful workflow. Perforce can manage many types of digital assets, from source code to multimedia to documents, using a variety of workflows and processes. In this article I’ll look at managing documents for the HR department. The HR documents and forms are subject to strong control and auditing, because they impact employee benefits and workplace regulations. (Note that the visual tools shown in this article may look different by the time they are generally available.)

Data Model

I’ll use a directory and branching model known as Standard Hosted with Emergency Bug Fix, taken from the Perforce Directory Standard (PDS). This model is similar to the streaming promotion model discussed in Practical Perforce. This model was not developed specifically for document management, but it works very well in my scenario. The normal workflow is shown below. Documents are drawn up or modified as proposed changes. These are moved up to a review stream for consideration by the HR manager, and finally they are promoted to the published stream. Documents in the published stream are official and in force. This part of the workflow is represented by the green triangles moving up to the published stream.

Document management model

Occasionally a published document must be amended quickly; perhaps a mistake is found in a benefits document, and must be corrected immediately. That emergency fix part of the workflow is shown in the figure above, with the red triangles representing that quick change. The change is very quickly moved down to the other streams.

Using Streams – Normal Workflow

The HR department receives a stream depot for its digital assets. The HR department keeps a few different types of data in the HR depot, and the stream called final contains the in-force versions of the data. Only the HR manager has permission to put data into the final stream. For documents, the review and proposed streams have a view that only pulls in the HR documentation.

Paths:
share docs/...

Any HR department member is allowed to check in changes to the proposed stream, and the review stream is limited to the senior HR assistants. The relevant lines from the protections table are shown below.

Protections for HR streams

This stream model is shown in the figure below.

Stream graph

A promotion process, from proposed to final, is very simple. An HR aide checks in an updated version of a document in the proposed stream. A senior HR assistant periodically pulls new documents to the review stream, and makes any necessary corrections. Finally, the HR manager notices that there are documents waiting for final approval.

If the HR manager only wants to promote certain files or changelists, she can access other options on the promotion dialog. Finally, the HR manager can promote the files and submit them.

Using Streams – Hot Fix Workflow

Now I’ll briefly describe what happens when the HR manager has to make a quick amendment to an official document. She would check in the change directly on the final stream, and use the stream GUI to merge that change down to the review stream.

Merge notification

After noticing that a merge is pending, she can use the context menus to start the merge process, just like she did with the promotion process. Finally, an HR assistant would merge the change down to the proposed stream so it is in sync with the other streams.

Easy and Intuitive

The HR manager and her assistants are not experts in version control tools. They need a simple, effective way to manage their document workflow – and that’s exactly what streams gives them. The stream GUI gives them an intuitive sense of where documents are kept during their lifecycle, and a quick, easy way to see whether any documents are in need of review and promotion. Actually performing the promotion only takes a few mouse clicks. Combined with the rest of the Perforce tool set, including the Microsoft Office plug-in, streams provide a way to easily model and manage a document workflow.