Home >

AX1593

Designing composite plan files with Axiom forms

When using form-enabled plan files, it is possible to design composite plan files. A composite plan file means that the contents of the plan file are sourced from multiple separate files instead of all 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 composite form design can be used for any form, not just plan files. For more information on creating composite forms—including how to share information between forms and how to manage the save and update process—see Using composite forms. This topic discusses the design considerations unique to creating composite plan files.

Setting up composite plan files

In order to use composite plan files, 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 composite forms and Saving data from composite forms.

End user experience

When a user opens a composite plan file, 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 composite plan files

When using composite plan files, 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. Process management and workflow ownership 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 composite plan files

If you want to use Process Plan Files with composite plan files, the plan file template must be set up to enable "processing with utilities." Because the planning content for composite 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 composite plan files, 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.