The Perseids Platform is a loose coupling of open source tools and services providing a platform for collaborative editing and annotation of texts.
At the bottom of the Perseids application stack, a Git repository provides versioning support for all documents, annotations and other related objects managed on the platform. Git forks, branches and merges are used to manage concurrent access to the same documents and related objects by different users and groups.
Next in the stack is the Son of SUDA Online application (SoSOL), a Ruby on Rails application which serves as a workflow engine on top of Git. It manages interactions with the git repository and provides additional functionality including a user model, document validation, templates for documentation creation, review boards and communities. SoSOL also uses a relational database to store information about document status and to track the activty of users, boards, communities. (See also http://ryanfb.github.io/papers-BICS/sosol-bics-draft.pdf )
SoSOL uses the OpenID and Shibboleth/SAML protocols to delegate responsibility for user authentication to social or institutional identitiy providers. Social identity providers (IdP) are supported through a 3rd party gateway, currently Janrain Engage. Shibboleth/SAML providers can be configured on a one-on-one basis, or via agreement with a federation.
The Perseids deployment of SoSOL also delegates some functionality to external databases and services. It calls on an implementation and extension of a CTS API, deployed in an eXist-db XML repository to support working with document fragments that can be addressed using a canonical citation scheme. It also interacts with helper services for tokenization and retrieval of remote resources.
The SoSOL application itself provides lightweight user interfaces for creating and editing documents and annotations, but in order to support an open-ended set of different editing and annotation activities, we rely on integrations with external web-based tools for editing and annotating, via RESTful interactions between the tools and the SoSOL application.
The following are typical scenarios motivating extension of or integration with the Perseids platform:
- support for a new identifier/document type
- support for a new type of stand-off annotation for an existing identifier/document type
- use of an existing editing or annotating interface with documents managed by the Perseids platform
- use of the SoSOL review workflow component of the Perseids platform with a 3rd party site
Each of these scenarios requires a slightly different set of developer skills and approaches as described further below.
The Perseids SoSOL deployment currently supports working with the following types of documents:
- Texts and Translations encoded in EpiDoc compliant TEI-XML
- Commentaries on texts and other linkable targets (adhering to the Open Annotation data model)
- Annotations on texts and other linkable targets (adhering to the Open Annotation data model)
- Treebank/Morpho-syntactic Annotations adhering the Perseus Ancient Language Dependency Treebank schema
- Translation Alignment Annotations adhering to the alpheios.net alignment schema.
- Collections of Images
Publications can consist of combinations of one or more of the above types of documents.
Perseids uses CTS URNs as stable identifiers for primary source texts and CITE URNs Commentaries, Annotations and Images.
Adding support for additional document types and/or stable identifier types is possible. This requires a clearly defined and consistent stable identifier syntax for the document type and extension of the base Identifier class (in Ruby) to implement the business logic for the identifier and document type, including specification of a schema against which the document can be validated, if desired.
Developer Skills required: Ruby, XML, XSLT, Javascript, RDF
There are two main approaches supported for integrating an external tool with Perseids SoSOL:
- directly via the RESTful APIs of the external tool and SoSOL
- by deploying the tool as a plugin on the Arethusa framework
Currently user session sharing and management between external tools and SoSOL can supported through the use of CSRF tokens. Future plans include support for OAuth and/or JWT.
This diagram shows the basic sequence of interactions between Perseids SoSOL, a Social IdP gateway, a Social IdP and an external web application. In this example interaction, the Social IdP provides the user with secure access to their credentials, SoSOL manages version history and business logic related to individual documents (e.g. identification of available tools for editing), the Web application provides an editing/annotating UI for a given document type.
Tools that have already been integrated with the Perseids SoSOL application in this manner include:
- the Alpheios Treebank Editor
- the Alpheios Alignment Editor
- the Recogito Toponym Annotation Tool
- the Perseus Fragmentary Texts Annotation Editor prototype
- the Artheusa Annotation Framework
See the Perseids Data Management Apis for further details on available API calls for external web applications.
Developer Skills required: Understanding of RESTful APIs, plus whatever knowledge is required for development of the external web application
The Arethusa Annotation Framework has been integrated with Perseids SoSOL to provide an alternative, more fluid user experience for working with annotations of multiple types on a single document or set of documents. Arethusa's design is intended to fill a number of important goals:
- to make annotating accessible and enjoyable, lowering the entry barrier for the user by providing access to related resources and services at the point of annotation.
- to make the developer's job easier, by giving her tools and a framework for adding new functionality in a modular fashion and for binding diverse resources together in new ways.
- to be fully open and have the ability to participate in external workflows that route digital content, together with its provenance, to and from diverse destinations.
Arethusa is built on the angular.js javascript web application framework and provides a back-end independent plugin infrastructure for accessing texts, annotations, linguistic services from a variety of sources. Arethusa leverages javascript APIs and HTML templates, as well as command line tools for automatic generation of plugin skeletons, to make it very easy for developers with HTML 5 and Javascript skills to customize the platform and add additional features.
Arethusa acts as a broker between the SoSOL Perseids back-end (as well as other back-end datasources) and the front-end annotating and editing tools. Core Arethusa libraries handle the details of interacting with SoSOL for documents and related user data, and custom editing interfaces can be developed as javascript-based plugins.
The work involved in developing of a new Arethusa plugin can be more or less involved, depending upon the circumstance. The simplest type of plugin is an alternate editing interface for an already-supported document/annotation type. This would require developing:
- an HTML 5 template and associated CSS for the layout of the editing interface
- Javascript libraries defining event handlers and other implementation of business logic for the editing interface
A more complex type of plugin is one which provides not only a new editing interface, but also works with a new document type or format. This would require developing:
- an HTML 5 template and associated CSS for the layout of the editing interface
- Javascript libraries to:
- define event handlers and other implementation of business logic for the editing interface
- retrieve annotation tokens and data from the source document(s) and make them accessible to the core Arethusa state object
- persist annotation tokens and data from the core Arethusa state back into their original representation
- listen for and react to actions of other components of the annotation environment
This type of addition to the platform might also require comparable changes on the Perseids back-end, to support a new identifier/document type, as described above. And it often involves data modeling work to consider implications of cross-document alignment and integration with other types of related resources.
The Arethusa plugin developer's guide provides developers with detailed guidance on all of the above tasks.
Developer Skills required: Javascript, HTML5, CSS (Angular experience helpful but not essential), Understanding of RESTful APIs and linked data concepts.
Coming soon...