Hi Everyone,
A bit earlier on Acumatica Cloud Development Conference I had a Black Belt Development practices. As part of it I covered an automation tools Acumatica supports.
In this article I want to extend this topic a bit with more examples and links.
Automate Acumatica Wizard Installation
Acumatica installation wizard is a standard MSI (Microsoft Installer) package that can be managed with standard windows tools.
For example there is msiexec.exe tool that can do installation and de-installation from console. Here you can read more about msiexec parameters.
With Acumatica you can use following command to install it:
msiexec.exe /i /a /qn “AcumaticaERPInstall.msi"
- /i – installation command
- /qn – quiet mode with no dialogs
- /a – install as administrator
Automate Acumatica Instance Deployment
Acumatica Configuration wizard is the tool that can deploy and configure Acumatica Instance. It also has 2 modes: Windows Forms mode (AcumaticaConfig.exe) and Console (ac.exe) mode. With console mode you can deploy Acumatica Instance in unattended mode.
You can read more about Acumatica Console commands here.
Here you can find a command how to install new Instance with Demo Data
ac.exe -cm:"NewInstance" -s:"#DatabaseServer#" -d:"#DatabaseName#" -c:"ci=2;cp=1;ct=Demo;cv=True;cn=Company;" -i:"#InstanceName#"
-h:"C:\Program Files (x86)\Acumatica ERP\#FolderName#" -w:"Default Web Site" -v:"#InstanceName#" -po:"Default App Pool" -a:"AnonymousUser"
Replace here #…# with real data.
And here you can find the smalles possible command
ac.exe -cm:"NewInstance" -s:"(local)" -d:"AcuInst" -i:"AcuInst" -h:"" -w:"Default Web Site" -v:"AcumaticaERP" -po:"DefaultAppPool"
Also remember that you can use Acumatica Wizard UI to generate console commend on the fly:
Getting Source Code from Repository
If you use any source control to store your customization, you can use it’s API to get source code in the unattended mode.
For example Git has a couple of command that can be used to get repository with code locally:
$ git clone https://github.com/Acumatica/CustomizationBuildScript.git
Automate Compilation of Source Code
With Acumatica you most probably use .Net Platform and C# Language to write a customization code. .Net has a very powerful utility MSBuild that can not only compile your source code but also can automate whole build procedure. Please read more about MSBuild here and more about console commands here.
Following command will compile project downloaded from github on the previous step.
MSBuild YogiFonLib\YogiFonLib.sln /property:Configuration=Release /t:Rebuild
Automate Packaging of the Customization Project
You know that Acumatica customization is usually distributed and applied as a *.zip package. That means you need to pack customization into the package before you can use it.
luckily Acumatica has another tool – PX.CommandLine.exe – that can help us to automatically package files stored in Source Control. This tool is located inside AcumaticaInstance\bin folder starting with 2017R2 update 6.
PX.CommandLine.exe /method BuildProject /website "" /in "" /out "Cust.zip"
- /method BuildProject – Required. Action that will be executed.
- /in “path\to\source\folder” – Required. Action that will be executed.
- /out “path\to\output\file.zip” – Required. Path to resulting customization package. Output will be a zip archive.
- [/website “path\to\site\root\”] – Optional. Path to web site folder, can be omitted if tool executable is inside site’s \bin folder.
- [/include “path\to\additional\files.ext“ “site\relative\path\to\file.ext”]… – Optional. Has two parameters – an absolute path to file that should be added to package and a relative path inside site folder where this file will be copied after customization is published, both paths should contain filename with extension. This argument can be repeated more than one time.
- [/includeDirectory “path\to\directory” “site\relative\path”]… – Optional. Has two parameters – an absolute path to folder that has files that should be added to package and a relative path inside site folder where these files will be copied after customization is pubshed. This argument can be repeated more than one time.
- [/description “Package description”] – Optional. Description of customization package.
- [/level “customization level”] – Optional. Level of customization package, should be an integer.
Automate Customization Publication
Acumatica Instance provides the API to publish/unpublish customizations thought the code. unfortunately due to technical reasons it is not possible to do that without up and running instance. So you need to have fully configured and installed Acumatica instance before you can publish customization there. Read more about publish customization through Web Services API here.
class Program { static void Main(string[] args) { ServiceGate gate = new ServiceGate(); gate.CookieContainer = new System.Net.CookieContainer(); gate.Url = "http://localhost/Summit/api/ServiceGate.asmx"; LoginResult lr = gate.Login("admin", "123"); gate.UploadPackage("Cust", File.ReadAllBytes("Cust.zip"), true); gate.PublishPackages(new string[] { "Cust" }, false); } }
Automate Tests Launch
Acumatica provides the tool that you can use for automatic regression tests thought the browser API. You can read more about test framework here.
On every new builds you will need to do following 2 things:
- Generate new wrappers using class generation –
ClassGenerator.exe
- Launch Tests with TestLauncher and configuration file –
MyTest.exe /config "example.xml"
The benefits of its automation is that you can have a continues build and test of your customization every night or every new version. If you complete all these steps you just now need to come in the morning and collect tests results.
To organize on really daily basis and even in parallel Acumatica Internally uses approach with virtual machines. Developers can queue the test and when VM is free, special script will reset all settings, deploy Acumatica and customization (if needed) using method descried here and then launch testes.
Hope it helps and have a fast automation!
Sergey,
What other ‘/methods’ are available for PXCommandLine?
Thanks
Hi Kyle, as far as I know, that is the only one usage of PXCommandLine for now – compile customization.
Hi Sergey,
Thanks for your reply. Much Appreciated.
From your reply, I now understand how we can automate ‘the Open from Folder’ and Publish step. This will be very useful
It would have been great if there were command line utilities to automate ‘Detect Modified files’ and ‘Save to Folder’. But it’s not a big issue and can be carried out manually from Acumatica portal … Or we might consider to use the Browser Automation provided bv the Acuamtica Test Framework to do this for us 🙂
Thanks also regarding the tip to consider tables structure, reports etc.
Regards,
Joseph
Hi Joseph.
Actually this automation is described in the part “Automate Packaging of the Customization Project”.
“PX.CommandLine.exe” tool can pack project saved in the folder into the ZIP package. Than you can upload this package with Web services API as described in step “Automate Customization Publication”.
Please check PX.CommandLine.exe tool, it looks like it does exactly what you need.
BTW, when you check for files changes, you also should check tables structure, reports and so on.
Hope it helps.
Hi Sergey,
Very useful blog.
I would have some questions regarding best practice to work as teams.
We are following the below approach to work within a team of around 3 developers:
When a developer completes changes and he is ready to submit the code to ‘source control’, he follows these steps:
1. Build Visual Studio Project
2. Open Customization Project In Acumatica
3. Click Detect Modified files so that changes are detected
4. Publish to ensure that there are no issues
5. Click ‘Save Project to Folder’
6. Commit Code to Git and Merge Code with Other Developers. Latest Code, including Acumatica Customization Project are now on the developer’s machine
7. Rebuild Visual Studio Project (containing the Customization Project dll)
8. Load Acumatica, Go to Customization Project and use ‘Open Project from Folder’
9. Click Detect Modified Files (so that new dll is detected)
10. Publish
In your blog you are describing automation to build the Visual Studio Project and to package and Publish the Customization Project.
However, this does not seem to describe how to automate ‘Save/Open from Folder’ in Customization Project so that the Customization Project is included in source control. Automating this step would be very important for us, as for example, developers can forget to use ‘Open from folder’, which would result in losing changes of another developer. Is it possible to automate this step? Are we correct in following the above steps to merge the code and work across teams, or is there a better approach?
Thanks,
Joseph