diff --git a/docs/dev/README.md b/docs/dev/README.md index fe22859f..6049d884 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -34,3 +34,4 @@ Only Committers on the PASS Eclipse project are able to make changes to the code * [Docker Dependencies](integration-test-docker-dependencies.md) - Integration Testing and Docker Dependencies * [Components](components.md) - PASS project components * [Releasing PASS](release.md) - Releasing the PASS project +* [Data model](model/README.md) - Data model of the PASS project diff --git a/docs/dev/model/Deposit.md b/docs/dev/model/Deposit.md new file mode 100644 index 00000000..345d2cd0 --- /dev/null +++ b/docs/dev/model/Deposit.md @@ -0,0 +1,39 @@ +# Deposit + +A [Submission](Submission.md) can have multiple Deposits, each to a different [Repository](Repository.md). This entity describes the interaction of PASS with a target [Repository](Repository.md) for an individual [Submission](Submission.md) with the purpose of satisfying one or more [Policies](Policy.md). + +| Attribute | Type | Description | +| ---------------- | ------ | ------------- +| id* | String | Autogenerated identifier of object. | +| depositStatusRef | String | A URL or some kind of reference that can be dereferenced, entity body parsed, and used to determine the status of Deposit | +| depositStatus* | String | Status of deposit ([_see list below_](#deposit-status-options)) | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| submission* | To One | [Submission](Submission.md) | Submission this Deposit is a part of | +| repository* | To One | [Repository](Repository.md) | Repository being deposited to | +| repositoryCopy | To One | [Repository Copy](RepositoryCopy.md) | Repository Copy for this Deposit | + +*required + +## Deposit status options + +These are the possible statuses for a Deposit in the order they could occur. Note that not all repositories will go through every status. + +
+
Intermediate status
+
A Deposit with an intermediate status indicates that the processing of the Deposit is not yet + complete. At some indeterminate point in the future, the status may be updated to a terminal + state. +
+
Terminal status
+
A Deposit with a terminal status indicates that the processing of the Deposit is complete. +
+
+ +| Value | State | Description | +| --------- | ----- | --- | +| submitted | Intermediate | PASS has sent a package to the target [Repository](Repository.md) and is waiting for an update on the status | +| rejected | Terminal | The target [Repository](Repository.md) has rejected the Deposit | +| failed | Intermediate | A failure occurred while performing the deposit, it may be re-tried later. | +| accepted | Terminal | The target [Repository](Repository.md) has accepted the [Files](File.md) into the repository and they are pending publication if not published already | diff --git a/docs/dev/model/File.md b/docs/dev/model/File.md new file mode 100644 index 00000000..9aeaf366 --- /dev/null +++ b/docs/dev/model/File.md @@ -0,0 +1,30 @@ +# Files + +Files are associated with a [Submissions](Submission.md) to be used to form [Deposits](Deposit.md) into [Repositories](Repository.md) + +| Attribute | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| name* | String | File name, defaults to filesystem.name | +| uri* | String | Relative URI to the file servive which will return the bytestream | +| description | String | Description of file provided by [User](User.md) | +| fileRole | String | Role of the file ([_see list below_](#file-role-options)) | +| mimeType | String | Mime-type of file | + + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| submission* | To One | [Submission](Submission.md) | Submission the File is a part of | + +*required + +## File role options + +Status options for grant + +| Value | Description | +| ------------- | ------------- | +| manuscript | Author accepted manuscript | +| supplemental | Supplemental material for the [Publication](Publication.md) | +| figure | An image, data plot, map, or schematic | +| table | Tabular data | diff --git a/docs/dev/model/Funder.md b/docs/dev/model/Funder.md new file mode 100644 index 00000000..f9759897 --- /dev/null +++ b/docs/dev/model/Funder.md @@ -0,0 +1,16 @@ +# Funder + +Funder / sponsor of a [Grant](Grant.md). + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| name* | String | Funder name | +| url | String | Funder URL | +| localKey | String | Local key assigned to the funder within the researcher's institution to support matching between PASS and a local system. The value is in the form of : `domain:type:value`. For a funder at JHU, an example would be`"johnshopkins.edu:funder:8675309"` | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| policy | To One | [Policy](Policy.md) | Policy associated with the Funder | + +*required diff --git a/docs/dev/model/Grant.md b/docs/dev/model/Grant.md new file mode 100644 index 00000000..070a1c9b --- /dev/null +++ b/docs/dev/model/Grant.md @@ -0,0 +1,33 @@ +# Grant + +Grants are imported from the institutional Grant system (FIBI in the case of JHU). They are associated with the Grant's PIs via their [User](User.md) records. Users of PASS can assign the Grants associated with them to [Submissions](Submission.md). + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| awardNumber* | String | Award number from funder | +| awardStatus | String | Status of award ([_see list below_](#status-options)) | +| localKey | String | A local key assigned to the Grant within the researcher's institution to support matching between PASS and a local system. The value is in the form of : `domain:type:value`. For a grant at JHU, an example would be`"johnshopkins.edu:grant:8675309"` | +| projectName* | String | Title of the research project | +| awardDate* | String | DateTime the grant was awarded | +| startDate | String | DateTime the grant started | +| endDate | String | DateTime the grant ended | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| primaryFunder* | To One | [Funder](Funder.md) | Funder that is the original source of the funds. This will often be the same as directFunder. | +| directFunder* | To One | [Funder](Funder.md) | Funding organization from which funds are directly received. This will often be the same as primaryFunder. | +| pi* | To One | [User](User.md) | User who is the Principal investigator | +| coPis | To Many | [[User](User.md)] | Users who are the co-principal investigators | + +*required + +## Status options + +Status options for grant + +| Value | Description | +| ------------- | ------------- | +| active | Grant currently active | +| pre_award | Award not yet received | +| terminated | Grant period is complete | diff --git a/docs/dev/model/Journal.md b/docs/dev/model/Journal.md new file mode 100644 index 00000000..2f438e1a --- /dev/null +++ b/docs/dev/model/Journal.md @@ -0,0 +1,24 @@ +# Journal + +A Journal is associated with a [Publication](Publication.md). In some cases, the Journal may be important for determining whether the [User](User.md) needs to manually create a [Submission](Submission.md) through PASS or whether the publisher has a pre-existing arrangement with the target [Repository](Repository.md). Specifically, in the case of the National Institutes of Health Public Access Policy, many Journals already make arrangements to submit the author's accepted manuscript to PubMed Central directly. + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| journalName* | String | Name of the journal | +| issns | String[] | Journal ISSNs - Elements are of the form type:value, where type is one of Online or Print, and value is the usual ISSN value xxxx-xxxx. Examples would be Online:1234-5678 and Print:9876-5432. When a type for an ISSN is not known, it should be stored with an empty type (for example :2468-1357).| +| nlmta | String | National Library of Medicine Title Abbreviation | +| pmcParticipation | String | This field indicates whether a journal participates in the NIH Public Access Program by sending final published article to PMC. If so, whether it requires additional processing fee ([see list below](#pmc-participation-options)) | + +*required + +## PMC Participation options + +These are the possible submission methods relating to PMC deposits. A full description of these methods can be found on the [NIH public access website](https://publicaccess.nih.gov/submit_process.htm) + +| Value | Description | +| ------------- | ------------- | +| A | PMC deposit route A. Journals automatically post the paper to PMC | +| B | PMC deposit route B. Authors must make special arrangements for some journals and publishers to post the paper directly to PMC | +| C | PMC deposit route C. Authors or their designee must submit manuscripts to NIHMS | +| D | PMC deposit route D. Some publishers will submit manuscripts to NIHMS | diff --git a/docs/dev/model/Policy.md b/docs/dev/model/Policy.md new file mode 100644 index 00000000..b01e7254 --- /dev/null +++ b/docs/dev/model/Policy.md @@ -0,0 +1,17 @@ +# Policy + +A Policy describes the access compliance requirements for a specific [Funder](Funder.md) or Institution. These Policies are used to determine which [Repositories](Repository.md) a [Publication](Publication.md) should be [submitted](Submission.md) to in order to be in compliance with its associated [Grants](Grant.md) and the User's institutional policies. + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| title* | String | Title of policy e.g. "NIH Public Access Policy" | +| description | String | Several sentence description of policy | +| institution | String | URI identifying the Institution whose Policy this is (unused) | +| policyUrl | String | URL to the actual policy on the policy-owner's page | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| repositories* | To Many | [Repositories](Repository.md) | Repositories that satisfy this policy | + +*required diff --git a/docs/dev/model/Publication.md b/docs/dev/model/Publication.md new file mode 100644 index 00000000..75b2711f --- /dev/null +++ b/docs/dev/model/Publication.md @@ -0,0 +1,18 @@ +# Publication +Publication metadata to be associated with one or more [Submission](Submission.md) + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| title* | String | Title of work represented by Submission e.g. the title of the article | +| publicationAbstract | String | Abstract for work represented by Submission | +| doi | String | DOI of item being submitted, if available | +| pmid | String | PMID of item being submitted, if available | +| volume | String | Volume of journal that contains item (if article) | +| issue | String | Issue of journal that contains item (if article) | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| journal | To One | [Journal](Journal.md) | Journal the publication is part of (if article) | + +*required diff --git a/docs/dev/model/README.md b/docs/dev/model/README.md new file mode 100644 index 00000000..959d2bba --- /dev/null +++ b/docs/dev/model/README.md @@ -0,0 +1,37 @@ +# PASS Data Model + +The PASS data model is represented using (JSON API)[https://jsonapi.org/]. + +In this project you will find +* [Model Objects](#model-objects) - a description of the fields for each object in the model +* [Model Diagram](#model-diagram) - a diagram showing the relationships between each object + +## Model Objects +The data model consists of the following components. Each is documented in full on its own page, you can see all of these pages in the [model](/docs/dev/model/) folder. + +* [Deposit](Deposit.md) +* [File](File.md) +* [Funder](Funder.md) +* [Grant](Grant.md) +* [Journal](Journal.md) +* [Policy](Policy.md) +* [Publication](Publication.md) +* [Repository](Repository.md) +* [RepositoryCopy](RepositoryCopy.md) +* [Submission](Submission.md) +* [SubmissionEvent](SubmissionEvent.md) +* [User](User.md) + +## Model Diagram + +![data model](pass_data_model.png) + +## Notes + +### Identifiers + +An object is uniquely identified by a tuple consiting of its id attribute and its type. + +### DateTime attributes + +DateTime attributes are strings formatted as per the Java DateTimeFormatter with pattern `yyyy-MM-dd'T'HH:mm:ss.SSSX`. diff --git a/docs/dev/model/Repository.md b/docs/dev/model/Repository.md new file mode 100644 index 00000000..c77cb017 --- /dev/null +++ b/docs/dev/model/Repository.md @@ -0,0 +1,39 @@ +# Repository + +A Repository is the target of a [Deposit](Deposit.md). It is a platform where [copies](RepositoryCopy.md) of [publications](Publication.md) can be [deposited](Deposit.md) in order to comply with [Funder](Funder.md) and institutional access [policies](Policy.md). + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| name* | String | Name of repository e.g. "PubMed Central" | +| description | String | Several sentence description of repository | +| url | String | URL to the homepage of the repository so that PASS users can view the platform before deciding whether to participate in it | +| agreementText | String | The legal text that a `submitter` must agree to in order to submit a publication to this Repository | +| formSchema | String | _(deprecated)_ Stringified JSON representing a form template to be loaded by the front-end when this Repository is selected | +| integrationType | String | Type of integration that PASS has with the Repository ([_see list below_](#integration-type-options)) | +| repositoryKey | String | Key that is unique to this Repository instance within PASS. Used to look up the Repository when its URI is not available (e.g. prior to the creation of this Repository resource in Fedora). See below for a [_list of currently used keys_](#repository-key-values). | +| schemas | String[] | Contains an array of relative URIs that the pass-core metadata service can resolve to JSON schema documents describing the repository's metadata requirements | + +*required + +## Integration type options + +These are the possible types of integration a Repository can have with PASS. + +| Value | Description | +| --------------- | ------------- | +| full | PASS can make [Deposits](Deposit.md) to this Repository, and will received updates about its status | +| one-way | PASS can make [Deposits](Deposit.md) to this Repository but will not automatically receive updates about its status | +| web-link | A deposit cannot automatically be made to this Repository from PASS, only a web link can be created. | + +## Repository key values + +These are the repository keys currently used in PASS. This list will grow as more repositories are supported. + +| Value | Repository name | +| --------------- | ------------- | +| pmc | [PubMed Central](https://www.ncbi.nlm.nih.gov/pmc/) | +| jscholarship | [Johns Hopkins JScholarship](https://jscholarship.library.jhu.edu/) | +| eric | [Education Resources Information Center](https://eric.ed.gov/) (ERIC) | +| dec | [Development Experience Clearinghouse](https://dec.usaid.gov/dec/) (DEC) | +| dash | [Harvard DASH](https://dash.harvard.edu/) | diff --git a/docs/dev/model/RepositoryCopy.md b/docs/dev/model/RepositoryCopy.md new file mode 100644 index 00000000..3c7483f9 --- /dev/null +++ b/docs/dev/model/RepositoryCopy.md @@ -0,0 +1,29 @@ +# Repository Copy + +A Repository Copy represents a copy of a [Publication](Publication.md) that exists in a target [Repository](Repository.md). The Repository Copy either (1) was the result of an accepted [Deposit](Deposit.md) from PASS, in which case there would be a link to the Copy from the related Deposit record, or (2) was created outside of PASS by some other process. In this second instance, the PASS system stores the information to help determine whether a Publication is already compliance. + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| externalIds | String[] | IDs assigned to this entity by the target repository | +| copyStatus* | String | Status of the copy in the external repository's workflow ([_see list below_](#copy-status-options)) | +| accessUrl | String | URL to access the item in the repository, could allow Users to see the final result | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| publication* | To One | [Publication](Publication.md) | Publication that this is a copy of | +| repository* | To One | [Repository](Repository.md) | Repository being deposited to | + +*required + +## Copy status options + +These are the possible statuses for a Deposit in the order they could occur. Note that not all repositories will go through every status. + +| Value | Description | +| --------------- | ------------- | +| accepted | The target [Repository](Repository.md) has indicated that the Deposit has been accepted| +| in-progress | The target [Repository](Repository.md) is processing the files | +| stalled | The target [Repository](Repository.md) has detected a problem that has caused the progress to stall. This will likely require some direct interaction with the repository to re-initiate the process. Examples include, when there are incorrect files, or when a user did not respond to a validation request in a resonable time. | +| complete | The target [Repository](Repository.md) has accepted the files, and publication is pending if not already complete | +| rejected | The target [Repository](Repository.md) has rejected the files. | diff --git a/docs/dev/model/Submission.md b/docs/dev/model/Submission.md new file mode 100644 index 00000000..79e66825 --- /dev/null +++ b/docs/dev/model/Submission.md @@ -0,0 +1,62 @@ +# Submission +In order to comply with [funder](Funder.md) and institutional access [policies](Policy.md), [Users](User.md) may be required to submit their [Publications](Publication.md) to one or more [Repositories](Repository.md). A Submission is associated with one `submitter` and one Publication. It encapsulates a User satisfying one or more Policies relevant to their Publication by either (1) [Deposits](Deposit.md) initiated in PASS or (2) [Copies](RepositoryCopy.md) of the publication that already exist in the target repositories. The User can start a Submission by describing their Publication and attaching relevant [Grants](Grant.md) to it. The PASS system will use this information to determine which policies apply, and will help the User send the Publication out to the Repositories that will fulfill them. + +Note that the source of a Submission record is not always a PASS User. In some instance, Submissions are created as a result of an import process designed to ensure that the User can see data relevant to their compliance with Policies in a uniform way. + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id | String | Autogenerated identifier of object | +| metadata | String | Stringified JSON representation of metadata captured by the relevant repository forms. This will hold extended metadata relevant to the repositories selected in the Submission workflow. It may include fields such as embargoEndDate, embargoText, pmid, and anything else required by specific repositories etc. | +| source* | String | Indicates whether the record came from outside of PASS as an import, or was created through the system ([_see list below_](#source-options)) | +| submitted* | boolean | When true, this value signals that the Submission will no longer be edited by the User. It indicates to Deposit services that it can generate Deposits for any Repositories that need one. This becomes "true" when the User clicks "submit" in the UI. For Submissions generated by loader processes this value will be false when the User must complete the Submission, or true if it is merely pointing to an existing copy of the Publication in a Repository. | +| submittedDate | String | DateTime the record was submitted by the [User](User.md) through PASS | +| submissionStatus* | String | The current status of the Submission, derived from the [Deposit](Deposit.md) status(es), [RepositoryCopy](RepositoryCopy.md) status(es) and the `eventType` of the most recent [SubmissionEvent](SubmissionEvent.md) ([_see list below_](#submission-status-options)) | +| aggregatedDepositStatus | String | Current combined status of Deposits, utilized by Deposit Services. The initial status of a new Submission will be "not-started" ([_see list below_](#aggregated-deposit-status-options)) | +| submitterName | String | Name of submitter. This field is used when a preparer nominates a submitter that is not yet a PASS [User](User.md). The name is temporarily stored for use in communications with the submitter until a `User.id` is available. Once there is a URI for `submitter`, the `submitterName` should be null. | +| submitterEmail | String | Email of submitter, formatted as a URI e.g. `mailto:first.last@example.com`. This field is used when a preparer nominates a submitter that is not yet a PASS [User](User.md). The email value is temporarily stored for use in communications with the submitter until a `User.id` is available. Once there is a URI for `submitter`, the `submitterEmail` should be null. | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| publication* | To One | [Publication](Publication.md) | Publication represented in this Submission | +| repositories* | To Many | [Repository](Repository.md) | Repositories that this Publication will exist in when the Submission is completed | +| submitter | To One | [User](User.md) | User responsible for submitting the Submission. The User will be the individual who either (a) created this Submission through PASS, thus claiming responsibility; (b) was designated as `submitter` by a `preparer`; or, (c) has been assigned the role based on their being PI of an associated [Grant](Grant.md). When this value is null, it indicates there is not yet a User record for the designated submitter. In this instance there should be a value in `submitterName` and `submitterEmail`. | +| preparers | To Many | [User](User.md) | Users who prepared, or who could contribute to the preparation of, the Submission. Preparers can edit the content of the Submission (describe the [Publication](Publication.md), add [Grants](Grant.md), select [Repositories](Repository.md)) but cannot approve Repository agreements, or submit the publication - these tasks must be performed by the `submitter`. | +| grants | To Many | [Grant](Grant.md) | Grants that are associated with the User and are relevant to the Publication being submitted | +| effectivePolicies | To Many | [Policy](Policy.md) | Policies that will be satisfied via deposit through PASS | + +*required + +## Submission status options + +Below are the possible values for the `Submission.submissionStatus` field. They are listed in the order they would typically occur, and with an indication of the arrangement of the data that will result in this status. Note that not all Submissions will go through every status. + +| Value | Description | Data determining status | +| ------------------------ | ------------- |----------------------| +|draft|Newly created Submissions _by the UI_ will have this status by default. Only unsubmitted Submissions should have this status. Submissions created by other processes may use a different status.|Default status for Submissions newly created by a user interacting with the UI. +| manuscript-required | When the PASS system identifies a need for a User to submit a Publication to a particular Repository, it will create a new Submission record with this status in order to prompt the User to provide the document and complete the Submission. For example, PASS imports information from the NIH Public Access Compliance system, which contains information about out of compliance publications - these will appear in the PASS system for PI of the corresponding Grant with the label `manuscript-required`. | New Submissions of this type are created with this status already set | +| approval-requested | A Submission was prepared by a `preparer` but now needs the `submitter` to approve and submit it or provide feedback. | `Submission.submitted=false` and the most recent [SubmissionEvent](SubmissionEvent.md) has `eventType=approval-requested`. | +| changes-requested | A Submission was prepared by a `preparer`, but on review by the `submitter`, a change was requested. The Submission has been handed back to the `preparer` for editing. | `Submission.submitted=false` and the most recent [SubmissionEvent](SubmissionEvent.md) has `eventType=changes-requested`. | intermediate | +| cancelled | A Submission was prepared and then cancelled by the `submitter` or `preparer` without being submitted. No further edits can be made to the Submission. | `Submission.submitted=false` and the most recent [SubmissionEvent](SubmissionEvent.md) has `eventType=cancelled`. | +| submitted | The submit button has been pressed through the UI. From this status forward, the Submission becomes read-only to both the `submitter` and `preparers`. This status indicates that either (a) the Submission is still being processed, or (b) PASS has finished the Deposit process, but there is not yet confirmation from the Repository that indicates the Submission was valid. Some Submissions may remain in a `submitted` state indefinitely depending on PASS's capacity to verify completion of the process in the target [Repository](Repository.md). | `Submission.submitted=true`, and the Publication associated with the Submission is in a positive status for each Repository i.e. it's `RepositoryCopy.copyStatus` is not `rejected` or `stalled`, and in the absence of a RepositoryCopy, the `Deposit.depositStatus` is not `rejected`. | +| needs-attention | Indicates that a [User](User.md) action may be required outside of PASS. The Submission is stalled or has been rejected by one or more [Repository](Repository.md) | The `copyStatus` of one or more [RepositoryCopy](RepositoryCopy.md) for the Submission is `rejected` or `stalled`. In the absence of a `RepositoryCopy`, the [Deposit](Deposit.md) for that Repository has a `depositStatus` of `rejected`. To be clear, a positive status on the RepositoryCopy can override a negative status on the Deposit. | +| complete | The target repositories have all received a copy of the Submission, and have indicated that the Submission was successful. | There is a RepositoryCopy with `repoCopyStatus=complete` for each of the target repositories. | + +## Aggregated Deposit status options +These are the possible statuses for a Submission's aggregatedDepositStatus field. They are listed in the order they would occur. Note that not all Submissions will go through every status. + +| Value | Description | +| -------------------------- | ------------- | +| not-started | No [Deposits](Deposit.md) have been initiated for the Submission | +| in-progress | One or more [Deposits](Deposit.md) for the Submission have been initiated, and at least one has not reached a status of "accepted" or "rejected" | +| failed | One or more [Deposits](Deposit.md) for the Submission has a status of "failed" | +| accepted | All related [Deposits](Deposit.md) for the Submission have a status of "accepted" | +| rejected | One or more [Deposits](Deposit.md) for the Submission has a status of "rejected" | + +## Source options + +These are the possible sources of a Submission + +| Value | Description | +| ------------- | ------------- | +| pass | Submission record was created or submitted via the PASS user interface | +| other | Submission record was automatically created by harvesting and ingesting from a 3rd party service e.g. NIHMS | diff --git a/docs/dev/model/SubmissionEvent.md b/docs/dev/model/SubmissionEvent.md new file mode 100644 index 00000000..a76ad133 --- /dev/null +++ b/docs/dev/model/SubmissionEvent.md @@ -0,0 +1,39 @@ +# SubmissionEvent +The SubmissionEvent model captures significant events that are performed by an agent and occur against a [Submission](Submission.md). In the current implementation, the agent will be a PASS [User](User.md). The definition of "significant" will evolve depending on which events are useful to capture in order to e.g. trigger notifications, or form an audit trail. The events that are currently deemed significant for capture are documented under [`eventType`](#event-type-options). + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| eventType* | String | The type of event ([_see list below_](#event-type-options)) | +| performedDate* | String | DateTime the event was performed by the [User](User.md) | +| performerRole | String | Role of the person performing the event ([_see list below_](#performer-role-options)) | +| comment | String | A comment relevant to the SubmissionEvent. For example, when a `changes-requested` event occurs, this might be added by the User through the UI to communicate what changes should be made. | +| link | String | A URI for a resource relevant to the SubmissionEvent. For example, when a `changes-requested` event occurs, this may contain an Ember application URL to the affected Submission. | + +| Relationship | Type | Target | Description | +| ---------------- | ------ | --------- | ----------- | +| performedBy* | To One | [User](User.md) | User responsible for performing the event | +| submission* | To One | [Submission](Submission.md) | Submission that the event relates to | + +*required + +## Event type options + +The following describes the types of events that might be recorded as SubmissionEvents. + +| Value | Description | +| ------------------------ | ------------- | +| approval-requested-newuser | A Submission was prepared by a `preparer` on behalf of a person who does not yet have a [User](User.md) record in PASS. The `preparer` is requesting that the `submitter` join PASS and then approve and submit it or provide feedback. | +| approval-requested | A Submission was prepared by a `preparer` who is now requesting that the `submitter` approve and submit it or provide feedback. | +| changes-requested | A Submission was prepared by a `preparer`, but on review by the `submitter`, a change was requested. The Submission has been handed back to the `preparer` for editing. | +| cancelled | A Submission was prepared and then cancelled by the `submitter` or `preparer` without being submitted. No further edits can be made to the Submission. | +| submitted | The submit button has been pressed through the UI. | + +## Performer role options + +The following describe the roles of people who might perform a SubmissionEvent. + +| Value | Description | +| ------------------------ | ------------- | +| preparer | An individual who can prepare a Submission on behalf of another User - select the Publication, Repositories, Files, and Grants - but cannot approve the Repository agreements or submit the record for Deposit. | +| submitter | An individual responsible for a Submission. A person with this role can do all of the tasks that a `preparer` can do, but also approve any Repository agreements and submit the record for Deposit. | \ No newline at end of file diff --git a/docs/dev/model/User.md b/docs/dev/model/User.md new file mode 100644 index 00000000..0fcab431 --- /dev/null +++ b/docs/dev/model/User.md @@ -0,0 +1,28 @@ +# User + +A User of the PASS system. This includes prefered person information that can be used to autopopulate [Contributor](Contributor.md) records + +| Field | Type | Description | +| ------------- | ------------- | ------------- | +| id* | String | Autogenerated identifier of object | +| username* | String | Unique login name used by User | +| firstName | String | First name(s) of User | +| middleName | String | Middle name(s) of User | +| lastName | String | Last name(s) of User | +| displayName | String | Name for display. Separate names may not be available, but a person should always at least have a display name. | +| email | String | Contact email for User | +| affiliation | String[] | The affiliation(s) of the User with their institution, for example `STAFF@inst.edu`. An institution may have multiple organizational units, and a User may have a different affiliation with any given OU. A User having an affiliation with multiple OUs in an institution would have multiple values, for example `FACULTY@medicine.inst.edu` and `STUDENT@engineering.inst.edu`. | +| locatorIds* | String[ ] | A list of ids associated with the user by various system that PASS interacts with. The value of each entry would be in the form of : `domain:type:value`. For example, `["johnshopkins.edu:hopkinsid:DRA2D", "johnshopkins.edu:employeeid:12345", "johnshopkins.edu:jhed:bostaur1"]`. The following values for `type` are considered deprecated: `jhed`, `hopkinsid`. The preferred types are `eppn` and `unique-id`, respectively. | +| orcidId | String | ORCID ID for the User | +| roles* | String[] | User roles ([_see list below_](#role-options)) | + +*required + +## Role options + +Role options for User + +| Value | Description | +| ------------- | ------------- | +| submitter | User who can view and manage Submissions for personal Publications or those associated with their own Grants | +| admin | User who can manage Submissions for personal Publications or those associated with their own Grants, as well as view Submissions for all Grants | diff --git a/docs/dev/model/pass_data_model.png b/docs/dev/model/pass_data_model.png new file mode 100644 index 00000000..d0962ec0 Binary files /dev/null and b/docs/dev/model/pass_data_model.png differ