View source for UNC File Storage Layout

= UNC File Storage Layout =

The UNC File Storage Layout defines how local file documents are physically stored in the UNC document root. UBIK supports a flat layout and a folder-partitioned layout.

Folder partitioning is available from UBIK 5.2 and is the recommended layout for UNC file storage. To maintain downward compatibility, the default remains the existing flat layout until an administrator starts the transfer.

The layout changes only the physical file location. The document object and its '''LOCALPATH''' value remain unchanged.

== Scope ==

The UNC File Storage Layout applies only when '''File Storage Mode''' is set to '''UNC'''.

Folder partitioning is not a separate File Storage Mode. The existing modes remain unchanged:

{| class="wikitable"
! Value
! File Storage Mode
|-
| 0
| Undefined
|-
| 1
| UNC
|-
| 2
| Cloud
|}

Only local file documents with '''IsLocalDoc = true''' are affected. Cloud documents and non-local file documents are ignored.

== UNC File Storage Layout Setting ==

The database setting '''UNC File Storage Layout''' identifies the layout currently used by the database.

{| class="wikitable"
! Value
! Description
|-
| Flat
| Local file documents are stored directly in the document root folder.
|-
| Folder Partitioning
| Local file documents are distributed across generated subfolders based on the document UID.
|}

The setting is visible in the database settings but is read-only. It can be changed only by successfully completing the transfer tool.

For new and existing databases, the default value is '''Flat'''. Updating a database does not change its existing '''File Storage Mode''' or move any files automatically.

== Storage Layouts ==

=== Flat ===

With the flat layout, local file documents are stored directly in the document root folder.

Example:

:''.../doc/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

=== Folder Partitioning ===

With folder partitioning, UBIK generates two folder levels from the document UID:

* The first character of the UID is used for the first folder level.
* The second and third characters of the UID are used for the second folder level.
* Generated folder names use lowercase characters.

Example UID:

:''8ec24142-17eb-4640-bdcf-31d696c398de''

Resulting physical path:

:''.../doc/8/ec/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

== LOCALPATH and Physical File Resolution ==

The '''LOCALPATH''' property continues to contain only the file name and extension:

:''8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

Folder-partitioning subfolders are not stored in '''LOCALPATH'''. UBIK calculates the complete physical file path when the file is accessed, using:

* the document root path
* the File Storage Mode
* the UNC File Storage Layout
* the document UID and '''LOCALPATH'''

== Database-wide Layout ==

A database uses one UNC storage layout for all local file documents. Flat storage and folder partitioning must not be mixed within the same database.

After a successful transfer, all existing and newly created local file documents use the selected layout.

== Transferring Local File Documents ==

Administrators can transfer all local file documents to the other layout using:

:''Tools → Apply UNC File Storage Layout to All Files''

Tooltip:

:''Updates all local files to use the other UNC file storage layout.''

The tool is available only when '''File Storage Mode = UNC'''. Because there are only two layouts, UBIK determines the target automatically:

{| class="wikitable"
! Current layout
! Target layout
|-
| Flat
| Folder Partitioning
|-
| Folder Partitioning
| Flat
|}

The '''UNC File Storage Layout''' setting is changed only after all affected files have been transferred successfully.

=== Transfer Process ===

For each local file document, UBIK:

# calculates the current and target physical file paths
# creates the required target folders
# copies the file to the target path
# verifies that the copied file exists
# deletes the source file only after successful verification

If a file already exists at the target path, the transfer is aborted to prevent data loss.

The transfer changes only the physical storage location. It does not:

* change '''LOCALPATH'''
* update UTS
* create a new document version
* update the update session
* fire events

Empty folders may remain in the previous folder structure after the transfer, but they no longer contain transferred files.

=== Access During the Transfer ===

Local file documents are locked database-wide for all clients and services while the transfer is running. During this time, users and services cannot:

* create new local file document objects
* change existing local file document objects or their properties
* open, read, download, or view local document files

Cloud documents and non-local file documents remain available and are not affected by the lock.

== Transfer Result and Error Handling ==

After a successful transfer, UBIK changes the database setting to the target layout and displays the number of transferred files.

Example:

:''1000 files have been transferred.''

If the transfer fails or is interrupted:

* the transfer is aborted
* the affected file document is reported
* the '''UNC File Storage Layout''' setting remains unchanged
* the database is not left with a mixed UNC storage layout
* the administrator must start the transfer again

A transfer is aborted if a file cannot be found, copied, verified, or deleted, or if the target file already exists.

Failure message:

:''The transfer could not be completed. The UNC File Storage Layout has not been changed.''

== Example: Migrating an Existing Database ==

An existing UBIK database contains 1000 local file documents in flat UNC storage.

# The system is updated to UBIK 5.2.
# The existing File Storage Mode remains unchanged.
# The new '''UNC File Storage Layout''' setting is initialized as '''Flat'''.
# All existing documents remain readable in their current locations.
# An administrator selects ''Tools → Apply UNC File Storage Layout to All Files''.
# UBIK locks local file documents and transfers all files to the generated folder structure.
# After all files have been copied, verified, and removed from their source locations, the layout setting changes to '''Folder Partitioning'''.
# UBIK confirms that 1000 files have been transferred. <br>
<br>
From this point onward, newly created local file documents are stored using folder partitioning.

== See also ==

* [[SYSCLS_DOCUMENT]]
* [[SYSCLS_FILEDOCUMENT]]
* [[FILEDOCUMENT]]
* [[SYSCLS_EDITABLEDOCUMENT]]
* [[Documents (Client)]]

[[Category:Document|UNC File Storage Layout]]
[[Category:Studio|UNC File Storage Layout]]
[[Category:Studio tools|UNC File Storage Layout]]