wiki:Help/UserRelateDocument

ESTEST Relating Documents

This document seeks to help users understand how and why to form relations between documents in ESTEST.

What are relations?

A document relation is a link or edge between two UR XML document nodes in ESTEST. These links means that a physical simulation or publication is related to another simulation or publication.

This mechanism provides an easy way to point to resources pertinent to a document such as similar physical simulation data or a relevant paper publication. The relation reference is based on a list of UUIDs written in UR XML data of a document.

How to relate documents

There are currently two ways to relate two or more documents; the first is a general method that can be used by anyone having access to the documents and the other is restricted to the document(s) owner. We describe the first one first.

Viewing any UR XML document summary (a sample is shown)

will give the registered user a button to "Edit Relations" underneath the "Related Records" section. Clicking on this button will popup a form to modify the relations of a document.

/estrac/imgs/Help/Screenshot-ESTEST-view-edit-relations.png

This page shows a list of currently related documents given by elements with a checkbox input. Unchecking the box next to a related record and clicking "Done" will remove the relation from the current document only (see dangling pointers below). A new relation can be formed between the current document and another document by filling in the UUID of the other document in the text input form element(s). Clicking "Done" in this case will form a bi-directional link between the current document and the other document--that is the other document will also be related to the current document.

The second method of forming relations between document is available to the owner of documents only and operates only on the set of documents the user owns. The user interface for this method is provided directly in the account management page for the registered user under the list of documents the user has created.

http://estest.ucdavis.edu/estrac/blog/imgs/estest-account-relate.png

Checking any number of these documents and then clicking the "Relate" button will form bi-directional links between every document in the set with every other document in the set except itself.

Caution on dangling pointers

Whereas forming relations between documents is always a bi-directional process, two documents are always related to each other, the method of removing relations from a document acts only on one document at a time. Therefore, it takes two remove operations to fully destroy the edge between documents. Should a document be deleted while a relation pointing to it exists in another document that relation effectively points to nothing and becomes a dangling pointer; try to proactively avoid this.

Last modified 6 years ago Last modified on 08/25/11 12:35:09