AX1752

Scheduler task: Copy On Demand Plan Files

This task copies on demand plan files from one file group to another. It performs the same actions as the Copy On Demand Plan Files command in the Command Library.

This is an advanced feature and should only be used if it is the only way to achieve the desired population of plan files between two related file groups. It is the responsibility of the solution designer to ensure that the copied plan files will behave as expected in the target file group. For example, the plan file must be designed to dynamically save to the appropriate tables and columns within the context of the new file group.

The Copy On Demand Plan Files task uses two tabs to define the properties of the task.

  • Options: Defines the options to be used for the copy operation
  • Plan Files: Specifies the plan files to copy

Options tab

The following options are available on the Options tab. Note that all of these options can be changed dynamically by using system variables.

Item Description

Source File Group

The file group to copy plan files from. Click the folder icon to select a file group. You can select any on-demand file group, or any file group alias that currently points to an on-demand file group.

Destination File Group

The file group to copy plan files to. Click the folder icon to select a file group. You can select any on-demand file group, or any file group alias that currently points to an on-demand file group.

Keep original plan file creator

Specifies whether the plan file creator for the copied plan files is set to the same creator as the original plan files. By default, this option is enabled.

If this option is disabled, then the plan file creator for the copied plan files is set to the user identity used by the Scheduler job when it is run.

Use default template

Specifies whether the copied plan files have the option to adopt the default template of the new file group. This is primarily intended to be used when copying plan files to a file group that uses virtual, form-enabled plan files, so that the copied plan files can be converted to virtual files and use the new template.

  • If disabled (default), then the target file group must contain copies of the original templates that were used to create the plan files from the source file group. If these templates are not present, then the copy process will fail.

  • If enabled, then the copied plan files will be assigned a template as follows:
    • If the target file group contains copies of the original templates that were used to create the plan files from the source file group, the copied plan files use those templates.
    • If the target file group does not contain copies of the original templates, the copied plan files use the default template specified for the target file group in the file group properties.

    If the target file group does not contain copies of the original templates and does not have a designated default template, then the copy process will fail.

Copy plan file attachments

Specifies whether plan file attachments are copied to the target file group when a plan file is copied. By default, this option is enabled.

If this option is disabled, then plan file attachments will not be copied to the target file group.

Save plan files after copy

Specifies whether the new plan files are processed and saved in the target file group after the copy is performed. This is intended to perform a save-to-database within the context of the new file group. By default, this option is disabled.

If you enable this option, then after the plan files are copied to the new file group, they are opened, refreshed, and saved (including a save-to-database). The refresh includes all active Axiom queries where Refresh during document processing is enabled.

Regardless of whether this option is enabled, if it is ever intended to save the copied plan files in the target file group, then they must be designed so that they save data to the appropriate tables after being copied.

NOTES:  

  • If Process with Utilities is enabled for the target file group, then utility processing is performed instead of normal processing. The default data source is used.

  • If you enable this option but also specify a Copy data utility, then the new plan files are not processed and saved. Instead, the designated utility file is processed for each new plan file.

Copy data utility

Optional. Specifies a utility file to process for each copied plan file. You can select any file in the Utilities folder of the target file group, or a file in the Reports Library.

The primary purpose of this option is to handle copying virtual plan files between file groups. Because the plan files are virtual, no data exists in the file itself and therefore saving the new plan file will not populate data for the new file group. Instead, you should create a utility file that queries in the necessary data for the original plan file, then saves the necessary data for the new plan file to the appropriate tables for the new file group. Reserved document variables are available to return information in the utility file such as the old plan file code and the new plan file code.

For more information, see Copy data utility.

NOTE: Save plan files after copy must be enabled in order to specify a copy data utility. If a utility is specified, then the new plan files are not saved and instead the utility file is processed for each new plan file.

Default Values

Optional. This section can be used to apply default values to any columns in the target plan code table, when the new record is created in the target file group. For more information, see Defining default values.

Plan Files tab

On the Plan Files tab, specify the plan files from the source file group that you want to copy to the target file group. There are three different options that you can use to specify the plan files: Choose from list, Use filter, and All.

The most common option when copying plan files using Scheduler is to define a filter. You can dynamically copy a subset of designated plan files using the filter. If the Scheduler task is triggered by using RunEvent, you can pass in the filter from the source of the RunEvent (such as an Axiom form).

Copy a filtered set of plan files

To use a filter to copy 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 specify the filter directly, or use a job variable.

To specify the filter, click the Filter Wizard button. You can also manually type a filter criteria statement into the filter box. The filter must use the plan code table of the source file group, or a lookup table. For example: CapReq2018.Transfer=1, where CapReq 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.

If you want to set the filter dynamically, you can use the Filter system variable to override the filter defined in the task. This is intended for use when running Scheduler jobs via RunEvent. If a variable value is specified when triggering the event, such as the value CapReq2018.CapReq IN (45,67,98) , then that filter statement is used to determine the plan files to be copied instead of the filter defined in the task.

Copy all plan files

To copy all plan files, select All. When the Scheduler task is executed, Axiom Software will copy all plan files in the file group (except for those hidden via the Show on List column). This is not a common use case for the copy feature, but can be used if needed.

Copy selected plan files

To copy certain plan files, select Choose from list, and then select the check boxes for the plan files that you want to copy. When the Scheduler task is executed, Axiom Software will copy only the selected plan files. This is not a common use case for the copy feature, but can be used if needed.

NOTE: This option is not available when using a file group alias as the source 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.

Defining default values

When the copy action is performed, the columns for the new record are populated as follows:

  • If a value has been defined for a column in the Default Values section, that value is used.
  • Otherwise, the value from the original record in the source file group is used. This only occurs if the column names match in the source and target tables, and if the column in the target table is a compatible data type to accept the copied value.

If a column exists in the source table but not the target table, that value is ignored and does not cause an error. If a column exists in the target table but not in the source table, then it is only populated during the copy action if a default value has been defined. If the target table contains columns with lookup relationships, those columns must be populated with valid values (either from the original record or by using default values) or else the copy action will fail.

To define default values for the new records:

  • Click the plus button to add a new column/value pair to the Default Values section.

  • In the left-hand box, type the name of the column in the target plan code table. For example: SourceID. Do not use Table.Column syntax.

  • In the right-hand box, type the value to be placed in this column. You can enter a "hard-coded" value, or you can enter the name of a column from the source plan code table in brackets to use the value from that column. For example, [CapID]. The column reference is only necessary if you want the source column value to be placed in a column that has a different name than the source column. If the columns have the same name, the value will be copied automatically as noted previously in this section.

For both the column name and the value, you can use file group variables via a file group alias. Axiom Software looks up the current target of the alias, and finds the current value of the designated variable within that file group. Built-in variables and custom variables can both be used. To reference a variable, use the following syntax:

{FileGroupAliasName.VariableName}

For example: {CP_CurrentYear.FileGroupYear} returns the file group year for the file group that is currently the target of the CP_CurrentYear alias.

Scheduler job variables can also be used in the column name and in the value.

Overriding task settings using system variables

All of the settings for the Copy On Demand Plan Files task can be overridden using system variables. This is intended for use when the task is being triggered by RunEvent (such as from within an Axiom form), and you want to pass in variable values to determine how the task is run.

The variable names for this task are as follows:

Variable Description

CopyDataSourceFileGroupID

 Overrides the Source File Group. Must be set to a valid file group ID. File group names or alias names cannot be used.

CopyDataTargetFileGroupID

Overrides the Destination File Group. Must be set to a valid file group ID. File group names or alias names cannot be used.

CopyDataUtilityPath

Overrides the Copy data utility. Must be set to a valid document path in Axiom Software.

Filter

Overrides the Plan File Filter to specify the plan files to copy. Must be set to a valid filter criteria statement.

KeepOriginalPlanFileCreator

Overrides the option Keep original plan file creator. Must be set to a valid Boolean value (True/False).

UseDefaultTemplate

Overrides the option Use default template. Must be set to a valid Boolean value (True/False).

CopyPlanFileAttachments

Overrides the option Copy plan file attachments. Must be set to a valid Boolean value (True/False).

SavePlanFilesAfterCopy

Overrides the option Save plan files after copy. Must be set to a valid Boolean value ( True/False).

To override task properties using these variables:

  • Add the variables that you want to use to the Job Variables tab. For example, if you want to override the source and target file groups, the copy data utility, and the plan file filter, then add those variables to the Job Variables tab. You do not need to add a variable name if you do not plan to override it.

    Example Job Variables tab to override certain settings for the copy task

    You do not need to define a default value for the variable. If the value is blank, then the setting defined in the task is used. The corresponding task property will only be overridden if the variable has a defined value.

  • You do not need to add the variables to the task properties. The variables automatically overwrite the task properties if they have defined values.

  • When configuring RunEvent, define values for the variables as needed. For example, you could have a form where you allow the user to select the source and target file group for the copy action. Based on the user's selected file group names, you can use the GetFileGroupID function to determine the IDs for those file groups. You can then pass those IDs as variable values for the variables CopyDataSourceFileGroupID and CopyDataTargetFileGroupID.

    Example RunEvent properties to pass certain variable values to the copy task

Plan file process considerations

If the target file group has an active plan file process, the new plan file is started in that process as part of the plan file creation. The process initiator for the plan file is set as follows:

  • If the plan file process has a designated Process Initiator Column, the user listed in that column is the process initiator.

  • If the plan file process does not have a Process Initiator Column, or the column value is blank, then:
    • If Keep original plan file creator is enabled for the command, then the original plan file creator is the process initiator.
    • Otherwise, the user performing the copy operation is the process initiator.

Copy data utility

If a Copy data utility is specified, this processing is performed as follows:

  • The selected plan files are first copied to the new file group. If the plan files are virtual, then the placeholder document records are copied instead of physical plan files.
  • The utility file is opened once before processing begins. Any data lookups or Axiom queries that are configured to refresh on open are executed at that time.
  • The utility file is then iteratively processed for each new plan file as follows:
    • Document variables are set in the utility, and the workbook is calculated.
    • Axiom queries set to Refresh during document processing are refreshed.
    • A save-to-database is executed.

The utility file is not closed and reopened for each new plan file. All processing occurs within the same file session, similar to when performing multipass file processing.

The following reserved document variables are available to the utility file, to be returned using GetDocumentInfo. These variables return necessary information about the copied plan files and the source and target file groups.

Variable Description

SourceFileGroupID

The ID of the source file group. You can use this ID in functions such as GetFileGroupVariable—for example, to return the name of the data table to query from the source file group.

SourcePlanCode

The plan code of the original plan file from the source file group. You can use this code to filter Axiom queries to return data for the original plan file.

TargetFileGroupID

The ID of the target file group. You can use this ID in functions such as GetFileGroupVariable—for example, to return the name of the data table to save data to for the target file group.

TargetPlanCode

The plan code of the new plan file in the target file group. You can use this code to save data for the new plan file.

For example, GetDocumentInfo("Variable","SourceFileGroupID") returns the ID of the source file group.

See also