Managing Customization Projects by Using the PX.CommandLine Tool
- Run validations of all
PXGraph
andPXCache
extensions in the current application domain - Upload and publish a customization package to the website
- Validate a published customization project before upgrading your MYOB Acumatica instance
- Unpublish customization projects from the website
- Build a customization package that uses existing files or is based on a customization project
- Delete a customization project from the instance, and the instance's database
- Merge multiple customization projects into a single customization project
- Export a snapshot
- Run a customization plug-in update
- Update the pages and files of the website by using a customization package file
To perform the actions described above, you can use the PX.CommandLine tool provided by MYOB Acumatica Customization Platform.
Using the PX.CommandLine Tool
The PX.CommandLine tool represents an executable file (PX.CommandLine.exe) located in the \Bin folder of your customization project.
When you run PX.CommandLine.exe
, you supply a set of command-line
parameters, with each presented in the following format.
parameter_name "parameter_value"
The PX.CommandLine tool supports the following syntax.
PX.CommandLine.exe
/website "path\to\web\site\root"
/method (ValidateExtensions | UploadCustomization | ValidateCustomization |
RemoveCustomization | PublishCustomization |BuildProject | DeleteProject |
MergePackages | ExportSnapshot | RunPluginsUpdate | UpdatePages)
You can use the following parameters:
/website
: Optional. This parameter provides a path to a website folder. You use this parameter if the PX.CommandLine.exe executable file is not located in the \Bin folder of your website./method
: Required. This parameter indicates the action that should be executed and can have one of the following values:- ValidateExtensions
- UploadCustomization
- ValidateCustomization
- RemoveCustomization
- PublishCustomization
- BuildProject
- DeleteProject
- MergePackages
- ExportSnapshot
- RunPluginsUpdate
- UpdatePages
The following sections describe the use of these parameter values.
Validating an Extension
You can use the ValidateExtensions value of the /method
parameter
to run validations of all PXGraph
and PXCache
extensions
in the current application domain. If a validation error occurs, the tool exits with
Code 1
, and the validation error is written to the console.
You should also specify the /CustomizationTempFilesPath
parameter if the
CustomizationTempFilesPath
parameter is not specified in the
Web.config file. This parameter provides a temporary path that the
customization engine uses while performing the validations.
You can call the ValidateExtensions
method by using the following
syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method ValidateExtensions
/CustomizationTempFilesPath "path\to\temp\folder"
Uploading a Customization Project
You can use the UploadCustomization value of the /method
parameter
to upload a customization project from a customization package (.zip
archive) to an MYOB Acumatica instance.
You can use the following required and optional parameters with this method:
/path
: Required. You use this parameter to specify the path to the customization package (.zip archive) that you want to upload to your instance./name
: Optional. You use this parameter to specify the custom name for the customization project. If unspecified, the name of the archive without the extension will be used./replace
: Optional. You specify this parameter to instruct the customization engine to override an existing customization project with the same name as the one you want to upload. If you do not specify this parameter and you upload a customization project by specifying a name by using the/name
parameter, and a customization project with the same name already exists, the PX.CommandLine tool will throw an error.
You can call the UploadCustomization
method by using the following
syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method UploadCustomization
/path "path\to\zip\archive\package.zip"
/name "CustomizationName"
/replace
Removing a Customization Project
You can use the RemoveCustomization value of the /method
parameter
to unpublish all customization projects of the current website. The project remains on the
website and can be published again.
You can call the RemoveCustomization
method by using the following
syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method RemoveCustomization
Validating a Customization Project
You can use the ValidateCustomization value of the /method
parameter to validate customization projects before upgrading an MYOB Acumatica instance. You must have the files of the target version of the website, and of the
current version of the website that has all the required customization projects published.
You should use the /website
parameter to specify the path to the target
version of the website and the /src
parameter to specify the path to the
current version of the website. You should also specify a value for the
/CustomizationTempFilesPath
parameter if required, as described in the
previous section.
When the ValidateCustomization
method is called, the tool applies the
customization projects from the current version of the website to the target version of the
website and validates the result. If a validation errors occurs, the tool exits with
Code 1
.
You can call the ValidateCustomization
method by using the following
syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method ValidateCustomization
/src "path\to\source\website"
/CustomizationTempFilesPath "path\to\temp\folder"
Publishing a Customization Project
You can use the PublishCustomization value of the /method
parameter
to publish a customization project to your MYOB Acumatica instance. Starting from MYOB Acumatica
2024.2.1 Preview 1, you can publish any number of customization projects to your instance. You use
the /name
parameter to specify the names of the customization projects that
you want to publish.
You can use the optional /merge
parameter to specify that all the existing
customization projects should remain published. If this parameter is not specified, all
existing customization projects will be unpublished except for those specified by the
/name
parameter. The /merge
parameter instructs the
customization engine to merge the customization projects specified by the
/name
parameter with all the currently published customization
projects.
Starting from MYOB Acumatica
2024.2.1 Preview 1, you can also specify the optional
/skipPreviouslyExecutedDbScripts
parameter to the skip the execution of
the database scripts that are included with the customization, if they were already executed
previously.
You can call the PublishCustomization
method by using the following
syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method PublishCustomization
/name "CustomizationName"
/merge
/skipPreviouslyExecutedDbScripts
Building a Customization Package
You can use the BuildProject value of the /method
parameter to
build a customization package. You must also specify values for the /in
and
/out
parameters.
You can call the BuildProject
method by using the following syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method BuildProject
/in "path\to\source\folder"
/out "path\to\output\file.zip"
You can use the following required and optional parameters with this method:
/in
: Required. For this parameter, you specify the path to the folder upon which the new customization package will be based. This folder may contain either a customization package that will be modified or the files that will be included in the new customization project./out
: Required. You use this parameter to specify the path to the customization package that you build by using the PX.CommandLine tool. The output is a .zip archive./website
: Optional. For this parameter, you specify a path to a website folder. You use this parameter if the PX.CommandLine.exe executable file is not located in the \Bin folder of your website./include
: Optional. The parameter consists of two values: the absolute path to a file that should be added to the output package, and the relative path inside the/website
folder where the file is copied after you publish the customization project. This parameter may be repeated any number of times./includeDirectory
: Optional. The parameter consists of two values: the absolute path to a folder containing files that should be added to the output package, and the relative path to a folder in the website folder where these files are copied after the customization project is published. This parameter may be repeated any number of times./description
: Optional. For this parameter, you specify the description of the output customization package./level
: Optional. This is the level of the customization package, which helps MYOB Acumatica Customization Platform to resolve conflicts while multiple customization projects are being merged. The value must be an integer. For details about the level of a customization project, see the description of the Level column of the Customization Projects (SM204505) form.
For example, if you have a customization package located in the C:\AcumaticaSites\T300 folder and you want to build a customization package based on this project, you use the command shown in the following code.
PX.CommandLine.exe /method BuildProject
/in "C:\AcumaticaSites\T300"
/out "C:\AcumaticaSites\MyNewPackage.zip"
This command builds a customization package and puts the resulting .zip archive in the C:\AcumaticaSites folder.
You can also build a new customization package based on a project stored in a source control folder. To do that, you execute a command that looks similar to the one shown in the following code.
PX.CommandLine.exe /website "path_to_Acumatica_website"
/method BuildProject
/in "path_to_customization_source_control_folder"
/out "full_name_of_customization_file.zip"
Deleting a Customization Package
You can use the DeleteProject value of the /method
parameter to
delete a customization project from your instance, and the instance's database. You must use
the /name
parameter to specify the name of the customization project that
you want to delete.
You can call the DeleteProject
method by using the following syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method DeleteProject
/name "CustomizationName"
Merging Multiple Customization Packages
You can use the MergePackages
value of the /method
parameter to merge multiple customization packages into a single package. You must also
specify all of the following parameters:
/website
: The path to the website folder/packages
: The path to the customization packages or directories with project names separated by the ; and | delimiters, as shown in the following example:package_path1;project_name1|package_path2;project_name2|package_path3;project_name3
/resultPath
: The path to the merged customization package
You may also use the optional /level
parameter to specify the level of the
merged customization package. The value of this parameter is an integer.
You can call the MergePackages
method by using the following syntax.
PX.CommandLine.exe /website "c:\repos\repo2\WebSites\Pure\Site"
/method MergePackages
/packages "c:\repos\lego1\CcsLego\ConstructionFeatures.zip;ConstructionFeatures|
c:\repos\Construction\shared\ConstructionPackage.zip;ConstructionPackage"
/resultPath "c:\repos\repo2\WebSites\Pure\Site\Bin\MergedConstruction.zip"
/level "1"
Exporting a Snapshot
You can use the ExportSnapshot
value of the /method
parameter to create a snapshot in the XML format by using a snapshot configuration file, and
export the snapshot to the Snapshots directory of your MYOB Acumatica instance. You must specify the path to snapshot configuration file that you want to use
by using the /config
parameter.
You may also use the optional /c
parameter to specify the company ID from
which the snapshot should be taken. If this parameter is not specified, the company ID
2 is used by default.
You can call the ExportSnapshot
method by using the following syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method ExportSnapshot
/config "path\to\snapshot\export\config.esc"
/c "3"
Executing a Customization Plug-In Update
You can use the RunPluginsUpdate
value of the /method
parameter to work with the CustomizationPlugin
classes of all published
customization projects. For more information about customization plug-ins, see Custom Processes During Publication of a Customization and To Add a Customization Plug-In to a Project.
The RunPluginsUpdate
method runs the
CustomizationPlugin.UpdateDatabase
methods from customization plug-ins of
all published customization projects. If the UseRuntimeCompilation
setting
is set to true in the Web.config file, then the customization
plug-ins are also collected from the App_RuntimeCode folder.
You must use the RunPluginsUpdate
method only if the customization package
that you published has a customization plug-in that implements the
UpdateDatabase
method. You can call the RunPluginsUpdate
method by using the following syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method RunPluginsUpdate
Updating the Pages of the Website
You can use the UpdatePages
value of the /method
parameter to update the pages and files of your MYOB Acumatica website from a customization package file. This file can have the
.zip or .xml file extension. You must specify
the path to this file by using the /path
parameter. You can also specify
the path to the directory that contains the customization instead of specifying the path to
a customization package file.
You may also use the optional /replace
parameter to instruct the
customization engine to replace the existing pages and files of your website.
You can call the UpdatePages
method by using the following syntax.
PX.CommandLine.exe /website "path\to\web\site\root"
/method UpdatePages
/path "path\to\package.zip"
/replace