General Instructions
Event Organizer and Calendar
Advanced Users & XML
Certificate Instructions
To refer to your document use the syntax DarkSide-doc-XXXX where XXXX is the document number (1 to 6 digits). You can also use the form DarkSide-doc-XXXX-vXX to refer to a specific version of a document. The DarkSide-doc-XXXX form refers to the latest version.
You can also construct URL's that link to your document. The URL is of the form
https://darkside-docdbcert.fnal.gov/cgi-bin/cert/ShowDocument?docid=XXXX&version=XX,
where the X's represent just the numbers of the document and version.
(I.e. leave off the DarkSide-doc-
and -v.
) As above, you can leave off the
&version=XX to refer to the latest version.
Using "as of" instead of version number: Instead of specifying a version number, you can specify &asof=2002-12-25 which will give you the version of this document current as of December 25, 2002.
There is a script interface which fetches files from DocDB. The URL is
https://darkside-docdbcert.fnal.gov/cgi-bin/cert/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
https://darkside-docdbcert.fnal.gov/cgi-bin/cert/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.
Any simple search can be embedded into a URL for reference from a web page. The most useful searches are by author, topic, keyword, or events.
To link to a topic, you must first find out the topic ID number. The easiest way to do this is to simply click on that topic from the list by topic page. The URL for a single topic will be https://darkside-docdbcert.fnal.gov/cgi-bin/cert/ListBy?topicid=xxx. Similarly, links to documents by authors are most easily found by the list by author page.
Use the search form to link to a keyword: https://darkside-docdbcert.fnal.gov/cgi-bin/cert/Search?keywordsearchmode=anysub&keywordsearch=xxxxxxx.
Conferences and meetings are topics, but have special display capabilities: ?topicid=xxx&mode=conference or https://darkside-docdbcert.fnal.gov/cgi-bin/cert/DisplayMeeting?conferenceid=xxx.
If your links are from a public page, be sure to use the links for the publicly accessible DocDB. Only publicly accessible documents will be listed.
By using the search capabilities, more complicated combinations of documents can be shown. To do this, link to the Search script with correct parameters as described below. Producing these kinds of searches requires an understanding of two additional parameters, innerlogic and outerlogic, both of which can have values of AND and OR. For instance, if you specify two authors, innerlogic=OR will return documents by either author while AND will require the document to be authored by both people. To understand outerlogic, take the example of searching for an author and a topic. outerlogic=OR will require a document to either have the correct author or the correct topic, while AND will require both. Both options can be specified at the same time. outerlogic defaults to AND and innerlogic defaults to OR. But, this could change in the future, so specify these values if you want to be absolutely sure.
Here is a (nearly) complete list of search parameters that can be specified:
For titles, abstracts, keywords, publication info, file names and file descriptions, you should specify the
searchmode
also. Currently there are four modes:
More modes can be added if required. To search for more than one word, place the code for a space (%20) between them.
To search for more than one author, topic, etc. (fields with numbers) you can specify more than one in the URL (see the examples).
Examples:
An XML interface for retrieving information from and submiting information to DocDB is partially complete. It is not fully complete, but it may satisfy the most common needs.
Any link to Search or ShowDocument described above will generate XML output if &outformat=xml is added to the parameter list. Search returns a summary of the found documents while ShowDocument returns all the meta-info for the document.
This output is easy to incorporate into your own programs and should be more stable than the HTML counterparts (although internal changes in DocDB's formats may change the XML output). Future improvements to the XML facilities of DocDB may include XML output from ListBy, XML output of events, and XML output of topic, author and other lists. If any of these enhancements would be useful to you, please contact your administrator or the developers.
Since version 8.4 DocDB has supported uploads of XML data describing documents. This is done with the XMLUpload script. The XML output of ShowDocument described above can be used almost directly to create a new document. One new XML element must be added to such an XMLFile and a second element is optional. Both elements must be added as children of <docdb> (at the same level as <document>).
The first XML element is control which has two parameters: mode and
usedate. mode must be one of three values, new
, bump
, or updatedb
. New
ignores the document ID in the uploaded XML and creates a new document with the included
information. Bump uses that document ID and creates a new version of that document with the
XML information. Updatedb uses the document ID and the version and updates the metadata for that version.
usedate, if present (the value is unimportant) will take the
modification dates for the document from the XML. The default is to use the current date and
time. So the control element might look like this:
<control>
<mode>new</mode>
<usedate>yes</usedate>
</control>
The second element XML element (which is optional) is authentication which contains the username and password needed to download the file(s) in the document from the remote source. It will look like this:
<authentication>
<username>http-basic-username</username>
<password>http-basic-password</password>
</authentication>
Generally speaking, when DocDB is processing an XML file, the id numbers describing things like topics, events, etc. are used and the names of those things shown in the XML file are ignored. Also, not all information about a document van be uploaded via XML. This can be changed if there is a need for it.
If the id numbers are missing, DocDB attempts a text match for the following information:
The following information cannot be uploaded via XML:
Finally, you will notice that there is no provision for adding files via XML. This could be added but was not needed at the moment.
It is also possible (and not too difficult) to write Perl programs to insert documents into DocDB. Examples of how to do this may be in scripts/examples in the DocDB source package. Help with this may also be obtained by writing the DocDB users mailing list linked from the DocDB homepage.
|
|
|
| Security, Privacy, Legal | |
DocDB Version 8.8.10, contact
Document Database Administrators