Use Cases

Actors

Here we describe the different roles a user can assume in documented use cases (see below for their in-depth description).

Visitor

Anyone who accesses the system without being logged in is a visitor, i.e. an anonymous user.

Possible actions: * accesses the available models, without prior knowledge of its identifier or other information * accesses the available models from a given category * retrieves models with specific criteria from the repository * gains more knowledge about a given model * downloads a given model in a specific format * runs simulations on a model using specific basic parameters * creates an account on the instance * submits a new model to the repository * checks the state of a model (under curation, published)

Owner

Anyone who submits a model while being logged in is the owner of the submitted model. If the model has been submitted by a visitor (which should only be possible in instances where curators are present), the owner of the model is the group of curators.

Possible actions: * uploads a new version of a model * annotates a model * transfers his model over to curation process * uploads a model to the repository * invites collaborator(s) * delete a model, if still private (not transferred to curation)

Collaborator

Anyone who is given access to an unpublished/non-public/private model is a collaborator. Login required.a

Possible actions: * uploads a new version of a model submitted by someone else * annotates a model of someone else

Reviewer

Anyone who needs to review a paper describing a (not yet published) model is a reviewer. Login is required.

Possible actions: * has read access to a model for a given period of time set * can see the status of previously reviewed models

Curator

Anyone who is carrying out the curation process on models from themselves or other people (who transferred their models to curation) and publishes the resulting models is a curator. The curation process consists of checking that the model corresponds to the reference publication and reproduces the results described. This might involved slightly changing the model structure and parameters, as well as attach some comments and files to the model (curation figure, simulator's files, SED-ML files, ...). Usually the curator works for the institution running the instance. Login is required.

Possible actions: * curates and annotates models coming from submitters and/or collaborators * attaches documents and comments to these models * publishes these models

Administrator

Anyone who maintains a Jummp instance is an administrator. Login is required.

Possible actions: * manages the releases of models * has access to the usage statistics TODO: this should rely on an external infrastructure * has access to the content statistics * has access to the contribution statistics * can approve (or not) the creation a new user account * all actions available to any other kind of actors

Abstract Actors

The following roles are only for annotation purposes. A user cannot be a submitter or contributor when logged in the system.

Submitter

Anyone who submits a model is considered a submitter of this particular model. If possible, this information will be added to the model annotation.

Contributor

Anyone who contributed to a model is a contributor. A contribution to a model is defined by: making a change to the model structure (update-model) or to the annotations (annotate-model). The submitter, any collaborators and curators who should be automatically added to the model annotations as "contributors".

Use cases

Each use case is described by these attributes: name (all lowercase verb-noun combination), summary, actors, pre(condition), input, output, post(condition), ui (user interface/interaction)

Here is a template for copy'n'edit.

|name |verb-noun| |summary | | |actors | | |pre | | |input | | |output | | |post | | |ui | |

Some explanations: * Actors should only list the typical users of this use case (in singular form) to highlight for whom this use case was written. For instance, we do not mention visitor if the use case requires login; we do not mention administrator even though he has access to all data and functionalities, if the use case was written mainly for different actors. * Input and output are really just that: logical data that needs to be passed back and forth. This implies that data not connected to a user input is also listed. When it makes sense we indicate where data come from, e.g. text input fields, previous selections, etc. * User interface/interaction tries to make the use case more concrete by giving an idea how a user would select or enter data, or which navigation choices are offered (without going into details).

Please break down the use cases such that all conditions and the resulting steps become clear. For instance, if model is invalid, error page is displayed, postcondition is unchanged, etc.

welcome-user

|name |welcome-user |summary | shows summary information depending on user |actors | all |pre | n/a |input | n/a |output | lists number of accessible models, number of public models\ only for logged-in user: submit-model button\ quick search box\ quick access to most important features |post | n/a |ui | click on buttons to search-models, login-user, submit-model

list-models

|name |list-models |summary | lists all the models, which the current user has access |actors | all |pre | n/a |input | n/a |output | provides a list of models |post | n/a |ui | each model has a hyperlink which allow access to the show-model action

list-models-from-category

|name |list-models-from-category |summary | lists all the models from a given category, which the current user has access |actors | all |pre | n/a |input | one or more categories, tags or labels + the operator to be used to compile the request (mainly and/or) |output | provides a list of models |post | n/a |ui |

login-user

|name |login-user |summary | user logs in to be authorised, i.e. granted access to models and web pages |actors | visitor |pre | user is not logged in |input | text input of account, password\ button log in |output | redirect to desired/intercepted page\ (in case the user followed a link which requires login) |post | session stores user and authorisations |ui | type in account, password\ click on button to continue\ password recovery option

logout-user

|name |logout-user |summary | logs out the current user |actors | any logged in users |pre | user is logged in |input | logout button |output | redirect to front page, with logout confirmation message |post | cleans session |ui |

search-models

|name |search-models |summary | searches and lists all models the current user has access to |actors | all |pre | user must be logged in to have access to non-public models |input | visitor can only retrieve public model\ submitter/collaborator/reviewer/curator can retrieve\ public, owned, accessible models |output | table of models (can be empty)\ text input of search criteria |post | n/a |ui | click on table header to sort table\ sort by latest update (default), name, model id, first author\ click on model name, model id to show-model\ click on text input to change search criteria\ click on button to search-models \It would be great if the columns to be displayed could be customised by the user (for logged in ones)\ button to return to the search results after the user clicked on one

show-model

|name |show-model |summary | shows a model in potentially tabbed view to visualise its content |actors | all |pre | n/a |input | model id |output | potentially tabbed view (can be inspired by BioModels V3 software) |post | n/a |ui | click on tab to show it

download-model

|name |download-model |summary | allows the download of a given model |actors | all |pre | n/a |input | model id, format |output | downloadable file of the requested model in the requested format |post | n/a |ui | browser window asking whether to open or save the file

share-model

|name |share-model |summary | provides access (read or write) to a model for another user |actors | submitter (collaborator?) |pre | n/a |input | model id, collaborator username, rights (read or write) |output | | |post | n/a |ui | auto-complete user selection field

show-model-status

|name |show-model-status |summary | shows the status of a model |actors | all (not for private models) |pre | n/a |input | model id |output | displays some basic info about the model: private, public, under curation, waiting publication, published, ... |post | n/a |ui | simple display page

simulate-model

|name |simulate-model |summary | simulates a model |actors | all |pre | n/a |input | model id, basic parameters |output | reaction graph (picture), raw data |post | n/a |ui | selection of the species to simulate and basic parameters

submit-model

|name |submit-model |summary | uploads a model from the local filesystem to the repository |actors | visitor, submitter, curator |pre | n/a |input | user\ model file (SBML or other supported formats)\ only for published model:\ - one of pubmed id, doi, url OR journal, title, authors, affiliation, abstract\ also for work-in-progress model:\ - model name (can be automatically retrieved from the file,\ if the submitted model is encoded in SBML)\ - comment\ submit button\ current date (automatically set: will be the submission and last update date) |output | summary of the submission (success or failure) |post | DB and RCS store new model DOMs and file |ui | click on text fields to enter:\ - publication info: PMID, DOI or URL (optional, c.f. work-in-progress models)\ - use service like CiteXplore to retrieve all publication details (provide a\ form in case of failure)\ - model details\ give feedback to user if a check fails, e.g. model is not valid

update-model

|name |update-model |summary | replaces a model with a newer version |actors | owner, collaborator, curator |pre | model must be already submitted to the system (c.f. submit-model) |input | model file\ comment\ update button\ current date (automatically set: will be date of last update) |output | summary of the submission (success or failure)\ notification to curator and submitter (if action has been performed\ by the submitter) |post | same as submit-model |ui | click on text field to enter comments\ click on button to update

delete-model

|name |delete-model |summary | deletes a model |actors | submitter, curator, administrator\ - submitter can only delete private/uncurated models\ - curator can only delete models under curation\ - administrator can do both |pre | model must be already submitted to the system (c.f. submit-model)\ user must either own the model, or be the administrator |input | user\ model\ text input of comment |output | notification to curator |post | DB and RCS still contain the model for a limited time, but it is not visible\ to the user; only the administrator can see it (and possibly undo the deletion) |ui | |

annotate-model

|name |annotate-model |summary | annotates a model |actors | submitter, curator, collaborator |pre | model must be already submitted to the system (c.f. submit-model) |input | model identifier |output | model is (partially) annotated |post | syntax checked |ui | allow the creation/edition/removal of annotations (no change to the model structure)

transfer-to-curation

|name |transfer-to-curation |summary | transfers a private model to the curation pipeline (where curators will check it, simulate it, potentially annotate it and finally, if all criteria are met, publish it) |actors | owner |pre | model must be already submitted to the system (c.f. submit-model) |input | model identifier |output | | |post | | |ui | simple button "transfer"

curate-model

|name |curate-model |summary | curates a model |actors | curator |pre | model must be already submitted to the system (c.f. submit-model) |input | model identifier |output | model is (partially) curated |post | | |ui | convert model to newest format\ add simulation results (comments, screenshots, simulator files)

attach-document

|name |attach-document |summary | attach a document to a model |actors | curator, submitter, collaborator |pre | | |input | model id, additional file |output | | |post | file uploaded in the filesystem and recoded in the database |ui | |

add-curation-comment

|name |add-curation-comment |summary | adds comments/info to a model |actors | curator |pre | model under curation |input | model id |output | | |post | info added to the database and model file (if possible) |ui | |

register-user

|name |register-user |summary | creates an user account |actors | visitor |pre | email address not yet in DB |input | full name\ institution\ email address |output | user and administrator receive notification |post | the creation of the account needs to be approved by a administrator |ui | |

approve-account-creation

|name |approve-account-creation |summary | approves the creation of an account to access the instance |actors | administrator |pre | register-user |input | | |output | user and administrator receive notification |post | account created in the user database |ui | simple yes/no dialogue

check-model-state

|name |check-model-state |summary | checks the state of a model in the public branch of the repository |actors | all |pre | | |input | model id |output | state of the model (under curation, waiting for reference paper to be published, published, ...) |post | | |ui | |

publish-model

|name |publish-model |summary | makes a model publicly available |actors | curator |pre | model is under curation |input | | |output | | |post | model is public\ can occur in search results of visitor |ui | |

release-models

|name |release-models |summary | releases public model as a downloadable archive |actors | curator, administrator |pre | models are flagged as public |input | | |output | tar-ball of models |post | | |ui | |

generate-usage-stats

|name |generate-usage-stats |summary | generates the statistics of the usage and access to the resource |actors | administrator |pre | | |input | | |output | show the number of users accessing the resource per day/month/year, ... |post | | |ui | |

generate-content-stats

|name |generate-content-stats |summary | generates some statistics of the content of the repository (this should be separated between public and private part): total number of models, total number of annotations, average numbers, tottal number of reactions, ... Numbers presenting the evolution of the repository from releases to releases should also be displayed. |actors | administrator |pre | | |input | | |output | display with the various numbers and diagrams of the evolution of the content of the repository over time |post | | |ui | |

generate-contribution-stats

|name |generate-contribution-stats |summary | generates the statistics of the contributions to the repository content (this should be separated between public and private part). For example it would show the activity of the various users (specially the curators) over time and over models. |actors | curator, administrator |pre | models are flagged as public |input | | |output | general contributions, contributions per model, contributions per user, ... |post | | |ui | |