AX2135

Saving data from an Axiom form

You can save data to the Axiom Software database from an Axiom form. For example, you might want to allow users to save comments about the data in the form, or use the form as a data input tool.

Only data saves are supported in Axiom forms. It is not possible to save the source file when it is being viewed as an Axiom form.

Configuring an Axiom form to save data

To set up an Axiom form to save data, you must do the following:

• Configure the source file for the Axiom form with a save-to-database process. This is the same setup that you would use for any Axiom spreadsheet file—for example, to enable Save Type 1 for a report or for a plan file template. Axiom forms can execute either Save Type 1 or Save type 4. When using Save Type 1, note that you may not want to enable Zero on Save in this environment, since data from previous saves is not persisted in the file.

• Configure the Axiom form with interactive components to collect user input, such as a combo box or a text box, or a formatted grid with one or more editable cells. The save-to-database process and the interactive component must interact in some way in the source file, so that when the user changes the interactive component and the updated state is submitted back to the source file, the data to be saved to the database updates in response.

By default, Axiom forms automatically use a save icon that displays in the right side of the Task BarThe gray bar that displays across the top of browser-based Axiom files, as well as various feature pages of the Web Client. The Task Bar provides access to various tasks that are specific to the current area, page, or document.. If a save-to-database process is enabled in the form, and the user has the appropriate security permissions to save data from the form, then this icon is active and can be used to save data. It is also possible to trigger the save from a button or another interactive component—for more information, see Alternate ways to trigger a save to database in a form.

IMPORTANT: For embedded formsBy using an Embedded Form component, a parent form can display one or more child forms within the same form instance. These forms can share values and leverage other special update and save behaviors., the save icon does not display if it is only enabled for the embedded child form. The parent form controls whether a save icon displays, and the icon only triggers a save-to-database in the parent form. This process can still be used to save data in a child form, but only when using the "manual save from parent" approach as described in Saving data for embedded forms.

Example form with save icon in Task Bar

When a user clicks the save icon, the full Axiom form update cycle is triggered, including submitting changed values, running Axiom queries, and then saving data to the database. For more information on the form update cycle, see Update and save behavior for Axiom forms and Axiom form update process. When the update cycle is triggered by the save icon, the Triggering Component is set to Axiom.FormSave.

If the form uses Axiom queries, it is important to understand the timing of when these queries are executed in relation to the save-to-database process. If your queries are not configured correctly, you may experience behavior such as the query overwriting the data to be saved to the database, or the query not showing data that was just saved to the database. For more information, see Axiom queries and saving data.

IMPORTANT: The source file for the Axiom form is not saved when a save-to-database is triggered from the Axiom form—only data can be saved when using this environment. If the data saved to the database is expected to be displayed in the Axiom form the next time a user accesses the form, you must configure the form so that any saved data will be queried back into the file using Axiom queries or GetData (functions or data lookups).

Alternate ways to trigger a save to database in a form

By default, all new Axiom forms are configured to use the save icon in the task bar to trigger a save-to-database. This is the preferred way to configure forms, to provide a consistent and intuitive way for users to save data from Axiom forms.

It is also possible to configure specific buttons and other interactive components in the form to trigger a save-to-database. This is the legacy way to configure saving data in an Axiom form, for older forms that were created before the introduction of the save icon on the task bar in version 2018.4.

Additionally, certain form designs may require the flexibility to save data using specific components instead of using the save icon. The primary reasons to do this are:

• When you need to execute one or more commands along with the save-to-database. The save icon in the task bar does not support executing commands, but Button components can be used to both save data and execute commands.
• When you need to trigger a save-to-database as part of a Dialog Panel Action—for example, on an OK action to save data and close the dialog panel.

Form components can be configured to trigger a save-to-database using the Save on Submit component property. In most cases a Button component is used, but you can also configure other interactive components to trigger a save. For example:

• If the save should occur immediately after a particular component is changed, then that component should be configured to Auto-Submit and Save on Submit. For example, if you want the save to occur immediately after the user has input text into a particular text box.

• If the save should only occur when the user decides that they are ready to save, then you should use a Button component that is configured to Save on Submit. For example, if you are using a formatted grid where the user is entering inputs into multiple cells, you probably don't want to trigger a save after each input—instead you want to wait until the user has completed all of their inputs, and then the user can click the button to save their changes.

When using content tags for Formatted Grid components, only Button tags can be configured to save on submit. Other interactive tags like Select tags and Checkbox tags cannot. However, the Formatted Grid component itself can be configured to save on submit, which means the save-to-database would occur whenever any control in the grid triggers a submit.

If you configure a component to save on submit, you may want to hide the save icon in the task bar, so that there is only one way to trigger the save in the Axiom form.

Axiom queries and saving data

When saving data to the database from a form, it is important to understand how Axiom queries are executed as part of the process, and configure the refresh behavior of the queries as appropriate.

During the form update process, Axiom queries are executed before the save-to-database occurs. This applies to any Axiom query that is active and configured to Refresh on manual refresh. For example, you may be using an Axiom query to populate a Formatted Grid component. You want to allow users to edit certain values in the grid and then save the changes to the database. If the Axiom query that populated the grid is still active and configured to run on manual refresh when the save is triggered, then the query will run after the user's changes are submitted to the source file and before the data gets saved to the database—meaning, the original values queried from the database will overwrite the user's changes.

In this case, you must make sure the query is not executed as part of this process. There are a variety of ways this can be done, depending on the needs of your particular form. For example:

• If you only need to run the query when the form is initially opened, you can enable the refresh option Refresh on file open and disable Refresh on manual refresh.

• If you need the query to run during certain update processes but not others, you can use formulas that read the Triggering Component and then dynamically enable and disable Refresh on manual refresh as needed. For more information, see Referencing the triggering component of an Axiom form update.

If you have an Axiom query that you want to run after the save-to-database occurs, you can use the refresh behavior option Refresh after save data. For example, if the save-to-database adds or updates a record in a particular table, and you are using an Axiom query to display the contents of that table in the Axiom form, you would want to enable this option so that the user does not have to manually refresh the form to see the changed data.

Axiom functions such as GetData are automatically calculated after a save-to-database and do not need any special settings to display the changed data.

Component enablement and saving data

The ability to save data from an Axiom form depends on the form configuration and the user's security permissions. The save icon and Save on Submit components are active and can be used if all of the following are true:

• A save-to-database process is enabled on the Control Sheet
• The user has the Allow Save Data security permission for the file
• If a data context is defined for the form, the user has the save lock for the data context
  

Otherwise, the save icon and Save on Submit components are inactive and cannot be used.

As needed, you can dynamically enable or disable the save-to-database in the Control Sheet based on some condition (for example, checking that all required fields have inputs). The save icon and Save on Submit components will toggle active or inactive based on whether the save-to-database is enabled.

If a save-to-database process is enabled, and if changed values have been submitted to the form but no save has yet occurred, then a warning message will display to the user if they attempt to close the form. This warning message informs the user that they have made changes in the form that will not be saved. The user can choose to return to the form to complete their save, or continue closing the form.

NOTE: The "unsaved changes" warning will occur even if the user does not currently have any way to execute the save—for example, if the save icon is hidden, or if no components have Save on Submit enabled. The only way to avoid the warning is to disable the save-to-database process on the Control Sheet.

User messaging when saving data

There are several layers of user messaging available when saving data to the database from an Axiom form. Some of these layers can be modified at the Axiom form level.

Messaging	Description
Prompt the user before saving	If you want to prompt the user to confirm that they want to perform the save, then you can define a Confirmation Message for the Button component. When the user clicks the button, the defined message will display and the user will have the option to continue or cancel. If canceled, then the form is not refreshed and no save-to-database occurs. This option is only available when using a Button component (or a Button tag) to perform the save. Other methods of saving—the save icon in the task bar, and other interactive Save on Submit components—do not support defining a confirmation message.
Display confirmation of successful save	By default, if the save-to-database is successful, no confirmation dialog displays to the user. The user's only indication of the save-to-database is the yellow status message that displays in the lower left-hand corner of the form while the save is processing. If desired, you can configure the form so that a confirmation message displays prominently after a successful save. In the Form Assistant task pane or the Form Designer dialog, click Edit Form Properties to open the Form Properties dialog, and then select the check box for Save Data Confirmation. (Alternatively, this setting can be enabled or disabled on the Form Control Sheet using the Show Save Data Confirmation property.) If this setting is enabled, then a save-to-database confirmation message displays to the user in a dialog. This message simply informs the user that the save completed successfully; it does not contain any details about records saved. The user must dismiss the dialog to return to the form.
Display error messages from the save	If any errors occur during the save process, these error messages display to the user in a dialog. The error messages are similar to those displayed in the Desktop ClientGeneral term for using either the Excel Client or the Windows Client, both of which are installed to the user's desktop. when saving data from a spreadsheet Axiom file, however, the specific cell addresses are not displayed because they would not be meaningful to the Axiom form user.
Display warning message for unsaved changes	If changes have been made in the Axiom form but no save has occurred, a warning message displays to the user if they attempt to close the Axiom form. The user can choose to continue closing the form or return to the form. This warning only occurs if both of the following are true: The form source file has a save-to-database enabled on the Control Sheet. Changed values have been submitted back to the source file but no save has been performed (in other words, the source file has unsaved changes). If changes have been made in the Axiom form but none of those changes have been submitted back to the source file, then no warning message will display because Axiom Software is not aware of any changes.