Managing Customization Projects by Using the PX.CommandLine Tool

You may need to perform the following actions when you are managing a customization project:
  • Building a customization package that uses existing files or is based on a customization project
  • Publish a customization package to the website
  • Unpublish customization projects from the website
  • Validate a published customization project before upgrading your MYOB Acumatica instance
  • Merge multiple customization projects into a single customization project

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 | ValidateCustomization | RemoveCustomization | 
BuildProject | MergePackages)

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
    • ValidateCustomization
    • RemoveCustomization
    • BuildProject
    • MergePackages

    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"

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"

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

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"

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 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"