diff --git a/docs/web-applications/dst/users-guide/v1.0/00-document-info.mdx b/docs/web-applications/dst/users-guide/v1.0/00-document-info.mdx new file mode 100644 index 000000000..4058ae9f9 --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/00-document-info.mdx @@ -0,0 +1,20 @@ +--- +title: Document Info +reportDate: October 2026 +reportType: Computer Program Document +reportTitle: Dam Screening Tool +reportSubTitle: User's Guide +reportAuthors: ['Adam Gohs, P.E.'] +reportAbstract: The Dam Screening Tool (DST) is a web application for screening-level risk analysis of dams. This User's Guide explains how to operate DST to create a screening, enter its information, evaluate its potential failure modes, assemble its risk results and take it through review. It documents every page, input and status indicator in the application and the workflow that connects them. The engineering methods behind the calculations are documented separately in the DST Technical Reference Manual and the System Response Library manuals. +reportSubjectTerms: ['Dam Screening Tool', 'DST', 'Dam Safety', 'Screening-Level Risk Analysis', 'Potential Failure Mode', 'Web Application', "User's Guide"] +citationGuide: "U.S. Army Corps of Engineers, Risk Management Center, Dam Screening Tool User's Guide, Lakewood, CO: U.S. Army Corps of Engineers, Risk Management Center, 2026." +--- + +import DocumentMetadata from '@site/src/components/DocumentMetadata'; +import NavContainer from '@site/src/components/NavContainer'; + + + +# Document Information + + diff --git a/docs/web-applications/dst/users-guide/v1.0/00-version-history.mdx b/docs/web-applications/dst/users-guide/v1.0/00-version-history.mdx new file mode 100644 index 000000000..b3babfc10 --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/00-version-history.mdx @@ -0,0 +1,19 @@ +--- +title: Version History +--- + +import NavContainer from '@site/src/components/NavContainer'; +import TableVersionHistory from '@site/src/components/TableVersionHistory'; + + + +# Version History + + diff --git a/docs/web-applications/dst/users-guide/v1.0/01-preface.mdx b/docs/web-applications/dst/users-guide/v1.0/01-preface.mdx new file mode 100644 index 000000000..a43e662e6 --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/01-preface.mdx @@ -0,0 +1,32 @@ +--- +title: Preface +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Preface + +The Dam Screening Tool (DST) is a web application for screening-level risk analysis of dams. This User's Guide explains how to operate DST: how to +create a screening, enter its information, evaluate its potential failure modes, assemble its risk results, and take it through review. It documents +each page, input and status indicator in the application, and the workflow that connects them. + +The guide is written for dam safety engineers and analysts who build screenings, and for the reviewers who read and comment on them. It assumes a +working knowledge of dam safety risk analysis; terms specific to the DST interface are defined where they first appear. + +The User's Guide describes how to use DST, not the engineering behind it. The calculations DST performs are documented in the DST Technical Reference +Manual and in the System Response Library manuals for each screening model. + +## Document Organization + +- **[Chapter 2, Introduction](./02-introduction.mdx)** — what DST is, what a screening-level risk analysis is, and the modules of a screening in + workflow order. +- **[Chapter 3, Getting Started](./03-getting-started.mdx)** — the Dashboard, creating and copying screenings, the screening team, and requesting + access to other screenings. +- **[Chapter 4, Working in DST](./04-working-in-dst.mdx)** — navigation, automatic saving and calculation, messages, tables, verification, + Submission Readiness, the input lock and editing conflicts, shared by every screening page. + +## Contact Us + +For questions or concerns, please email RMC.Software@usace.army.mil. diff --git a/docs/web-applications/dst/users-guide/v1.0/02-introduction.mdx b/docs/web-applications/dst/users-guide/v1.0/02-introduction.mdx new file mode 100644 index 000000000..18252b09c --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/02-introduction.mdx @@ -0,0 +1,91 @@ +--- +title: Introduction +--- + +import Figure from '@site/src/components/Figure'; +import FigReference from '@site/src/components/FigureReference'; +import NavContainer from '@site/src/components/NavContainer'; +import TableReference from '@site/src/components/TableReference'; +import TableVertical from '@site/src/components/TableVertical'; + + + +# Introduction + +The Dam Screening Tool (DST) is a web application for screening-level risk analysis of dams. A screening team uses DST to characterize the hazards +loading a dam, identify and evaluate the dam's potential failure modes, estimate the consequences of failure, and combine those pieces into risk +estimates. The team then records its findings and takes the screening through review, all within the same application. + +All of a dam's work in DST is organized as a **screening**. A screening holds everything the team enters, every result DST produces for that dam, and +the screening's review history. Each screening has a team led by a Facilitator, and every page of the screening is open to the team at the same time. + +## Screening-Level Risk Analysis + +A screening-level risk analysis estimates a dam's risk from the information readily available for the dam and the judgment of the screening team. DST +supplies a consistent structure for that work. Expert-developed screening logic recommends which potential failure modes to evaluate, structured +workflows estimate the system response for each one, and integrated services perform the hydraulic, consequence and risk computations. + +DST reports risk estimates; it does not make dam safety decisions. The results carry the level of detail of the information and judgment behind them, +and they are not a substitute for a detailed risk assessment. How DST computes each result, and the assumptions and limitations of each method, are +documented in the DST Technical Reference Manual and in the System Response Library manuals for each screening model. + +DST supports two types of screening. An **Official** screening is a screening of record that can be submitted for review. A **Testing** screening is +for practice and training; it cannot be submitted for review or produce official reports. + +## The Screening Workflow + +Inside a screening, the module navigation on the left of the page lists the screening's modules in workflow order +(). summarizes +what the team does in each module and which later modules use the result. + +
+ + + +The modules are not a strict sequence. The team may work in any module at any time, and several team members may work in different modules at once. +Results that depend on earlier modules recalculate automatically when their inputs change, and a team member verifies the data on each page once it is +complete. These shared behaviors are described in [Chapter 4, Working in DST](./04-working-in-dst.mdx). + +## Using This Guide + +[Chapter 3, Getting Started](./03-getting-started.mdx), describes the Dashboard, creating a screening and managing the screening team. [Chapter 4, Working in DST](./04-working-in-dst.mdx), describes the +navigation and the behaviors shared by every screening page. The chapters after it follow the module order in +, and the Review chapter is written for reviewers as well as screening teams. + +The guide names pages, tabs, buttons and fields exactly as they appear in DST, in **bold** where the user selects or enters them. The figures show +fictional screenings and, where a dam is taken from the National Inventory of Dams, public data for that dam. diff --git a/docs/web-applications/dst/users-guide/v1.0/03-getting-started.mdx b/docs/web-applications/dst/users-guide/v1.0/03-getting-started.mdx new file mode 100644 index 000000000..c109e9f59 --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/03-getting-started.mdx @@ -0,0 +1,445 @@ +--- +title: Getting Started +--- + +import Figure from '@site/src/components/Figure'; +import FigReference from '@site/src/components/FigureReference'; +import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableReference from '@site/src/components/TableReference'; +import TableVertical from '@site/src/components/TableVertical'; + + + +# Getting Started + +Every session in the Dam Screening Tool (DST) begins on the Dashboard. The Dashboard lists the screenings the user works on, the review assignments the +user holds, and a catalog of every official screening in DST. From the Dashboard the user creates new screenings, opens existing ones, manages each +screening's team, and requests access to screenings owned by others. + +This chapter describes the Dashboard and the actions available from it. Working inside a screening — navigation, automatic saving, verification and +the other behaviors shared by every screening page — is described in [Chapter 4, Working in DST](./04-working-in-dst.mdx). + +## The Dashboard + +The Dashboard opens after the user signs in, and the user returns to it at any time by selecting **Home** in the site header or the USACE castle logo. + shows the Dashboard for a user assigned to several screenings, and + describes each numbered region. + +
+ + + +Administrators can also publish site alerts, which appear in a colored band at the top of the Dashboard. An alert with an × can be dismissed; it returns +the next time the page loads. + +### My Screenings + +The **My Screenings** tab lists every screening on which the user is the Facilitator, a Team Member or a Viewer. Screenings on which the user is only a +reviewer appear on the My Reviews tab instead. Selecting a screening's name opens that screening. + + + +Selecting a column heading sorts the table by that column, and selecting it again reverses the order. The table opens sorted by **Modified**, newest +first. **Status** sorts in workflow order rather than alphabetically. + +A screening's **Type** is set when it is created: + +- **Official** — a formal screening that can be submitted for review and approval. +- **Testing** — a practice screening. A Testing screening cannot be submitted for review, never appears in the Search Catalog, and shows **N/A** for + its status. + +An Official screening shows one of these statuses: + +- **In Progress** — the screening team is entering and evaluating the screening. A screening also returns to In Progress if a review lead rejects it. +- **Submitted** — the Facilitator has submitted the screening. Submission starts the first review level immediately, so this status is usually brief. +- **Under Review** — one of the screening's review levels is in progress. Inputs are locked except during a review level's resolution period. +- **Complete** — every review level is approved. +- **Needs Facilitator** — the screening lost its Facilitator, for example because the Facilitator's account was deactivated. Inputs stay locked until an + administrator assigns a new Facilitator. + +The review process behind these statuses is described in Chapter 27, Review. + +#### Finding a screening + +The filter bar narrows the list: + +- **Status** — All, In Progress, Submitted, Under Review, Complete or Needs Facilitator. +- **Type** — All, Official or Testing. +- **Per page** — 15, 25 or 50 screenings per page. +- **Search** — matches any part of the screening name, dam name or description, and a whole number also matches that screening ID. Pressing the **/** + key moves the cursor to the search box. +- **All screenings** (administrators only) — lists every screening in DST, not only the administrator's own. + +Each active filter appears as a chip below the bar; × on a chip removes that filter, and **Clear all** removes them all. When more screenings match than +fit on one page, the page controls below the table move between pages. + +#### Actions on a screening + +The **⋮** button at the end of each row opens the screening's actions (). Only the +actions the user is permitted to take appear. + +
+ +Opens the Manage Team dialog (see Managing the screening team)., + 'Changes the screening name.', + <>Creates a new screening from this one (see Copying a screening)., + 'Removes the screening from DST.', + ], + ]} +/> + +Rename and Delete disappear once a screening is submitted: its name stays fixed through review, and only an administrator can delete it. + +**Delete** asks for confirmation. A deleted screening disappears for everyone, but it is not erased; an administrator can restore it. + +#### When there are no screenings + +A user with no screenings sees an empty Dashboard with a **Create Your First Screening** button +(). The filter bar is hidden until the user has at least one screening. If filters +hide every screening, the table is replaced by "No screenings match your filters" and a **Clear filters** link. + +
+ +### My Reviews + +The **My Reviews** tab lists every review level on which the user is a reviewer +(). It is organized into three tables: + +- **Active Reviews** — review levels in progress now, or about to start because every earlier level is approved. Rows that need the user's action are + listed first. +- **Upcoming Reviews** — review levels that will start after an earlier level finishes. +- **Completed Reviews** — approved review levels, newest first. The **Show** drop-down sets how far back the list reaches: the last 90 days (the + default), 6 months, a year, or all. + +
+ + + +Selecting a row opens the screening's Review page. The steps a reviewer takes there are described in Chapter 27, Review. The My Reviews tab loads its +list the first time it is opened; reloading the page shows activity that happened since. + +### Search Catalog + +The **Search Catalog** tab lists every official screening in DST, including screenings the user has no access to +(). It lets a user find a screening of interest and ask its Facilitator for +access. Testing screenings never appear in the catalog. + +
+ + + +The **Status** drop-down and the search box filter both the pending requests and the browse list, and **Per page** sets the length of the browse list +(25, 50 or 100). The catalog refreshes itself every 45 seconds while it is open, so an approved request moves out of the pending list without a reload. + +#### Requesting access to a screening + +The user selects the key icon at the end of the screening's row. The Request Access dialog opens. }, + { + title: ( + <> + The user may enter a Reason for request (optional, up to 1,000 characters), such as the user's role for the dam, and selects{' '} + Send Request. + + ), + }, + { + title: ( + <> + DST confirms "Access request sent. The screening Facilitator will review it." The screening moves to Pending access requests, + and the Facilitator receives a notification and an email. + + ), + }, + { + title: ( + <> + The Facilitator, or an administrator, approves or denies the request from the screening's management page. Approval grants Viewer access; either + way, the user receives a notification and an email. + + ), + }, + ]} +/> + +A request cannot be withdrawn from the Dashboard. After a denial the screening returns to the browse list and the user may request access again. A request +for a screening with status Needs Facilitator waits until a Facilitator is assigned. + +## Creating a Screening + +Any signed-in user can create a screening. The user selects **+ New Screening** on the My Screenings tab, selects **Create Your First Screening** on an +empty Dashboard, or presses the **n** key from anywhere on the Dashboard. The **New Screening** dialog opens with every field empty. + shows the dialog completed for a dam taken from the National Inventory of Dams +(NID), and describes each field. + +
+ +Official or Testing (see My Screenings)., + 'Up to 200 characters, for example "FY26 Screening — Example Dam".', + <>The dam being screened, found in the NID or entered by name (see Choosing the dam)., + <>Appears only for an Official screening of a USACE dam (see USACE dams)., + 'NAVD88, NGVD29 or Other; Other adds a box for the datum name (up to 50 characters).', + 'US Customary or SI (Metric). A dam taken from the NID is fixed at US Customary.', + 'The purpose of the screening, up to 2,000 characters.', + ], + ]} +/> + +**Create** stays unavailable until every required field is complete and the dam's NID record has finished loading. Vertical Datum and Units cannot be +changed after the screening is created. + +Selecting **Testing** as the Type adds the note "Testing screenings are for practice and cannot be submitted for review or produce official reports." +and removes the USACE Facilitator requirement (). The same figure shows the +datum name box that appears when Vertical Datum is **Other**. + +
+ +### Choosing the dam + +The **Dam** field searches the NID as the user types, by dam name, state, NID ID or county. Each match shows the dam's Federal ID and name with its +county and state beneath. The last choice in the list is always **Use "…" as entered**, for a dam that is not in the NID +(). + +
+ +- **Selecting an NID dam** links the screening to that NID record. The field shows the dam name followed by "— NID linked", DST loads the dam's NID record + ("Loading NID data..."), and Units is fixed at US Customary. On Create, DST copies the dam's NID data into the screening. +- **Selecting Use "…" as entered**, or leaving the field with text typed and nothing selected, creates a dam entered manually. DST notes that the + screening will not be linked to the NID and that the dam information will be entered manually + (). + +
+ +The × on the dam chip clears the selection. If the search finds nothing, the list reads "No NID matches found." and offers only Use "…" as entered. If the +NID cannot be reached, DST reports "The National Inventory of Dams is currently unavailable. Please try again later." + +### USACE dams + +An Official screening of a dam owned by USACE needs a USACE Facilitator. When the user selects a USACE dam from the NID, the **USACE Facilitator** field +appears (). It searches the members of the USACE Facilitators +group by name or email; the user selects a person, and **Change** replaces the selection. + +
+ +The selected Facilitator becomes the screening's Facilitator and is notified, and the user who created the screening joins its team as a Team Member. +For every other screening — any non-USACE dam, and any Testing screening — the user who creates it becomes its Facilitator. If the USACE Facilitators +group has no members, DST reports "No USACE Facilitators available. Contact your administrator." and the screening cannot be created until an +administrator adds one. + +### After the screening is created + +DST opens the new screening's Screening Information page. No confirmation message appears. Every new screening starts with two review levels, Level 1 and +Level 2. DST also begins collecting background data for the dam — reservoir data for the stage-duration curve, and seismic hazard data where the dam's +location supports it — which may take a few minutes to appear on the Hazards pages. + +## Managing Screenings + +### Managing the screening team + +**Manage Team** in a screening's row actions opens the Manage Team dialog (). It is +available to the screening's Facilitator and to administrators. + +
+ +- **Facilitator** — shows the screening's Facilitator. An administrator can select **Replace** to assign a different Facilitator while the screening + is In Progress or Testing. The previous Facilitator loses access to the screening. +- **Team Members** — lists the screening's Team Members and Viewers. The role drop-down switches a person between Team Member and Viewer, and the remove + icon removes the person from the screening. +- **Add Member** — searches active users by name or email. The user chooses the role in the drop-down beside the search box and selects + **+ Add as Team Member** or **+ Add as Viewer** on the person. + +Every change in this dialog takes effect immediately, with no confirmation step, and DST confirms each one. Reviewers are not managed here; they are +assigned to each review level on the screening's Review page. + +While a screening is under review, Team Members and Viewers can still be added and removed, but the Facilitator stays fixed. Once a screening is Complete, +or while it needs a Facilitator, only Viewer access can be changed. The dialog states which of these applies. + +### Copying a screening + +**Copy** creates a new screening from an existing one. Anyone on the screening can copy it. The **Copy Screening** dialog names the copy "(Copy)" +followed by the original name and asks for its **Type**, which defaults to the original's. The user becomes the Facilitator of the copy, except for an +Official copy of a USACE dam, which needs a USACE Facilitator as described in [USACE dams](#usace-dams). + +A copy carries over the screening's name, description, vertical datum, units and dam data. It does not carry over hazards, the information +entered on the Dam Information pages, failure mode screening, selection or evaluation, consequences, risk analysis, Major Findings, documents, the +screening team, or review history, and the dam data in the copy is unverified. The copy starts with its own Level 1 and Level 2 review levels and opens +on its Screening Information page. + +### Renaming a screening + +**Rename** opens a dialog with the screening's current name. The user edits the name (up to 200 characters) and selects **Rename**; DST confirms the new +name. A screening can be renamed only while it is In Progress or Testing. If another user changed the screening at the same moment, DST reports that the +page was refreshed and the rename is not applied; the user renames it again. diff --git a/docs/web-applications/dst/users-guide/v1.0/04-working-in-dst.mdx b/docs/web-applications/dst/users-guide/v1.0/04-working-in-dst.mdx new file mode 100644 index 000000000..cbc5aa4e1 --- /dev/null +++ b/docs/web-applications/dst/users-guide/v1.0/04-working-in-dst.mdx @@ -0,0 +1,322 @@ +--- +title: Working in DST +--- + +import Figure from '@site/src/components/Figure'; +import FigReference from '@site/src/components/FigureReference'; +import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableReference from '@site/src/components/TableReference'; +import TableVertical from '@site/src/components/TableVertical'; + + + +# Working in DST + +Every page inside a screening shares the same navigation and the same rules for saving, calculating, reporting problems and verifying data. This +chapter describes those shared behaviors once. The chapters that follow describe each page's own inputs and refer back here for everything common to +all pages. + +## The Screening Page + +A screening opens on its Screening Information Overview page. shows a +typical screening page, and describes each numbered region. + +
+ + + Home returns to the Dashboard. Resources links to related external sites, and Help holds the + Change Log and Terms & Conditions. The bell and the avatar menu at the right are described in{' '} + The site header. + , + 'The screening name and its eight modules, in workflow order. The selected module is highlighted.', + 'The selected module name followed by its pages. A dot after a page name shows its verification status.', + <>Shows whether the page has been verified, and verifies it (see Human Verification)., + <>Problems the page has found with its inputs, grouped by severity (see Messages and Highlighted Cells)., + 'The inputs, tables, charts and results of the selected page.', + ], + ]} +/> + +## Navigation + +### The site header + +The site header appears on every DST page. The USACE castle logo and **Home** return to the Dashboard. **Resources** lists the RMC Website, the +National Inventory of Dams, the USACE Dam Safety Program and FEMA Dam Safety, each opening an external site. **Help** includes the **Change Log**, +which lists what changed in each release of DST, and **Terms & Conditions**. + +The bell opens the **Notifications** list, with **Mark all read** at the top. An amber badge on the bell counts unread notifications. The avatar +shows the user's initials and opens a menu headed by the user's name, email address and role, with **View Profile** and **Logout**. Users with +administrative duties see further items in this menu, and an amber badge on the avatar counts items awaiting their attention. + +### Modules and pages + +The module navigation on the left lists the eight modules of the screening. Selecting a module opens its first page, and the sub-navigation bar across +the top of the page lists that module's pages. Selecting a page in the sub-navigation opens it. The browser tab shows the page name and the screening +name, so several screenings or pages can be told apart when open in separate tabs. + +The button beside the screening name, **Collapse navigation**, narrows the module navigation to icons only, leaving more room for the page; a module's +name then appears when the pointer rests on its icon. **Expand navigation** restores it. DST remembers the choice on that computer. + +### Tablets and phones + +DST adapts its navigation to the width of the screen: + +- **Laptop and desktop screens** show the full layout in . +- **Tablet screens** keep the sub-navigation bar but always show the module navigation as icons only. +- **Phone screens** replace the module navigation with a menu button, **Open navigation**, at the left of the sub-navigation bar. It opens a panel + listing every module, with the current module's pages beneath it. The sub-navigation bar uses shortened page names, such as **Operational** for + Operational Data. + +### Who else is on the page + +When other users have the same screening open, their initials appear in circles at the right of the sub-navigation bar, before the verification +badge. Resting the pointer on a circle shows the user's name, role and the page that user is viewing. Up to four circles appear; beyond that, a +**+N** circle lists the rest. Seeing another user on the same page is a cue to coordinate before editing the same inputs (see +[Editing Conflicts](#editing-conflicts)). + +## Saving + +DST saves every entry automatically. There is no Save button on any page that holds screening inputs: + +- **Text and number fields** save when the user leaves the field, by pressing Tab or selecting elsewhere on the page. +- **Selections** — drop-down lists, check boxes, toggles and option buttons — save as soon as the user makes them. +- **Tables** save shortly after each change (see [Tables](#tables)). +- **Rich-text editors**, used for the Major Findings sections and failure mode rationales, save after the user pauses typing for two seconds, and + again when the user leaves the editor. + +When a save takes longer than a second, **Saving…** appears with a spinner at the right of the sub-navigation bar. DST shows no message when a save +succeeds. The cross-section editors are the one exception to automatic saving; they have their own Save and Cancel buttons, described in Chapter 8, +Cross-Section Editors. The Inundation Geometry and Consequence Data pages warn with an **Unsaved Changes** dialog if the user tries to leave while +an entry there has not yet been saved. + +Saving an entry may change other pages. When the change makes earlier results out of date, DST clears those results and says so in a notice, and +any verification of the page is cleared (see [Human Verification](#human-verification)). + +## Automatic Calculation + +DST has no Calculate or Run buttons. Each calculation starts on its own once every input it needs is complete and valid, and runs again whenever one +of those inputs changes. While a calculation runs, the affected chart or result shows that it is updating. + +When an input changes after results were calculated, DST clears the out-of-date results and shows a notice explaining what changed — for example, +that Dam Information or Hydrologic Hazard inputs changed, that the results were cleared, and that the analysis will recalculate automatically. A +notice may also ask the user for a new selection, such as when the cross section or material a result depended on has been deleted. + +The calculations depend on separate calculation services. If a service cannot be reached, a dismissible alert appears at the top of the affected +pages, such as "The calculation service is currently unavailable. PFM calculations are temporarily unavailable." Inputs still save while a service is +unavailable, and the calculations run once it returns. + +## Messages and Highlighted Cells + +DST checks each page's inputs every time they save and reports what it finds in the message banner at the top of the page. + shows a banner with two kinds of message, and + describes each callout. + +
+ +Row and selection commands for the table (see Tables)., + ], + ]} +/> + +The banner holds up to three cards, one per severity: + +- **Required Inputs** (light blue) lists inputs the page still needs. +- **Warnings** (amber) are advisories. They point out something worth checking but do not block anything. +- **Errors** (red) list inputs that are invalid. + +Required inputs and errors must be resolved before the screening can be submitted for review (see +[Submission Readiness](#submission-readiness)); warnings never prevent submission. A message about another page ends with a **Go to** link to that +page. Messages never stop the user from typing, saving or moving between pages, and they update each time the page saves. On a page without a +banner, warnings and errors appear instead as notices in the corner of the screen. + +DST also marks individual inputs: + +- A table cell whose value causes an error is tinted red. A cell holding text that is not a number is also tinted, and that entry is saved as + blank. +- A **Required** tag beside a field's label marks an input the page needs. +- A justification box that is still empty shows an amber outline and the note **Justification required** beside its title. The note clears as the + user types. Missing justifications are listed on the Submission Readiness page rather than in the page banner. + +## Tables + +Curves and other series of values are entered in tables that work like a spreadsheet: + +- **Selecting and editing.** Selecting a cell and typing replaces its value. Dragging, or selecting one cell and then another with Shift held, + selects a range; Ctrl-click adds cells to the selection. **Delete** clears the selected cells. +- **Moving between cells.** The Up and Down arrow keys move between rows. Tab and Shift+Tab move between editable cells. Pressing Tab in the last cell + adds a new row, as long as the last row holds a value. +- **Pasting.** A block copied from a spreadsheet pastes into the table starting at the selected cell, and the table adds rows as needed. Tables with a + fixed set of rows keep their rows and paste only what fits. +- **Copying.** Ctrl+C copies the selected cells. Ctrl+A selects every cell. +- **Toolbar.** The icon buttons above the table add, insert and delete rows, select all cells, copy the selection with or without its column headers, + and paste. Resting the pointer on a button shows its name. Tables with a fixed set of rows hide the row commands. + +Table entries save shortly after each change, and the table's messages arrive with the save. + +## Human Verification + +Each page that holds entered data is verified by a member of the screening team, who attests that the data on the page is accurate. Verification +is required before the screening can be submitted for review. shows a +page before and after verification. + +
+ +- **Verifying.** The amber **Unverified** badge at the right of the sub-navigation bar is a button. A single selection verifies the page; there is no + confirmation. The badge turns into a green **Verified** label, and resting the pointer on it shows who verified the page and on what date. +- **Who can verify.** The Facilitator and Team Members can verify while the screening's inputs are open for editing. For anyone else the badge is + unavailable, with the explanation "Only screening team members can verify this page." A page may also hold off verification while it is still + collecting data, such as Stage Duration while its reservoir data downloads. +- **Edits clear verification.** Changing any input on a verified page clears its verification, and the badge returns to Unverified. Calculations + that DST clears because an input changed elsewhere can clear a page's verification too. +- **Tab dots.** The dot after a page name in the sub-navigation is amber when the page needs verification and green when it is verified. A page that + holds several verifiable parts, such as Failure Mode Evaluation with one entry for each failure mode location, shows a green dot only when every + part is verified. A page with nothing to verify has no dot. + +## Submission Readiness + +The **Submission Readiness** page, under the Review module, gathers everything that stands between the screening and its submission for review. + shows the page, and + describes each callout. + +
+ + + +Verification itself happens only on each page, never on the Submission Readiness page. The screening is ready when no module has an issue and every +verification item is verified. Required inputs and errors count as issues; warnings do not. + +### Submitting for review + +Only the Facilitator sees **Submission Controls**. **Submit for Review** stays unavailable until every module is ready, and it is never available for +a Testing screening ("Testing screenings cannot be submitted for review."). Submitting is a single, final step: + +The Facilitator selects Submit for Review. A confirmation dialog explains what happens next. }, + { + title: ( + <> + The dialog notes that the first review level starts its review period immediately and its reviewers are notified, that all inputs lock and + unlock only during a level's resolution period, and that a submission cannot be rescinded. + + ), + }, + { title: <>The Facilitator selects Submit for Review in the dialog to confirm, or Cancel to return. }, + ]} +/> + +Once the screening is submitted, the Submission Controls section reads "This screening is under review. To withdraw it, ask the review lead of the +active level to reject it." The review that follows is described in Chapter 27, Review. + +## Input Lock + +A screening's inputs lock when it is submitted for review and stay locked through completion. They unlock only while the active review level is in +its resolution period, so the team can respond to review comments. While inputs are locked, a strip across the top of every page explains why +(), every input is read-only, and table cells turn gray. + +
+ + + +Calculations do not run while inputs are locked, and pages cannot be verified. Reviewers continue to read every page and comment on it. + +## Editing Conflicts + +Several team members can work in a screening at once. When two users change the same record and the second save arrives after the first, DST keeps +the first save, reloads the page with the latest data, and shows a notice to the second user — usually "This record was modified by another user. +Your page has been refreshed." The second user's conflicting entry is not kept and must be entered again if it is still wanted. Seeing other users on +the page (see [Who else is on the page](#who-else-is-on-the-page)) helps the team avoid conflicts. + +## Comments + +During review, reviewers leave comments directly on the page they concern. A reviewer on the active review level sees a round **Add a review +comment** button at the bottom right of each page during the review period; it opens a comment panel beside the page. Commenting, team responses and +backcheck are described in Chapter 27, Review. diff --git a/src/docConfig.js b/src/docConfig.js index 3aa150ad4..3aaa5a237 100644 --- a/src/docConfig.js +++ b/src/docConfig.js @@ -299,7 +299,8 @@ const docs = [ software: 'dst', doc_location: 'web-applications/dst/users-guide', doc_name: "Dam Screening Tool User's Guide", - active: false, + sidebar_label: "Dam Screening Tool User's Guide", + active: true, draft: true, }, { diff --git a/static/bibliographies/web-applications/dst/users-guide/v1.0/bib.json b/static/bibliographies/web-applications/dst/users-guide/v1.0/bib.json new file mode 100644 index 000000000..fe51488c7 --- /dev/null +++ b/static/bibliographies/web-applications/dst/users-guide/v1.0/bib.json @@ -0,0 +1 @@ +[] diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-empty-state.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-empty-state.png new file mode 100644 index 000000000..d8836959a Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-empty-state.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-manage-team.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-manage-team.png new file mode 100644 index 000000000..74d52dc24 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-manage-team.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-reviews.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-reviews.png new file mode 100644 index 000000000..a8ca7de39 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-reviews.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-screenings.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-screenings.png new file mode 100644 index 000000000..47f819010 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-my-screenings.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-dam-search.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-dam-search.png new file mode 100644 index 000000000..1b78aa5aa Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-dam-search.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-nid.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-nid.png new file mode 100644 index 000000000..7f14e6006 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-nid.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-testing.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-testing.png new file mode 100644 index 000000000..7442a3718 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-testing.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-usace-facilitator.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-usace-facilitator.png new file mode 100644 index 000000000..a282333d6 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening-usace-facilitator.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening.png new file mode 100644 index 000000000..e64742308 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-new-screening.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-row-actions.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-row-actions.png new file mode 100644 index 000000000..1ecc763e8 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-row-actions.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-search-catalog.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-search-catalog.png new file mode 100644 index 000000000..da3629270 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/dashboard-search-catalog.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/screening-modules-nav.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/screening-modules-nav.png new file mode 100644 index 000000000..53dd01859 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/screening-modules-nav.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-input-lock.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-input-lock.png new file mode 100644 index 000000000..9058214e6 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-input-lock.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-messages-and-grid.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-messages-and-grid.png new file mode 100644 index 000000000..f42dc4123 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-messages-and-grid.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-screening-page.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-screening-page.png new file mode 100644 index 000000000..2ec204a2d Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-screening-page.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-submission-readiness.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-submission-readiness.png new file mode 100644 index 000000000..ade49f529 Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-submission-readiness.png differ diff --git a/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-verification.png b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-verification.png new file mode 100644 index 000000000..a8f7b82ab Binary files /dev/null and b/static/figures/web-applications/dst/users-guide/v1.0/figures/working-in-dst-verification.png differ