AX1148
Add Plan File command
Use the Add Plan File command to create a new plan file for an on-demand file group.
Can be used in
- Axiom forms
- Task panes
- Ribbon tabs
When the Add Plan File command is selected from the Command Library as the shortcut target, it displays as command://AddPlanFile (or using the legacy syntax of command://AddPlanFileCommandAdapter).
Shortcut parameters
This command uses the following shortcut parameters:
| Item | Description |
|---|---|
|
File Group |
The file group for which to create new plan files. 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. If you are using the command in an Axiom form, and the form-enabled file is a file group utility, then an additional option is available: Use Current File Group. This option means that the command will always point to the file group where the file is currently located, even if you clone the file group or copy the file to a different file group. This is the recommended option when setting up an Add File Form for a file group. This option is located at the top of the Show file groups list. |
|
Open plan file after creation |
Specifies whether the plan file is automatically opened after it is created. By default this is enabled. You might clear this check box if end users do not need to immediately work with the new plan files they have created. This option is primarily intended for use within Axiom forms (for example, if the end user is creating the plan file via the web, but the resulting plan file is a spreadsheet), but can also be used in other contexts if appropriate. |
Additional parameters for task panes and ribbon tabs only
| Item | Description |
|---|---|
|
Prompt for required values |
Specifies whether the user will be prompted to define values for required columns in the plan code table. In this context, required columns are alternate key columns, validated columns, and the Template column (if used), because if these columns do not have defined values, then the plan file creation will fail. For more information, see Collecting values for the plan code table when creating an on-demand plan file. By default, this option is enabled. This means that a dialog will display to the user so that the user can define values for any required columns. If values are defined for required columns in the Default Values section, those values will be pre-populated in the dialog but the user can change the values. If this option is disabled, then no dialog will display to the user, and instead the values defined in the Default Values section will be used. In this case, all required columns must have values defined in the Default Values section, or else the plan file creation will fail. This option only applies when no Add File Form is defined for the file group, meaning that you are using the "built-in" functionality to prompt the user for required columns. Effectively, disabling this option causes the system to bypass the built-in dialog. If instead an Add File Form is being used, then that form should be set up to send all necessary values to the plan code table (whether those values are determined as a result of user input or not). |
Additional parameters for Axiom forms only
| Item | Description |
|---|---|
|
Use new browser window for new plan file |
Specifies whether the new plan file opens in a new browser window or in the current window (replacing the current contents). |
|
Processing step |
Specifies when the command will be executed during the form update process. By default, this is set to Form - After Processing, which means that the command will be performed after the entire form update process is complete. If desired, you can specify a different processing step for the command. For more information, see Timing of command execution and Axiom form update process. NOTE: If the command is configured to execute at an earlier processing step, the actions of adding the new record and creating the plan file will occur at the specified processing step. However, if the command is configured to open the new plan file after creation, that action will continue to occur at the After Processing step. |
|
Optional target cell for new record ID |
Optional. The target cell in the source file to place the ID of the new record after it has been created. For example: You might use this if you want to first create the new record / plan file, then reference that new record number in a save-to-database process to a different table. |
Default Values
The Default Values section can be used to apply values to columns in the plan code table when the new record is created.
To define default values:
- 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. For example:
Description. Do not use Table.Column syntax. -
In the right-hand box, type the value to be used for this column, or enter a cell reference in brackets to read the value from the current spreadsheet. For example:
[Sheet1!A1].If the command is used in a form, the cell reference is read from the form source file. If the command is used in a task pane or a ribbon tab, the cell reference is read from the currently active spreadsheet. For task panes and ribbon tabs, the cell reference is only useful if you know which spreadsheet will be the currently active spreadsheet when the command is used—for example, when using an associated task pane with a particular file.
This section must be completed as follows:
-
When using the command in an Axiom form, required columns and any other columns can be included in the Default Values as needed.
Validated columns can be included in the Default Values or not, depending on whether you want the user to specify a value (or whether a value should be calculated in the file). If you do not need a specified or calculated value for a particular column, then you can omit the column and instead use the default value for the column (as defined in the column properties).
- When using the command in a task pane or ribbon tab, the requirements vary depending on the file group configuration:
- If the file group has a defined Add File Form, then this section is irrelevant. When the command is used, it will launch the Add File Form, and that form will be used to create the plan file.
- Otherwise, Default Values for required columns are optional if Prompt for required values is enabled, and required if it is disabled.
In this context, "required columns" means any column that must be assigned a value when the new record is created in the plan code table. This includes validated columns, alternate key columns, and the designated Template column (if applicable to the file group). Depending on your system setup, other columns may be required. For example, if users have a plan file filter that references a column in the plan code table (such as Dept.Owner), then that column must be populated at creation in order for users to have permission to the resulting plan file.
Visibility
In task panes and ribbon tabs, items using this command are only visible if the current user has the Create New Records security permission for the 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).
In Axiom forms, the command used does not impact whether the button is visible or enabled. If the user does not have the Create New Records security permission for the file group, then an error will result when the user attempts to create a new plan file.
Remarks
-
When this command is used in a task pane or a ribbon tab, it behaves the same as when using the "add new file" option in the Open Plan Files dialog (the exact text of this command is user-definable). This means that if an Add File Form is defined for the file group, then using this command will cause the form to be opened instead of creating a new plan file directly using the built-in functionality. For more information, see How end users work with on-demand plan files.
-
Special considerations apply when using this command in an Axiom form. For more information, see Creating new on-demand plan files using an Axiom form.
