wiki:Help/UserRefDocument

Referencing ESTEST Documents

This document describes two ways to reference and link to UR XML documents hosted on ESTEST servers. Effective collaboration and publication depend on sharing both individual references and groups of UR XML documents in a straightforward way.

Reference UUID

Every UR XML document in ESTEST is uniquely identified by a Universally Unique Identifier (UUID) Version 4 that is a random string of 32 hexadecimal digits and four hyphens. Technically this UUID is the only identifier in the ESTEST database that is guaranteed to have 1-1 correspondence to a document on the server.

The UUID can be used as a search field. Additionally, several web pages on ESTEST accept the uuid or a list of uuids as a GET parameter and these links can be embedded like any standard URL. For example, the XQuery web transform page view.xql accepts 1 uuid GET parameter and displays the HTML summary for that UR XML document.

http://estest.ucdavis.edu/exist/estest/www/xql/view.xql?uuid=a5344e4c-c0db-43ec-a468-c625b05ee0da

This link can be copy/paste in email, chat, blog, etc. any technology that accepts the URL standard.

Reference Identifier

Another identifier associated with UR XML documents is a string identifier that is an abstraction for a file name. This string is delimited by forward-slash tokens that simulate directory hierarchy. Unlike UUID, this identifier string is not unique and may be duplicate even by the same user. Nevertheless, you can search for this identifier string or part of the string to return all matching documents with the same prefix. For example, the search

http://estest.ucdavis.edu/exist/estest/www/xql/search.xql?q=yuangm%2Flattice_constants

returns all UR XML documents with the identifier string matching the prefix "yuangm/lattice_constants".

Reference via Search Resutls

Instead of compiling long lists of many UUID references, if you are able to uniquely identify a set of UR XML documents using an identifier string prefix; then all these documents may be referenced collectively in one search term. In order to ensure this search collection returns only your documents it is a good idea to filter for your username in the search parameters. In addition, the search results may be displayed using HTML lists-of-lists to give a tree-like file hierarchy view of the documents. For example,

http://estest.ucdavis.edu/exist/estest/www/xql/search.xql?nfuuids=0&q=yuangm%2Flattice_constants&uf=yuangm&view=dir

returns search results of documents with identifiers matching the string prefix "yuangm/lattice_constants" and only those documents that belong to the user "yuangm". The view of these results shows the simulated directory hierarchy implied by the '/' tokens.

Short URL Trick

Sometimes a URL to ESTEST: either to search with GET parameters for the query and options or to view with the embedded UUID can be too long to easily specify in print material such as a publication. In these cases, you may use a Short URL service to generate a short url that will redirect to the original link on ESTEST. For example, we can shorten the url

http://estest.ucdavis.edu/exist/estest/www/xql/view.xql?uuid=1018852b-2486-4fdd-a753-3c5c6b6db66b -> http://goo.gl/bpJlQ

or

http://estest.ucdavis.edu/exist/estest/www/xql/search.xql?nfuuids=0&q=yuangm%2Flattice_constants&uf=yuangm&view=dir -> http://goo.gl/oqTcN

These two examples use the http://goo.gl/ service, others http://tiny.cc/, https://bitly.com/ are available.

Last modified 6 years ago Last modified on 03/16/12 12:01:53