Add docs.

Author: manthey

README.rst

@@ -48,9 +48,29 @@ Development
 
 The most convenient way to develop on HistomicsUI is to use the `devops scripts from the Digital Slide Archive <https://github.com/DigitalSlideArchive/digital_slide_archive/tree/master/devops>`_.
 
+Annotations and Metadata from Jobs
+----------------------------------
+
+This handles ingesting annotations and metadata that are uploaded and associating them with existing large image items in the Girder database.  These annotations and metadata re commonly generated through jobs, such as HistomicTK tasks, but can also be added manually.
+
+If a file is uploaded to the Girder system that includes a ``reference`` record, and that ``reference`` record contains an ``identifier`` field and a ``fileId`` field, specific identifiers can be used to ingest the results.  If a ``userId`` is specified in the ``reference`` record, permissions for adding the annotation or metadata are associated with that user.
+
+Metadata
+========
+
+Identifiers ending in ``ItemMetadata`` are loaded and then set as metadata on the associated item that contains the specified file.  Conceptually, this is the same as calling the ``PUT`` ``item/{id}/metadata`` endpoint.
+
+Annotations
+===========
+
+Identifiers ending in ``AnnotationFile`` are loaded as annotations, associated with the item that contains the specified file.  Conceptually, this is the same as uploaded the file via the annotation endpoints for the item associated with the specified ``fileId``.
+
+If the annotation file contains any annotations with elements that contain ``girderId`` values, the ``girderId`` values can be ``identifier`` values from files that were uploaded with a ``reference`` record that contains a matching ``uuid`` field.  The ``uuid`` field is required for this, but is treated as an arbitrary string.
+
+
 Funding
 -------
-This work is funded in part by the NIH grant U24-CA194362-01_.
+This work was funded in part by the NIH grant U24-CA194362-01_.
 
 .. _HistomicsUI: https://github.com/DigitalSlideArchive/HistomicsUI
 .. _Docker: https://www.docker.com/

histomicsui/handlers.py

@@ -59,17 +59,29 @@ def _itemFromEvent(event, identifierEnding, itemAccessLevel=AccessType.READ):
         return {'item': item, 'user': user, 'file': image, 'uuid': reference.get('uuid')}
 
 
-def resolveAnnotationGirderIds(event, results, data, girderIds):
+def resolveAnnotationGirderIds(event, results, data, possibleGirderIds):
     """
     If an annotation has references to girderIds, resolve them to actual ids.
 
     :param event: a data.process event.
     :param results: the results from _itemFromEvent,
     :param data: annotation data.
-    :param girderIds: a list of annotation elements with girderIds needing
-        resolution.
+    :param possibleGirderIds: a list of annotation elements with girderIds
+        needing resolution.
     :returns: True if all ids were processed.
     """
+    # Exclude actual girderIds from resolution
+    girderIds = []
+    for element in possibleGirderIds:
+        # This will throw an exception if the girderId isn't well-formed as an
+        # actual id.
+        try:
+            if Item().load(element['girderId'], level=AccessType.READ, force=True) is None:
+                girderIds.append(element)
+        except Exception:
+            girderIds.append(element)
+    if not len(girderIds):
+        return True
     idRecord = _recentIdentifiers.get(results.get('uuid'))
     if idRecord and not all(element['girderId'] in idRecord for element in girderIds):
         idRecord['_reprocess'] = lambda: process_annotations(event)