AX1621

Processing plan files with utilities

You can use the Process Plan Files feature to iteratively process a set of utilities per plan file, so that the utilities are processed using data for each plan file. This feature is primarily intended to support form-enabled plan files that use embedded forms, where the content of each plan file is sourced from various utility files instead of defined within the plan file itself. For more information on when utility processing is needed, see Using utility processing for plan files.

When a plan file is processed with utilities, the plan file itself is not processed. The plan file is opened and refreshed to initially set shared variables and to obtain the list of utilities to process for that plan file. Then, each utility is opened, refreshed, and a save-to-database is executed. Shared variables are automatically passed to each utility so that data queries can be filtered by plan code. Document variables can optionally be passed to each utility as well.

In order to process with utilities, the template must contain a ProcessPlanFileUtilities data source. For more information on creating this data source, see Creating ProcessPlanFileUtilities data sources.

Process Plan Files is only available to administrators and to users with the Process Plan Files security permission. Users with this permission can process any plan file where they have at least read-only access. The user executing the processing does not need to have security access to the utilities being processed.

NOTE: This topic discusses how to run Process Plan Files interactively, from the file group menu. Alternatively, you can run Process Plan Files using Scheduler, and schedule it for automated execution.

To process plan files with utilities:

1. On the Axiom tab, in the File Groups group, click the arrow next to the file group name to bring up the file group menu, then click Process Plan Files.

   

   TIP: You can also access Process Plan Files in the Explorer task pane.

   The Process Plan Files dialog opens.

2. On the Options tab, select Process with Utilities if it is not already selected.

   

   If the file group is configured so that utility processing is the default processing mode, then this mode is selected by default. This is controlled by the Process Plan Files with Utilities option in the file group properties.

3. On the Options tab, complete the other processing options as needed.

   By default, plan files are processed on the Axiom Application Server, but you can optionally process plan files locally if desired (ideally, only when processing a small handful of plan files). For more information on these processing options, see Options tab.

4. On the Plan Files tab, specify the plan files to process.

   You can process all plan files that you have access to, or process only a subset of plan files. When processing a subset, you can manually select individual files to process, or you can define a filter to process the plan files that meet the filter. For more information on selecting plan files to process, see Plan Files tab.

5. On the Utilities tab, specify the data source to use for processing. This data source defines the list of utilities to be processed per plan file.

   Data sources are listed per template, but will be evaluated separately for each plan file. For more information on selecting the data source for processing, see Utilities tab.

6. Click OK to begin processing.

   A message box displays the number of plan files you are about to process, and asks you to confirm that you want to continue. Click Yes to continue. If the number of plan files is not as expected, you can click No to cancel the process and return to the Process Plan Files dialog.

If you chose to process plan files on the Axiom server rather than the local client, then a Scheduler job is created and you will be notified of the job results when it is complete. You can work on other Axiom Software tasks while the job is processed.

If you chose to process plan files on your local client, then a status bar displays as files are processed. When the process is complete, a dialog opens to display the results.

How plan files are processed

When plan files are processed using Process Plan Files in Process with Utilities mode, the following occurs for each plan file:

1. The plan file is opened and refreshed. This includes running data lookups configured to refresh on open, and running eligible Axiom queries. The following data is read from the plan file:

   • The initial values for shared variables are set, so that they can be passed to the utilities.
   • The list of utilities to process is read from the ProcessPlanFileUtilities data source in the plan file. Only utilities that are flagged as enabled in the data source will be processed for this plan file. If the plan file contains multiple data sources, the data source that was selected in the Process Plan Files dialog is used.

2. Each utility is opened and processed as follows, starting with the first utility in the list and continuing downward:

   • The current set of shared variables is passed to the utility. Document variables, if defined in the data source for the utility, are also passed.
   • The utility is refreshed, including running data lookups configured to refresh on open, and running eligible Axiom queries.
   • A save-to-database is executed in the utility.
   • Shared variables are updated for any changes made in the utility. These variables are then passed to the next utility to be processed. If one utility depends on a value set in another utility, then these utilities must be processed in the appropriate order.

Active Axiom queries are eligible for processing in the plan file and in the utilities if Refresh During Document Processing is enabled. Refresh on Open queries are also run in the utilities only.