Actions and results
What each Documents button and automatic behaviour does, with worked numbers and what the system refuses.
On this page (16)
Library
| Action | When | What you do | What happens |
|---|---|---|---|
| Open the library for the first time | A test company with Documents installed and no library yet | Open Documents > Library | Starting masters created once: 4 retention policies (COMMERCIAL 5 y, TAX 5 y, PERSONNEL 5 y from expiry, PERMANENT 100 y), 6 document types (CONTRACT, LICENCE, CERTIFICATE, FINANCE, POLICY, GENERAL) and 6 workspaces (Company, Finance, Human Resources, Contracts, Legal, Shared); the index of other modules' files is built |
| Files other modules keep appear | A test sales order with an attachment, a test employee with a passport document, a project document | Open Library, Every store | All three listed with their Store (Record attachments, Employee documents, Project documents) and Linked record (e.g. SO number - customer); they are not copied, only indexed |
| Tab counts | 3 active files, 1 uploaded by you, 1 expiring in 45 days | Look at the tabs | All 3, My documents 1, Expiring 1, Quarantine 0; counts follow the Workspace / Store / Linked to / Kind / held filters |
| Filters narrow on the server | Files in several stores | Choose Store = Employee documents, then Kind = PDF, then tick Under legal hold | Each choice narrows the list and the tab counts; choosing a Workspace sets Store to Library; clearing restores all |
| Search | A file tagged 'renewal' and a contact file for 'TEST Trading' | Search 'renewal', then 'TEST Trading' | Finds by tag and by linked record label; search runs on the server across pages |
| Sort and paging | More than 80 files | Sort by Size descending; go to page 2 | Order kept across pages (server sort); 80 rows per page by default |
| List / Grid view | Switch to Grid; reload the page | Cards with icon (or image thumbnail), name, record, state chip and size; Grid is remembered after reload | |
| State chip rules | Files: expiry in 45 days, expired yesterday, expiry in 120 days, archived, held | Look at State | Expiring (amber), Expired (red), Available (green), Archived (grey), Held (red); held wins over expiry; a file removed at source shows 'Removed at source' |
| Size display | Files of 900 bytes, 1,536 bytes and 1.5 MB (1,572,864 bytes) | Look at Size | '900 B', '2 KB' (1,536 / 1,024 = 1.5, rounded), '1.5 MB' |
| Side panel | Click a row | Panel opens: Preview with key facts; Details (size, type with MIME tooltip, SHA-256 short, uploaded by / at, tags, hold reason); Versions (library files only); Activity; buttons Open document and Download | |
| Refresh index | Add an attachment to a test sales order in Sales | Library > Refresh index | The new attachment appears at once (otherwise within 10 minutes - the index refreshes itself when older than 10 minutes); tooltip shows 'Indexed <date time>' |
| File removed at its source | An indexed attachment | Delete the attachment in its module; Refresh index; tick Library filters to see removed files via API state=missing | Row kept as a tombstone (present = false) with state 'Removed at source'; opening its content answers 'This file has been removed from the module that kept it.' (410) |
| Export manifest | Some filtered rows, one named '=SUM(A1)' (test) | Export manifest | document-manifest.csv (UTF-8 with BOM) with Name, Store, Linked record, Record type, Category, Kind, Size (bytes), SHA-256, Version, Uploaded, Uploaded by, Expires, Legal hold, Sensitivity, Tags; only the rows you can see under the filters; '=SUM(A1)' written as text with a leading apostrophe; audit 'Export manifest' with the file's hash |
| Export limit | A view holding more than 10,000 files (2,000 x 5) | Export manifest | Refused: 'This view holds <n> files. Narrow it before exporting.' |
Upload wizard
| Action | When | What you do | What happens |
|---|---|---|---|
| Upload one PDF | dms.manage | Upload; choose a 1 MB PDF; Continue; Type Licence or permit, Expiry 31 Dec 2026, tag 'licence', folder Legal; Continue; Library only; Review; Upload 1 file | File state Checking -> Ready -> Filed; dialog closes, Library switches to My documents showing it as Version 1, Owner = you, Classification 'Licence or permit', Sensitivity Internal; audit 'file uploaded v1 <bytes> bytes' |
| Several files at once | Choose 3 files (PDF, DOCX, XLSX); keep Apply to all ticked; set type General document and tag 'batch'; Upload 3 files | Tally '3 accepted - 0 rejected'; all three filed with the same type and tag; Review lists each with Type, Folder, Expires | |
| Per-file classification | Choose 2 files; step 2 untick 'Apply these values to all accepted files'; click the second file on the left and give it another type | Each file keeps its own values; Review shows the different types | |
| Refused file is never sent | Choose test.exe, a .bat, an .svg and a valid PDF | The three are Rejected with the reason beside them ('.exe files are not kept in the library: programs, scripts and web pages can run.' etc.); tally '1 accepted - 3 rejected'; only the PDF is uploaded | |
| Type read from the bytes | A text file renamed invoice.png; a real PNG renamed scan.pdf | Choose both | invoice.png refused 'This file is named as an image but its contents are text/plain.'; scan.pdf accepted and shown as Image (the bytes decide) |
| HTML disguised as text | A file notes.txt whose content starts with <html> | Choose it | Refused: 'This file is a web page (HTML), which can run scripts; it is not kept.' |
| Image bomb | A tiny PNG declaring 20,000 x 20,000 pixels (400 million; limit 50 million) | Choose it | Refused: 'This image unpacks to far more pixels than any document needs, and is refused.' |
| Damaged files | A truncated JPG; a .zip with broken bytes | Choose them | 'This image is damaged and cannot be read.'; 'This file says it is a zip archive but is damaged.' |
| Type limits re-checked | Choose a 30 MB PDF and a JPG; step 2 choose type Contract (pdf, word, 25 MB) | Both re-checked: PDF 'The file is 30.0 MB; this document type takes at most 25 MB.' (413); JPG 'This document type takes pdf, word files, not image.'; both turn Rejected | |
| Default size limit | Choose a 60 MB PDF with no type | Rejected: 'The file is 60.0 MB; this document type takes at most 50 MB.' A 210 MB file: 'A file may be at most 200 MB.' | |
| Duplicate warning (hash) | A PDF already in the library or attached to a sales order | Upload the same file again | Review warns '<file> is already held as "<name>" (<store>, <record>).' The upload is still allowed; both rows show the same SHA-256 and the bytes are stored once |
| Expiry warning | Type Licence or permit (carries an expiry) | Leave Expiry empty; go to Review | Warning '<file>: Licence or permit usually carries an expiry date.' Upload still allowed |
| Unclassified warning | Leave type Unclassified; Review | Warning '<file>: no document type - it will be filed as unclassified.'; with no warnings 'Everything required is filled in.' | |
| Link to a record | A test customer TEST Trading LLC; you hold partner.view | Step 3: Record type Contacts; type 'TEST'; pick the customer; Upload | Continue disabled until a record is picked; filed with Linked record 'TEST Trading LLC'; the customer's Documents button count rises by 1 |
| Cancel leaves nothing | Choose 2 valid files, reach Review, press Cancel | Nothing stored: Library and Storage usage unchanged (the check step stores nothing) | |
| Partial failure | Choose 2 files; before Upload, in another tab archive the chosen document type; Upload | Files refused show 'Failed' with 'Choose an active document type.'; message 'Some files were not filed; their reasons are shown beside them.'; dialog stays open; filed ones are not uploaded twice on retry | |
| Required description (field setting) | Fields: Document description = Required (approved) | Upload a file with empty description | Upload blocked: 'This company requires a description on every document: <file>.'; field shows *; with a description it files |
Document record
| Action | When | What you do | What happens |
|---|---|---|---|
| Open read-only | A library file | Open document | Read-only; Edit, New version, Download in the action row; More menu shows hold / archive / disposal per rights; viewer left, four cards right |
| Edit and save metadata | Edit; change Name, type to Certificate, Sensitivity Confidential, Folder Legal, tags 'a, b'; Save | 'Saved.'; values shown; History adds 'file updated' with the changed keys (name, folder, tags, type) before/after; revision +1 | |
| Discard | Edit; change Name; Discard | Stored values back; nothing saved | |
| Edit conflict | Same document open in two tabs | Tab 1 Edit + Save; tab 2 Edit + Save | Tab 2 refused 'This record changed. Reload it before saving.' |
| New version | A library file at version 1 | New version; choose an updated PDF | 'Version 2 published.'; chip Version 2; Versions tab: v2 current, v1 kept with its own SHA-256, size and uploader; audit 'version published v2 <hash>' |
| Old version stays readable | File with v1 and v2 | Versions tab: View on v1; Download on v1 | Viewer shows v1 and chip 'Version 1'; download gives the v1 bytes (same SHA-256 as listed); Download in the action row follows the version shown |
| New version obeys the type | File of type Contract (pdf, word, 25 MB) | New version with a JPG | Refused: 'This document type takes pdf, word files, not image.'; still version 1 |
| Restore an older version | File with v1 and v2 | Look for a Restore / Make current action | Not built: only View and Download per version. To restore, download v1 and upload it as a new version (v3, same hash as v1) - note |
| Check-out / check-in | Look for Check out / Lock for editing | Not built: anybody with dms.manage can add a version; concurrent new versions are separated only by the revision check - note | |
| Archive and restore | Active library file | More > Archive; check Library; More > Restore from archive | 'Archived.' - file leaves the All tab (state archived); 'Restored.' - back in All; History records both |
| Links tab | A file linked to a customer | Open Links | Store Library, Business record 'Contacts: TEST Trading LLC', Needs permission partner.view (library-only files show dms.view) |
| Indexed file from another module | An employee passport (Employee documents) | Open document | No Edit / New version / Archive; Policy 'Kept by its module'; Links: 'the file stays in that module and opens under its rules'; legal hold available to dms.dispose holders |
| History | A file uploaded, edited, held and released | History tab | Every library event with user and Dubai time: file uploaded, file updated, hold placed, hold lifted, version published, disposal proposed / approved (max 200) |
| Place legal hold | dms.dispose | More > Place legal hold; matter 'Dubai Courts case TEST-2026-001'; Confirm | 'Legal hold placed.'; chip Held; Retention card 'Legal hold: Yes - Dubai Courts case TEST-2026-001'; Propose disposal disabled; file appears with 'Under legal hold' filter |
| Hold needs a reason | Place legal hold with an empty matter | Refused: 'Say why the file is held - the legal request or matter.' | |
| Release legal hold | A held file | More > Release legal hold; reason; Confirm | 'Legal hold released.'; hold reason cleared; Propose disposal enabled again; audit 'hold lifted' |
| Hold an indexed file | An attachment of a test sales order | Place legal hold on it | Held in the library only (index row); the sales order and its attachment are not changed; shown Held in the Library |
| Retention date (from filing date) | Upload a Contract (COMMERCIAL 5 y from filing) on 2 Oct 2026 | Retention card | Policy 'Commercial records'; Eligible 02 Oct 2031 (2 Oct 2026 + 5 years) |
| Retention date (from expiry) | Type with PERSONNEL (5 y from expiry); file expires 15 Mar 2027 | Retention card | Eligible 15 Mar 2032; with no expiry it falls back to the filing date (2 Oct 2026 -> 2 Oct 2031) |
| 29 February | Policy 1 year from expiry; file expires 29 Feb 2028 | Retention card | Eligible 28 Feb 2029 (no 29 Feb in 2029) |
| No policy | Unclassified file or GENERAL type (no policy) | Retention card; try Propose disposal | Policy None, Eligible -; propose refused 'This file is kept until its type has a retention policy; it is not yet eligible.' |
| Not yet eligible | Contract uploaded today (eligible 2031) | More > Propose disposal; Confirm | Refused: 'This file is kept until 2031-10-02; it is not yet eligible.' |
| Propose disposal | An eligible, unheld file (TESTDISP); user A with dms.dispose | A: More > Propose disposal; reason 'Test retention ended'; Confirm | 'Disposal proposed. Somebody else must review it.'; Retention tab 'Disposal: proposed - Test retention ended'; Disposal review lists it, Proposed by A |
| Propose twice | A proposal already open | Propose disposal again | No second row: the open proposal is returned |
| Disposed file is frozen | A disposed file | Open it | No Edit / New version / Archive / Propose; API edit 'A disposed file is not changed.'; API new version 'A disposed file takes no new versions.' |
Retention policies / Document types
| Action | When | What you do | What happens |
|---|---|---|---|
| Make a file eligible today (test set-up) | dms.configure | New policy TEST0, 0 years, from filing date; New type TESTDISP using it; upload a file of that type | Retention 'Eligible' = today; the file appears in Disposal review > Past their retention |
Disposal review
| Action | When | What you do | What happens |
|---|---|---|---|
| Proposer cannot decide | A's proposal | A opens Disposal review | Row shows 'Awaiting another reviewer' (no buttons); API decide by A refused 'Somebody other than the person who proposed it must review a disposal.' |
| Approve and dispose | A's proposal; user B with dms.dispose | B: Approve and dispose; confirm the browser prompt | State approved, Reviewed by B; file state Disposed; bytes deleted from storage; Retention register 'Disposed - tombstones' lists it; versions show 'disposed'; download refused 'This file's content has been disposed of; only its record remains.'; audit 'disposal approved - bytes deleted, tombstone kept' |
| Reject | A proposal | B: Reject; confirm | State rejected, Reviewed by B; file unchanged; a new proposal can be made later |
| Decide twice | An approved proposal (two tabs open) | Approve again from the stale tab | Refused: 'This record changed. Reload it before saving.' (or 'This disposal is already approved.') |
| Hold placed after proposal | A's proposal open | C places a legal hold on the file; B approves | Refused: 'This file was placed under legal hold after the proposal; it is not disposed of.'; bytes kept |
| Shared bytes survive | File X and file Y uploaded with identical bytes; X eligible | Dispose of X (propose A, approve B); open Y | Y still previews and downloads (the stored object is kept while another file points at it); X tombstone keeps name, hash and versions |
| Held files never eligible | An eligible file under legal hold | Open Disposal review | Not listed in 'Past their retention' |
Preview
| Action | When | What you do | What happens |
|---|---|---|---|
| PDF inline | A 3-page PDF | Open it | Shown in the browser's own PDF viewer inside the page; header '3 pages'; Download works |
| Images | A JPG | Open; Zoom in, Zoom out, Rotate, Full screen | Image shown; zoom and 90-degree rotation work; full screen toggles |
| Excel / Word / PowerPoint without LibreOffice | A 2-sheet .xlsx, a .docx with a table, a 3-slide .pptx | Open each | Sheets as tables with sheet tabs (first 500 rows, 60 columns, 12 sheets); Word as headings, paragraphs and tables; slides with title, bullet lines and a strip 'n of 3' |
| Office as PDF | Server has LibreOffice or A2N_DMS_OFFICE_VIA_GOTENBERG=1 | Open a .docx | Shown as PDF with ' - converted from Office'; converted once and cached by hash |
| Old Office format | A .doc file, no converter on the server | Open it | 'This older Office format needs LibreOffice on the server to preview. Download it to open it.' with Download |
| CSV, text, e-mail, ZIP | A .csv, a .txt over 300 KB, a .eml with an attachment, a .zip | Open each | CSV as a table; text with 'Only the beginning is shown. Download for the rest.'; e-mail with Subject, From, To, Date, Attachments; ZIP lists entries and sizes |
| Audio / video | An .mp3 and an .mp4 | Open each | Browser player with controls |
| HTML kept by another module | An .html attachment saved by another module (if any) | Open it in the library | 'This file's contents can run in a browser, so it is only downloaded.'; download only |
Documents smart button
| Action | When | What you do | What happens |
|---|---|---|---|
| Count across stores | A test customer with 1 attachment (Contacts) and 2 library files linked to it | Open the customer | Smart button 'Documents 3'; refused or no right -> no button (never a wrong count) |
| Open narrowed library | Click Documents | Library opens with bar 'Documents of Contacts: TEST Trading LLC' and only that record's files; 'Show all documents' clears it | |
| Upload from the record | Library narrowed to a record | Upload; go to step 3 | Record type and record already filled; the new file is filed on that record |
| Other records | Open a test sales order, invoice, product, employee, vehicle, manufacturing order and project | Each shows the Documents button with its own count |
Expiring documents
| Action | When | What you do | What happens |
|---|---|---|---|
| Window | Files expiring in 20, 50, 100 days and one expired last week | Within 30, 60, 90, 180 days | 30: expired + 20-day (2); 60: + 50-day (3); 90: 3; 180: 4; sorted earliest first; includes other stores (employee passports, vehicle registrations) |
Retention register
| Action | When | What you do | What happens |
|---|---|---|---|
| Library files and tombstones | Active, held and disposed library files | Open | Active files with Legal hold reason and Versions; disposed ones under 'Disposed - tombstones (n)' |
Storage usage
| Action | When | What you do | What happens |
|---|---|---|---|
| Totals | Library holds a 1.5 MB and a 3 MB file; attachments 2 MB | Open | Library 2 files 4.5 MB; Record attachments 1 file 2.0 MB; KPI 3 files, 6.5 MB; by kind totals add up to the same; only what you can see |
Workspaces and folders
| Action | When | What you do | What happens |
|---|---|---|---|
| Create workspace and sub-folder | dms.configure | New folder 'Test workspace' (Top level); New folder 'Licences' inside it | Both listed; Inside shows 'Workspace' / 'Test workspace'; Upload and Library Workspace lists include them |
| Folder with a permission | A user U with dms.view but not hr.private.view | Edit 'Licences': Only for permission hr.private.view; U opens Library | U no longer sees the folder or any file in it (and its sub-folders); an admin still does; files are re-indexed with the permission |
| Folder loop refused | Folder A with child B | Edit A: Inside = B | Refused: 'A folder cannot sit inside itself.' |
Document types
| Action | When | What you do | What happens |
|---|---|---|---|
| Create and use a type | New type TESTLIC, pdf + image, 15 MB, Licence policy, Carries an expiry; upload a 16 MB PDF with it | Type listed; upload refused 'The file is 16.0 MB; this document type takes at most 15 MB.' | |
| Archive a type | Edit TESTLIC: tick Archived; open Upload | Not offered in Upload or Edit lists; existing files keep it |
Retention policies
| Action | When | What you do | What happens |
|---|---|---|---|
| Edit a policy | A file under COMMERCIAL eligible 2 Oct 2031 | Edit COMMERCIAL: 7 years | The file's Eligible date becomes 02 Oct 2033 (computed live); audit 'retention saved - 7 years from created' |
Indexed stores
| Action | When | What you do | What happens |
|---|---|---|---|
| Which stores you can open | A user with dms.view and fleet.view only | Open Indexed stores | Fleet documents and Library 'Can open'; Employee documents (hr.private.view), Recruitment (hr.applicant.all), Payroll (payroll.view) etc. 'Hidden from you' |
Applications > Documents > Features
| Action | When | What you do | What happens |
|---|---|---|---|
| Turn off Retention and disposal | Admins A and B | A proposes Retention and disposal = Off; B approves | Menus Disposal review, Retention register, Retention policies disappear; saving a policy or deciding a disposal refused 'Retention and disposal is disabled for this company.' (409 capability_disabled); existing records still readable |
| Turn off Indexed external stores | Admins A and B | Propose Off; approve; press Refresh index | Menu Indexed stores disappears; Refresh index refused 'Indexed external stores is disabled for this company.' |
| Protected switches | Try to turn off Legal hold | Library and Legal hold are always on; Legal hold is protected and cannot be turned off |
Applications > Documents > Fields
| Action | When | What you do | What happens |
|---|---|---|---|
| Hide Document date | Admins A and B | Set Document date = Hidden; approve; open Upload and a document record | Date box gone from the wizard and the record (unless a value exists, then shown disabled) |
| Require Folder description | Set Folder description = Required; approve; create a folder without one | Refused: 'Folder description is required by this company.'; label shows * |