|
|
| Line 1: |
Line 1: |
| − | == Introduction ==
| |
| − | This document provides the technical documentation of the AnnoSys system. Therein, the following methodology is used. First, a reference to basic workflow definitions is given. Then, an overview of the system architecture introduces the technical components implemented to realise these workflows. Next, a detailed description of the basic data model and its implementation with the means of the W3C Open Annotation specification is provided. Finally, the specification of technical interfaces or configuration details are provided in the following section for each technical component whenever apropriate.
| |
| − |
| |
| − | == Basic Workflow ==
| |
| − | Our publication ''[http://www.ingentaconnect.com/content/iapt/tax/2013/00000062/00000006/art00011 Annotating Biodiversity Data via the Internet]''<ref name="AnnoSys_AnnotatingBiodivData">Tschöpe, O., Macklin, J. A., Morris, R. A., Suhrbier, L. & Berendsohn, W. G. 2013. Annotating Biodiversity Data via the Internet. – Taxon 62(6): 1248-1258. Online available at http://www.ingentaconnect.com/content/iapt/tax/2013/00000062/00000006/art00011<br/></ref> provides an detailed description of the basic workflows elaborated for AnnoSys.
| |
| − |
| |
| − | == System Architecture ==
| |
| − | AnnoSys' implementation aims to model the basic workflow and to integrate further requirements identified in <ref name="AnnoSys_AnnotatingBiodivData"></ref> as close as possible. Therefore, AnnoSys is composed of the following interacting system components:
| |
| − | * Repository
| |
| − | * User Interface
| |
| − | * Security
| |
| − | * Message System
| |
| − | * Services
| |
| − |
| |
| − | [[Image:Technical_Specification_Overview.png|frame|none|''AnnoSys system architecture'']]
| |
| − |
| |
| − | The repository component provides functionalities to archive annotations including the relating original record documents presented to the user at an annotation's creation time. A web based, but desktop oriented user interface supports annotators, curators and users to intuitively manage annotation workflows. The security component is responsible for secure authentication, authorisation and data privacy concerns within the system. The task of the message system component is to organise information flows such as informing annotators, curators or other users about status changes in annotation workflows. Finally, the service component provides interfaces to enable data exchange with external clients or services interacting with the repository.
| |
| − |
| |
| − | The following sections elaborate on AnnoSys' system components.
| |
| − |
| |
| − | === Repository ===
| |
| − | Within AnnoSys, [http://www.openannotation.org/spec/core/20130208/index.html W3C Open Annotation Data Model (OA)]<ref name="W3C_OASpec">Sanderson, Robert; Ciccarese, Paolo; Van de Sompel, Herbert. ''W3C Open Annotation Data Model - Community Draft, 08 February 2013''. Retrieved 01 August 2013, from http://www.openannotation.org/spec/core/20130208/index.html.<br/></ref> serves as a basis data model to store and exchange annotation data. While OA's data model is defined based on the [http://www.w3.org/RDF/ Resource Description Framework (RDF)]<ref name="W3C_RDF">W3C RDF Working Group, ''Resource Description Framework (RDF)'', http://www.w3.org/RDF/, 22 March 2013. Retrieved 16 December 2013<br/></ref>, record documents are delivered based on [http://www.w3.org/XML/ Extensible Markup Language (XML)]<ref name="W3C_XML">W3C. ''Extensible Markup Language (XML)'', 29 October 2013. Retrieved 16 December 2013, from http://www.w3.org/XML/<br/></ref> exchange formats like e.g. [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD]<ref name="TDWG_ABCD">Holetschek, Jörg, ''ABCD - Access to Biological Collection Data'', http://wiki.tdwg.org/twiki/bin/view/ABCD/, 02 March 2010. Retrieved 16 Dec 2013<br/></ref>. Due to the close relationship of annotations and record documents, both have to be archived within the AnnoSys repository to ensure exact recovery of annotation data at any later point in time. Finally, the repository also comprehends agent(user) profile data and agent authentication and authorisation information.
| |
| − | ==== Annotations ====
| |
| − | In consideration of the RDF oriented nature of OA based annotation data, AnnoSys uses so called RDF stores (aka. triple stores) to store annotations. These stores can be regarded as databases primarily specializing in storing and retrieving of RDF data. Usually, information stored in RDF stores can be retrieved by queries specified using the [http://www.w3.org/TR/sparql11-overview/ SPARQL]<ref name="W3C_SPARQL">W3C SPARQL Working Group. ''SPARQL 1.1 Overview - W3C Recommendation 21 March 2013''. Retrieved 16 December 2013, from http://www.w3.org/TR/sparql11-overview/<br/></ref> query language.
| |
| − |
| |
| − | Some recent evaluation reports and RDF store benchmarking studies <ref name="EUROPEANA_RDFSTOREREPORT">Bernhard Haslhofer, Elaheh Momeni, et al. (2011). ''Europeana RDF store report''.<br/></ref><ref name="BSBM_2011_02">Chris Bizer and Andreas Schultz (2011). ''BSBM V3 Results (February 2011)''. Retrieved 02 August 2013 from http://www4.wiwiss.fu-berlin.de/bizer/BerlinSPARQLBenchmark/results/V6/index.html.<br/></ref><ref name="BSBM_2009_03">Chris Bizer and Andreas Schultz (2009). ''Berlin SPARQL Benchmark Results.'' Retrieved 02 August 2013 from http://www4.wiwiss.fu-berlin.de/bizer/BerlinSPARQLBenchmark/results/index.html.<br/></ref> evaluated individual strengths and weaknesses of different RDF stores. Referring to these evaluation results, AnnoSys decided to use [http://jena.apache.org/documentation/tdb/ Apache Jena TDB]<ref name="APACHE_JENA_TDB">The Apache Software Foundation (2013). ''Apache Jena - TDB.'' Retrieved 03 August 2013, from http://jena.apache.org/documentation/tdb/.<br/></ref> for development and prototype implementations and [http://www.openlinksw.com/dataspace/doc/dav/wiki/Main/ Virtuoso Open-Source Edition]<ref name="VIRTUOSO">OpenLink Software. ''Virtuoso Open-Source Edition''. Retrieved 02 August 2013 from http://virtuoso.openlinksw.com/dataspace/doc/dav/wiki/Main/.<br/></ref> for productional use.
| |
| − |
| |
| − | ==== Original Record documents ====
| |
| − | Referring to the experience gained from the BioCASE annotation system <ref name="SYNTHESYS_Annotation">Anton Güntsch, Walter G. Berendsohn, Pepé Ciardelli, Andrea Hahn, Wolf-Henning Kusber & Jinling Li (2009): ''Adding content to content – a generic annotation system for biodiversity data''. Studi Trent. Sci. Nat. 84: 123-128.<br/></ref> its file system based, hierarchical storage architecture has proofed to be a suitable solution for efficiently storing and accessing XML based original record documents(e.g ABCD, [http://rs.tdwg.org/dwc/index.htm Darwin Core]<ref name="TDWG_DarwinCore">Wieczorek, John, Döring, Markus, De Giovanni, Renato, Robertson, Tim, Vieglais, Dave, ''Darwin Core'', http://rs.tdwg.org/dwc/index.htm (2009), accessed 05 Dec 2011<br/></ref>) in a biodiversity context. Following that experience, the current repository implementation stores original record documents on the server's file system in a configurable directory location.
| |
| − |
| |
| − | ==== Agent Profiles ====
| |
| − | The term ''agent profiles'' aggregates the following information concerning system agents (users):
| |
| − | * personal metadata
| |
| − | * authentication & authorisation data
| |
| − | * personal annotation repository
| |
| − | * preferences configuration
| |
| − |
| |
| − | While an agent's personal metadata comprises his real name, affiliation and email address only, authentication & authorisation data add login credentials (username, password), roles and a unique agent identifier to the profile. Please find any details about the information stored for registered agents within the security database in section [[#Security_2|Security]].
| |
| − |
| |
| − | Additionally, according to the best practices recommended by the [http://www.openannotation.org/spec/core/ W3C Open Annotation Data Model]<ref name="OpenAnnotation_DataModel">Sanderson, Robert; Ciccarese, Paolo; Van de Sompel, Herbert (2013). ''W3C Open Annotation Data Model - Community Draft, 08 February 2013'', http://www.openannotation.org/spec/core/, accessed 26 November 2013<br/></ref>, the personal metadata is also stored based on the [http://xmlns.com/foaf/spec/ FOAF vocabulary]<ref name="FOAF_Specification">Brickley, Dan; Miller, Libby (2010). ''FOAF Vocabulary Specification 0.98 - Namespace Document 9 August 2010 - Marco Polo Edition'', http://xmlns.com/foaf/spec/, accessed 26 November 2013<br/></ref> together with annotation data within AnnoSys' RDF store. For privacy reasons, agents' email addresses or other sensible information are not publicly accessible in the RDF store.
| |
| − |
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | |+ align="bottom"|''Agent metadata properties''
| |
| − | ! property
| |
| − | ! definition
| |
| − | |-
| |
| − | | rdf:type || agent type (foaf:Person, foaf:Organization or dcTypes:Software)
| |
| − | |-
| |
| − | | foaf:name || agent's name
| |
| − | |-
| |
| − | | foaf:member || optional list of members (for agent type foaf:Organization only)
| |
| − | |}
| |
| − |
| |
| − | AnnoSys maintains a personal annotation repository per registered agent within the system. These repositories keep track on any annotation data created and edited by authenticated agents and are neither publicly accessible nor by other system users. On publication, annotation data will be moved from the publishing agent's personal annotation repository to AnnoSys' publicly accessible RDF store. Annotations may also be manually removed by authenticated agents via the user interface.
| |
| − |
| |
| − | The preferences configuration may also be managed by authenticated agents via the user interface. It holds agent individual system configurations like e.g. a list of currently opened documents in the user interface for restoring at the next login.
| |
| − |
| |
| − | The security database is realised as [http://www.sqlite.org/ SQLite]<ref name="SQLite">Hipp, D. Richard. ''SQLite''. Retrieved 16 December 2013 from [http://www.sqlite.org/.<br/></ref> database. The personal annotation repositories are named according to the agent's resourceId in AnnoSys. The private annotation repositories are created as [http://jena.apache.org/documentation/tdb/ Apache Jena TDB]<ref name="APACHE_JENA_TDB"></ref> model in a directory location on the server including any personal agent profiles in subdirectories named according the agent's system resourceid.
| |
| − |
| |
| − | === User Interface ===
| |
| − | Providing and managing annotations may become a complex job either to annotators or data curators. For instance, annotators have to gather specimen data, analyse a potentially large number of data objects and annotate or comment specific data elements accurately. Again, data curators have to analyse these annotations, accept or reject them possibly along with individual comments and have to reintegrate them back into their data collections. Further on, any of these activities should be documented and communicated back to annotators and other subscribing members of the community.
| |
| − |
| |
| − | As the main focus of both annotators and curators should be on preparing accurate information, a suitable user interface should give advice and guide users through all these workflows. Furthermore, it should allow a clear presentation of information, adoption to individual user preferences and provide convenient guidance and support through the most common workflow activities. This requires modern web user interfaces providing functionality and look and feel of desktop applications. Fortunately, due to recent web toolkit developments based on the [http://www.adaptivepath.com/ideas/ajax-new-approach-web-applications Asynchronous JavaScript and XML (Ajax)]<ref name="AJAX">Garrett, J. J. (2005, 18 February 2005). "Ajax: A New Approach to Web Applications." from http://www.adaptivepath.com/ideas/ajax-new-approach-web-applications.<br/></ref> technology, desktop alike applications can be implemented for the web now as well.
| |
| − |
| |
| − | Here, AnnoSys decided to use Eclipse's Eclipse's [http://eclipse.org/rap/ Remote Application Platform (RAP)]<ref name="ECLIPSE_RAP">The Eclipse Foundation (2013). "Enabling modular business apps for desktop, browser and mobile." Retrieved 26 November, 2013, from http://eclipse.org/rap/.<br/></ref> for developing a desktop oriented web user interface. The main reason for that decision was that Eclipse RAP imposes only small requirements on client machine's capabilities and does not transmit potentially large documents over the network. Thus, any complex functionality is executed on the server.
| |
| − |
| |
| − | === Security ===
| |
| − | The security component provides the following functionalities:
| |
| − | * agent profile management
| |
| − | * secure authentication
| |
| − | * role based authorisation
| |
| − | Agent profile management combines the maintenance of the security database and personal profile stores for each registered agent ([[#Agent_Profiles|see Agent Profiles]]).
| |
| − |
| |
| − | Agent profile management also facilitates the agent registration process. The agent registration consists of filling in a form with the required information. After running the registration procedure successfully, agents can immediately login to the system and start editing and publishing annotations. Please find any details about the information to be entered in section [[#Secure_Authentication|Secure Authentication]].
| |
| − |
| |
| − | Agent authentication is secured by individual agent credentials to be entered in the login dialog. Moreover, any data transmissions initiated through network connections are secured by the [http://tools.ietf.org/html/rfc2818 Hypertext Transfer Protocol Secure (HTTPS)]<ref name="RFC_HTTPS">Rescorla, E. (2000). "HTTP Over TLS" Retrieved 13 December, 2013, from http://tools.ietf.org/html/rfc2818.<br/></ref>.
| |
| − |
| |
| − | Based on the implementation of role based authorisation, AnnoSys may restrict access to certain functionalities based on permissions. These permission may either be compiled in and assigned to agents through role definitions (e.g. curator for a given collection) or individually by system administrators on institutional request. Please find details in section [[#Role_Based_Authorisation_Management|Role Based Authorisation Management]].
| |
| − |
| |
| − | In AnnoSys, any security relevant implementations base on the [http://shiro.apache.org/ Apache Shiro]<ref name="APACHE_SHIRO">The Apache Software Foundation (2013). "Welcome to Apache Shiro." Retrieved 13 December, 2013, from http://shiro.apache.org/.<br/></ref> framework. The security database is held in a [http://www.sqlite.org/ SQLite]<ref name="SQLite"></ref> database.
| |
| − |
| |
| − | For security reasons and with respect to data privacy, the security database, personal profile stores and other system relevant configuration files are stored in a location on the server inaccessible for unauthorised AnnoSys agents or external services.
| |
| − |
| |
| − | === Message System ===
| |
| − | Via the message system, AnnoSys aims to inform registered agents and curators about annotation workflow status changes triggered by agent or system interactions.
| |
| − | Therefore, the message system forwards notifications related to annotation workflow activities initiated by agents, curators or the system itself.
| |
| − | Notifications are dispatched via system internal message queues and are individually manageable by registered agents via the user interface.
| |
| − | Additionally, notifications are also send to agents by email.
| |
| − |
| |
| − | In particular, the following kinds of annotation publishings cause the message system to trigger notifications regarding annotation workflow status changes:
| |
| − | * original record annotations published by annotators
| |
| − | * curator decisions reported by the AnnoSys curator interface
| |
| − | * version updates of collection records, either detected on repository import processing or reported by curators (not implemented yet)
| |
| − |
| |
| − | On occasion of any annotation workflow status change described above, the message system issues notifications according to the following topics agents may subscribe to:
| |
| − | * subsequent publication of annotations relating to records previously annotated by the given agent (automatically)
| |
| − | * publication of annotations relating to records an agent actively subscribed to
| |
| − | * publication of annotations relating to a group of records which meet specific criteria an agent previously defined
| |
| − |
| |
| − | Furthermore, the message system automatically issues notifications to curators on occasion of any annotation published and related to those records within collections a curator has registered for.
| |
| − |
| |
| − | Summarising the set of notifications specified above, AnnoSys may issue the following kinds of messages:
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | ! message type
| |
| − | ! definition
| |
| − | |-
| |
| − | | ANNOTATION_PUBLISHED || annotation issued by an annotator
| |
| − | |-
| |
| − | | ANNOTATION_CURATED || annotation curated by a collection manager
| |
| − | |}
| |
| − | (Currently the messages aren't distinguished by type. Although messages might have different content depending on the notification event.)
| |
| − |
| |
| − | Technically, the message system builds up on the [http://www.oracle.com/technetwork/java/jms-136181.html Java Message Service (JMS)]<ref name="ORACLE_JMS">Oracle. "Java Message Service (JMS)." Retrieved 16 December, 2013, from http://www.oracle.com/technetwork/java/jms-136181.html.<br/></ref> standard developed by the Java Community Process and defined within specification JSR 914<ref name="ORACLE_JSR914">Rich Burridge Mark Hapner, Rahul Sharma, Joseph Fialli, Kate Stout (2002) Java Message Service.<br/></ref>. Therefore, the JMS provider [http://activemq.apache.org/ Apache ActiveMQ]<ref name="APACHE_ACTIVEMQ">Apache Software Foundation (2011). "ActiveMQ." Retrieved 16 December 2013, from http://activemq.apache.org/.<br/></ref> is used in tandem with [http://camel.apache.org/ Apache Camel]<ref name="APACHE_CAMEL">Claus Ibsen and Jonathan Anstey (2010). "Camel in Action", Manning.<br/></ref> to realise internal and external message transports.
| |
| − |
| |
| − | Please find further technical details in section [[#Message_System_2 | MessageSystem]].
| |
| − |
| |
| − | === Services ===
| |
| − | The service component enables external services to access public data from the AnnoSys repository. Therefore, AnnoSys provides the following services and interfaces:
| |
| − | * RESTful web services
| |
| − | * Linked Open Data
| |
| − | * SPARQL Endpoint
| |
| − |
| |
| − | Primarily, the RESTful web service interface is intended for collaborating data portals to display information about annotations or original record documents stored in the AnnoSys repository in general, or with regard to a specific record based on its tripleId. Thus, beside lists all annotations or records available in the repository, external services may also request a list of available annotations relating to a specific record based on its tripleId. These lists contain stable URIs referring to the related annotation or record stored in the repository.
| |
| − |
| |
| − | Any of these stable URIs are resolvable, such as either the denoted annotation can be downloaded as RDF/XML document, or the original record as XML document from the AnnoSys repository. That way, the AnnoSys repository and any services are completely following the recommendations of the Linked Open Data paradigm.
| |
| − |
| |
| − | Finally, external services may run self-defined SPARQL queries on the AnnoSys annotation repository via the [https://annosys.bgbm.fu-berlin.de/AnnoSys/sparql AnnoSys SPARQL endpoint]<ref name="W3C_SPARQL"></ref>. Any non-anonymous resource in the repository's RDF store is also based on stable URI and thus, follows the Linked Open Data paradigm. RESTful and Linked Open Data services are implemented using the [https://jax-rs-spec.java.net/ Java API for RESTful Services (JAX-RS)]<ref name="ORACLE_JAX-RS">Pericas-Geertsen, Santiago; Potociar, Marek (2013). "AX-RS: Java™ API for RESTful Web Services - Version 2.0 Final Release May 22, 2013", Oracle Corporation. Retrieved 16 December 2013, from http://download.oracle.com/otn-pub/jcp/jaxrs-2_0-fr-eval-spec/jsr339-jaxrs-2.0-final-spec.pdf.<br/></ref>
| |
| − |
| |
| − |
| |
| − | == Annotation Context Model ==
| |
| − | AnnoSys' annotation context modelling approach founds on the presumption that annotations will be related to any kind of metadata related to physical specimens uniquely identifiable by [http://wiki.tdwg.org/GUID Globally Unique Identifiers (GUIDs)]<ref name="TDWG_GUIDs">TDWG, ''Welcome to the Globally Unique Identifiers (GUID) Wiki'', http://wiki.tdwg.org/GUID (2009), accessed 22 Oct 2012<br/></ref><ref name="TDWG_GUID_AS">Richards, Kevin; ''TDWG GUID Applicability Statement'', 09 September 2009, http://www.tdwg.org/standards/150/download/, accessed 19 December 2011<br/></ref>). Beyond that, the accessibility of those record data in an XML document based standard like [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD]<ref name="TDWG_ABCD">Holetschek, Jörg, ''ABCD - Access to Biological Collection Data'', http://wiki.tdwg.org/twiki/bin/view/ABCD/ (02 March 2010), accessed 05 Dec 2011<br/></ref> is assumed. In the biodiversity domain, there are several use cases like e.g. the annotation of georeferences which require to simultaneously address multiple record data elements (e.g. longitude, latitude) in a single annotation for providing useful information. That is, the annotation context model combines general meta information determining e.g. the annotated record or the annotator's name with an aggregated list of data element selectors. With each of these selectors, an expectation towards the curator of the collection the record relates will be expressed. The expectation may either state to update, add or remove the selected data element within the record. Furthermore, the annotator may propose new or corrected values to the selected data elements and/or may make natural language comments. Based on these information, the curator may decide to either update a collection's database or not.
| |
| − |
| |
| − | Therefore, in AnnoSys the annotation context will be defined by
| |
| − | * A UUID for the specimen's metadata data object (original record data)
| |
| − | * The specimen metadata object
| |
| − | * A set of element selectors within the specimen metadata object affected by the annotation
| |
| − |
| |
| − | === Annotation Context Selection ===
| |
| − | Using AnnoSys, annotators may identify several data elements within a record to be worth annotating. While AnnoSys is designed to support XML record documents, a mechanism to select these data elements has to be developed and implemented. During the evalution phase, it turned out that using XML diff representations or inserting annotated values and/or natural language comments as XML comments into XML record documents results in either cryptic result representations, low performance or conceptual difficulties. Therefore, AnnoSys developed the idea of realising some kind of "recorder" functionality to capture those XML data elements selected by annotators.
| |
| − |
| |
| − | For that, [http://www.w3.org/TR/xpath20/ XPath]<ref name="W3C_XPath">Berglund, Anders, Boag, Scott, et al., ''XML Path Language (XPath) 2.0 (Second Edition) - W3C Recommendation 14 December 2010 (Link errors corrected 3 January 2011)'', http://www.w3.org/TR/xpath20/ (14 December 2010), accessed 05 Dec 2011<br/></ref> expressions provide suitable means to unambiguously identify either single or sets of data elements within XML documents of any record format. In particular, XPath based element selectors can be used to uniquely identify (sets of) data elements like
| |
| − | * "all elements named "xxx" located below the element "yyy""
| |
| − | * "all elements named "xxx" with a value "zzz""
| |
| − |
| |
| − | == Annotation Data Model ==
| |
| − | The data model outlined within the next sections is centered on the [[#Annotation Context Model|Annotation Context Model]] developed earlier in this document. So, the annotation data model bases in two interrelated parts:
| |
| − | * Annotation Metadata Specification
| |
| − | * Annotated Elements Specification
| |
| − |
| |
| − | While the metadata specification provides general meta information (e.g. determining the annotated record or annotator's name), the "recorder" functionality is realised through a list of data elements capturing those data elements selected for annotation by the annotator. These "annotated elements" are "recorded" according to the XPath selector method outlined in section [[#Annotation Context Selection|Annotation Context Selection]]. The following sections will provide more detailed information on both parts.
| |
| − |
| |
| − | [[Image:Annotation_Data_Model.png|frame|none|''Annotation Data Model'']]
| |
| − |
| |
| − | Built up on these base concepts, enhanced concepts have been added in order to permit curators to communicate annotations about the curational processing of annotations. Also, a concept for mass (or multi) annotations has been developed in order to link together identical annotations addressing identical errors in a (large) number of distinct record documents. The latter concept was also introduced for curation annotations. Thus, the annotation data model reflects the following extended concepts as well:
| |
| − | * Curation Annotation Specification
| |
| − | * Curated Elements Specification
| |
| − | * Mass (or Multi) Annotation Specification
| |
| − | * Mass (or Multi) Curation Annotation Specification
| |
| − |
| |
| − | === Annotation Metadata Specification ===
| |
| − | The annotation metadata provides information regarding the following general aspects
| |
| − | * annotation creation
| |
| − | * annotated record
| |
| − | * annotating agent
| |
| − |
| |
| − | Valid annotations must include any data described within the following sections for each aspect separately.
| |
| − |
| |
| − | ==== Annotation creation ====
| |
| − | The ''annotation creation'' entails the generation of following data elements:
| |
| − | ;Motivation
| |
| − | : Usually, annotations will be instantiated for well determined reasons. Within [http://wiki.tdwg.org/twiki/bin/view/AnnotationsIG/DataExtensionsToAO extensions]<ref name="TDWGAnnotationsIG_AODExtensions">Morris, Paul J., ''Proposed AOD Extensions to AO'', http://wiki.tdwg.org/twiki/bin/view/AnnotationsIG/DataExtensionsToAO (06 July 2011), accessed 05 Dec 2011<br/></ref> proposed by the [http://wiki.tdwg.org/AnnotationsIG/ TDWG Annotations Interest Group]<ref name="TDWGAnnotationsIG">Morris, Paul J., ''TDWG Wiki AnnotationsIG'', http://wiki.tdwg.org/AnnotationsIG (2011), accessed 05 Dec 2011<br/></ref> the term ''motivation'' was introduced to express the intension for which an annotator has made the annotation. Within this document, we will use it synonymously with the term ''annotation type'' describing a precompiled set of data element selectors used in typical, domain specific annotation use cases. Currently, AnnoSys supports the following motivations (annotation types):
| |
| − | : * Determination
| |
| − | : * Duplicate Locality
| |
| − | : * Gathering
| |
| − | : * Nomenclatural type
| |
| − | : * Other
| |
| − | : * Sequence
| |
| − | : * Record basis
| |
| − | : * Scientific name
| |
| − | : * Unit Mark
| |
| − |
| |
| − | ;Datetime (of the creation)
| |
| − | : The creation's datetime describes the point in time the annotation was published by the system. This time is usually different to the time, the annotation was created within the system for user processing. The time's granularity is given in milliseconds.
| |
| − |
| |
| − | ;AnnoSysID (of the annotation)
| |
| − | :The AnnoSysID of the annotation shall uniquely identify any annotation created. In accordance to the [[#AnnoSysID.27s_and_Globally_Unique_Identifiers_.28GUIDs.29|AnnoSysID's and Globally Unique Identifiers (GUIDs)]], the AnnoSysID is constructed based on the following components:
| |
| − | :;institutionID
| |
| − | :: Is currently filled with the institutionId of the organisation running the AnnoSys instance creating the annotation(e.g. "BGBM").
| |
| − | :;collectionID
| |
| − | :: Is currently filled with the name of the annotation repository (e.g. "AnnoSys").
| |
| − | :;unitID
| |
| − | :: In order to produce unique unitIDs, this field is currently filled with the time in milliseconds since 01/01/1970 when the annotation was first instantiated by the AnnoSys system.
| |
| − | :Since, annotations are not intended to be modified after publication and [http://www.openannotation.org/spec/core/20130208/index.html W3C Open Annotation Data Model (OA)] actually is the only standard supported for annotation exchange, the fields '''version''' and '''format''' are currently unneeded.
| |
| − |
| |
| − | ==== Annotated record ====
| |
| − | The term ''annotated record'' compiles the following information with regard to the XML record document representation and the relating annotated specimen unit:
| |
| − | ;record GUID
| |
| − | :The record GUID identifies the physical specimen unit to which the annotated XML record document relies on and is expected to be represented as tripleId.
| |
| − | ;record document format
| |
| − | :The record document format describes the standard format of the annotated XML record document. This is expected to be specified by the namespace URI of the relating version of the XML standard format (e.g. ABCD v2.06: http://www.tdwg.org/schemas/abcd/2.06).
| |
| − | ;record document version
| |
| − | :The revision information reflects any kind of version information regarding the annotated record document. As, we can not expect any revision information from the XML record document, the time in milliseconds since 01/01/1970 when downloading the document first into the AnnoSys repository will be used.
| |
| − |
| |
| − | ==== Annotating agent ====
| |
| − | An ''annotating agent'' is either a person or a machine conducting the annotation. Conforming to the common practice considering physical specimen objects in botanical museums, only a minimum set of data is captured:
| |
| − | ;name
| |
| − | :The name field includes first name(s) and last name(s) of the annotating person, or the name and version of the software or service used to create the annotation.
| |
| − | ;institution
| |
| − | :The institution denotes the organisation the annotating agent belongs to. If the institution field is empty, the authorisation component will consider the agent as member of the "private taxonomist" group.
| |
| − | ;email
| |
| − | :The email address the annotating person, or the email address of the annotating machine's administrator. For privacy reasons, this information is not subjected to be made public.
| |
| − |
| |
| − | === Annotated Elements Specification ===
| |
| − | According to the [[#Annotation Context Model|Annotation Context Model]] described in the previous chapter, the ''annotated elements'' represent a list of element selectors each linked with the following information in order to annotate the selected data element in the XML record document:
| |
| − | ;element selector
| |
| − | :is realised according to section [[#Annotation_Context_Selection|element selectors]]. Regarding the interpretation of selectors, the following special cases apply:
| |
| − | :# A selector pointing at the XML document's root element ("/") is interpreted as to address the entire data record. In particular, this means is used to express general comments about the referenced data record.
| |
| − | :# A selector pointing at a data element, for which the relating XML Schema does not allow for values to be entered, does not allow for entering annotated values as well.
| |
| − |
| |
| − | ;annotated value (optional)
| |
| − | :enables annotators to propose a new value for the selected data element. The proposed value must correspond to the data type specified in the document's relating XML Schema.
| |
| − | ;expectation
| |
| − | :expresses the expected corrective to be taken by the curator with regard to the annotated data record in the collection database. Within AnnoSys, the following expectations may be expressed:
| |
| − | :;update
| |
| − | ::the value of the selected data element should be updated by the annotated value in the annotated data record.
| |
| − | :;remove
| |
| − | ::the selected data element should be removed from the annotated data record
| |
| − | :;add
| |
| − | ::a new data element according to the element selector should be added to the annotated data record including the given annotated value and/or comment.
| |
| − | ;comment (optional)
| |
| − | :permits annotators to annotate or to make natural language comments for the selected data element. Comments are always expected to be a text string.
| |
| − |
| |
| − | While both, ''annotated value'' and ''comment'' are optional, one of both must be present in order to provide valuable information. That is, annotation elements neither including annotated value nor comment are considered as to be invalid.
| |
| − |
| |
| − | = Repository =
| |
| − | == Records ==
| |
| − | Referring to the experience gained from the BioCASE annotation system <ref name="SYNTHESYS_Annotation">Anton Güntsch, Walter G. Berendsohn, Pepé Ciardelli, Andrea Hahn, Wolf-Henning Kusber & Jinling Li (2009): ''Adding content to content – a generic annotation system for biodiversity data''. Studi Trent. Sci. Nat. 84: 123-128.<br/></ref> its file system based, hierarchical storage architecture has proofed to be a suitable solution for efficiently storing and accessing XML based original record documents(e.g [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD]<ref name="TDWG_ABCD"/>, Darwin Core) in a biodiversity context. Following that experience, the current repository implementation stores original record documents on the server's file system in a configurable directory location. Using ABCD terms, the following file path creation scheme is used.
| |
| − | * '''$RECORD_BASE_DIR/SourceInstitutionID/SourceID/format/UnitID.revision.xml'''
| |
| − |
| |
| − | Thereby, the tripleID (''SourceInstitutionID'', ''SourceID'' and ''UnitID'', [[#Globally_Unique_Identifiers_.28GUIDs.29_in_AnnoSys|see GUIDs in AnnoSys]]) will be extracted from the individual original record document depending on its data standard(e.g ABCD, Darwin Core). The ''format'' part within the file path creation scheme will be determined by a system-wide, predefined mapping scheme assigning an XML namespace prefix to the XML namespace URI for any data standard supported by the system. Finally, the ''revision'' part within the file name describes the datetime an original record document was first stored within the repository. According to the respective data elements defined within the [#Data Model|Data Model], the value of ''revision'' is specified as the time in milliseconds since 01/01/1970.
| |
| − |
| |
| − | Whenever required for some substantial reasons(e.g. query performance), later revisions of AnnoSys may optionally store original record documents in a dedicated XML database or may introduce search engines like [http://lucene.apache.org/solr/ Apache Solr]<ref name="Apache_Solr"> Apache Software Foundation (2012). ''Apache Solr''. Retrieved 26 November 2013 from http://lucene.apache.org/solr/.<br/></ref> for optimising e.g. query performance.
| |
| − |
| |
| − | == Annotations ==
| |
| − | The storing of annotations in AnnoSys is twofold. First, each user has a personal user profile, which also includes a manageable repository holding any unpublished annotations of the given user. Second, there is a public repository, where annotations were moved to whenever a users initiates to publish an annotation.
| |
| − |
| |
| − | Thereby, the user profile repositories are realised using [http://jena.apache.org/documentation/tdb/ Apache Jena TDB]<ref name="APACHE_JENA_TDB"></ref> based triple stores. Whereas, the public annotation repository uses an [http://www.openlinksw.com/dataspace/doc/dav/wiki/Main/ Virtuoso Open-Source Edition]<ref name="VIRTUOSO"></ref> triple store. Nevertheless, both triple stores are implemented in AnnoSys using the [http://jena.apache.org/ Apache Jena]<ref name="APACHE_JENA">The Apache Software Foundation (2014). ''Apache Jena - A free and open source Java framework for building Semantic Web and Linked Data applications.'' Retrieved 27 January 2014, from http://jena.apache.org/.<br/></ref> Software APIs.
| |
| − |
| |
| − | In both kinds of triple stores, annotations are stored according to the [http://www.openannotation.org/spec/core/ W3C Open Annotation Data Model]<ref name="OpenAnnotation_DataModel"></ref> driven by the activities of the [http://www.w3.org/community/openannotation/ W3C Open Annotation Community Group]<ref name="W3COpenAnnotationCommunityGroup">W3C, ''W3C Community and Business Groups - Open Annotation Community Group'', http://www.w3.org/community/openannotation/ (2012), accessed 25 Oct 2012<br/></ref>. Due to some constraints in the current release of the [http://www.openannotation.org/spec/core/ W3C Open Annotation Data Model], the current implementation of the [[#Annotation_Data_Model|Annotation Data Model]] specified for AnnoSys with the means of the [http://www.openannotation.org/spec/core/ W3C Open Annotation Data Model] results from thorough discussions with the [http://www.w3.org/community/openannotation/ W3C Open Annotation Community Group]. Therefore, the following sections details the integration of AnnoSys' [[#Annotation_Data_Model|Annotation Data Model]] with the [http://www.openannotation.org/spec/core/ W3C Open Annotation Data Model].
| |
| − |
| |
| − | === W3C Open Annotation implementation of the AnnoSys [[#Annotation_Data_Model|Annotation Data Model]] ===
| |
| − |
| |
| − | Principally, there are two means to implement complex data models with W3C Open Annotation. First, just the basic OA features are used to identify a target (in this case a versioned record document) and to realise annotations by formalising an own ontology to describe the annotations within the body. Second, trying to make use of all W3C OA features in order to express annotations with the means of W3C OA completely. Within AnnoSys, we decided to use the second alternative in order to provide a solution as close as possible to the current standard, and thus to be interpretable in non-biodiversity domains as well.
| |
| − |
| |
| − | Therefore, the W3C Open Annotation implementation of the AnnoSys Annotation Data Model introduces new motivations reflecting the annotation types specified in the [[#Annotation_Data_Model|Annotation Data Model]]. Also, it uses multiple targets and bodies to implement the annotated elements also specified in the [[#Annotation_Data_Model|Annotation Data Model]]. Finally, the oa:hasScope property relation is used to realise a weak, but adequate linking between body and target of an annotation element. Within the next paragraphs provenance, target and body parts of the AnnoSys implementation will be elucidated in more detail.
| |
| − |
| |
| − | [[Image:OpenAnnotationDataModel.png|frame|none|''W3C Open Annotation implementation of the AnnoSys [[#Annotation_Data_Model|Annotation Data Model]]'']]
| |
| − |
| |
| − | The oa:motivatedBy properties of the provenance part of the AnnoSys implementation extends the predefined class oa:editing to provide classes for the implementation of the AnnoSys motivation use cases (annotation types). As the basic expectation of annotators towards an collection curator is to edit or update the collection database based on the published annotation. So, the following classes have been derived from ''oa:editing'' to reflect the defined annotation type:
| |
| − | * annosys:Determination
| |
| − | * annosys:DuplicateLocality
| |
| − | * annosys:Gathering
| |
| − | * annosys:NomenclaturalType
| |
| − | * annosys:Other
| |
| − | * annosys:Sequence
| |
| − | * annosys:RecordBasis
| |
| − | * annosys:ScientificName
| |
| − | * annosys:UnitMark
| |
| − |
| |
| − | The remaining properties are straight forward uses of the W3C OA Specification providing the following information:
| |
| − | ;annotated by
| |
| − | :the annotating agent, which is usually a foaf:Person, but may also be represented as prov:Software agent if (mass) annotations were created by a corresponding service.
| |
| − | ;annotated at
| |
| − | :datetime, the annotation was published.
| |
| − | ;serialised by
| |
| − | :the software agent, which has created the annotation in favour of the annotator(e.g. AnnoSys system).
| |
| − | ;serialised at
| |
| − | :datetime, the annotation was first created within the system before it has been published by the annotator.
| |
| − |
| |
| − | The annotated elements of an annotation are realised as tuples of target and body each. Due to the open world assumption defined wihtin the W3C OA Specification, any target and any body may be reused by any other annotation and thus, the statement expressed by these resources must always be true. Therefore, body and target of an annotated element can not be "hardlinked", because this would contradict to the open world assumption. Here, the oa:hasScope property comes in place, which provides a kind of weak linking and could be interpreted in the sense of:
| |
| − | The target this body is scoped to was examined by the annotator when the annotation(body) was created. In fact, even though the relationship is not hardlinked, it expresses exactly what we require to model the annotated element. The body tracks the expectation, annotated value and the comment created by an annotator when examining a selected data element within a given record identified within the target.
| |
| − |
| |
| − | A specific target part of an annotated element is identified through a oa:hasSource, oa:hasState and a oa:hasSelector property, which will be described within the next paragaphs.
| |
| − |
| |
| − | ;<nowiki>oa:hasSource</nowiki>
| |
| − | :a target's source represents the tripleId of the physical specimen object in a museum(e.g. BGBM:Herbar:0001) which is somehow represented as a dataset.
| |
| − | ;<nowiki>oa:hasState</nowiki>
| |
| − | :the state of the dataset represents the state of record document related to the target source as presented to the annotator at annotation time.
| |
| − | :;<nowiki>oa:cachedSource</nowiki>
| |
| − | ::the cached source represents the record XML document within the AnnoSys repository as it was downloaded from a record data provider. The cached source is stored as stable http-URI, which can be used to retrieve the given document from the AnnoSys repository via the AnnoSys Linked Data services.
| |
| − | :;<nowiki>oa:when</nowiki>
| |
| − | ::as we selected oa:TimeState class, when describes the datetime, when the record document referred to by the cached source property was retrieved and stored within the AnnoSys repository.
| |
| − | ;<nowiki>oa:hasSelector</nowiki>
| |
| − | :<nowiki>oa:FragmentSelector</nowiki> is used here as class type to describe the AnnoSys element selector. In particular, fragment selectors support the XPointer specification, which permits to adequately state namespaces and [http://www.w3.org/TR/xpath20/ XPath]<ref name="W3C_XPath"></ref> selectors to identify the elements in the XML record document specified within the hasCachedSource property.
| |
| − | :;<nowiki>dcterms:conformsTo</nowiki>
| |
| − | ::namespaceURI of the XPointer specification
| |
| − | :;<nowiki>rdf:value</nowiki>
| |
| − | ::XPointer expression selecting an annotated element within the XML record document denoted in the hasCachedSource property
| |
| − |
| |
| − | A specific body part of an annotated element is represented by its scope(annotated target) and a body holding the values of an annotated element
| |
| − | ;<nowiki>oa:hasScope</nowiki>
| |
| − | :refers to the specific target resource this specific body resource relates to
| |
| − | ;<nowiki>oa:hasSource</nowiki>
| |
| − | :refers to the body resource holding the values of the annotated element
| |
| − | :;<nowiki>rdf:type</nowiki>
| |
| − | ::a class introduced by AnnoSys describing the expectation of the annotator towards the curator of the collection database. The following clases are currently supported:
| |
| − | ::*annosys:Update
| |
| − | ::*annosys:Remove
| |
| − | ::*annosys:Add
| |
| − | :;<nowiki>dcterms:description</nowiki>
| |
| − | ::the natural language comment of the annotator with regard to the selected annotated element.
| |
| − | :;<nowiki>rdf:value</nowiki>
| |
| − | ::the annotated value proposed by the annotator with regard to the selected annotated element.
| |
| − |
| |
| − | In comformance to the W3C Open Annotation specification, a oa:Composite element is used to group specific target or body resources, if multiple specific targets and bodies have been used to model multiple annotated elements. If only a single annotated element had been modeled, oa:hasTarget or oa:hasBody would refer to a specific target or body element respectively.
| |
| − |
| |
| − | = User Interface =
| |
| − | This section will neither focus on operating the user interface nor its elements. Please refer to the current [https://annosys.bgbm.fu-berlin.de/sites/default/files/Users%20Instructions.pdf user instructions] document for any details.
| |
| − |
| |
| − | Within this section, the configuration of ''annotation types'', their relating data templates in terms of ''annotation use case specifications'' and the concomitant definition of record document format namespaces and element selectors as well as the current implementation details of specification based user interface support will be documented.
| |
| − |
| |
| − | Any user interface related configuration files are properties based. They will locate in the subdirectory ''config'' of the system's configuration home directory (henceforth referred to as '''${AnnoSys.home.dir}''').
| |
| − |
| |
| − | All of these properties files will be evaluated on system startup only! That is, any changes will require a system restart in order to be considered.
| |
| − |
| |
| − | == Annotation types ==
| |
| − | The configuration of annotation types takes place within the following property files:
| |
| − | * namespace.properties
| |
| − | * selector.properties
| |
| − | * annotation.properties
| |
| − |
| |
| − | The ''namespace.properties'' file is used to map namespace prefixes to their relating namespace URIs. Beyond that, it specifies which XML document formats in terms of namespace URIs are supported by the AnnoSys software. The file ''selector.properties'' defines reusable constants for XML element selectors based on the [http://www.w3.org/TR/xptr-framework/ XPointer Framework]<ref name="XPOINTER">Grosso, Paul; Maler, Eve; Marsh, Jonathan; Walsh, Norman."XPointer Framework - W3C Recommendation 25 March 2003". Retrieved 23 May, 2014, from http://www.w3.org/TR/xptr-framework/.<br/></ref>. Within the ''annotation.properties'', element selectors defined above are finally organised to compose annotation types and to define user input value restrictions.
| |
| − |
| |
| − | ;Note
| |
| − | :Placeholders may be used (and are highly recommended to enhance readability) in any ''.properties'' files to reference and being evaluated within expressions defined for any other property name in any of the AnnoSys properties configuration files. Referenced placeholders simply substitute the evaluated value defined by the referenced property. Placeholders may be stated like '''${property name}''' in any expression.
| |
| − |
| |
| − | === Namespace Support ===
| |
| − | Within the file ''namespace.properties'' any namespace supported ("known") by the AnnoSys system have to be configured. In particular, for any supported namespace a unique system-wide namespace prefix and the relating namespace URI have to be specified. Optionally, a (machine readable) namespace specification document may be given. Based on the specification document, AnnoSys' user interface analyses the data standard provided therein in order to facilitate automatic user supporting functionalities like
| |
| − | * input validation
| |
| − | * input restriction by drop-down selections
| |
| − | * provision of XML element specific documentation
| |
| − | * ...
| |
| − |
| |
| − | The architecture of AnnoSys' namespace support is designed to be generic in terms of data formats and data standards. Nevertheless, currently only XML data and [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD]<ref name="TDWG_ABCD"/> standard are implemented.
| |
| − |
| |
| − | ==== Namespace URI Mappings ====
| |
| − | In order to be correctly interpreted by the AnnoSys software, namespace URI mappings must be defined according to the following schema:
| |
| − |
| |
| − | '''NamespaceURI.<namespace prefix> = expression(namespaceURI)'''
| |
| − | ;NamespaceURI
| |
| − | :Prefix required to retrieve Namespace URI mapping definitions within an arbitrary list of properties by the system.
| |
| − | ;namespace prefix
| |
| − | :The namespace prefix to be assigned with the namespace URI expression.
| |
| − |
| |
| − | Example
| |
| − | NamespaceURI.abcd2.06 = http://www.tdwg.org/schemas/abcd/2.06
| |
| − |
| |
| − | Maps the namespace prefix ''abcd2.06'' to the namespace URI ''http://www.tdwg.org/schemas/abcd/2.06''.
| |
| − |
| |
| − | ==== Namespace configuration ====
| |
| − | Any namespace to be supported or "known" by the AnnoSys software must be expressed in a property according to the specification described in this section. Mainly, a namespace configuration consists of the following information
| |
| − | * Namespace prefix mapping of the data standard specification
| |
| − | * Link(s) to (machine readable) specification document(s)
| |
| − |
| |
| − | Even though the configuration design is generic in terms of supporting undetermined specification types, currently only [http://www.w3.org/TR/xmlschema-0/ XML-Schema]<ref name="XMLSchema">Fallside, David C.; Walmsley, Prescilla."XML Schema Part 0: Primer Second Edition - W3C Recommendation 28 October 2004". Retrieved 28 May, 2014, from http://www.w3.org/TR/xmlschema-0/.<br/></ref> based specification document support is implemented by AnnoSys.
| |
| − |
| |
| − | Within the subsequent description, namespace configurations are identified by namespace prefixes and bound to a list of parameter expressions determining the relating namespace URI, and specification document.
| |
| − |
| |
| − | '''Namespace.<namespace prefix> = expression-list(namespaceURI,specification type, local specification file path, specificationURI, default)'''
| |
| − | ;Namespace
| |
| − | :Prefix required to retrieve Namespace URI mapping definitions within an arbitrary list of properties by the system.
| |
| − | ;namespace prefix
| |
| − | :The namespace prefix assigned with the namespace configuration.
| |
| − | ;namespaceURI (required)
| |
| − | :Prefix required to retrieve Namespace URI mapping definitions within an arbitrary list of properties by the system.
| |
| − | ;specification type (optional)
| |
| − | :Currently, only type ''xsd'' (XML-Schema) specification support is implemented.
| |
| − | ;local specification file path (optional)
| |
| − | :Path to the namespace relating specification in the local file system.
| |
| − | ;specificationURI (optional)
| |
| − | :URI of the namespace relating specification. If the local specification is neither configured nor accessible, AnnoSys attempts to resolve the specification document from the given URI.
| |
| − | ;default (required)
| |
| − | :Indicates, if the software assigns this namespace configuration per default to the given namespace URI. Possible values are ''true'' or ''false'', where ''true'' must be assigned only once to the given namespace URI.
| |
| − |
| |
| − | Example:
| |
| − | Namespace.abcd2.06 = ${NamespaceURI.abcd2.06}, xsd, ${AnnoSys.home.dir}/schema/abcd/2.06/ABCD_2.06.xsd, http://rs.tdwg.org/abcd/2.06/ABCD_2.06.xsd, false
| |
| − | Namespace.abcd2.06a = ${NamespaceURI.abcd2.06}, xsd, ${AnnoSys.home.dir}/schema/abcd/2.06/a/ABCD_2.06a.xsd, http://rs.tdwg.org/abcd/2.06/a/ABCD_2.06a.xsd, false
| |
| − | Namespace.abcd2.06b = ${NamespaceURI.abcd2.06}, xsd, ${AnnoSys.home.dir}/schema/abcd/2.06/b/ABCD_2.06b.xsd, http://rs.tdwg.org/abcd/2.06/b/ABCD_2.06b.xsd, true
| |
| − | Namespace.biocase = ${NamespaceURI.biocase}, , , , true
| |
| − |
| |
| − | The first three lines configure the namespace support for different versions of [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD]<ref name="TDWG_ABCD"/> documents. As any of these versions is defined based on the same namespace URI, the most recent version is configured to be used by default.
| |
| − |
| |
| − | The last line configures the namespace support for the BioCASE protocol. Thereby, no XML-Schema specification is provided, as it is not subjected to annotation.
| |
| − |
| |
| − | === Definition of element selectors ===
| |
| − | Element selectors are used within the AnnoSys software to reduce the complexity of selector usage through assignment of a system-internal unique name. As element selectors are represented by property names, the placeholder concept enables system-wide reusing of named element selectors.
| |
| − |
| |
| − | In order to be correctly interpreted by the AnnoSys software, any selector constant must be defined according to the following schema:
| |
| − |
| |
| − | '''ElementSelector.<selector type>.<selector name>.<namespace prefix> = expression(XPointer)'''
| |
| − | ;ElementSelector
| |
| − | :This is a prefix required to retrieve ElementSelector definitions within an arbitrary list of properties by the system.
| |
| − | ;selector type
| |
| − | :The selector type for marking selector expressions to be retrieved by the AnnoSys system must be '''xpointer'''.
| |
| − | :Any other types may be used and will not be evaluated by the software. In particular, we use '''xpointerconst''' to define intermediary place holder expressions, which are substituted in the finally defined selector expression.
| |
| − | ;selector name
| |
| − | :Defines the selector's name, which is used by the AnnoSys system to identify a given selector expression.
| |
| − | ;namespace prefix
| |
| − | :Defines the XML document's namespace prefix to which the selector expression applies. That way, the same ''selector name'' may be defined with regard to several document standards. Currently, AnnoSys supports [http://wiki.tdwg.org/twiki/bin/view/ABCD/ ABCD 2.06b]<ref name="TDWG_ABCD"/> documents only.
| |
| − | ;expression
| |
| − | :Here, a valid expression according to the XPointer Framework is expected by the evaluating software.
| |
| − |
| |
| − | Example:
| |
| − | NamespaceURI.abcd2.06b = http://www.tdwg.org/schemas/abcd/2.06
| |
| − | ElementSelector.xpointer.xmlns.abcd2.06b = xmlns(abcd2.06b=${NamespaceURI.abcd2.06b})
| |
| − | ElementSelector.xpointerconst.DataSets.abcd2.06b = ${ElementSelector.xpointer.xmlns.abcd2.06b}xpointer(/abcd2.06b:DataSets
| |
| − | ElementSelector.xpointerconst.DataSet.abcd2.06b = ${ElementSelector.xpointerconst.DataSets.abcd2.06b}/abcd2.06b:DataSet
| |
| − | ElementSelector.xpointerconst.Unit.abcd2.06b = ${ElementSelector.xpointerconst.DataSet.abcd2.06b}/abcd2.06b:Units/abcd2.06b:Unit[1]
| |
| − | ElementSelector.xpointer.UnitID.abcd2.06b = ${ElementSelector.xpointerconst.Unit.abcd2.06b}/abcd2.06b:UnitID)
| |
| − |
| |
| − | The selector expression evaluated for property ''ElementSelector.xpointer.UnitID.abcd2.06b'' is:
| |
| − | xmlns(abcd2.06b=http://www.tdwg.org/schemas/abcd/2.06)xpointer(/abcd2.06b:DataSets/abcd2.06b:DataSet/abcd2.06b:Units/abcd2.06b:Unit[1]/abcd2.06b:UnitID)
| |
| − |
| |
| − | The element selector named ''UnitID'' of type ''xpointer'' will evaluate the first occurence of a unit id element within a given ABCD document of namespace ''http://www.tdwg.org/schemas/abcd/2.06''.
| |
| − |
| |
| − |
| |
| − | === Definition of Annotation Types ===
| |
| − | Annotation types define a subset of data elements, which may potentially be subject of annotation within a determined annotation workflow like ''Determination'' or ''Gathering''. Before starting to create annotations, a predefined annotation type has to be selected by the annotator from a drop-down selection box. After having determined the annotation type that way, the standard view presents to the annotator only those data elements as defined in the corresponding template for the given annotation type. Thus, an annotation type definition consists of a list of element selectors determined in favour of a given annotation workflow.
| |
| − |
| |
| − | '''AnnotationType.<namespace prefix>.<name> = expression-list(element selectors)'''
| |
| − | ;AnnotationType
| |
| − | :This is a prefix required to retrieve AnnotationType definitions within an arbitrary list of properties by the system.
| |
| − | ;namespace prefix
| |
| − | :Defines the XML document's namespace prefix to which the annotation type definition applies to. The namespace prefix must be given as defined in section [[#Namespace_Support|Namespace Support]].
| |
| − | ;name
| |
| − | :Defines the name of the annotation type, which is used by the AnnoSys system to internally identify a given annotation type definition.
| |
| − | ;element selectors
| |
| − | :Specifies the list of template defining element selectors(cmp. [[#Definition_of_element_selectors|Definition of element selectors]]).
| |
| − |
| |
| − | Example:
| |
| − | AnnotationType.abcd2.06b.Determination = \
| |
| − | ${ElementSelector.xpointer.PreferredIdentifierRole.abcd2.06b}, \
| |
| − | ${ElementSelector.xpointer.PreferredHigherTaxonName.abcd2.06b}, \
| |
| − | ${ElementSelector.xpointer.PreferredHigherTaxonRank.abcd2.06b}, \
| |
| − | ${ElementSelector.xpointer.PreferredFullScientificName.abcd2.06b}
| |
| − | The annotation type named ''Determination'' is defined for the namespace prefix ''abcd2.06b'' and consists of the element selectors named as ''PreferredIdentifierRole'', ''PreferredHigherTaxonName'', ''PreferredHigherTaxonRank'' and ''PreferredFullScientificName'' and defined for the same namespace.
| |
| − |
| |
| − | === Definition of Annotation Restrictions ===
| |
| − | In addition to element value restrictions potentially defined in a specification document and automatically evaluated by the AnnoSys user interface, individual restrictions may be configured using the term ''AnnotationRestriction''. An annotation restriction specifies a list of input values permitted for a given element selector. That list of permitted input values will be shown to the annotator within a drop-down selection box and automatically opened within the related input field of the user interface. The names of annotation restrictions are expressed as [http://www.w3.org/TR/xpath20/ XPath]<ref name="W3C_XPath"></ref> selectors, where any '/' characters were replaced by '_' characters. The latter is due to the fact that annotation restrictions also apply to the annotation editor's ''Expert View'', where restrictions are only evaluated on a XPointer expression basis.
| |
| − |
| |
| − | ;Note
| |
| − | :This will be subject of modification in a later revision where the XPath expression be replaced by the name of an element selector.
| |
| − |
| |
| − | '''AnnotationRestriction.<namespace prefix>.<XPath expression> = expression-list(permitted values)'''
| |
| − | ;AnnotationType
| |
| − | :This is a prefix required to retrieve AnnotationType definitions within an arbitrary list of properties by the system.
| |
| − | ;namespace prefix
| |
| − | :Defines the XML document's namespace prefix to which the annotation restriction definition applies to. The namespace prefix must be given as defined in section [[#Namespace_Support|Namespace Support]].
| |
| − | ;XPath expression
| |
| − | :Defines an XPath selector to the addressed element, where any '/' characters must be replaced by '_' characters.
| |
| − | ;permitted values
| |
| − | :Specifies a list of permitted values as to be shown in a drop-down selection box within the related input field in the user interface.
| |
| − |
| |
| − | Example:
| |
| − | AnnotationRestriction.abcd2.06b._DataSets_DataSet_Units_Unit_SpecimenUnit_NomenclaturalTypeDesignations_NomenclaturalTypeDesignation_TypeStatus = \
| |
| − | Isotype, \
| |
| − | Syntype, \
| |
| − | Isosyntype, \
| |
| − | Holotype, \
| |
| − | Lectotype, \
| |
| − | Neotype, \
| |
| − | Parataype, \
| |
| − | Epitype
| |
| − | The permitted input values (''Isotype'', ''Syntype'', etc.) are specified for record documents within the defined namespace ''abcd2.06b'' for elements matching the XPath expression ''/DataSets/DataSet/Units/Unit/SpecimenUnit/NomenclaturalTypeDesignations/NomenclaturalTypeDesignation/TypeStatus''.
| |
| − |
| |
| − | == Synonyms list ==
| |
| − | The synonyms list contains mappings of taxonomic family names defined by the element selector ''PreferredHigherTaxonName'', which may be used synonymously in search operations conducted via the user interface as well as in evaluating user defined subsriptions. The configuration of annotation types takes place in the property file defined within the [[#annosys.properties|AnnoSys System Configuration file ''annosys.properties'']] using the option ''AnnoSys.synonyms.file'' (default: /etc/AnnoSys/resources/synonyms.properties).
| |
| − |
| |
| − | Mappings must be defined in both directions and family names must be given in lowercase. Any number of mappings are permitted.
| |
| − |
| |
| − | Example:
| |
| − | asteraceae = compositae
| |
| − | compositae = asteraceae
| |
| − | Defines the synonymity betwenn the family names ''Asteraceae'' and ''Compositae''.
| |
| − |
| |
| − | = Security =
| |
| − | In AnnoSys, any security relevant implementations base on the [http://shiro.apache.org/ Apache Shiro]<ref name="APACHE_SHIRO">The Apache Software Foundation (2013). "Welcome to Apache Shiro." Retrieved 13 December, 2013, from http://shiro.apache.org/.<br/></ref> framework. Further on, any security or privacy relevant information is stored in a file holding a [http://www.sqlite.org/ SQLite]<ref name="SQLite"></ref> database. The following sections will provide further details about the internal parts of the security component.
| |
| − |
| |
| − | == Security Database ==
| |
| − | As any other system relevant configuration files, the security database is stored in a location on the server inaccessible for unauthorised AnnoSys agents or external services.
| |
| − |
| |
| − | The figure ''Security Database Schema'' below shows an entity relationship diagram revealing data and table relationships as organised in the security database. Therein, the ''agents'' table is used for storing user authentication and profile data. The table ''institutions'' holds a list of any known institutions either by requesting and updating the GBIF institutions web service or by additions created by users while registering to the AnnoSys Security Database.
| |
| − | [[Image:AnnoSys2-authDb.png|frame|none|''Security Database Scheme'']]
| |
| − | The following sections provide some implementation details about authentication and agent profiles in AnnoSys.
| |
| − |
| |
| − | == Secure Authentication ==
| |
| − | Agent authentication is secured by individual agent credentials to be entered at the login dialog. Moreover, any data transmissions initiated through network connections are secured by the [http://tools.ietf.org/html/rfc2818 Hypertext Transfer Protocol Secure (HTTPS)]<ref name="RFC_HTTPS">Rescorla, E. (2000). "HTTP Over TLS" Retrieved 13 December, 2013, from http://tools.ietf.org/html/rfc2818.<br/></ref>.
| |
| − |
| |
| − | For user authentication, the following data is relevant and retrieved from the security database's ''subjects'' table.
| |
| − | ;uid
| |
| − | :the user id, or the login name an agent fills into the login dialog.
| |
| − | ;credential
| |
| − | :the agent's credential, or the password an agent fills into the login dialog. Credentials are stored as digest values according to [https://shiro.apache.org/static/1.3.1/apidocs/org/apache/shiro/authc/credential/DefaultPasswordService.html#DEFAULT_HASH_ALGORITHM Apache Shiro's 3.1 DefaultPasswordService Hash Algorithm (SHA-256)].
| |
| − | ;status
| |
| − | :the current status of the agent. Currently, only active (1) and inactive (0) are supported values.
| |
| − |
| |
| − | The relationship with agent data in the annotation repository is realised through the following data elements:
| |
| − | ;resourceid
| |
| − | :the current resource URI of the agent representing the users's identity in the annotation repository.
| |
| − | ;type
| |
| − | :the agent type (Person, Organisation or Software) according to the agent metadata properties defined in section [[#Agent_Profiles|Agent Profiles]].
| |
| − | ;name
| |
| − | :the agent's name
| |
| − | ;institution
| |
| − | :the agent's institution as a key to the ''institution'' element in the table ''institutions'', where the element ''institutionName'' represents the name of the given institution
| |
| − |
| |
| − | Additionally, the following information is held by the security database:
| |
| − | ;mailbox
| |
| − | :the agent's email address used for communication via the AnnoSys Message System.
| |
| − | ;mailboxLocale
| |
| − | :the agent's locale used communication via the AnnoSys Message System.
| |
| − | ;uiLocale
| |
| − | :the agent's locale used for displaying the AnnoSys User Interface.
| |
| − | ;description
| |
| − | :to be used by system administrators for additional natural language information about the agent.
| |
| − |
| |
| − | == Agent Profile Management ==
| |
| − | Agent profile management combines the maintenance of the security database and personal profile stores arranged for each registered agent ([[#Agent_Profiles| cmp. Agent Profiles]]). Currently, the agent registration process consists of filling in a form with the required information as outlined in in section [[#Secure_Authentication|Secure Authentication]]. Registered agents may immediately login to the system and start editing and publishing annotations. Also, a personal profile store including a store capturing personal system preferences will be instantiated on a per agent basis. If imposed by measures against system misuse (e.g. spam bot registrations), the registration procedure may be hardened by appropriate measures in the future.
| |
| − |
| |
| − | Furthermore, system administrators may decide to inactivate or delete agents and their profiles from the system for reasons of misuse or security. This will impact the deletion of any annotations published by those agents as well.
| |
| − |
| |
| − | = Message System =
| |
| − | Via the message system, registered agents are informed about annotation events triggered by agent or system interactions. Therefore, notifications in terms of email messages are issued based on subscriptions defined by registered agents. Registered agents can manage their subscriptions via the user interface.
| |
| − |
| |
| − | Technically, the Message System bases on the [https://javaee.github.io/javamail/ JavaMail API]<ref name="ORACLE_JAVAMAIL_API">Oracle. "
| |
| − | JavaMail - JavaMail Reference Implementation." Retrieved 10 April, 2018, from https://javaee.github.io/javamail/.<br/></ref> to send emails via an SMTP server,
| |
| − | and a subscription component which manages the subscriptions and assigns messages to agents when a new annotation matches the criteria of a subscription defined by an agent.
| |
| − |
| |
| − | == Subscriptions ==
| |
| − |
| |
| − | Subscriptions are a means for agents to individually determine those kinds of annotations they want to be notified about. They are based on a quite simple data model (see diagram ''Subscription database scheme'') and are currently persisted in a SQLite database.
| |
| − |
| |
| − | [[Image:AnnoSys2-subscriptionDb.png|frame|none|''Subscription database scheme'']]
| |
| − |
| |
| − | Mainly, subscriptions consist of composable search criteria to determine matching annotations. Search criteria are defined by AnnoSys ontology concepts, comparison types and expected values. They can further be aggregated by logical operators and are expressed by JSON data structures in string format. Agents may create an unlimited amount of subscriptions. The following table shows the currently supported representation of a subscription in the database tables ''subscriptions'' and ''agentSubscriptions'':
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | |+ align="bottom"|''Database table subscriptions''
| |
| − | ! name !! description
| |
| − | |-
| |
| − | | id || (uu)id of the subscription
| |
| − | |-
| |
| − | | label || label of the subscription (assigned by agent)
| |
| − | |-
| |
| − | | subscription || Composite search criteria as JSON string
| |
| − | |}
| |
| − |
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | |+ align="bottom"|''Database table agentSubscriptions''
| |
| − | ! name !! description
| |
| − | |-
| |
| − | | subscriberUid || (uu)id of the (subscribing) agent
| |
| − | |-
| |
| − | | subscriptionId || (uu)id of the subscription
| |
| − | |}
| |
| − |
| |
| − | On publication of new annotations, the criteria of any subscriptions are checked for matching the given annotation values. Thereby, the criteria either refers to an element's value in the original record's xml document or an annotation element's value in the annotation to be checked. If the criteria of a subscription match the relating information of an annotation, the agent having issued the subscription will be notified by a corresponding email message. The notification messages will be sent via the SMTP server configured by the Message System.
| |
| − |
| |
| − | == Implementation ==
| |
| − |
| |
| − | There are several actors involved in processing messages:
| |
| − |
| |
| − | * AnnotationStore
| |
| − | * MessageSystem
| |
| − | * SubscriptionSubSystem
| |
| − | * JadeRenderer
| |
| − |
| |
| − | First the AnnotationStore gets notified, that a new annotation is about to be published.
| |
| − |
| |
| − | The AnnotationStore calls the MessageSystem to process subscriptions affected by the new annontation(s). Via its SubscriptionSubSystem, the MessageSystem checks for all subscriptions matching the new annotation(s). For all matching subscriptions, it retrieves the subscribing agents from the agentSubscriptions relationsship and their corresponding profiles (including their email addresses) from AnnoSys' SecuritySystem. According to the current mailbox locale stored in an agent's profile, the language for the email template is selected and passed combined with parts of the corresponding agent profile to the JadeRenderer. The JadeRenderer generates the HTML-content of the email message which will finally be sent to the subscribing agent.
| |
| − |
| |
| − | === Jade ===
| |
| − |
| |
| − | The templates are located in resource/templates. The language for the templates is jade. An overview of the syntax can be found at http://jade-lang.com/ and https://naltatis.github.io/jade-syntax-docs/ with interactive input boxes.
| |
| − |
| |
| | = Services = | | = Services = |
| | == Preliminaries == | | == Preliminaries == |
| Line 995: |
Line 411: |
| | | | |
| | The following sections will briefly describe the deployment and building of the [[media:AnnoSys.war.zip.zip|''AnnoSys.war'']] file, and the basic configuration options to adopt the AnnoSys configuration if required. | | The following sections will briefly describe the deployment and building of the [[media:AnnoSys.war.zip.zip|''AnnoSys.war'']] file, and the basic configuration options to adopt the AnnoSys configuration if required. |
| − |
| |
| − | == TODO ==
| |
| − | === Virtuoso setup ===
| |
| − | === Eclipse & RAP Release Update ===
| |
| − | === Https-Proxy setup ===
| |
| − | === annosys.properties anpassen ===
| |
| − | === mvn install ausführen vor kompilieren ===
| |
| − | === AnnoSys.launch Run Configuration zum Starten ===
| |
| − |
| |
| − | == Deploying [[media:AnnoSys.war.zip|''AnnoSys.war'']] file ==
| |
| − | Deploying the [[media:AnnoSys.war.zip|''AnnoSys.war'']] with Jetty is easy. Simply copy the file into the ''webapps'' subdirectory of Jetty's home directory (''/var/lib/jetty8/webapps'' on Debian) and restart jetty (''/etc/init.d/jetty8 restart'') and AnnoSys should be reachable on the URL http://<servername>:8080/AnnoSys/AnnoSys''.
| |
| − |
| |
| − | == Building AnnoSys.war file from source code ==
| |
| − | Unpack the file [[media:AnnoSys.Project.zip|''AnnoSys.Project.zip'']] and import or open the project from the subdirectory ''org.bgbm.annosys'' with your [http://www.eclipse.org/downloads/packages/eclipse-rcp-and-rap-developers/keplerr Eclipse Kepler Edition "Eclipse for RCP and RAP Developers"]. Within the ''Package Explorer View'' on the left side, double-click on the file ''annosys.target'' to install the RAP v2.1 target platform for AnnoSys. The project should be compiled and built against the platform automatically.
| |
| − |
| |
| − | Next, double-click on the file ''AnnoSys.warproduct'' which should open the conifguration dialog of Eclipse WAR Product export wizard. Usually, just executing the ''export wizard'' should be fine. If something does not work as expected, first executing ''Add Required Plug-ins'' within the step 1 ''Configuration'' dialog should solve dependency problems. Finally, deploy your generated AnnoSys.war file as described above.
| |
| − |
| |
| − | == AnnoSys System Configuration ==
| |
| − | AnnoSys' system configuration is based on the [http://commons.apache.org/proper/commons-configuration/ Apache Commons configuration] framework and is subdivided to the following configuration files:
| |
| − | * annosys.properties
| |
| − | * annotation.properties
| |
| − | * selector.properties
| |
| − | * schema.properties
| |
| − |
| |
| − | Further on, that directory is the default location for configuration files of [http://shiro.apache.org/ Apache Shiro]<ref name="APACHE_SHIRO"></ref> and the [http://logging.apache.org/log4j/1.2/ Apache log4j] logging system.
| |
| − | * shiro.ini
| |
| − | * log4j.properties
| |
| − |
| |
| − | If not configured otherwise in your self-built war file, the configuration files will be expected in the directory ''/etc/AnnoSys/config/''. The following sections will briefly introduce into the configuration options on a per file basis.
| |
| − |
| |
| − | === annosys.properties ===
| |
| − | ;AnnoSys.run
| |
| − | :Defines, if AnnoSys is running in test or release mode. Currently, this only defines if curators denoted in annotated records are automatically notified by email if no curators are registered for the given record. Possible values: ''test'' or ''release'' (default: ''test'').
| |
| − |
| |
| − | ;AnnoSys.home.dirfixed
| |
| − | :The base directory, where AnnoSys stores any system relevant data and configuration files (default: ''etc/AnnoSys'')
| |
| − | <br />
| |
| − | ;AnnoSys.servlet.context
| |
| − | :The name of the servlet context which usually corresponds to the name of the deployed war file (default: ''/AnnoSys''). '''This option must be set accordingly. Otherwise, AnnoSys will generate incorrect and unresolvable repository resourceURIs!'''
| |
| − | ;AnnoSys.servlet.path
| |
| − | :The AnnoSys servlet path wihtin the servlet context (default: ''/AnnoSys''). '''This option must be set accordingly. Otherwise, AnnoSys will generate incorrect and unresolvable repository resourceURIs!'''
| |
| − | <br />
| |
| − | ;AnnoSys.repository.uri
| |
| − | :The server URL hosting the AnnoSys application (default: ''https://annosys.bgbm.fu-berlin.de''). '''This option must be set accordingly. Otherwise, AnnoSys will generate incorrect and unresolvable repository resourceURIs!'''
| |
| − | ;AnnoSys.repository.record
| |
| − | :The base location of the record repository (default: ''${AnnoSys.home.dir}/repository/record'')
| |
| − | ;AnnoSys.repository.record.temp
| |
| − | :The location for temporary files used by the record repository (default: ''${AnnoSys.repository.record}/temp'')
| |
| − | ;AnnoSys.repository.record.baseId
| |
| − | :The base resource GUID for record repository resources. The format is ''<base_URI>, <base_LSID-URN>, <base-InstitutionId>, <base-CollectionId>, <base-UnitId>, <base-version>, <base-format>'' (default: ''${AnnoSys.repositorfixedy.record.uri}, ${AnnoSys.lsid.urn}, , , , '').
| |
| − | ;AnnoSys.repository.record.uri
| |
| − | :The base URI for record resources to be accessed via LinkedOpenData or REST services (default: ''${AnnoSys.repository.uri}${AnnoSys.servlet.context}/services/records'').
| |
| − | ;AnnoSys.repository.model.baseId
| |
| − | :The base resource GUID for annoation repository resources. The format is ''<base_URI>, <base_LSID-URN>, <base-InstitutionId>, <base-CollectionId>, <base-UnitId>, <base-version>, <base-format>'' (default: ''${AnnoSys.repository.model.uri}, ${AnnoSys.lsid.urn}, BGBM, AnnoSys, , , '').
| |
| − | ;AnnoSys.repository.model.uri
| |
| − | :The base URI for annotation resources to be accessed via LinkedOpenData or REST services (default: ''${AnnoSys.repository.uri}${AnnoSys.servlet.context}/services/annotations'').fixed
| |
| − | ;AnnoSys.repository.message
| |
| − | :The base location of the message repository (default: ''${AnnoSys.home.dir}/repository/message '').
| |
| − | <br />
| |
| − | ;AnnoSys.repository.model.type
| |
| − | :Type of the annotation RDF store. Possible values: ''tdb'' ([http://jena.apache.org/documentation/tdb/ Apache Jena TDB]<ref name="APACHE_JENA_TDB"></ref> or ''virtuoso'' ([http://www.openlinksw.com/dataspace/doc/dav/wiki/Main/ Virtuoso Open-Source Edition]<ref name="VIRTUOSO"></ref>)(default: ''virtuoso'').
| |
| − | :Note:For performance reasons in the user interface, the current AnnoSys implementation uses virtuoso stores only as backup repository. Anyway, the [[#SPARQL_Endpoint|SPARQL Endpoint]] is served only from the virtuoso store. For that, virtuoso store must be configured as backup RDF store.
| |
| − |
| |
| − | ;AnnoSys.repository.model
| |
| − | :Location or URI of the annotation RDF store. While for tdb stores, a directory path is expected (e.g. ''${AnnoSys.home.dir}/repository/model''), virtuoso stores rather expect a URI like ''jdbc:virtuoso://localhost:1112''
| |
| − |
| |
| − | ;AnnoSys.repository.model.user
| |
| − | :Login id to access an RDF store. Usually, this is required for virtuoso stores.
| |
| − | ;AnnoSys.repository.model.password
| |
| − | :Password to access an RDF store. Usually, this is required for virtuoso stores.
| |
| − |
| |
| − | ;AnnoSys.repository.model.backup.type
| |
| − | :Type of the annotation RDF backup store. Possible values: ''tdb'' ([http://jena.apache.org/documentation/tdb/ Apache Jena TDB]<ref name="APACHE_JENA_TDB"></ref> or ''virtuoso'' ([http://www.openlinksw.com/dataspace/doc/dav/wiki/Main/ Virtuoso Open-Source Edition]<ref name="VIRTUOSO"></ref>)(default: ''virtuoso'').
| |
| − | :Note:For performance reasons in the user interface, the current AnnoSys implementation uses virtuoso stores only as backup repository. Anyway, the [[#SPARQL_Endpoint|SPARQL Endpoint]] is served only from the virtuoso store. For that, virtuoso store must be configured as backup RDF store.
| |
| − |
| |
| − | ;AnnoSys.repository.model.backup
| |
| − | :Location or URI of the annotation RDF backup store. While for tdb stores, a directory path is expected (e.g. ''${AnnoSys.home.dir}/repository/model''), virtuoso stores rather expect a URI like ''jdbc:virtuoso://localhost:1112''
| |
| − |
| |
| − | ;AnnoSys.repository.model.backup.user
| |
| − | :Login id to access an RDF backup store. Usually, this is required for virtuoso stores.
| |
| − | ;AnnoSys.repository.model.backup.password
| |
| − | :Password to access an RDF backup store. Usually, this is required for virtuoso stores.
| |
| − | <br />
| |
| − | ;AnnoSys.repository.agent
| |
| − | :The base location of the [[#Agent_Profile_Management|Agent profiles]] (default: ''${AnnoSys.home.dir}/repository/agent'')
| |
| − |
| |
| − | ;AnnoSys.repository.agent.baseId
| |
| − | :The base resource GUID for agent repository resources. The format is ''<base_URI>, <base_LSID-URN>, <base-InstitutionId>, <base-CollectionId>, <base-UnitId>, <base-version>, <base-format>'' (default: ''${AnnoSys.repository.record.uri}, ${AnnoSys.lsid.urn}, BGBM, AnnoSys, , , '').
| |
| − |
| |
| − | ;AnnoSys.repository.agent.uri
| |
| − | :The base URI for agent resources to be accessed via LinkedOpenData or REST services (default: ''${AnnoSys.repository.model.uri}'', same as for annotations).
| |
| − | <br />
| |
| − | ;AnnoSys.authDB
| |
| − | :LocationURI of the [[#Security_Database|Security Database]] (default: jdbc:sqlite:${AnnoSys.home.dir}/authDB.sqlite)
| |
| − |
| |
| − | ;AnnoSys.authStore.importRecordStoreOnStart
| |
| − | :Option to be set when roles and permissions within the [[#Security_Database|Security Database]] should be updated based on the record available from the record repository. As roles and permissions were updated on any successful record import, this should only be activated for system maintenance reasons. Possible values: ''true'' or ''false'' (default: false)
| |
| − |
| |
| − | ;AnnoSys.authStore.admin.role
| |
| − | ;Role name for AnnoSys administrators (default: ''administrator:BGBM:AnnoSys''). If neither this admin role nor the admin permission below is configured in the [[#Security_Database|Security Database]], then the ''Administration'' tab is shown without login. So, a user having that role should be installed immediately after system installation!
| |
| − |
| |
| − | ;AnnoSys.authStore.admin.permission
| |
| − | ;Permission name for AnnoSys administrators (default: ''admin:BGBM:AnnoSys:security''). If neither this admin permission nor the admin role above is configured in the [[#Security_Database|Security Database]], then the ''Administration'' tab is shown without login. So, a user having that role should be installed immediately after system installation!
| |
| − | <br />
| |
| − | ;AnnoSys.namespaceURI
| |
| − | :AnnoSys namespapce uri (default: (http://annosys.bgbm.org#'').
| |
| − |
| |
| − | ;AnnoSys.lsid.urn
| |
| − | :lsid URN prefix for internal use (default: ''urn:lsid'').
| |
| − | <br />fixed
| |
| − | ;AnnoSys.smtp.host
| |
| − | :SMTP server for outgoing emails
| |
| − |
| |
| − | ;AnnoSys.smtp.port
| |
| − | :SMTP server port for outgoing emails (default: ''25'') (optional).
| |
| − |
| |
| − | ;AnnoSys.smtp.protocol
| |
| − | :SMTP protocol to be used for outgoing emails (optional).
| |
| − |
| |
| − | ;AnnoSys.smtp.username
| |
| − | :Login id for outgoing SMTP server (optional).
| |
| − |
| |
| − | ;AnnoSys.smtp.password
| |
| − | :Password for outgoing SMTP server (optional).
| |
| − |
| |
| − | ;AnnoSys.mail.from
| |
| − | :Email header ''From'' to be used for outgoing emails (default: ''AnnoSys Message System<annosys@bgbm.org>'').
| |
| − | <br />
| |
| − | ;AnnoSys.message.broker.start
| |
| − | :Option to be set for starting the [[##Message_System_2|Message System]] on system start. Possible values: ''true'' or ''false'' (default:''true'')
| |
| − |
| |
| − | ;AnnoSys.message.broker.name
| |
| − | :Name for the ActiveMQ message broker instance (default:''AnnoSys'').
| |
| − |
| |
| − | ;AnnoSys.message.broker.url
| |
| − | :URL of the ActiveMQ message broker instance (default: ''vm://${AnnoSys.message.broker.name}'').
| |
| − |
| |
| − | ;AnnoSys.message.templatesfixed
| |
| − | :The base location of the templates used by the [[##Message_System_2|Message System]] for outgoing emails (default: ''${AnnoSys.home.dir}/resources/templates'').
| |
| − |
| |
| − | ;AnnoSys.message.subscription.db
| |
| − | :LocationURI of the [[##Message_System_2|Message System]]'s subscription database (default: jdbc:sqlite:${AnnoSys.home.dir}/repository/subscriptions/subscriptions.db).
| |
| − |
| |
| − | ;AnnoSys.message.subscription.add.icon
| |
| − | :Icon location for the subscription-add functionality (default: ''icons/add_att.gif'')
| |
| − | ;AnnoSys.message.subscription.delete.icon
| |
| − | :Icon location for the subscription-delete functionality (default: ''icons/application-exit-4-22x22.png'')
| |
| − | ;AnnoSys.message.subscription.help.icon
| |
| − | :Icon location for the subscription-help functionality (default: ''icons/system-help-3-22x22.ico'')
| |
| − |
| |
| − | ;AnnoSys.message.default.mailaddress
| |
| − | :AnnoSys's default mailaddress for user replies (default: ''annosys@bgbm.org'')
| |
| − | <br />
| |
| − | ;AnnoSys.synonyms.filefixed
| |
| − | :List of synonym expressions used in searches with respect to families (default: ''${AnnoSys.home.dir}/resources/synonyms.properties'')
| |
| − | <br />
| |
| − | ;AnnoSys.termsOfUse.url
| |
| − | :URL of the terms of use document (default: ''https://annosys.bgbm.fu-berlin.de/node/54'')
| |
| − |
| |
| − | ;AnnoSys.help.pdfurl
| |
| − | :URL of the terms of user's manual (default: ''https://annosys.bgbm.fu-berlin.de/sites/default/files/Users%20Instructions.pdf'')
| |
| − |
| |
| − | ;AnnoSys.improve.urlfixed
| |
| − | :URL of the AnnoSys ticket system to record bug reports or other user proposal (default: ''https://annosys.bgbm.fu-berlin.de/trac/newticket'')
| |
| − |
| |
| − | ;AnnoSys.homepage.url
| |
| − | :URL of the AnnoSys web home page (default: ''https://annosys.bgbm.fu-berlin.de/'')
| |
| − | <br />
| |
| − | ;AnnoSys.template.pdf.determination
| |
| − | :Location of the stylesheet for creating PDF-labels for annotations of type determination (default: ''${AnnoSys.message.templates}/pdf/determination.xsl'')
| |
| − | <br />
| |
| − | ;AnnoSys.log4j.configuration
| |
| − | :Location of the log4j configuration file (default: ''${AnnoSys.home.dir}/config/log4j.properties'').
| |
| − | <br />
| |
| − | ;AnnoSys.toolbar.annosys.icon
| |
| − | :Icon location for the annosys web home page functionality in the main toolbar (default: ''icons/AnnoSys-Logo-89x24.png'')
| |
| − | ;AnnoSys.toolbar.publish.icon
| |
| − | :Icon location for the publish functionality in the main toolbar (default: ''icons/earth_upload-24x24.ico'')
| |
| − | ;AnnoSys.toolbar.preferences.icon
| |
| − | :Icon location for the preferences functionality in the main toolbar (default: ''icons/preferences-desktop-user-password-22x22.ico'')
| |
| − | ;AnnoSys.toolbar.search.icon
| |
| − | :Icon location for the search functionality in the main toolbar (default: ''icons/system-search-5-22x22.png '')
| |
| − | ;AnnoSys.toolbar.login.icon
| |
| − | :Icon location for the login functionality in the main toolbar (default: ''icons/preferences-system-login-22x22.ico'')
| |
| − | ;AnnoSys.toolbar.logout.icon
| |
| − | :Icon location for the logout functionality in the main toolbar (default: ''icons/application-exit-3-22x22.ico'')
| |
| − | ;AnnoSys.toolbar.help.icon
| |
| − | :Icon location for the help functionality in the main toolbar (default: ''icons/help-contents-5-22x22.ico'')
| |
| − | ;AnnoSys.toolbar.improve.icon
| |
| − | :Icon location for the improve functionality in the main toolbar (default: ''icons/trac-24x24.png'')
| |
| − | ;AnnoSys.toolbar.subscriptions.iconfixed
| |
| − | :Icon location for the subscription functionality in the main toolbar (default: ''icons/hdd_web-24x24.ico'')
| |
| − | ;AnnoSys.toolbar.administrator.icon
| |
| − | :Icon location for the administrator functionality in the main toolbar (default: ''icons/user-group-properties-22x22.ico'')
| |
| − |
| |
| − | ;AnnoSys.imagebutton.undo.icon
| |
| − | :Icon location for the ''undo'' functionality in the annotation editor (default: ''icons/rewind.png'')
| |
| − | ;AnnoSys.imagebutton.remove.icon
| |
| − | :Icon location for the ''remove'' functionality in the annotation editor (default: ''icons/gnome_edit_delete-16x16.ico'')
| |
| − | ;AnnoSys.imagebutton.verify.icon
| |
| − | :Icon location for the ''verify'' functionality in the annotation editor (default: ''icons/ok_st_obj.gif'')
| |
| − | ;AnnoSys.imagebutton.annosys.icon
| |
| − | :Icon location for the currently unused functionality in the annotation editor (default: '' = icons/A-16x16.png'')
| |
| − |
| |
| − | ;AnnoSys.recordselectionview.information.icon
| |
| − | :Icon location for the ''information'' functionality in the import record selection dialog (default: ''icons/mail-mark-important-2.ico'')
| |
| − |
| |
| − | ;AnnoSys.notificationDialog.addEmail.icon
| |
| − | :Icon location for the ''add email'' functionality in the message systems notification dialog (default: ''icons/icons/add_obj.gif'')
| |
| − | <br />
| |
| − | ;AnnoSys.locales
| |
| − | :List of supported system locales in preferred order (default: ''en-GB, de-DE'')
| |
| − |
| |
| − | === shiro.ini ===
| |
| − | This is the main configuration file of the [http://shiro.apache.org/ Apache Shiro]<ref name="APACHE_SHIRO"></ref> system used by the [[#Security_2|Security System]]. For more detailed information, please refer to the [http://shiro.apache.org/ Apache Shiro] documentation.
| |
| − |
| |
| − | ==== Section [main] ====
| |
| − | ;cacheManager
| |
| − | :Defines the cache manager implementation class (default: ''org.apache.shiro.cache.MemoryConstrainedCacheManager'').
| |
| − | ;securityManager.cacheManager
| |
| − | :Assigns the cache manager to the security manager (default: ''$cacheManager'')
| |
| − |
| |
| − | ;passwordService
| |
| − | :Defines the password service implementation class for the password matcher (default: ''org.bgbm.annosys.security.shiro.ApacheSHA1PasswordService'').
| |
| − |
| |
| − | ;passwordMatcher
| |
| − | :Defines the password matcher for the AnnoSys authentication realm (default: ''org.apache.shiro.authc.credential.PasswordMatcher'').
| |
| − |
| |
| − | ;passwordMatcher.passwordService
| |
| − | :Assigns the password service to the password matcher (default: ''$passwordService'').
| |
| − |
| |
| − | ;annosysRealm
| |
| − | :Defines the AnnoSys authentication realm implementation class (default: ''org.bgbm.annosys.security.shiro.AnnoSysJdbcRealm'').
| |
| − |
| |
| − | ;annosysRealm.credentialsMatcher
| |
| − | :Assigns the password matcher for the AnnoSys authentication realm (default: ''$passwordMatcher'').
| |
| − |
| |
| − | ;annosysRealm.authenticationCachingEnabled
| |
| − | :Enables authentication caching for the AnnoSys authentication realm (default: ''true'').
| |
| − |
| |
| − | ;annosysRealm.permissionsLookupEnabled
| |
| − | :Enables permission lookup for the AnnoSys authentication realm (default: ''true'').
| |
| − |
| |
| − | ;sessionManager
| |
| − | :Defines the session manager implementation class (default: ''org.apache.shiro.web.session.mgt.DefaultWebSessionManager'').
| |
| − |
| |
| − | ;securityManager.sessionManager
| |
| − | :Assigns the session manager to the security manager (default: ''$sessionManager'').
| |
| − |
| |
| − | ;securityManager.sessionManager.globalSessionTimeout
| |
| − | :Sets the AnnoSys session timeout (default: ''36000000'' (10h)).
| |
| − |
| |
| − | ;sessionListener
| |
| − | :Defines the session listener implementation class (default: ''org.bgbm.annosys.security.shiro.ShiroSessionListener''). This is used to clean up web session correctly wihtin AnnoSys.
| |
| − |
| |
| − | ;securityManager.sessionManager.sessionListeners
| |
| − | :Assigns the session listener to the security manager (default: ''$sessionListener'').
| |
| − |
| |
| − | ;securityManager.sessionManager.sessionIdCookie.secure
| |
| − | :Enables setting of secure session cookies for the session manager (default: ''true'').
| |
| − |
| |
| − | ;securityManager.sessionManager.sessionIdCookie.domain
| |
| − | :Sets the cookie domain for session cookies (default: ''annosys.bgbm.fu-berlin.de'')
| |
| − |
| |
| − | ;logout.redirectUrl
| |
| − | :Sets the redirection URL for session logout (default: ''/AnnoSys'').
| |
| − |
| |
| − | ==== Section [urls] ====
| |
| − | ;/AnnoSys/logout = logout
| |
| − | :Defines ''/AnnoSys/logout'' as logout URL.
| |
| − |
| |
| − | = Dependencies =
| |
| − | The following table lists the frameworks and libraries used to implement the AnnoSys software. Any libraries were included via the [http://maven.apache.org/ Apache Maven] dependencies mechanisms, which automatically resolves hundreds of further dependencies. Therefore, just the dependencies defined within the Maven ''pom.xml'' file and their licensing will be listed here.
| |
| − |
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | |+ align="bottom"|''List of AnnoSys dependencies''
| |
| − | ! group
| |
| − | ! artifact
| |
| − | ! version
| |
| − | ! license
| |
| − | |-
| |
| − | | org.apache.activemq || activemq-all || 5.8.0 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.activemq || activemq-pool || 5.8.0 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-core || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-jms || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-activemq || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-jaxb || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-mail || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.camel || camel-core-osgi || 2.12.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.axis || axis || 1.4 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.shiro || shiro-core || 1.2.3 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.shiro || shiro-web || 1.2.3 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.apache.jena || apache-jena-libs || 2.10.1 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.xerial || sqlite-jdbc || 3.7.15-M1 || [http://www.sqlite.org/copyright.html Public Domain]
| |
| − | |-
| |
| − | | net.sf.opencsv || opencsv || 2.3 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | commons-configuration || commons-configuration || 1.9 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | org.jdom || jdom2 || 2.0.5 || [http://www.jdom.org/docs/faq.html#a0030 Apache 2.0 style license]
| |
| − | |-
| |
| − | | com.sun.xsom || xsom || 20110809 || [https://xsom.java.net/ Dual license]: [http://web.archive.org/web/20090125222439/http://www.sun.com/cddl/cddl.html CDDL 1.0] and [http://glassfish.java.net/public/CDDL+GPL_1_1.html GPL v2.0]
| |
| − | |-
| |
| − | | com.google.code.gson || gson || 2.2.4 || [http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 licence]
| |
| − | |-
| |
| − | | de.neuland-bfi || jade4j || 0.4.0 || [http://opensource.org/licenses/MIT MIT license]
| |
| − | |-
| |
| − | | junit || junit || 4.11 || [http://www.opensource.org/licenses/cpl1.0.txt Common Public License Version 1.0]
| |
| − | |-
| |
| − | | xmlunit || xmlunit || 1.5 || [http://opensource.org/licenses/bsd-license.php BSD License]
| |
| − | |-
| |
| − | | org.agmip.thirdparty || ximpleware-vtd-xml || 2.11 || [http://opensource.org/licenses/GPL-2.0 GPL v2.0]
| |
| − | |}
| |
| − |
| |
| − | Additionally, the following libraries for the Apache Jena Virtuoso driver are included directly, as they are not available as Maven artifact:
| |
| − | {| class="wikitable" style="text-align: left;"
| |
| − | |+ align="bottom"|''List of AnnoSys dependencies''
| |
| − | ! library
| |
| − | ! license
| |
| − | |-
| |
| − | | virt_jena2.jar || [http://virtuoso.openlinksw.com/dataspace/doc/dav/wiki/Main/VOSLicense GPL v2.0 style license]
| |
| − | |-
| |
| − | | virtjdbc4.jar || [http://virtuoso.openlinksw.com/dataspace/doc/dav/wiki/Main/VOSLicense GPL v2.0 style license]
| |
| − | |-
| |
| − | |}
| |
| | | | |
| | = References = | | = References = |
| | <references /> | | <references /> |
Within the services documentation, some place holders are used to shorten reading and to adopt it easily to other or changing environments.
For testing purposes, the most recent release is available under the following URLs:
AnnoSys provides the following types of interfaces for integration with Data Portals or other applications
The user interface can be invoked either to enable portal users to annotate the data record currently reviewed in the data portal, to examine an annotation related to the data record or to redirect users to the AnnoSys application main page including an annotation search interface.
To enable users to annotate a data record, the relating data must be transferred to the AnnoSys application first. Then, the user will be redirected to the AnnoSys Annotation Editor. This may be done either by providing AnnoSys with a URL, where the document can be downloaded by AnnoSys directly, or by providing a set of parameters instructing AnnoSys to download the corresponding data record from a BioCASE provider.
The URL referring to the record data document to be passed to AnnoSys via the parameter recordURL, i.e.
In case of any of the document holds more than a single data record, the AnnoSys user interface provides a record selection dialog where annotators may select records for further being processed as multiple individual annotations from a list of successfully transmitted data records.
The BioCASE provider and the data record to be retrieved by AnnoSys must be passed via the following parameter set
The repository URI corresponds to the UUID identifier used to retrieve any data stored in the AnnoSys repository like annotations or annotated records through AnnoSys' Linked Open Data Services described in section Web Services.
The URI referring repository data object can be passed to AnnoSys via the parameter repositoryURI, i.e.
The following example links are all referring to the same object: B 40 0025800 (Padina Pavonia):
The Linked Open Data services provide access to resources referring to data stored in the AnnoSys repository. Therewith, annotations can be retrieved as RDF data, and the relating record documents as XML documents.
The RESTful services provide access to other information related to annotations or records, like if there are annotations stored in the repository for a given record.
For legacy reasons e.g. to data portals connected AnnoSys I, AnnoSys also provides the former (legacy) service entries:
The next sections will provide detailed information regarding the provided services.
All repository requests return an either an RDF graph containing the repository object as described in our repository object model or a JSON annotation object as described in section JSON Annotation Object.
Returns a JSON object containing a list of URLs referring to to all available annotations in the AnnoSys repository.
Imports any annotations available from an AnnoSys I repository into this repository.
Any exception thrown during the import process will result in anHTTP-Status 500 to be returned.
Any exception thrown during the import process will result in an HTTP-Status 500 to be returned.
Backups the AnnoSys repository's RDF graph to the given (server local) file path.
Any exception thrown during the import process will result in anHTTP-Status 500 to be returned.
Restores the AnnoSys repository's RDF graph to the given (server local) file path.
Any exception thrown during the import process will result in anHTTP-Status 500 to be returned.
All annotation requests return an either an RDF graph containing the annotations as described in our annotation model or a JSON annotation object as described in section JSON Annotation Object.
Returns a JSON object containing a list of JSON objects referring to to all available annotations in the AnnoSys repository.
Returns the annotation with the given annotationId as RDF graph, if it exists. Otherwise, HTTP-Status 404 is returned.
The RDF document format may be selected by the optional parameter format. Any format supported by Apache Jena may be chosen (defaults to JSONLD).
Returns a JSON object containing a list of URLs referring to to all available annotations in the AnnoSys repository.
Returns a JSON object containing information about all annotations referring to the record in the AnnoSys repository according to the given record tripleId. In particular, this includes annotations created for all record versions stored in the AnnoSys record repository.
An JSON Annotation Object contains the following meta information about an annotation which is intended for being displayed at a data portal user interface:
An JSON Agent Object contains the following meta information about an agent either stored as annotation creator, generator or organisation one of the former's may belong to:
AnnoSys also provides a SPARQL endpoint enabling external services or applications to run self-defined queries against the AnnoSys annotation repository. The SPARQL endpoint is driven by Virtuoso Open Source.
