AX2565

Scheduler task: Process Plan Files

This task processes plan files in a file group. It performs the same actions as the Process Plan Files utility available from the file group menu.

The Process Plan Files task uses several tabs to define different options. The available tabs 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)
• Processing Variables: Defines variables to pass into plan files from Scheduler, and to Scheduler from plan files

Options tab

The following options are available on the Options tab:

Item	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 with 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 default processing mode for that file group, then Process with Utilities is selected by default.
Select File Group	The file group for which plan files will be processed. You can select any file group or file group alias. NOTES:   If you select a file group alias, then you cannot select individual plan files on the Plan Files tab. Only the Use Filter and All options are supported for use with aliases. This is because the alias could change to point to any file group, which could result in a different list of plan files. File group scenarios are not available on the list cannot be processed via Scheduler.
Advanced Options: Worker Batch Size	Optional. Specifies the number of plan files to be processed in each batch. The batch size must be a number between 10 and 100. By default this is left blank, which means that the batch size is automatically calculated based on the number of plan files to be processed divided by the total number of threads on all enabled Scheduler servers. Generally speaking, you should not customize this setting unless you are advised to by Axiom Software Support. NOTE: Each batch of plan files is processed by a subordinate job. These subordinate jobs are automatically created for the Process Plan Files task and are processed in parallel, dependent on the number of Scheduler threads that are available at any one time.

Options for Normal Processing mode

If Normal Processing is the selected processing mode, the following additional 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.

Process all plan files

To process all plan files, select All. The list of all plan files is generated each time the Scheduler task is executed, so that if new plan files have been added then those new plan files will be included in the processing (the reverse is also true if any plan files have been removed).

Alternatively, you can select Choose from list and then select the check box in the column header, causing all current plan codes to be selected. However, in this case the list of selected plan codes is fixed and therefore will not automatically adjust for any future changes.

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 the Scheduler task is executed, 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.

NOTE: This option is not available when using a file group alias as the selected file group for the task. This is because the alias could change to point to any file group, which could result in a different list of plan files.

Process a filtered set of plan files

To use a filter to process a subset of plan files, select Use Filter. When the Scheduler task is executed, 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.

You can also use a job variable for the filter. For example, you can define a job variable named "filter" and then place the text {filter} in the filter box. This is intended for use when running Scheduler jobs via RunEvent. If a variable value is specified when the event is triggered, such as the value dept.region='west', then that filter statement will replace the {filter} variable and will be used to determine the list of plan files to be processed.

NOTE: If you use a variable, and you leave the default value for that variable blank within the Job Variables tab, then all plan codes will be processed if no value is passed by the RunEvent function. You may want to define a default filter that results in no values (such as 1=0), so that plan files are only processed if a valid filter value is passed.

Axiom Queries

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.

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.

Processing Variables

This tab can be used to define variables to pass into plan files before processing begins, and to pass variables back to the Scheduler job after processing has been performed. This tab is optional and is only used in special situations.

Pre-Processing Document Variables

This section can be used to pass document variables into plan files before processing. This can impact the processing of plan files if the files are configured to use the variable values in some way.

For each pre-processing document variable, you can specify a variable name and a variable value. The plan files must be set up with GetDocumentInfo functions that return the values for the specified variables.

To edit the variable settings, double-click the applicable cell to make the cell contents editable. When you are finished editing, you can press the Enter key or Tab key to exit the cell, or click outside of the cell.

Item	Description
Variable Name	The name of the variable. Do not enclose the variable name in curly brackets (you are not using the variable here, you are defining its value).
Variable Value	The value of the variable. The value can be a "hard-coded" value, or it can be a job variable that will be resolved at time of processing. If you use a job variable to define the value, the job variable must be enclosed in curly brackets.

Pre-Processing Workbook Variables

This section can be used to pass values into plan files before processing. This can impact the processing of plan files if the files are configured to use the values in some way.

For each pre-processing variable, you can specify a workbook location to place the value, and the value to be placed.

Item	Description
Workbook Location	The location in the workbook for the value to be placed. Any existing value in this location will be overwritten for the duration of the processing. If the file is saved as part of the processing, then the value will be saved in the file. The location can be specified using SheetName!CellRef syntax (for example: Report!A13), or by using a named location in the file.
Formula	The value to be placed in the specified workbook location. The value can be a "hard-coded" value, or a formula, or a job variable that will be resolved at time of processing. If the value is a formula, the formula is placed into the target cell and calculated in the plan file. The formula can be any formula that would be valid within a spreadsheet in the Axiom client. This includes using Excel functions and Axiom functions. The formula can also use job variables, which will be resolved before placing the formula in the target cell.

The specified location and value will apply to all plan files being processed by the task. If you are going to use pre-processing variables, the location should be predefined in the template and therefore available to all plan files built using that template. If the plan files will be built using multiple templates, then all templates should be set up with the same designated location, or you should set up separate processing tasks based on template type.

Post-Processing Workbook Variables

This section can be used to pass a value from plan files back to the Scheduler job after processing has been performed. This can impact the processing of subsequent tasks in the job if those tasks are configured to use the value in some way.

For each post-processing variable, you can specify the location in the workbook to find the value, and the job variable to use that value.

NOTE: If this task processes multiple plan files, the resulting variable value will be from the last file that was processed.

Item	Description
Workbook Location	The location in the workbook to find the value to be passed to Scheduler. This value will become the value for the assigned job variable for the duration of executing the current job (unless a later process within the same job overwrites the value for the same job variable). The location can be specified using SheetName!CellRef syntax (for example: Report!A13), or by using a named location in the file.
Job Variable	The job variable that you want to use the value in the specified workbook location. Do not enclose the variable name in curly brackets (you are not using the variable here, you are simply referencing the variable name). If the job variable does not already exist in the job (on the Job Variables tab), then it will be created. However, in most cases you will want the variable to be already set up with a default value, so that the job does not have validation errors that prevent saving.

The specified location and job variable will apply to all plan files being processed by the task. If you are going to use post-processing variables, the location should be predefined in the template and therefore available to all plan files built using that template. If the plan files will be built using multiple templates, then all templates should be set up with the same designated location, or you should set up separate processing tasks based on template type.

Even though the task may process many plan files, only the job variable value from the last-processed plan file will be used. The plan files must be set up so that all plan files result in the same value after processing, or else your results will vary depending on which plan file was the last file to be processed.