AX1593
Form-enabled plan files can use embedded forms in order to source the contents of the plan file from multiple separate "child" files, instead of needing to design the entire plan file contents within a single template. These separate files are displayed as embedded within the plan file form, creating a parent/child relationship between the files.
The benefits of this approach include:
- Simplifies form design by breaking up contents into discrete units.
- Enables dynamic content for the plan file.
- Enables re-use of the child forms (for example, in multiple related plan file templates).
Instead of needing to include every possible variation of content within a single file (the plan file template), all of the needed content can be defined in separate utility files. To dynamically source the content, the template can be configured so that it opens a particular content file or not, depending on some factor particular to each plan file.
The embedded form design can be used for any form, not just plan files. For more information on using embedded forms—including how to share information between forms and how to manage the save and update process—see Using embedded forms. This topic discusses the design considerations unique to plan files with embedded forms.
Setting up plan files with embedded forms
In order to use plan files with embedded forms, the plan file template and the child files must be set up as follows:
-
The form-enabled template must contain a Menu component to allow switching between multiple child files, and an Embedded Form component to display the currently selected child file. The parent template itself usually does not have much content, though it may display overall titles and brief summary content in addition to the menu and embedded form. For more information on using these components, see Menu component for Axiom forms and Embedded Form component for Axiom forms.
-
The child files must be form-enabled utility files within the same file group as the template. This is necessary so that all child files have the same file group context as the template / plan files, and so that the child files and templates will be kept together as the file group is cloned or for scenario creation.
-
The template and the child files must be set up with shared variables as appropriate, to share values between all the files in the shared form instance. At minimum, the template must define a shared variable for the current plan code, and the child forms must reference that variable value, so that all files are retrieving and saving data for the current plan code. For more information, see Sharing variables between parent and child forms.
In most cases, Use Virtual Plan Files should be enabled for the file group. This means that physical plan files are not stored in the system, and instead the plan files are dynamically created from the template each time they are accessed. Although the plan files could be persistent if desired, there is not much to be gained from storing the physical files because files are not saved in the forms environment (only data), and because most of the plan file contents are sourced from the child files instead of the plan file template itself.
When designing the contents of the parent and child forms, make sure that you understand the update behavior for plan files in a shared form instance, especially in terms of understanding when save-to-database is triggered. For more information, see Form session and update behavior for embedded forms and Saving data for embedded forms.
End user experience
When a user opens a plan file with embedded forms, the parent plan file opens and displays the child form that is designated as the starting selected ID for the Menu component. The user can interact with the currently displayed child form, or the user can switch to another child form by using the menu.
As the user switches from child form to child form, the state of each child form is maintained on the Axiom Application Server, even if that form is not currently visible. So it is not required to save data before switching child forms, unless you want to do so for design purposes (for example, if one child form queries data that is saved from another child form).
Security considerations for plan files with embedded forms
When using plan files with embedded forms, users with access to the plan files also need access to the child forms (the utility files). Plan file permission sets defined on the File Groups tab in Security are not sufficient to view the child form contents, because they only grant permission to the plan file itself. Ownership in a plan file process will not grant or "elevate" access to the child forms.
On the Files tab of Security, users with access to the plan files should also be granted the following access to the Utility folder of the relevant file group (either at the user or role level):
- Read-Only access
- Allow Save Data is enabled
- Show in Explorer is disabled
This configuration allows the user to open the utility files using the references within the plan file, but the utility files will not display in file explorer views throughout the system, such as in the Explorer task pane in the Desktop Client, or in the Forms browse page in the Web Client. This is most likely the desired level of access for these users. If a user needs a different level of access, it can be configured as needed.
Processing plan files with embedded forms
If you want to use Process Plan Files with embedded forms, the plan file template must be set up to enable "processing with utilities." Because the planning content for these plan files is contained in utility files instead of within the plan files, using traditional plan file processing would not update planning data. Instead, you want to be able to process the child utilities using each plan code.
To accomplish this, you create a ProcessPlanFileUtilities data source in the template. This data source lists the child utilities to be processed and the processing order.
When using Process Plan Files with embedded forms, select the Process with Utilities processing mode. For each plan file to be processed, the plan file is opened, refreshed, and shared variables are set. The list of utilities to process is read from the data source in the plan file. For each enabled utility in the data source, the shared variables are passed into the utility, then the utility is refreshed and a save-to-database occurs. The plan code is passed from the plan file to the utilities using the shared variables (along with any other necessary information), so that the utilities can be filtered as needed for the current plan code. Using the shared variables for this purpose means that you can leverage the same variable setup for processing that you do when users work within the live form.
To make "processing with utilities" the default processing option for a file group, enable Process Plan Files with Utilities in the file group properties. This means that Process Plan Files will default to utility processing, and plan file process definitions will use utility processing to validate plan files if Save and validate plan file before advancing to next step is enabled for a process step.
For more information, see Using utility processing for plan files.
