Overview

Greetings, Community,

As you may know Acumatica has a console tool PX.CommandLine. It is mentioned in Acumatica Help Portal:
https://help.acumatica.com/(W(89))/Help?ScreenId=ShowWiki&pageid=0450cd3a-9c71-4ee3-a11c-46128f227d04

For a long time the documentation did not describe all capabilities of the PX.CommandLinetool. The only thing described was how to use the tool to build the customization package. However, the PX.CommandLinetool can do many other tasks that could be useful for your CI pipelines.

The documentation on Help Portal was updated recently with more actions supported by the PX.CommandLine tool, and the rest of the tool’s capabilities will be documented in the future.
Since the documentation is not yet I complete, I would like to describe the PX.CommandLine tool’s capabilities in this post.

PX.CommandLine Tool - General Information

The PX.CommandLine tool is a console application that can be used to work with customization packages in automated scenarios such as CI scripts. It allows developers to integrate into scripts various operations done by Acumatica Customization Editor such as building, upload, and deletion of customizations, running validations on customization packages, publication of the customization to the site, unpublishing all customization package from the site, and some other operations as well.

The tool supports different commands with different command line arguments which I will describe later. This section describes the common syntax for calling the tool and lists shared command line arguments.

Command Line Syntax

PX.CommandLine.exe [/website "path\to\web\site\root"] /method (ValidateExtensions | UploadCustomization | RemoveCustomization | ValidateCustomization | PublishCustomization | BuildProject | DeleteProject | MergePackages | ExportSnapshot | ...) <parameters specific for each method>

The tool supports two kinds of arguments:

• Normal arguments that are name value pairs like this:

  /argumentName "argument value"

   

• Flags that do not use values. They represent boolean switches that usually enable or disable some tool's behavior:

  /flagName

Shared Arguments

The PX.CommandLine tool can perform different actions with their own specific arguments and flags, some of them are required and some are optional. But there are important arguments which are shared by all actions:

• /website: The path to the website folder. The argument can be considered optional and omitted if the tool executable is inside the site's Bin folder.

• /method: The parameter that indicates which action should be executed. Most of the methods are public but there are some methods designed to be used only internally. Actions may use their own additional specific arguments and flags. You can read about them in the action description.

Methods Description

This section contains the description of tool's public methods and their specific arguments. The methods are:

• ValidateExtensions
• UploadCustomization
• RemoveCustomization
• ValidateCustomization
• PublishCustomization
• BuildProject
• DeleteProject
• MergePackages
• ExportSnapshot
• UpdatePages

This post will describe each of these methods.

ValidateExtensions

PX.CommandLine.exe [/website "path\to\web\site\root"] /method ValidateExtensions 
[/CustomizationTempFilesPath "path\to\temp\folder"] 
[/output ("json"|"<anything, json is the only recognized format currently>")]

This method runs validation of all PXGraph and PXCache extensions in the current application domain. Validation errors are written in the console.

Arguments

• /CustomizationTempFilesPath: A temporary path, which is used by the customization engine. This argument is used if the web.config file does not specify the setting CustomizationTempFilesPath in the appSettings section like this:

  <add key="CustomizationTempFilesPath" value="<full path to the folder>" />

  Otherwise, it can be considered optional and omitted.

• /output: An optional parameter specifying the output format of data. The default format of data is plain text. There is only one supported value "json" (any casing can be used) that will change the output data format from the plain text to JSON. If any other value is specified or the /output parameter is omitted, then the plain text format will be used.

UploadCustomization

PX.CommandLine.exe [/website "path\to\web\site\root"] /method UploadCustomization /path "path\to\package.zip" 
[/name "CustomizationName"] [/replace]

This method uploads the customization from a customization package .zip file specified by /path argument to the Acumatica site.

Arguments

• /path: Required. The path to the customization package .zip file that should be uploaded to the site.

• /name: Optional. The custom name for the customization project. If not specified, the name of the archive without the extension will be used.

• /replace: Optional. This flag tells the customization engine to override an existing customization project with the same name, if it exists. If the /replace flag is not specified and the project with the same name (with the usage of the /name argument if it is provided) already exists on the site, then the error will be thrown.

RemoveCustomization

PX.CommandLine.exe [/website "path\to\web\site\root"] /method RemoveCustomization

This method unpublishes all customizations of the current site. Customization projects remain on the site and can be published again.

ValidateCustomization

PX.CommandLine.exe [/website "path\to\web\site\root"] /method ValidateCustomization /src "path\to\source\website" [/CustomizationTempFilesPath "path\to\temp\folder"]

The purpose of this method is to validate customizations before upgrade of an Acumatica ERP instance. To use it, it is necessary to have the files of the site of the target version and of the current version of the site with all needed customizations published. When the method is called, the tool applies the customizations from the current version of the site to the target version of the site and validate the result.

Arguments

• /website: The standard web site path argument but for the current context it has a different meaning. It is the path to the site of the target version. The convention about omitting /website argument if the tool executable is inside the site's Bin folder is still valid.

• /src: The path to the current version of the site with all needed customizations published. This argument is required.

• /CustomizationTempFilesPath: A temporary path, which is used by the customization engine. This argument is used if the web.config file does not specify the setting CustomizationTempFilesPath in the appSettings section like this:

  <add key="CustomizationTempFilesPath" value="<full path to the folder>" />

  Otherwise, it can be considered optional and omitted.

PublishCustomization

PX.CommandLine.exe [/website "path\to\web\site\root"] /method PublishCustomization /name "CustomizationName" [/merge]

This method publishes the customization package or packages specified by the /name argument. The command supports publication of multiple customization packages starting from Acumatica 2024R2 Preview 1. Use the optional /merge flag to ensure that all the currently published projects stay published. Otherwise, everything but the specified project or projects will be unpublished.

Starting from Acumatica 2024R2 Preview 1 you can use the optional
/skipPreviouslyExecutedDbScripts flag to skip the execution of the already executed DB scripts.

Arguments

• /name: Required. The name of the customization package on Acumatica site.
  
  Starting from Acumatica 2024R2 Preview 1 you can specify for the /name setting multiple customization projects that will be published together. In that case the customization names should be separated by the "|" delimiter like this:

  "Package1|Package2|Package3"

   

• /merge: Optional. This flag tells the customization engine to merge the specified customization with all currently published projects. Otherwise, only the specified customization will be published on the site.
• /skipPreviouslyExecutedDbScripts: Optional. This flag is available starting from Acumatica 2024R2 Preview 1. The flag tells the customization engine to not execute the customization DB scripts that were already executed before. Otherwise, all customization's DB scripts will be executed during the publication of the customization package.

BuildProject

PX.CommandLine.exe [/website "path\to\web\site\root"] /method BuildProject 
/in "path\to\source\folder" /out "path\to\output\file.zip"
[/include "path\to\additional\files.ext" "relative\package\path\to\file.ext"]  <can be specified 0 or multiple times 
[/includeDirectory "path\to\directory\with\additional\files" "relative\package\path\to\directory\with\additional\files"] <can be specified 0 or multiple times>
[/system "relative\site\path\to\system\file.ext"] <can be specified 0 or multiple times>
[/description "Package description"] [/level "customization level, some integer"]

Arguments

• /in: Required. The path to the folder that should be used as a base for the new customization package. The folder can contain either a customization project that should be modified or the files that should be included in the new customization project.

• /out: Required. The path to the resulting customization package (ZIP file).

• /include: Optional. The absolute path to the file that should be added to the package and the relative path inside the site folder to which this file should be copied after the customization is published. Both paths should contain the file name with extension. This argument can be repeated multiple times.

• /includeDirectory: Optional. The absolute path to the folder that contains files that should be added to the package and the relative path inside the site folder where these files should be copied after the customization is published. This argument can be repeated multiple times.

• /system: Optional. This argument allows you to specify the site relative path to a system file from the Acumatica site that will be replaced by the customization on publish. The customization package will keep information that this file is system and the customization engine will create a backup copy of the original file when the customization will be published. This will prevent the site from breaking when the customization is unpublished.
  
  Usually, when the customization is unpublished, its files are deleted. But the removal of a system file will break the site. Therefore, the files marked as system are not deleted, they are restored to original versions from the backup. This argument can be repeated multiple times.

• /description: Optional. A description of the customization package.

• /level – Optional. The level of the customization package. The level is an integer number.

Building of a customization stored in a source control folder
 

Click Source Control > Save Project to Folder on the toolbar of the Customization Project Editor to export the customization from the site to a source control folder.

The customization source control folder contains all files from the exported customization project, including new and customized pages, SQL scripts, site map changes, and assemblies.

Use the following command to build a customization from a source control folder:

PX.CommandLine.exe /website "path_to_Acumatica_website" /method BuildProject 
/in "path_to_customization_source_control_folder" /out "full_name_of_customization_file.zip"

DeleteProject

PX.CommandLine.exe [/website "path\to\web\site\root"] /method DeleteProject /name "CustomizationName"

This method deletes the specified customization package from the Acumatica site and site's database.

Argument

• /name: Required. The name of the customization on Acumatica site that should be deleted from the site and site's database.

MergePackages

PX.CommandLine.exe [/website "path\to\web\site\root"] /method MergePackages 
/packages "c:\path\to\package1.zip;"Package1 Name"|c:\other\path\to\package2.zip;"Package21 Name|..." 
/resultPath "c:\path\to\merged\result\package\MergedPackages.zip" 
[/level "customization level of merged package, some integer"]

This method merges the packages specified by paths to the customization projects zip files and customization names. The merge result is stored at the specified path /resultPath.

Arguments

• /packages: Required. In this argument you should pass paths to customization packages that should be merged into one project. For this command there are three different ways to specify a customization package's path:
      - Path to .zip file with the customization,
      - Path to .xml customization file,
      - Path to the directory with the customization
  
  Project names are separated by ; and | delimiters. The format:

  package_path1;project_name1|package_path2;project_name2|package_path3;project_name4

   

• /resultPath: Required. The path to resulting customization package with everything merged.

• /level – Optional. The level of the merged customization package. The level is an integer number.

ExportSnapshot

PX.CommandLine.exe [/website "path\to\web\site\root"] /method ExportSnapshot 
/config "path\to\snapshot\export\config.esc" [/c "CompanyID, integer"]

This method creates a snapshot using a specified snapshot configuration .esc file and exports it to Snapshots directory of the instance, XML export format is used. Use optional /c parameter to use specify the company ID to take the snapshot from. If unspecified, the company ID 2 is used.

Arguments

• /config: Required. A path to the specified snapshot configuration .esc file.

• /c: Optional. An integer company ID from which the snapshot should be taken. If unspecified, the company ID 2 is used.

UpdatePages

PX.CommandLine.exe [/website "path\to\web\site\root"] /method UpdatePages /path "path\to\package.zip" [/replace]

Starting from 2023r210 a new UpdatePages method is added to the PX.CommandLine tool. This method updates the pages, code files and files of the Acumatica web site from a customization package file specified by /path argument to the Acumatica site.

Arguments

• /path: Required. The path to the customization package file with pages and files that will be used to update the website. For this command there are three different ways to specify a customization package's path:
  • Path to .zip file with the customization,
  • Path to .xml customization file,
  • Path to the directory with the customization.

• /replace: Optional. This flag tells the customization engine to replace the existing pages and files.