New settings for persistent locks

[mmattel]

What Needs to be Documented?

New UI setting created in docs, referencing:
owncloud/core#36452 (Include settings for the persistent locks)

Where Does This Need To Be Documented?

Admin/Storage section

Why Should This Change Be Made? (Optional)

Changes made in core

What Type Of Content Change Is This? (Optional)

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

Which Manual Does This Relate To? (Optional)

• Admin Manual
• Developer Manual
• User Manual
• Android
• iOS
• Branded Clients
• Desktop Client
• Other

@jvillafanez @micbar @pmaier1

[mmattel]

Referencing: #2663 (Core: new functionality: file action to explicitly lock a file)

Which is the component for the user

[pmaier1]

Thanks for opening this! Here's some general input on file locking which I have written for the release notes:

---

ownCloud Server 10.5 comes with great enhancements for content collaboration. Manual file locking allows users to lock files in shared areas while working on them in order to prevent concurrent changes from other users (check-in/check-out).

The feature builds on the xref:release_notes.html#webdav-locks[WebDAV Locks backend] which has been introduced with Server 10.1 and is now available in the ownCloud Web Interface. Using the context menu of files, every user who has access can lock them. Users can recognize locked files by the means of a new lock indicator. While a file is locked, other users can still access it but they can not make any changes. Locked files can manually be unlocked by the lock owner (the user who locked the file; exclusive locking) using the "Locks" tab in the file details view (right sidebar).

To prevent files being locked infinitely, there is a mechanism that automatically expires locks after a certain time. The expiration time of locks can be configured via the "Manual File Locking" section in the Admin -> Additional settings or using occ commands:

• Default timeout for the locks if not specified (in seconds): Maximum lifetime of a lock set via the web interface (or by not specifying a timeout value when calling the WebDAV Locks API)
  occ config:app:set files lock_timeout_default --value 1800

• Maximum timeout for the locks (in seconds): Maximum lifetime of locks which is allowed to be set by calling the WebDAV Locks API
  occ config:app:set files lock_timeout_max --value 86400

By default locks set in the web interface will expire after 30 minutes. The maximum lock time by default is one day.

TIP: Please change the lock expiration settings according to your needs. Usually you will only need to change the default timeout as this applies to locks set in the web interface.

TIP: The user-facing components in the web interface are disabled by default. Administrators can enable the feature by executing the following occ command: occ config:app:set files enable_lock_file_action --value yes

[mmattel]

@pmaier1 pls ping me on talk

[jvillafanez]

By default locks set in the web interface will expire after 30 minutes. The maximum lock time by default is one day.

We probably need to clarify if the web UI will explicitly set 30 minutes of expiration, or if it will use whatever value is the default. For me, it isn't clear if changing the default value in the settings will affect the web UI

[jvillafanez]

As far as I see in the PR, there is no explicit lock timeout being set, so it will use whatever default value is configured in the settings page.

[mmattel]

For the reference, the code in core has hardcoded limits set, see:

class LockManager {

 	const LOCK_TIMEOUT_DEFAULT = 30 * 60;  // default 30 minutes
 	const LOCK_TIMEOUT_MAX = 24 * 60 * 60;  // max 1 day

[jvillafanez]

If the admin doesn't configure any value, those will be used as default and max values.

[mmattel]

We have to be more precise.
Not only in case you have no max value set, but also if you have set a value greater than the max value.

if ($timeout < 0 || $timeout > $maxTimeout) {
	// ensure the timeout isn't greater than the one configured as maximum
	$timeout = $maxTimeout;

This is important, because this is the reason for closing owncloud/core#37579 (No limits for for persistent lock values)

[jvillafanez]

The process of setting the effective timeout is explained in owncloud/core#36452 (comment) , ensuring the effective timeout is always in range.

[voroyam]

Thanks for opening this! Here's some general input on file locking which I have written for the release notes:

ownCloud Server 10.5 comes with great enhancements for content collaboration. Manual file locking allows users to lock files in shared areas while working on them in order to prevent concurrent changes from other users (check-in/check-out).

The feature builds on the xref:release_notes.html#webdav-locks[WebDAV Locks backend] which has been introduced with Server 10.1 and is now available in the ownCloud Web Interface. Using the context menu of files, every user who has access can lock them. Users can recognize locked files by the means of a new lock indicator. While a file is locked, other users can still access it but they can not make any changes. Locked files can manually be unlocked by the lock owner (the user who locked the file; exclusive locking) using the "Locks" tab in the file details view (right sidebar).

To prevent files being locked infinitely, there is a mechanism that automatically expires locks after a certain time. The expiration time of locks can be configured via the "Manual File Locking" section in the Admin -> Additional settings or using occ commands:

• Default timeout for the locks if not specified (in seconds): Maximum lifetime of a lock set via the web interface (or by not specifying a timeout value when calling the WebDAV Locks API)
  occ config:app:set files lock_timeout_default --value 1800
• Maximum timeout for the locks (in seconds): Maximum lifetime of locks which is allowed to be set by calling the WebDAV Locks API
  occ config:app:set files lock_timeout_max --value 86400

By default locks set in the web interface will expire after 30 minutes. The maximum lock time by default is one day.

TIP: Please change the lock expiration settings according to your needs. Usually you will only need to change the default timeout as this applies to locks set in the web interface.

TIP: The user-facing components in the web interface are disabled by default. Administrators can enable the feature by executing the following occ command: occ config:app:set files enable_lock_file_action --value yes

@pmaier1 I edited your comment from --value true to --value yes because in the final version it's got to be "yes". I hope you are fine with it.

[pmaier1]

@pmaier1 I edited your comment from --value true to --value yes because in the final version it's got to be "yes". I hope you are fine with it.

Sure, thanks. Actually this is outdated. The source of truth are the release notes https://doc.owncloud.com/server/admin_manual/release_notes.html#file-locking-in-the-web-interface

[voroyam]

Great. We done a great job advertising the new feature but no one documented it. Perfect. Issue is open since January. 1 Year no progress. Please don't write "PR welcome".

[mmattel]

Somone writing a PR is still welcome!
Even such a PR must undergo the very normal time consuming process of writing, adoptig, tuning and quality checks, the invite statement is totally ok. If the focus is not set to such a task, the result is the outcome you describe. And yes, this is frustrating!
BTW, there are tons of other open issues pointing to work to be done...

[voroyam]

The difference is - we (ownCloud) don't advertise the other stuff publicly like:
"Hey -Look at this new awesome Feature (...for what we don't have a real documentation, just a blog entry) get it while it's hot!"

[voroyam]

#2888

[voroyam]

no one will do it if I don't do it myself.

Apparently I am the only one who is ashamed when Customers ask me: "where is this documented?" and I can't provide them a proper page...

[voroyam]

I am out. Will send our blog articles instead.

[voroyam]

fixed with #2903