CD DocDB FAQ
Contents:
What is a document?
What types of files should be posted in DocDB?
How do I know which topic to use?
What's the deal with keywords?
How do I link to a document?
Are there any existing sector standards for posting documents?
What functions may I perform as a DocDB user?
What is a document?A document, in DocDB lingo, is actually a collection of files, sort of like a folder. A document can contain any number of different types of files. But don't think of your DocDB document exactly as a folder. Your document should contain at least one file (whether it be a Word document, PDF file, graphic, whatever); additional files in that document should be closely related.
For example, let's say you're attending CHEP, and you have submitted both a paper and a poster. You could create two documents--one for your CHEP paper and one for your CHEP poster, or you could create a single document for both. The single document approach allows you to keep all your CHEP stuff together. But what if you went to CHEP for the last three years? Does it make sense to put these all in a single document? Probably not. First of all, are all your papers, posters or presentations on the same topic? Second, if there is no valid reason for keeping all the files together, creating a new document is desirable.
What types of files should be posted in DocDB?
There really isn't anything business-related that can't be posted in DocDB, but a partial list of things that are appropriate includes:
- files that need to be kept as a record or for reference later, such as project status reports
- files to which access should be restricted to a particular set of people
- files that need to be shared
- conference presenations, papers or posters and journal articles.
- procedures and manuals
but- Make sure you supply a document format that everyone can view (e.g. PDF) along with source formats of your document.
How do I know which topic to use?
Topics should be broad categories based on work that is being done, not on the organization you are a part of. The right topic for your document might not exist yet! Please don't choose a topic that doesn't fit. Email docdb-adm@fnal.gov with questions.
Ideally, categories with many documents should be divided into subcategories. You can easily have a web page link to all documents within a particular topic.
Please take a moment to look at the list of topics. Do the topics listed reflect the work you're doing? Do any topics need subcategories? Once again, please email your suggestions and questions to the DocDB administrator.
What's the deal with keywords?
Keywords can help refine a set of documents. We think they should be used sparingly and thoughtfully. In fact, the best time to use them is when you need to define a set of documents that are used to collaborate among a small group of people, while the keywords used are communicated to these people.
Keywords in DocDB may be official or unofficial. Official keywords are those that appear in the keyword list (the same as the "keyword chooser," which is the pop-up window you can use to select your official keywords when you're adding or updating a document in DocDB). These must be added by the DocDB administrator. They can be displayed as a list in DocDB and the keyword field is searchable via the advanced search function in DocDB.
Unofficial keywords are keywords you enter yourself when you're adding/updating a document. They don't appear in the keyword list, but they ARE still a searchable in the keyword field in the database.
Topics can be nested or combined with keywords to refine a collection of documents and aid in searchability.
As an example, the sub-topic "Education and Outreach" contains over seventy documents. By using the keyword, Supercomputing , I'm able to get a subset of these documents (now, only nine). It may not make sense to make Supercomputing a subtopic of the Education and Outreach topic because documents relating to Supercomputing may be found in many topics within DocDB.
Linking to an entire document DocDB URLs are of the form:
For Public documents:
http://cd-docdb.fnal.gov/cgi-bin/ShowDocument?docid=XXXX&version;=XX
where the X's represent just the numbers of the document. In most cases, you will want to leave off the version so that the latest version of the document is displayed. If you want to link to an old version, add &version;=XX to refer to the latest version.
Usually, if you have a document that isn't public, you want to provide the link to the document in both the private (username/password) and the certificate instances:
For Private (username/password) documents:
http://cd-docdb.fnal.gov:8080/cgi-bin/ShowDocument?docid=XXXX&version;=XX
For Certificate documents:
"https://cd-docdb.fnal.gov:440/cgi-bin/ShowDocument?docid=XXXX&version;=XX
Using "as of" instead of version number: Instead of specifying a version number, you can specify &asof;=2007-12-25 which will give you the version of this document current as of December 25, 2007.
Linking to files in a document
From the official DocDB instructions:There is a script interface that fetches files from DocDB. The URL is
http://cd-docdb.fnal.gov:8080/cgi-bin/RetrieveFile?docid=XXXX&version;=XX&filename;=xxxxxx
The version number can be left off to get files from the latest version number. The filename can also be left off. If there is only one file marked Main that file will be retrieved. An alternate form is
http://cd-docdb.fnal.gov:8080/cgi-bin/RetrieveFile?docid=XXXX&version;=XX&extension;=xxx
so for instance you can specify PDF as the extension to retrieve the PDF file for a document. As above, version can be left off or asof can be specified. If your request matches no files or more than one file, the full document information will be shown and the user will have to choose the correct file.
For both of these actions, if you want the result to be publicly accessible, use the URLs that point to the publicly viewable database. The document must also be publicly accessible for this to work.
Are there any existing sector standards for posting documents?
Yes:
- instructions for posting pr oject status reports
- Instructions for posting conference documents (for events in which many people in the sector parti cipate, such as CHEP).
What functions may I perform as a DocDB user?
Anyone with write access to DocDB (whether through a username/password interface or a PKI certificate) has the ability to:
- create a new document or update a document that they have permission to update.
- add an author
The following functions require administrator access:
- deleting a document
- adding or changing Topics, Keywords (official keywords that appear in the keyword list), Institutions, Document Types, Security Groups and Journals.
- approving personal account access for certificate users.
