AX3004

Process Plan Files dialog

Use the Process Plan Files dialog to configure options for plan file processing. This topic provides a reference for the various options in this dialog. Process Plan Files is only available to administrators and to users with the Process Plan Files security permission.

The Process Plan Files dialog has several tabs to define different options. The tabs available in the dialog and the options on those tabs depend on the selected Processing Mode on the Options tab.

  • Options: Defines the overall processing mode and processing options
  • Plan Files: Specifies the plan files to process
  • Axiom Queries: Specifies which Axiom queries to run in plan files (only applies to Normal Processing)
  • Utilities: Specifies which data source to use for utility processing (only applies to Process with Utilities)

Options tab

The Options tab defines various options for processing. Some options vary depending on the selected processing mode, while other options are available for all modes.

General options

Option Description

Processing Mode

Select the type of processing to perform:

  • Normal Processing: Plan files are opened, refreshed, and saved. You can configure which actions occur. For more information, see Processing plan files.

  • Process with Utilities: A list of utilities is iteratively processed per plan file. Utilities are opened, refreshed with data for each plan code, and saved. This is primarily intended for processing form-enabled plan files that use embedded forms. For more information, see Processing plan files with utilities.

  • Update Persistent Plan Files: Update existing plan files for text, formatting, or formula fixes. This is an advanced feature. For more information, see Updating persistent plan files after creation.

  • Process with Custom Utility: Plan files are processed using a custom utility provided by Axiom Support. This is an advanced feature. For more information, see Processing plan files with a custom utility.

The default processing mode is Normal Processing. However, if the file group has been configured so that utility processing is the primary processing mode for that file group, then Process with Utilities is selected by default.

Process Plan Files on

Select one of the following:

  • Axiom Server (default): Process the utility on an Axiom Software Scheduler server. This frees up local resources and allows you to work on other Axiom Software tasks while the utility is being run. When the utility is finished processing, you will receive an email with the results.

  • Local Axiom Client: Process the utility on your local client machine. You cannot work on other Axiom Software tasks while the utility is being run, but when it is finished, the results display immediately.

You might want to process on the server if you are processing a large number of plan files and do not want to wait for the utility to complete before moving on to other tasks. However, if you are only processing a small number of plan files, and you want to see the results immediately, you can process on the client.

If you choose to process on the server, a Scheduler job will be created to process the plan files, with a start time of the current time. These requests are handled by the System.RefreshPlanFiles event handler in Scheduler. The job is run under the identity of the user who initiated the request.

NOTES:  

  • Process with Utilities mode can only be run in the Windows Client (or the Web Server engine). If you are currently in the Excel Client, the local client option is not available.

  • Process with Custom Utility mode can only be run in Excel. If you are currently in the Windows Client, the local client option is not available. If you choose to process on the server, Excel must be installed on the server.

Server Options

If the process is being executed on the Axiom Server, select Process plan files using the Axiom Web engine to use the Axiom Web engine to process the files instead of Microsoft Excel.

The Web engine is the Excel-compatible spreadsheet engine used by the Axiom Windows Client and the Axiom Web Client to read Axiom files without using Excel. It is always recommended to use the Web engine for processing, except in rare cases where plan files use Excel features that are not supported by the Web engine.

NOTES:  

  • If your system has been configured to use the Web engine for Scheduler processing by default, then this option will be checked automatically but can be disabled if desired. If your system is configured to always use the Web engine for Scheduler processing, then this option is checked and cannot be changed.

  • This option is enabled by default and cannot be changed when using Process with Utilities mode.

  • This option is disabled by default and cannot be changed when using Process with Custom Utility mode.

Notification Options

If the process is being executed on the Axiom Server, select one of the following options to specify how you want to be notified when the process is completed. The notification will include error information, if applicable.

  • Notification task pane (default): Display the notification in the Notifications task pane.
  • Email notification: Receive the notification by email, using your email address as defined in Axiom Security.
  • Both notifications: Receive the notification by email and in the Notifications task pane.

Options for Normal Processing mode

If Normal Processing is the selected processing mode, the following additional processing options are available on the Options tab:

Option Description

Save document after processing

Specifies whether plan files are saved during processing. This option is selected by default.

This option does not cause a save-to-database to be performed—that option must be selected separately.

NOTES:  

  • If this option is not selected, then the utility will open the file as read-only and will not attempt to acquire the document lock before processing.

  • If the file group uses virtual plan files, this option does not apply because the plan files cannot be saved. However, if the option is enabled, Axiom Software will attempt to acquire the document lock before processing, which is not necessary. This option should not be enabled when processing virtual plan files.

Run Save To Database on plan files after processing

Specifies whether a save-to-database is performed in plan files during processing. This option is selected by default.

This option does not cause the file itself to be saved—that option must be selected separately. It is not required to save the file in order to perform a save-to-database.

Create a plan file restore point before processing

If selected, then a plan file restore point will be created before processing begins. This option is not selected by default.

Restore points can be used to restore plan files to the state they were in before changes were made. For more information, see Restoring plan files from restore points.

NOTE: If the file group uses virtual plan files, this option does not apply. Plan files are not saved and therefore restore points are irrelevant.

Options for Process with Utilities

If Process with Utilities is the selected processing mode, there are no additional options on the Options tab.

Plan files are not saved when using Process with Utilities, and plan file restore points are not created. When using this mode, the processing is being performed in the utility files, not in the plan files, so it is not necessary to save the plan files. Additionally, in most cases the plan files used with this mode are virtual form-enabled plan files, so the save and restore options are irrelevant.

Options for Update Persistent Plan Files

If Update Persistent Plan Files is the selected processing mode, the following additional option is available on the Options tab:

Option Description

Report File

Click the Browse button to select the report file that is configured with the PlanFileReconfig_ControlSheet. This file must be saved in the Reports Library.

This control sheet contains the settings that will be applied to plan files during processing.

Plan files are always saved when using this processing option, and plan file restore points are always created before processing. A save-to-database is not performed in this mode, so if you need to save data, you should process plan files using Normal Processing after you have verified the results of the plan file update.

Options for Process with Custom Utility

If Process with Custom Utility is the selected processing mode, the following additional options are available on the Options tab:

Item Description

Report File

Click the Browse button to select the Microsoft Excel spreadsheet file that contains the VBA custom utility. The file must be saved in the Reports Library.

VBA Module

Select the VBA module to run as part of this utility. The drop-down list shows the VBA modules available in the selected file.

VBA Function

Select the VBA function to run as part of this utility. The drop-down list shows the VBA functions available in the selected module.

Plan files are always saved when using this processing option, and plan file restore points are always created before processing. A save-to-database is not performed in this mode, so if you need to save data, you should process plan files using Normal Processing after you have verified the results of the custom utility processing.

Plan Files tab

On the Plan Files tab, specify the plan files that you want to process. There are three different options that you can use to specify the plan files: Choose from list, Use filter, and All. You should use the option that corresponds to how many plan files you want to process—all plan files, or a subset of plan files. If you want to process a subset of plan files, you can select individual files to process or you can use a filter to define the subset.

NOTES:  

  • If a plan file is locked by another user, then it cannot be processed by the Process Plan Files utility. If you select a file that is currently locked by another user, then when you click OK to run the utility, a message box warns you of the locked file and prompts you to choose whether to continue. If you continue, the file lock will be checked again before the file is processed as part of the utility, and if the file is still locked then it will not be processed and an error will be noted in the results.

  • If the file group uses a Show on List column, then any plan code that is set to False will not display in the plan file list and will be ignored when processing.

Process all plan files

To process all plan files, select All. When you start processing, Axiom Software will retrieve the full list of plan files that you have access to and process those plan files.

Process selected plan files

To process certain plan files, select Choose from list, and then select the check boxes for the plan files that you want to process. When you start processing, Axiom Software will process only the selected plan files.

To find the plan files you are looking for, you can sort, filter, and group the list using standard Axiom grid features. You can show additional columns and hide columns by right-clicking in the column header. If you have filtered the list, you can select the check box in the header to select only the plan files that currently display in the dialog.

Process a filtered set of plan files

To use a filter to process a subset of plan files, select Use Filter. When you start processing, Axiom Software will process only the plan files that meet the filter.

You can use the Filter Wizard to create the filter, or you can manually type a filter criteria statement into the filter box. The filter must use the plan code table or a lookup table. For example: DEPT.Region='US West' where Dept is the plan code table.

Once you have entered a filter, you can click Refresh plan file list to show the plan files that currently match the filter. The refresh feature is intended to help you determine whether you have defined the filter correctly.

NOTE: When you define a filter, all plan files that meet the filter are automatically processed. You do not need to select any plan files for processing. If instead you want to filter the list and then individually select some plan files, use the Choose from list option. You can use the grid features to filter the list, and then select the specific plan files that you want to process.

Axiom Queries tab

On the Axiom Queries tab, select the queries that you want to run in the plan files. By default, all listed queries are selected. This tab only applies when using Normal Processing mode.

If you do not want to run a particular query, you can clear the check box. You can select or clear individual check boxes, or you can use the check box in the header to select or clear all queries currently displayed in the list. You can sort, filter, and group the list using standard Axiom grid functionality.

Example Axiom Queries tab

The list of Axiom queries is based on the source templates that were used to create the plan files. Only Axiom queries that meet the following criteria are eligible for selection:

  • Active is set to On, or the setting uses a formula.
  • Refresh during document processing is set to On.

If a query uses a formula for the Active setting, this means the query is dynamic and may or may not be run, depending on how the formula resolves in each plan file to be processed. When a particular plan file is processed, each selected query will be evaluated based on the current settings in that plan file. If both Active and Refresh during document processing are On for that plan file, then the query will be run. If either or both settings are Off for that plan file, the query will not be run. You can tell whether a query is dynamic or not by looking at the Dynamic column in the query list.

If a query is not selected on this tab, then that query will not be run in any plan files during processing, regardless of whether Active or Refresh during document processing are enabled in the plan file.

The plan file selection on the Plan Files tab affects the Axiom query list as follows:

  • If you have selected individual plan files, then only the eligible queries for the source templates of the selected plan files are shown.
  • If you have selected All or Use Filter, then all eligible queries for all used templates are shown. If the file group has templates that have not been used to create any plan files, then those templates are not included in the list.

The listed queries are identified by template, worksheet, and query name. The following additional properties are also listed for each query:

  • Refresh On Open: Indicates whether the Axiom query is configured to refresh automatically when the file is opened. This is for information purposes only, to help you determine whether the query needs to be included in the processing. The Refresh on Open status is ignored by Process Plan Files—if the query is selected it will be run along with the other selected queries, and if it is not selected it will not be run.

  • Dynamic: Indicates whether the query is dynamically enabled. True means that the query uses a formula for the Active setting.

NOTE: If a query is listed on this tab but it is grayed out and unavailable for selection, that means that although the query is active (either directly or dynamically), the query is not eligible to be run using Process Plan Files (because the setting Refresh during document processing is set to Off). This query is listed for your information only, so that you understand the query cannot be run as part of the process.

See also

Utilities tab

On the Utilities tab, select the ProcessPlanFileUtilities data source to use during processing. This data source determines which utility files are processed and the processing order. This tab only applies when using Process with Utilities mode.

Example Utilities tab

For each template listed, use the Utilities Data Source field to select the data source to use for plan files created from that template.

  • If the template only has one data source, that data source is selected.
  • If the template has multiple data sources, then the data source marked as the default data source is selected by default. If desired, you can use the drop-down list to select a different data source.

When plan files are processed, Axiom Software reads the specified data source in each plan file to determine the utilities to be processed for that plan file.

The plan file selection on the Plan Files tab affects the Utilities list as follows:

  • If you have selected individual plan files, then only the templates used to create the selected plan files are shown.
  • If you have selected All or Use Filter, then all used templates are shown. If the file group has templates that have not been used to create any plan files, then those templates are not included in the list.