DocDB

Introduction

The Mu2e Document Database (DocDB) is the core of Mu2e's institutional memory, containing presentations, internal notes, posters, policies, planning documents and project management documents; a document might even be a scan of something you drew on the back of a napkin. It is not just for "official" or "final" documents; it is an appropriate place to store works in progress and living documents. DocDB also contains copies of selected external documents to ensure that we have a reliable reference copy. Most documentation for Mu2e Computing and Software is found on the Mu2e wiki.

When you create documents in DocDB you will be asked to set the permissions for who may view or modify the document. Under the view permissions there is an option to make the document public. The lab security policy says that we may no longer use this option. The software has not yet been updated to remove hat option. Please do not choose it. If a document does need to be made public, see Communications_and_Collaborative_Tools#Fermilab_Public_DocDB.

Accessing DocDB

The url for the main page of the Mu2e DocDB is https://mu2e-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase. You may be prompted to enter your Fermilab services (SSO) username and password. If you have recently authenticated using SSO to other Fermilab applications, the system might bring you directly to the main page. The page should look like the following, with the exception that the "Last 7 Days" section will be different:

Checking your Permissions

To verify that the permissions on your DocDB account are set correctly, please click on [1] . If your permissions are correct, you will see a pdf file that reads "You have permission to read documents in the group "mu2e" on the Mu2e DocDB.". If you do not see this pdf file, send email to mu2e-docdb@fnal.gov .

To Request Additional Groups

DocDB uses user groups to control access to documents. A DocDB user may be a member of many groups but most people working on Mu2e only need membership in the group "mu2e"; membership is usually given at the time that your Mu2e computing accounts were created. There are separate read and modify groups for each version of each document. Some members of Mu2e will need to be members of additional groups, such as mu2e-techboard or groups related to the Mu2e construction project. If you need to request membership in additional groups:

1. Visit https://mu2e-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase
2. In the left hand sidebar click on "Apply to Groups".
   1. On this page, check that your username, name and email information are correct. If not, contact the Mu2e DocDB Administrators.
   2. On the left hand column, look to see the list of groups in which you are already a member. If you have no groups listed, but you can see the pdf files mentioned in the above section, that's OK. You have implicit membership in the group "mu2e" via another method for managing group membership.
   3. On the right hand side there is a scrolling box of group names. Select all groups that you request to join.
   4. To request one group and clear all other selections, left click on the group name; to toggle a group request on/off right click on the group name.
   5. In the notes field tell us why you need access to the additional groups and which university or lab you work for; for students, post-docs and technicians, please also tell us the name of your supervisor.
3. Click on the "Apply for Access" button.
4. This will send email to the Mu2e-DocDB administrators. Normally your access will be approved with in a few hours but it may occasionally take up to 1 day. You will receive an email when you are approved. If you apply on a weekend or holiday you may not get approval until the next working day.

Introduction

The Mu2e document management system is the Mu2e DocDB,

https://mu2e-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase/

The word "document" should be understood its broadest sense: it can be a note written in Word or LaTex, a PDF file, a PowerPoint presentation, a photograph, a poster, a video, a construction drawing, indeed anything that we wish to archive and catalog; it could even be a scan of something sketched on the back of a napkin. The one exception is source code, which is maintained in a source code management system; most Mu2e code can be found in the Mu2e GitHub organization. The technology underlying the document database is an open-source project, originally developed at Fermilab, named DocDB.

A document may have many versions; each version may contain a single file or many files; there may be a different number of files or type of files in each version. The meta-data stored with each version of each document includes the author, the creation date, a list of topics and keywords, read/write permissions, a document type and associations with events such as collaboration meetings, subgroup meetings or conferences. There is a search function that works on the meta-data; there is no full text search capability. It is possible to update the meta-data for an existing document without changing the document. There is a mechanism for collecting sign-offs on controlled documents and to lock documents so that they may not be modified. One may write URLs directly to a document or to a file within a document. One may write a URL asking to show the version of a document that was current as of a given date; this simplifies the task of preparing, and preserving, a snapshot of DocDB for use in a review. There are many more features.

Mu2e also uses DocDB to present agendas for meetings; the agendas contain links to the documents presented at the meeting. In this way DocDB allows a unified view of all of our documents; it does not artificially separate documents shown at meetings from other documents.

You can set watches on documents, or on groups of documents, and will be notified when one of those documents is updated.

Documentation

Most of the features of DocDB are well documented by DocDB's own documentation, which is available from the top link in the left hand side bar of the DocDB main page. The direct link is:

https://mu2e-docdb.fnal.gov/cgi-bin/sso/DocDBInstructions

Look at the bottom of the left hand side bar of this page, under "All Instructions", to find links to additional documentation. Because DocDB is such an important tool for everyone working on Mu2e, we recommend that you make some time to become familiar with all of this documentation.

Groups and Permissions

DocDB uses a group based permission system. The Mu2e DocDB has many groups, three of which are "mu2e", "mu2e-techboard" and "reviewer". These three will be sufficient to illustrate the main ideas. Each version of each document has a list of groups that may read the document and a list of groups that may modify the document. Each individual user is assigned a list of groups to which they belong. A user may read any document that has read permission for one or more of their groups. A user may modify any document that has write permission for one or more of their groups.

All people working on Mu2e are members of the group "mu2e" and most are members of only that group. Members of the Mu2e Technical Board are also members of the group "mu2e-techboard". There are some documents that are readable only by members of the Technical Board and not by regular members of Mu2e.

When Mu2e is being reviewed, we indicate which documents will be visible to reviewers by adding the group "reviewer" to the read permission list of each of those documents. Each reviewer must apply for their own DocDB account and the group "reviewer" is added to that account. In this way reviewers may see all documents that they are entitled to see but may not see other documents and may not modify or create any content in DocDB.

At one time it was legal to mark documents as publicly readable. This is no longer permitted but the group "public" still appears as a possible group in the read permission list for a document. The lab periodically scans for such documents and tells the administrators to remove public permission.

Customizing Your Account

Coming soon.

Obsolete Documents

By design, neither documents nor versions of documents may be deleted by normal users; even when obsolete, they are still part of the audit trail of how we got to where we are. If you wish to mark a document as obsolete you can use the "Notes and Changes" field, you can edit the metadata to add "Obsolete" to the title or you can add a new version containing a brief note that the document is obsolete. In the rare case that it is important to delete a document, contact a Mu2e DocDB administrator; there is a mail link to the administrators at the bottom of each DocDB page. Normally we only do this for documents that contain information that should not be visible within DocDB.

Guidelines

Coming soon.