AX1540
Using virtual plan files
In order to use virtual plan files, the templates for your file group must be designed to support "rebuildable" plan files. This means that all data necessary for the operation of the file must be able to be queried into the file from the database. As users make inputs and change the data, any data that needs to be retained for future use must be saved to the database, so it can be queried back into the file the next time it is accessed.
Using virtual plan files can greatly improve system performance if the file group has many plan files. Because the physical plan files are not stored in the database, file access activities can be performed much faster. Additionally, using virtual plan files makes it easier to adopt ongoing changes to templates and calc methods, because the latest template and calc methods will be used each time the plan file is accessed.
Rebuildable plan files versus persisted plan files
By default, plan files in Axiom Software are persisted files. When you create plan files from templates, each individual plan file is stored as a separate entity. When a user opens a plan file and makes edits, the plan file itself is saved as well as the planning data. This persisted file means that you do not need to save all of the user's inputs to the database; instead you only need to save the resulting planning data to be used for reporting. Any other inputs made by the user are saved in the plan file itself.
In contrast, a rebuildable plan file is specially designed to be re-created from the template each time the plan file is accessed. No data is stored in the plan file itself. Instead, the plan file works as follows:
- Data is queried from the database into the plan file.
- The user can make inputs and edits as needed within the plan file.
- All of the user's edits are saved from the plan file to the database.
- The next time a user opens the plan file, the saved data is queried back in from the database, so that the plan file starts at the same point the last user left it.
When using this rebuildable design, the plan file is not persisted as a permanent entity. Instead, the plan file serves as a temporary input form, as a means for the user to input data to be saved to the database. When the user closes the plan file, the file itself is not saved. This means that any data that needs to be retained for future use must be saved to the database so it can be retrieved later, because the data will not be saved in the file.
Form-enabled plan files are essentially rebuildable plan files, whether they are virtual or persisted. Because only data is saved in the Axiom forms environment, not the source file, form-enabled plan files must be designed as rebuildable. Even though the file may be persisted, the planning data in the file is "rebuilt" each time a user opens the form. Therefore, form-enabled files are ideal candidates for virtual plan files. If you have existing form-enabled plan files that you want to switch to virtual plan files, you may be able to make the change with little to no additional design effort.
Typically, traditional spreadsheet plan files are designed as persistent plan files. Although spreadsheet plan files can be designed as rebuildable and therefore made virtual, this requires a special design effort. Simply switching your existing persisted plan files to virtual plan files will not work, unless you know that these plan files are already designed as rebuildable (a rare situation).
Enabling virtual plan files
If the templates in a file group are designed to support rebuildable plan files, it is recommended to enable virtual plan files to improve system performance. To enable virtual plan files, select the option Use Virtual Plan Files. This option is located on the Options tab of the Edit File Group dialog, in the Plan File Options section.
If this option is enabled, then individual plan files are not stored for the file group. You will still see the document records for the plan files in Axiom Explorer, but these records are effectively placeholders to store the necessary document properties and to allow navigation to the files. The actual spreadsheet plan files do not exist and are not retained in the database.
When a user opens a plan file using any means—such as from Open Plan Files, or from the Process task pane, or from a hyperlink in a form home page—Axiom Software looks up the template that was used to initially "create" the plan file, and generates a temporary copy of the plan file using the current copy of that template. The user can then work in this file as normal. Any save performed by the user only triggers a save-to-database, it does not trigger a file save. When the user closes the plan file, the temporary copy is discarded.
When the temporary copy is created, it behaves as a normal plan file and the Control Sheet settings are applied as normal. Axiom Software does not perform any special processing on the file. For example, if you want an Axiom query to run when the file is opened, then that query must be configured to run on open.
One advantage of virtual plan files is that design changes to templates and calc methods can be propagated to plan files immediately. The next time a user opens a plan file, or the next time Process Plan Files is performed, the latest versions of the template and calc methods are automatically used to create the virtual plan file.
Note the following feature considerations and limitations when using virtual plan files in a file group:
-
Plan file restore points do not apply, because the physical plan files do not exist. It is not possible to restore to an earlier version of the plan file (though you could restore an earlier version of the template using document history, if appropriate).
-
The options to save plan files and create restore points in Process Plan Files do not apply. No errors will occur if the options are enabled, but the options will have no effect.
-
If you clone a file group with virtual plan files, and you choose to clone the plan files, then the placeholder document records will be copied to the new file group, so that the plan files in the new file group can be accessed.
-
In plan file processes, if you enable the option to validate plan files before the task can be completed, the validation will only perform a save-to-database, not a file save. Also, if the option to prompt the user to complete the current process task after saving is enabled, this will still occur when the save-to-database is performed.
-
Even though the plan file itself cannot be saved, users must still have read/write access to the plan file in order to upload and edit attachments, and to enable file locking for the virtual plan file. Plan file processes still operate as normal to elevate access to the plan files—so even though the user cannot save the file, the user's access will still be elevated to the equivalent of read/write.
-
Once a virtual plan file is created, it will always have the same values for Last Modified Date and Last Modified By. Users performing save-to-database in the plan files do not affect these values because the file itself is never saved.
Templates and virtual plan files
Virtual plan files must still be "created" from a template before they can be accessed. The creation process happens as normal, using Create Plan Files for standard file groups, and using the "create new" feature for on-demand file groups. When using virtual plan files, the creation process simply creates the placeholder document record, which allows users and system processes (like Process Plan Files) to access the virtual plan file.
When the virtual plan file is created, the document record is associated with the template that was used for the original creation. Whenever the plan file is accessed, Axiom Software uses the current version of that template to generate the temporary copy of the plan file. Any edits made to the template (and to calc methods) will be immediately available in the plan file. Therefore, you should use caution when editing a template that was used to create active plan files. Ideally, you should make changes in a test copy (leaving the current template intact for active plan files), then export the test copy and import it over the original template (to overwrite it and retain the document ID).
If you want a virtual plan file to use a different template, you must change the template assignment and then "re-create" the plan file using the Create Plan Files utility. This will overwrite the current placeholder document record with a new record that is associated with the new template.
File locking for virtual spreadsheet plan files
When using virtual plan files, the plan file itself is never saved. The file is generated on-the-fly based on the template when it is needed, and is not persisted otherwise. Only data can be saved from the virtual plan file.
This behavior means that "read-only" as it refers to the file itself is meaningless, and the only distinction that matters is whether the user can save data. Therefore, for virtual spreadsheet plan files, the ability to save data determines whether the file is flagged as read-only, and determines whether file locking applies.
When a user opens a virtual spreadsheet plan file, the file is flagged as read-only ("R/O" on the file tab) if the user is unable to save data, for any reason. This is meant as a signal to the user that they will be unable to save any data changes. If the user is able to save data, then the plan file is locked to the current user, in order to prevent other users from saving data in the file at the same time.
In order for this file locking behavior to apply, the user must have Read/Write with Allow Save Data permissions to the plan file. When process management elevates user permissions, it automatically grants this level of access, so this behavior automatically applies to step owners in a plan file process. However, if you want some users to have edit permissions at all times (not just when they are the step owner), then it is recommended to grant those users Read/Write with Allow Save Data instead of just Read-Only with Allow Save Data. If the user's access level is Read-Only, then the file will not be locked.
NOTE: This behavior does not apply to virtual form-enabled plan files. File locking does not apply to Axiom forms, and Axiom forms are not flagged as read-only. If you want to control data saves in form-enabled plan files, the save locking feature for Axiom forms can be used.
