Document Management
This page documents the document browser, upload, download, history, attachment, visibility, and PDF tool subsystems in SureDrive. It covers the Angular routes and controllers, the upload service, backend operation constants, and the document entity model.
Overview
Documents in SureDrive are stored within a folder hierarchy defined by the Content Model Editor. The document navigator is the primary user interface — it renders the folder tree on the left and a document list or preview panel on the right. All document operations (upload, download, move, share, sign, annotate, delete, restore) are initiated from this view.
Key owning modules:
- UI:
suredms-web-client—network/study/folder tree, upload wizard, document detail views - Service layer:
suredms-web-service— document streaming and processing endpoints - Domain model:
suredms-common—DocumentEntity,BlobDescriptor
Angular Routes
File: SC/suredms-web-client/src/main/webapp/app/js/state/app-states.js
| State | Template / Controller | Purpose |
|---|---|---|
app.network.study.browse.files | drive-file-navigator.html | Main SureDrive document navigator; folder tree + document list |
app.network.study.browse.document | StudyDocumentController | Document detail view; metadata, preview, workflow actions |
app.network.study.upload-drive | DriveUploadFilesController | Multi-file upload wizard for SureDrive |
app.network.study.browse.attachment | StudyAttachmentController | Attachment detail view for a specific document attachment |
Controllers and Services
DriveUploadFilesController
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/drive-upload-files.js
Orchestrates the multi-file upload process. Responsibilities:
- Collects files from the browser drag/drop or file picker.
- Allows users to assign content type (folder placement), metadata fields, and PDF conversion options per file.
- Supports
manualVersionChange(Major/Minor version increment selection during upload). - Emits upload progress events consumed by the progress indicator component.
StudyDocumentController
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/documents/study-document-details.js
Manages the document detail panel. Responsibilities:
- Renders document metadata and the PDF preview iframe.
- Surfaces actions: review, sign, initiate workflow process, associate with tasks.
- Delegates permission checks to
DocumentPermissionsHelper(see Role-Based Access Control).
StudyDocumentHistoryController
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/documents/study-document-history.js
Handles the version history panel for a document:
| Method | Operation |
|---|---|
fetchDocumentHistory | Calls Mobile.GetDocumentHistory to populate the versions list |
revertDocument | Calls OPERATION_DOCUMENT_RESTORE_VERSION to promote an older version to current |
UploadFilesHelperService
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-upload.js
Shared utility service for all document upload flows:
| Method | Purpose |
|---|---|
reloadRequiredMetadata | Fetches mandatory metadata fields based on content type and user role |
populateUploadTaskParams | Configures upload parameters when the upload is part of a workflow task |
handleEmail | Parses .msg / .eml files using JSZip; extracts attachments as individual document objects |
copyMetadataParameters | Synchronises metadata across multiple files in a batch upload |
ContentVisibilityService
Manages ACL rules for documents and folders. Implements the backend of the Configuring Document Visibility and Configuring Content Visibility Help flows. Works with ExpandedArchiveAclRule (see Role-Based Access Control).
TrashedArchiveService
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-trash.js
Handles soft-delete and permanent-delete flows:
| Method | Backend Operation |
|---|---|
undeleteArchive | Mobile.UndeleteDocuments — restores deleted documents |
purgeArchive | Mobile.PurgeDocuments — permanently removes documents |
StudyNavigatorFileEditorService
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator-file-editor.js
Facilitates in-browser PDF manipulation: Split, Merge, and Redact operations surfaced via the PDF Tools panel in the document detail view.
Document Entity Model
File: SC/suredms-common/src/main/java/com/sureclinical/suredms/entity/DocumentEntity.java
| Method | Description |
|---|---|
getVersion() | Internal numeric version counter |
getManualVersionString() | User-facing version string (e.g., 1.0, 2.1) |
getContentSize() | File size in bytes |
getDocumentStatus() | Lifecycle state: Draft, Effective, Obsolete |
isDocumentLocked() | true if the document is checked out or otherwise restricted |
Backend Operation Constants
Operations are defined in constants-operations.js and executed via ConnectionService. Key document operations:
| Constant | Operation String | Purpose |
|---|---|---|
OPERATION_MOBILE_UPLOAD_DOCUMENT | Mobile.UploadDocument | Streams document binary to the server |
| — | Mobile.GetDocumentHistory | Returns version list for a document |
OPERATION_DOCUMENT_RESTORE_VERSION | — | Promotes an older version to current |
| — | Mobile.UndeleteDocuments | Restores documents from trash |
| — | Mobile.PurgeDocuments | Permanently deletes documents |
Document Operations Reference
| Help Topic | Operation | Entry Point |
|---|---|---|
| Uploading Documents | DriveUploadFilesController → Mobile.UploadDocument | Documents area → Upload button |
| Downloading Documents | StudyDocumentController → download action | Document detail → Download |
| Moving Documents to Archive | DocumentPermissionsHelper.canBeMovedToArchive() + acquire queue service | Document detail → Move to Archive |
| Deleting Documents | Soft delete to trash | Document context menu → Delete |
| Restoring Documents | TrashedArchiveService.undeleteArchive | Trash → Restore |
| Permanently Deleting | TrashedArchiveService.purgeArchive | Trash → Permanently Delete |
| Document History | StudyDocumentHistoryController.fetchDocumentHistory | Document detail → History tab |
| Revert Version | StudyDocumentHistoryController.revertDocument | History tab → Revert |
| Moving / Copying | StudyNavigatorFileEditorService | Document context menu → Move / Copy |
| Configuring Visibility | ContentVisibilityService | Document detail → Visibility |
| Content Visibility (folder) | ContentVisibilityService | Folder context menu → Content Visibility |
| Using PDF Tools | StudyNavigatorFileEditorService → split / merge / redact | Document detail → PDF Tools |
| Sharing Documents | ACTION_SHARE_BOOKMARK / sharing service | Document detail → Share |
| Managing Attachments | StudyAttachmentController | Document detail → Attachments tab |
| Submitting Discrepancies | Quality review flow | Document detail → Submit Discrepancy |
| Working with Expired Documents | Expiry filter in navigator | Documents → filter by Expired |
| Importing from SharePoint | Connector integration (see Connectors) | Documents → Import from SharePoint |
Bookmarks
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/bookmarks/study-bookmark-navigator.js
StudyBookmarkNavigatorController manages the dedicated Bookmarks view — a filtered version of the document tree showing only user-marked favourites. The ACTION_SHARE_BOOKMARK action allows users to create a direct link to a bookmarked folder or document and share it with other team members.
Keyboard Navigation
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator.js
StudyAbstractNavigatorController injects KeyboardNavigationService to handle keyboard shortcuts across the Documents, Bookmarks, Acquire Queue, and Quality Queue views.
| Key | Method / Action |
|---|---|
↑ / ↓ arrow | selectPreviousEntity / selectNextEntity — move selection in the tree |
Enter | Open selected item |
Backspace | Navigate to parent directory |
Escape | Clear selection |
Delete | Trigger delete action on selected item (where applicable) |
KeyboardNavigationService.bindKeyListener is used in individual controllers to map additional keys to context-specific document actions.
Key Source Files Reference
Annotation Tool
The SureDrive Annotation Tool is embedded in the PDF document viewer. It supports text annotations, sticky-note comments, and search-based redaction.
Entry Point and Controller
File: SC/suredms-web-client/src/main/webapp/app/js/file/file-viewer.js
Controller: DocumentViewerController
| Method | Description |
|---|---|
toggleAnnotationBlock() | Opens or closes the annotation panel; validates that signing and watermarking are not concurrently active |
openAnnotationBlock(isRedaction) | Activates either the standard annotation tool or the redaction tool depending on the flag |
doAnnotate(confirm) | Saves pending annotations to the document |
doSearchTextRedaction(redaction) | Implements Search & Redact: sends document data to OPERATION_MOBILE_SEARCH_TEXT to locate text occurrences marked for redaction |
Permissions
The annotation UI gates access behind two feature flags:
| Feature Flag | Capability |
|---|---|
FEATURE_PDF_ANNOTATIONS | Standard PDF annotations (text, sticky notes) |
FEATURE_PDF_COMMENTS | Inline comment tool |
In addition, the document must have annotable = true — a flag controlled via Content Model Editor folder or content-type properties. Documents that are not annotable will not show the annotation toolbar.
Relationship to the Content Model Editor
Annotation labels and categories are defined as AnnotationDefinitionEntity records within the CME. AnnotationDefinitionEntity extends PropertyDefinitionEntity, which means annotation terms live alongside metadata term definitions in the content model. This allows structured annotation review: reviewers pick from a predefined vocabulary of annotation types when annotating a document.
Entity: SC/suredms-common/src/main/java/com/sureclinical/suredms/entity/AnnotationDefinitionEntity.java
Backend Processing
File: SC/suredms-web-service/src/main/java/com/sureclinical/suredms/webservice/ItextUtils.java
ItextUtils.redactPdfFile(File inputFile, File outputFile, List<Map<String, Object>> redactions) performs the server-side PDF surgery for redaction using the iText library. It handles complex PDF encodings including JBIG2 and JPX 2000 images.
Help reference: Using-the-SureDrive-Annotation-Tool_73793542.html
Document Tree Settings
The document navigator persists display preferences per user per study, including view mode, column sort, and tree expansion state.
Controller and Services
Controller: StudyAbstractNavigatorController
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator.js
| Setting | Description |
|---|---|
$scope.navigator.viewId | Active view mode: standard directory view, VIEW_BY_CATEGORY, or BY_ANNOTATIONS |
$scope.treeOptions | Angular tree component config: node equality checks, CSS class injection |
$scope.navigator.page | Current pagination state |
$scope.navigator.sort | Active column sort field and direction |
| Selection mode | toggleSelectionMode() enables bulk-action selection |
Persistence
Service: NavigatorPreferencesService
Repository: NavigatorPreferencesRepository
File: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator-filter-preferences-repository.js
Preferences are stored server-side per user/study pair via the NavigatorPreferencesService:
| Backend Operation | Purpose |
|---|---|
Mobile.GetDocumentNavigatorPreferences | Fetches saved preferences on navigator load |
Mobile.UpdateDocumentNavigatorPreferences | Persists changes when a user modifies view settings |
A preferencesHash detects whether settings have changed since last save. study-navigator-context.js restores the user’s previous tree expansion state (expandedNodes), selected node, and filter parameters when they return to the same study.
Help reference: Configuring-SureDrive-Document-Tree-Settings_73891863.html
Navigator Data Flow and Operations
StudyAbstractNavigatorController is the base class for the document tree and list area in SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator.js. It manages the full lifecycle of the folder tree and document list — loading entity hierarchies, applying filters, maintaining selection state, and coordinating document operations.
Key Nuxeo Automation Operations
| Operation | Purpose |
|---|---|
OPERATION_MOBILE_GET_ENTITY_DETAILS | Fetches detail metadata for a specific entity (folder or document) |
OPERATION_MOBILE_GET_ENTITY_HISTORY | Fetches the version history event list for an entity |
OPERATION_MOBILE_GET_DOCUMENT_DETAILS | Fetches document-specific metadata (content type, milestone, etc.) |
OPERATION_MOBILE_GET_DOCUMENT_CHECK_OUT | Retrieves check-out state of a document |
OPERATION_MOBILE_GET_DOCUMENT_SUFFIX | Returns the canonical file suffix for the document |
OPERATION_MOBILE_MOVE_DOCUMENTS | Moves selected documents to a different folder |
OPERATION_MOBILE_COPY_FOLDERS | Copies a folder subtree |
OPERATION_MOBILE_SET_DOCUMENT_LOCK | Sets or clears the document lock flag |
OPERATION_MOBILE_SET_DOCUMENT_SURVEY | Assigns survey metadata to a document |
OPERATION_MOBILE_SET_CONTENT_TYPE_LOCK | Locks an entity to a specific content type |
OPERATION_MOBILE_SET_CONTENT_TYPE_RESERVE | Reserves a content type slot for a document |
OPERATION_MOBILE_GET_MEDICAL_IMAGE_SLIDES | Fetches medical image slide metadata |
Navigator State Object
The controller maintains a top-level navigator object on $scope:
| Property | Type | Meaning |
|---|---|---|
navigator.view | object | Current view (By Category, By Site, etc.) — loaded from ViewCacheService.getViewForStudy |
navigator.currentEntity | entity | Currently selected folder or document |
navigator.entities | array | All loaded entities for the current view level |
navigator.children | array | Filtered subset of entities shown in the list |
navigator.selectedItems | array | Currently selected items (multi-select mode) |
navigator.expandedNodes | array | Tree nodes currently expanded |
navigator.filtering | object | Active filter parameters |
navigator.isLoadingInProgress | boolean | True while an entity load is in flight |
navigator.sort | object | Current sort column and direction |
navigator.page | object | Pagination state for list view |
Enrichment and Caching Services
| Service | Role |
|---|---|
DocumentEnrichmentService | enrichEntityTreeNode(entity) — adds UI helper properties to repository objects (display name, icon, action flags) |
EntityDetailsCacheService | reloadEntityDetails(entity) — refreshes cached metadata for an entity from the server |
ContentVisibilityCacheService | Caches ACL/blinding rule visibility decisions to avoid repeated server calls |
ContentVisibilityService | Applies blinding rules at render time to filter hidden folders from the tree |
StudyNavigatorContextService | restoreContext() — restores last expanded nodes, selected node, and filter state; isUserStorage() |
Navigator Preferences
User tree preferences (expanded nodes, selected node, view, sort direction, filter state) are persisted server-side via:
Mobile.GetDocumentNavigatorPreferences— loads saved preferences on navigator initMobile.UpdateDocumentNavigatorPreferences— saves preferences when the user changes them
A preferencesHash (JSON hash of current preferences) is compared against the last saved hash before sending an update to avoid redundant server writes. study-navigator-context.js restores the previous session state when the user returns to the same study.
Source: SC/suredms-web-client/src/main/webapp/app/js/network/study/study-navigator.js