Managing Customization Projects by Using the PX.CommandLine Tool

You may need to perform the following actions when you are managing a customization project:
  • Run validations of all PXGraph and PXCache 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