Usage Guides
The following sections delineate the business rules that define constraints and linkages between user interface components and the underlying data model. These rules are enforced as server-side logic that activates when database records are searched, changed, inserted, or deleted via user or application programming interfaces. Rules are grouped by class and specific features in the user interface.
Relationships
Class | Relation | Class | Statement |
|---|---|---|---|
Project | n..n | Agent | A project is associated with zero to many Agents and an Agent is associated with zero or many projects |
Project | n..n | Project Feature | A project is associated with zero to many Agents and an Agent is associated with zero or many projects |
Project Hierarchies
A project may participate in a parent-child relationship with another project
A parent project has one or many child projects
A parent project is a prerequisite to creating a child project. The parent is selected during the child project selection or
Several project attributes are automatically populated from the parent project when a child project is being created.
Projects hierarchies are limited to a single parent-child relationship
Projects that do not belong to hierarchies are simply referred to as projects
Child projects are handled in the same manner as parent projects, they share the same relationships with phases, types, etc.
Project Agents and Project Features may be inherited from the parent project to a child project.
Inheritance is a unidirectional process where a child may inherit from the parent, but not the converse
Inherit from parent adds all project agents or project features associated with the parent to the child project. The user may then remove the agents or features not applicable to the child project.
Project Stages
All projects are divided into a temporal-based distinguishable parts called stages. Each stage is identified by name and start/end dates.
Project stages are defined in a type vocabulary that can be edited by a system administrator
At any given time, a project may belong to one and only one project stage. There is no semantic or temporal overlap between project stages.
Project stage sequences are not predefined. The proper sequencing is the responsibility of the end user.
Project stage changes are stored in a separate timestamped database table, which can then be used to construct a project timeline.
Vocabularies
A vocabulary defines the terminology used within the system in a controlled manner.
In the portal, most vocabularies are 'type vocabularies'
Vocabularies are managed centrally through the User Interface.
Terms in a vocabulary may not be deleted if they are in use. The corresponding model records must be deleted or a new type has been assigned before a term can be deleted
Terms may only be created or updated by a portal administrator
Agents
An Agent may be associated with multiple projects
An Agent must have at least one defined role per project (Agent Role)
An Agent may have multiple defined roles on a single project.
A relationship may be established between an agent and user account.
Two agents may be related to one another in unidirectional relationship called an Agent Relation.
In an agent relation, the nature of the relationship between the subject agent and related agent is defined by a relation predicate (e.g., employed by)
An Agent Type must be defined for each agent.
Project Features
Each Project Feature has one Feature Type
A Project Feature may belong to zero to many Projects
A Project may be comprised of zero to many Project Features
A Project Feature may belong to both a Parent Project and its Child Project
Documents (Uploads)
Users assigned the admin or editor role may access any document uploaded to the portal by any user.
Documents are shared using Document Access Groups, where each document has an access group and the members of that group may access the document.
Users with the admin or editor role may access any document uploaded to the portal regarding of ownership or access group
Client Access to Documents
Clients may access a document if one of the following conditions are met.
Document uploaded by the client (Client owns the document)
Client belongs to the document access group associated with a document
Three concurrent conditions are true:*
Client belongs to the project access group associated with a project
The document is associated with the project
Both the document and project are visible to client
*Document access group policy is bypassed in the third option.
Project Lifecycles
All projects are divided into a temporal-based distinguishable parts called stages. Each stage is identified by name and start/end dates.
The project stage model defines the standardized set of stages for EPR projects. The state of a project at any given time is associated with one and only one project stage. There is no conceptual or temporal overlap between stages.
A chronological history of a project's stage changes is provided in the timeline view available on the individual project page
Each stage change is timestamped. The timeline is constructed by ordered stage start date in descending order
A stage change is defined as the start of a new phase and the end of the immediately preceding stage.
The end of the preceding stage may be different from the start of the new stage. Therefore, each stage is defined by a start date and optional end date.
For current purposes, the transition from one stage to another stage may not occupy a single temporal position (a single day of the year) Some ontologies stipulate that a preceding stage only exists if the x precedes y if and only if the time point at which x ends is before or equivalent to the time point at which y starts. (https://nfdi4ing.pages.rwth-aachen.de/metadata4ing/metadata4ing/1.2.1/index.html#http://purl.obolibrary.org/obo/RO_0002090) This level of rigor is not required for the project portal. Here, stage A precedes stage B if stage A and B are coincident in the sequence of stages that is characteristic of a specific project type as described in the project plan.
Advanced Handling
Project types are, in part, defined by a sequence of stages. Certain project types under the Ecological Restoration service domain omit specific stages relative to other types in the same domain. At this time, the specific sequence of stages associated with a project type are not regulated by the data model. This is possible, but until the need arrises the pragmatic approach is the preferred route.
Dates
Every project has a specific start and end date (format M/D/Y) per the binding contractual agreement (as written in legally binding documents).
Each stage as a start and end date that is not in a contractual agreement. Rather noted when all tasks associated with a stage are complete.
For two sequential stages, the end date of the first stage may be equal to the start date of the next stage. Therefore the two are ambiguous and should be separately recorded. Only the start or end date of a stage needs to be recorded. For current purposes, the end date is preferred and recorded when the stage is updated.
Stage end dates are recorded as part of the stage update process in the portal. Here, when the current stage of a project is updated, the user will enter the end date for the previous stage, which is then stored in a stage change tracking table
User Flows
User flow diagrams are a type of flowchart that illustrates the steps a user will take to complete a specific action in an application.
