Requirements

Uploading a Model

A user can upload a model file (SBML, CellML, NeuroML, ...) to a JUMMP instance. The model file will be stored in a version control system (VCS) and the meta-data or (annotations) will be extracted and stored in a relational database. If the submitter was logged in the system, he or she becomes the owner of the model. Otherwise, the curation group becomes the owner of the model. After that, the owner is able to view and download the uploaded model. He can upload new revisions of the model which will replace the latest version shown to the users.

Prerequisites

The user has to upload the model file via a web form and can enter additional information: * reference (DOI, PMID, ...) or link to the publication (if any at that time) * name of the model (optional: can also be extracted from the uploaded file) * comments * name and email address of the submitter (if user not logged in)

Validation

The model file is validated before the model is created (see Requirement for Uploading a Model Revision). Only valid model files are accepted and successfully submitted to the system.

Storing a Model

The model file has to be added to the VCS. For example, if using Subversion: svn add $file followed by svn commit and an initial Revision has to be created for this file.

The filename used in the VCS has to be unique to prevent name clashes. Because of that it is not possible to use the name of the uploaded file. A possible solution is to generate a unique identifier during submission. It can be based on the date and time of the submission (GMT).

Creating the Revision

This is very similar to the requirement of uploading a new Model Revision. If the file could be added to the VCS, a DOM object for the Revision has to be created. The Revision DOM object represents information provided by the VCS system to be used in the application. This includes:

• Revision number of VCS (e.g. 1234 in SVN, or SHA1-sum in Git or Mercurial)
• Link to the user who uploaded the revision. Rational: the interaction with VCS is done with the system user running the application instance. A user in the application does not refer to a user in the VCS. Therefore it has to be stored separately who uploaded a revision.
• Date of the upload, that is current date and time
• A comment which is used as the commit message (e.g. //Initial Import//)
• State
• Format
• Minor Revision

Creating the Model

The DOM object which has to be created for the new Model has to be linked to the created VCS revision. It is not allowed to have a Model without associated revisions. The Model receives several meta information:

• Name specified by the user or taken from uploaded file
• Original filename the filename of the uploaded file TODO: do we actually need that???
• Identifier the identifier used in the VCS

The DOM object for model and revision should be stored in one transaction as they depend on each other (revision requires model, model requires at least one revision).

Publications

The model might be linked to one or more publications. During the upload the user can specify the Pubmed ID or DOI (or similar identifier) which is used to fetch additional information from a publicly available webservice. In case the webservice fails the user could specify the paper information. For each publication some meta information is set: * Type TODO: what is this??? * Journal * Title * Authors * Affiliation * Abstract

Each Publication has to be added to the Model and stored.

Thoughts on Transaction

The complete process of storing a new model should be transactional (like any other action performed). That is either the model is uploaded to both VCS and Database or neither in the one, nor in the other. This is rather difficult as two storage solutions are used. To get the revision number the file has to be added and committed to the VCS which would be before the DB stored the model. At that point the DB transaction could fail, leaving the complete system in an inconsistent state. Most VCS systems do not support rollbacks, it is modelled in general as another commit doing the opposite of the commit which has to be rolled back.

To achieve a transactional behaviour the commit needs to be reverted in the VCS whenever the database fails. Assuming that VCS operations are always performed before the DB is altered, no additional requirements to the DB are needed.

ACL

During upload the access control has to be set for the new model. The user (if logged) becomes the owner of the model.

The user who performs an update of a model receives permanent read access to the associated revision.

Uploading a Model Revision

It has to be possible to upload a new revision to an existing model. The new revision replaces the old revision depending on the users rights to access the revision.

TODO: would worth to explain a bit more the access to previous revisions here...

Prerequisites

To upload a new model revision the model must already exist in the database. Only logged-in users are allowed to upload new revisions. The user must have the right to upload new revisions for the model. Uploading a new model revision is done by uploading a new model file to an existing model.

The user has to specify a comment when uploading a new revision.

Validation

The model file is validated (against the specifications of it own format) before it is accepted and stored as a new revision. It is checked whether the file is a model file at all and can be parsed. Basic checks must be performed to ensure that the new model file is related to the existing previous revision.

Storing a Revision

The new model file is committed to the VCS. The absolute path can be constructed from information in the model (e.g. filename) and the file will locally be overwritten and committed to the VCS system, e.g. //svn ci//. The comment specified during the upload is used as the commit message.

Creating the Revision

A new DOM object has to be added for the VCS revision. The same fields as described in the Requirement Upload Model have to be set. The new revision object has to be added to the existing DOM object representing the model.

Access Control

Users get read access depending on their right to read future revisions of the model. If a user has such a right on the model he receives read access to the revision. The user who uploads the revision becomes the owner of the revision and has the right to delete this revision as long as there is no newer revision.

Annotation

The annotations of each new model file have to be extracted using a library for the specific format. This task can be performed in the background after the file has been saved to the VCS. The annotations are described in more detail in the annotation requirements specification.

Concurrent Access

It is possible that two collaborating users are uploading a new model revision at the same time. This can result in a race condition when user B updates the file in the filesystem before user A's changes are committed. The commit of user A would commit user B's changes and user B's commit would fail (nothing to commit). User A's changes are completely lost. To prevent such a problem the service method must lock write access either to a model or to the complete VCS. No two parallel threads may change the VCS.

In general each commit must include only the model file. E.g. in case of Subversion a //svn ci// without a specified changeset would commit all currently added or changed files. This is implementation specific but present for all VCS's.

Delete Model Revision

It should be possible to delete the latest revision of a model.

Limitations

VCS systems do not allow to delete revisions. A common practice is to revert a commit which simulates a deletion. The revision itself is still present in the revision history of the VCS. Deleting a revision would mean changing the history of the VCS and directly manipulating the database. Modern VCS do not allow at all to delete a commit as that would rewrite the history of the repository and by that would change the commit hash of each and every commit afterwards.

This means a revision cannot be deleted physically. A file once uploaded will always be at least visible to the administrators of the database.

Prerequisites

The user who wants to delete a revision is logged-in and has the right to delete the latest revision of the model. It is not possible to delete revisions, which are not the latest revision as the changes are also present in the latest revision.

Deletion

Due to the limitations of the VCS, it is not possible to really delete a model revision. Therefore it is not required to delete the DOM object. It is sufficient to set a flag "deleted" and to ignore all such flagged revisions in the service layer. If the model does not contain any other revision, the model itself is also flagged as "deleted" as it is not possible to have a model without revisions. For the same reasons as discussed above a model is also not deleted from the VCS.

An administrator is able to restore a revision and a model by removing the deleted flag.

Delete Model

The owner (submitter) of a model should be able to delete the complete model.

Limitations

For deleting a complete model the same limitations apply as illustrated in the requirement for deleting a model revision.

Prerequisite

Only an owner is allowed to delete a complete model if and only if he has deletion right on the model. The right to delete a complete model is revoked as soon as the curation process begins.

Deletion

The deletion is performed in the same way as deleting all model revisions: the model is flagged as "deleted". The only difference is that also model revisions the user has not the right to delete, are deleted. The right to delete a model has preference over the right to delete a model revision.

An administrator is able to restore a deleted model by removing the deleted flag.

Collaboration

An owner of a model might grant read and write access to another user (collaborator). This collaborator is also able to view and download the model. If the owner granted write access, the collaborator is also allowed to upload new revisions of the model and annotate it.

Prerequisites

The owner of a model has the right to invite other users to read or write the model. The level of what can be granted to other users depends on the level of right the user currently has on the model. Rational: if the user does not have write access to the model (e.g. it is under curation) the user cannot grant write access to another user.

Granting Rights

Granting read access

The user can grant read access to single revisions, to all revisions or to all revisions including future revisions. A read right to a revision cannot be revoked as the user had once read access to it and by that might have collected all relevant information. The right to read future revisions can be revoked and is for example implicitly revoked by starting the curation.

Granting write access

The user can grant write access to the model. This means the collaborator gains the right to upload new model revisions. If the collaborator uploads a new revision he gains the normal rights on the revision as described in the Requirement to upload model revisions.

Revoking Rights

Revoking read access

An owner is only able to revoke read access for future revisions. The right to read existing revisions cannot be revoked as illustrated in the discussion on Granting read access. The user must have the right to read future revisions to revoke that right.

Revoking write access

An owner is able to revoke write access to the model. Existing revisions uploaded by the collaborator are not affected by revoking the right as the collaborator still has read access. The user must have the right to write revisions to revoke that right.

Transferring Ownership of Model

In case that the owner of a model ends his work on the model before the curation process started he should be allowed to transfer the complete ownership to a collaborator of the model in question.

Prerequisite

The user is owner of the model and the model state is not "under curation" or "published". The user the ownership should be transferred to has to be a collaborator of the model.

Access Control

Transferring the ownership means moving access rights from the owner to the new "owner". This includes * Write access (if not already granted to the new owner) * Delete model * Start curation * Invite other users for collaboration

All these rights are revoked from the previous owner.

Ownership

The transfer of ownership is only handled via the access control list. The actual linked owner from revision and model are unchanged. The process of transferring ownership can only be reverted by a new transfer from new owner to previous owner.

Begin Curation

An owner of the model must be able to start the curation process. The curators of the running instance have to be informed and have to gain the right to upload new revisions to the model, annotate it and add additional files and comments.

Prerequisites

The owner of the model has the right to begin the collaboration and the model is not in state "under curation" or "published". There has to be at least one user in the instance who is a curator.

Access Control

The begin of curation requires changes to the ACL of the model. Write access to the model (upload new model revision) has to be revoked for each user of the model, except the curators. The right to delete revisions or the complete model has to be revoked from all users. This implicitly ends collaboration on write access. The right to read future revisions and write to the model has to be passed to the group of curators.

Curation

The begin of curation sets the model state "under curation". The access control has to be altered as described above. The start of curation cannot be reverted by a user (only by a curator by rejecting the curation).

Notification

The curators need to be informed that a model has been set under curation. See Requirement specification on Notification.

Rejecting Curation

A curator has to be able to reject a model for curation. The owner needs to be informed and needs to get back write access, so that he can upload a new version and launch the curation process again.

Prerequisites

The curation process has been started by the owner of a model and no curator has uploaded a new revision of the model.

Access Control

The altering of the ACL which has been performed for starting the curation process has to reverted where possible. The information who had write access to the model is not known any more so write access can only be given to the owner (identified by the right to start curation) of the model. Read access to future revisions is also only passed to the owner. If the owner wants other users to collaborate on the model again, he has to grant the rights.

The right to read and write to the model is revoked from the curator group.

Rejecting

The model state is set back from "under curation" to "unpublished" and the ACL is altered as described above. The curator has to state a reason why he is rejecting the curation. This reason has to be passed to the owner of the model in a notification.

If the model was initially submitted by a non logged user, there should be a way to notify the submitter.

Publish Model

A curator can publish a model he has write access to (curation has been launch by the owner). The model becomes publicly available. The curator is still able to upload new revisions of the model which are not shown to the user. The curator has to explicitly publish such a revision again.

Prerequisite

The curation of model has been started and the model has not yet been published. The process is performed by a member of the curator group.

Publish

The state of the model is set to "published". The rights to the model are unchanged, that is the curators keep their rights on the model. The latest revision becomes publicly readable by setting the appropriate rights. Future revisions will not become publicly available automatically.

If a curator wants to publish a future created revision, he has to publish that revision.

Access Control

The right to read is added for all users (role user and role visitor) to the latest revision of the model. This makes the model implicitly available to search, download, etc.