AX1408

Copy On Demand Plan Files command

Use the Copy On Demand Plan Files command to copy a plan file from a source on-demand file group to a target on-demand file group. This command is intended for use in specialized solutions, where the affected file groups and their plan files have been designed to support this activity.

When this command is executed, a dialog displays a list of plan files in the source file group. The user can select one or more plan files to copy to the target file group. A new record is created in the target file group for each plan file that is copied.

Can be used in

• Task panes
• Ribbon tabs

When the Copy On Demand Plan Files command is selected from the Command Library as the shortcut target, it displays as command://CopyOnDemandPlanFiles or command://CopyOnDemandPlanFilesCommandAdapter (legacy syntax).

Shortcut parameters

This command uses the following shortcut parameters:

Item	Description
Dialog header	Optional. Defines custom descriptive text for the dialog header area (the area below the dialog title and above the list of plan files). If no text is defined here, the default descriptive text is: "Copy plan files between on-demand file groups, creating new records in the destination."
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.
Target 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 who is performing the copy action.
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 will be opened, refreshed, and saved (including a save-to-database). This process is performed by Scheduler, using the same process as when you choose to run Process Plan Files (normal processing) on the server. The refresh includes all active Axiom queries where Refresh during document processing is enabled. A confirmation message displays in the user's Notifications task pane when the process is complete. 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.
Filter	Optional. Defines a filter to limit the plan files shown in the selection dialog, when choosing plan files to copy. The filter must be based on the plan code table for the source file group, or on a reference table that the plan code table links to. You can type a filter criteria statement, or use the Filter Wizard to create the filter.

Default values

This command also supports defining default values. 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.

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 one of the following to dynamically determine the value to be placed in the column:

  • Source column name: Enter the name of a column from the source plan code table in brackets to use the value from that column. For example, [CapID]. This 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.

  • Sheet reference: Enter a cell reference in brackets to use the value in that cell. This cell reference is read from the plan files being copied, so the templates used to create the plan files must be designed to return the desired information. Note that using this option slows down the copy process significantly, because each plan file being copied must be opened and evaluated before the new record can be created. Therefore this option should not be used unless it is absolutely necessary.

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:

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. This column can be populated during the plan file creation by use of default values.

• 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.

Visibility

Items using this command are only visible if the current user's security permissions meet the following criteria:

• The user has at least read-only permission to one or more plan files in the source file group and the target file group (or the potential of being elevated to this level of permission by workflow or process management).
• The user has the Create New Records security permission for the target file group.

If the user does not have the appropriate permissions, then the item is hidden. You can use the Show restricted items option for the task pane or the ribbon tab to force the item to be visible at all times (but grayed out if unavailable).

Remarks

This command 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.