Home >

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. 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.

• The current lock status is shown using an icon in the gray task bar across the top of the form. Users can click the icon to open the Save Lock panel. This panel lists the user with the save lock, as well as other users who are currently viewing the form as read-only. This panel can be used to release the lock, and to acquire the lock (in certain cases).

NOTE: For composite 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 2019: 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, the current lock status is displayed in the right-hand side of the gray Task BarThe gray bar across the top of pages in the Web Client. The Task Bar provides access to various tasks that are specific to the current area, page, or document.. The status displays as follows:

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 icon shows as allowing saves, 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 user accesses the form, then the icon 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, and any components with Save on Submit enabled show as disabled in the form.

Users can click the save lock status icon to open the Save Lock panel. This panel shows all users who are currently accessing the file. The user with the save lock is shown with the lock next to their name. All other users show as read-only, with an eye icon.

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. Is Data Context Checked Out is set to Off, and components with Save on Submit enabled are disabled.

If the lock becomes available, other users in the form can request it by clicking Request 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. Is Data Context Checked Out is set to On, and components with Save on Submit enabled are enabled.

When the lock status changes due to an action in the Save Lock panel, a full form update is triggered. This is necessary to reset the status of Is Data Context Checked Out and any Save on Submit components. 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 Request Lock as follows:

• Administrators can request and 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 panel, 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 user closes the browser tab. In this case it takes about 5 minutes before the lock is released.
• The active data context for the form changes (see the following section).

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. The user is "downgraded" to read-only for the previous data context.

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. If the second user views the Save Lock panel, they will see the first user listed as a read-only user for department 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.

Administering save locks

Using the Save Lock Administration page in the Web Client, you can view all active sessions relating to data contexts in Axiom forms, and break save locks if necessary.

Only administrators, subsystem administrators, and users with the Administer Locked Items security permission can access this dialog and remove save data locks. Users with the Administer Locked Items security permission are limited to managing locks relating to documents that they have some level of access to. Subsystem administrators also have this limitation, plus they are limited to managing locks held by users in their subsystem.

To access the Save Lock Administration page:

1. In the Web Client, click the menu icon in the Global Navigation BarThe blue bar across the top of pages in the Web Client. The Global Navigation Bar provides access to system-wide features.. From the Area menu, select System Administration.

   

2. From the Navigation panel, select Tools > Save Lock Administration.

   

Alternatively, you can go to directly to the Save Lock Administration page as follows:

Example On-Premise URL		http://ServerName/Axiom/SaveLocks Where ServerName is the name of the Axiom Application Server, and Axiom is the default name of the virtual directory.
Example Cloud System URL		https://CustomerName.axiom.cloud/SaveLocks Where CustomerName is the name of your cloud service system.

The Save Lock Administration page displays a list of all data contexts that are currently active in at least one session.

Example active data contexts

To view the active sessions for a data context and see the users, click View Sessions. Then, if you need to break a save lock, click Break Lock.

Example active sessions for a data context

IMPORTANT: If the user is actually in the form when you break the lock, then that user may not be able to save their changes. If the form does not become locked to any other user in the meantime, then the user can reacquire the lock. However, if another user has acquired the save lock, then the original user will be unable to save.