AX1731

Enabling save locks for Axiom forms

You can enable "save locking" for an Axiom form, meaning that only one user at a time can save data from the form.

Axiom forms are always opened as read-only files. Users can save data to the database from the read-only file if they have the Allow Save Data permission. But because forms are never opened as read/write files, the file itself does not become locked to any particular user. This means that multiple users can access the form concurrently, and by default all of these users can save data from the form if they have the appropriate permissions.

In some cases this behavior is not desired, and you want only one user to be able to "reserve" the ability to save data from the form at any one time. In this case you can define a data context for the form, which enables one user to lock that context and save data. If another user accesses the form after the first user has locked it, that second user cannot save data until the first user releases the lock.

This process works as follows:

In the form source file, you define a data context, which is a unique name that represents the data save process in the form. This tells Axiom Software that you want only one user to be able to save data to this context at a time.
When a user with Allow Save Data permission accesses the file, they automatically acquire the "save lock" for that data context if it is available. This user can save data from the form as long as they have the save lock.
If other users with Allow Save Data permission access the form while the data context is locked to another user, they cannot save data. The save icon in the task bar and/or any components that are configured to save data are disabled.
When the user with the save lock releases it, another user can now acquire the lock for the data context and save data from the form.
When save locking is enabled, users have the option to view their current save lock status, and to release the lock or request the lock.

NOTE: For embedded forms, save locking can be configured at the parent form level, and will control saves in all embedded child forms. It is not possible to define different data contexts at the child form level and control them separately.

Defining the data context

To enable save locking for a form, complete the following fields on the default Control Sheet, in the Workbook Options section:

Item	Description
Data Context	The name of the data context (up to 250 characters). This can be a hard-coded name, or you can use a formula to define the name. For example, if the form is a plan file template, you may want the data context to be the current plan code plus the file group ID. You could use a formula like the following: =GetFileGroupID()&"_"&GetFileGroupProperty("PlanFile") This would create a data context something like 131_22000. IMPORTANT: Data contexts are applied across files. If you have two files that use the same data context name, then the save locking behavior will prevent concurrent saves in both files. If a user has the save lock for file 1, then other users cannot save data for that data context in either file 1 or file 2. If you want the data context to only apply to the current file, then you must make sure the data context name is unique to that file.
Data Context Description	The description of the data context (up to 200 characters). This can be hard-coded text, or you can use a formula to define the description. This description displays to users at the top of the Save Lock panel, when users are in the form. If left blank, then no description displays in the Save Lock panel. To continue the previous example, if the data context is 131_22000, you might want the description to read "Dept: 22000" or "Budget 2020: Dept 22000".

Item

Description

Data Context

The name of the data context (up to 250 characters). This can be a hard-coded name, or you can use a formula to define the name.

For example, if the form is a plan file template, you may want the data context to be the current plan code plus the file group ID. You could use a formula like the following:

=GetFileGroupID()&"_"&GetFileGroupProperty("PlanFile")

This would create a data context something like 131_22000.

IMPORTANT: Data contexts are applied across files. If you have two files that use the same data context name, then the save locking behavior will prevent concurrent saves in both files. If a user has the save lock for file 1, then other users cannot save data for that data context in either file 1 or file 2. If you want the data context to only apply to the current file, then you must make sure the data context name is unique to that file.

Data Context Description

The description of the data context (up to 200 characters). This can be hard-coded text, or you can use a formula to define the description.

This description displays to users at the top of the Save Lock panel, when users are in the form. If left blank, then no description displays in the Save Lock panel.

To continue the previous example, if the data context is 131_22000, you might want the description to read "Dept: 22000" or "Budget 2020: Dept 22000".

Example data context fields on Control Sheet

The third field, Is Data Context Checked Out, is maintained by Axiom Software when users access the file as a form. If the user currently has the save lock, this field is automatically set to On, otherwise it is set to Off. You can reference this field as needed to dynamically configure form components based on whether the current user has the save lock. For example, you may want to display a message to the user within the form if they cannot save data, or disable certain components.

The data context only applies to form-enabled files, and only when the file is opened as a form. The data context has no impact if the file is opened as a spreadsheet in the Desktop Client.

Save lock behavior

When a user accesses a form with a defined data context, whether or not they can save data depends on if they have the save lock.

By default, the save lock status displays as follows. This assumes that the form is configured to show the save icon in the task bar (which is the default behavior for newly created forms):

		User has the save lock and can save data
		User does not have the save lock and cannot save data

When a user with Allow Save Data permissions accesses the form, Axiom Software automatically acquires the save lock for the data context as long as no other user currently has it. This means that the save icon shows as active, the form property Is Data Context Checked Out is set to On, and the user can save data.

If another user already has the save lock when a second user accesses the form, then the save icon for the second user is inactive and shows as not allowing saves. As long as the first user has the save lock, the second user cannot save data. The form property Is Data Context Checked Out is set to Off.

The Save Lock dialog can be used to view the save lock status of all users accessing the form, and to release or acquire the save lock. This dialog can be opened as follows from the task bar:

The user with the save lock can click the down arrow next to the save icon to open the dialog.
Users without the save lock can click the inactive save icon to open the dialog.

The Save Lock dialog shows which user currently has the save lock. It also lists all other users who are currently viewing the form and could potentially acquire the save lock if it became available.

Example Save Lock panel where the current user has the save lock and can save data

Example Save Lock panel where the current user does not have the save lock and cannot save data

If desired, the user with the save lock can release it by clicking Release Lock. Once the lock is released, the user can no longer save data in the form, and Is Data Context Checked Out is set to Off.

If the lock becomes available, other users in the form can request it by clicking Acquire Lock. The first user to request the available lock will acquire it. If the lock is acquired, that user can now save data in the form, and Is Data Context Checked Out is set to On.

When the lock status changes due to an action in the Save Lock dialog, a full form update is triggered. This is necessary to reset the status of Is Data Context Checked Out, as well as to update the save icon in the task bar. When this update occurs, the triggering component is logged as Axiom.SaveLockPanel. If necessary, you can enable or disable queries based on this triggering component.

If the save lock is currently held by another user, it can be taken from that user using Acquire Lock as follows:

Administrators can take locks from other users at any time. This should only be done when absolutely necessary, as it means that the user with the lock will no longer be able to save data from their session once the administrator takes the lock.
If a user is logged into two different browser sessions, and they have the lock in one session, they can take the lock from themselves. Again, this means that data can no longer be saved from the session without the lock.

If a user does not explicitly release the lock using the Save Lock dialog, then it is automatically released when one of the following occurs:

The user logs out of the Web Client.
The user navigates to a different form or page in the Web Client. There may be a brief delay of 20 seconds or so before the lock is released.
The active data context for the form changes (see the following section).
The user completes the currently active process task, using either of the following button behaviors: Submit Process or Reject Process.
The user closes the browser tab in the Web Client, or the file tab in the Windows Client. For most browsers, there may be a brief delay of 10 seconds or so before the lock is released. However, when using Microsoft Internet Explorer, it may take approximately 5 minutes before the lock is released.

NOTES:

The locking behavior only applies if a data context is defined and a save-to-database is enabled in the file. Additionally, the Web Client Container must be enabled for the form.
If a user does not have Allow Save Data permissions, then the locking behavior does not apply. The user does not show in the Save Lock dialog because they do not have the potential of acquiring the save lock.
If the save-to-database is not enabled when the form is initially opened, the locking behavior does not apply. If the save-to-database later becomes enabled in the same session, the locking behavior becomes active and Axiom Software attempts to automatically acquire the lock. This only occurs the first time the save-to-database is enabled during a session.
Once a user has released the save lock for a particular data context, Axiom Software will not try to automatically acquire it within the same session. If the user wants to reacquire the lock, they must use the Save Lock dialog to request it.
If necessary, an administrator (or other user with the necessary security permissions) can break save locks. For more information, see Administering save data locks for Axiom forms.

Save lock behavior when not using the default save icon

If the form is not configured to use the default save icon in the task bar, then the save lock status displays as follows:

		User has the save lock and can save data
		User does not have the save lock and cannot save data

In this case, the save lock status icons are primarily informational because the user cannot also save data using the icon. Instead, the user must use a component within the form that is configured to Save on Submit. This configuration is intended to support backward-compatibility for forms that were created before the introduction of the save icon in the task bar, and also to support forms that need to use Save on Submit components instead of the save icon.

With the exception of the different icons, the save locking feature otherwise behaves in the same way. For example:

If the user does not have the save lock, they cannot save data from the form. Any Save on Submit components in the form are automatically disabled.
The user can click the save lock status icon in the task bar to open the Save Lock dialog. The dialog contents are the same, depending on whether the user has the lock or not.

Dynamically changing the data context

If a form is designed to save to different contexts depending on user selections, you can dynamically change the data context as well. For example, you may have a form that is designed to save data to a specific department, depending on the selection of a refresh variable. If the current department is 100, you don't want any other users to also save data to department 100 using this form. But other users can use the same form to save data to different departments.

Dynamic data contexts can be set up as follows:

Use a refresh variable (or an interactive form component) to determine the data that gets saved in the save-to-database process. For example, you can prompt the user to select a department or entity. The file is then refreshed with data as needed for the selected department or entity. The user can make inputs as appropriate and then save the data.
In the Data Context field, use a formula that sets the data context to the selected value of the refresh variable (plus any other attributes necessary to make the data context unique). You would also want the Data Context Description to change dynamically.

If the data context is dynamic and can change within the current session, it is treated as follows:

When the data context is changed, Axiom Software automatically attempts to acquire the save lock for the new context if it is available.
If the current user had a save lock when the data context was changed, the previous save lock is released.

Imagine that the data context uses the current value of a department refresh variable. When a user first opens the form, the department variable is not set and there is no data context. The user selects department 100 and refreshes. Axiom Software automatically attempts to acquire the lock for the department 100 data context. Once acquired, the user can save data within the form.

Within the same session, the user changes the value of the department variable to 200 and refreshes. Now Axiom Software releases the lock for 100, and attempts to acquire the lock for 200. If another user accesses the form at this point, they can now acquire the lock for 100.

NOTE: The data context itself only enables or prevents saving data; it does not control what data can be saved. If you want the file to only save data to department 100 when the data context is department 100, then you must configure the file as necessary so that the data queries and save-to-database are limited to that department.