AcumatiCares
Introduction
In traditional software development, the process of integration generally takes place at the end of a project after each person had completed their work. Integration generally takes days or weeks and can be painful. Conflicts occur because two developers modified the same bit of code. The code does not compile anymore. Things that were working previously and that no longer work. Code that doesn’t work in the production environment.
It doesn’t need to be like that! In this blog post, I want to introduce you to Continuous Integration and Continuous Delivery (CI/CD).
This post is based on a presentation that I gave at Acumatica Summit 2022. A full recording of the can be found here: https://www.youtube.com/watch?v=o_Ma4_C2b2w
What is CI/CD?
CI/CD is a software development practice that aims to automate and streamline the process of building, testing, and deploying software applications. It involves setting up a pipeline that automatically builds, tests, and deploys code changes as they are made, allowing for rapid iteration and deployment of new features and functionality.
Source: The Product Managers’ Guide to Continuous Delivery and DevOps
https://www.mindtheproduct.com/
Why should you use CI/CD?
There are several benefits to using CI/CD for developers building Acumatica solutions:
- Improved efficiency and productivity: CI/CD can help reduce the time and effort required to build, test, and deploy customizations by automating many of the manual steps involved in the process. This means that your team can focus on more important tasks, rather than spending time on tedious manual processes.
- Enhanced quality and reliability: By automating testing and deployment, CI/CD can help identify and fix problems earlier in the development process, reducing the risk of issues being introduced into production environments. This can help ensure that your customizations and modifications to your Acumatica instance are of the highest quality and reliability.
- Increased speed and agility: CI/CD enables developers to rapidly iterate on their code and get it into production faster, enabling them to respond more quickly to business needs and market changes. This can help your small business stay competitive in an ever-changing market.
How to Set up a CI/CD Pipeline for Acumatica Development Projects?
Setting up a CI/CD pipeline for your Acumatica development projects can seem intimidating at first, but it is a fairly straightforward process. Here are the steps you will need to follow:
- Choose a source control system: You will need to use a source control system to manage and track changes to your codebase. There are several options available, such as Git, Mercurial, and Subversion. Choose the one that best meets your needs and is the most familiar to your team.
- Set up a build server: You will need a build server to automate the process of building, testing, and deploying your code. This can be a physical machine or a virtual machine hosted in the cloud.
- Configure your build server: Once you have a build server set up, you will need to configure it to run the necessary tools and processes for building, testing, and deploying your code. This will typically involve installing and configuring a build automation tool such as Azure DevOps.
- Set up a test environment: You will need a separate environment for running automated tests on your code. This can be a physical or virtual machine, and can be hosted on-premises or in the cloud.
- Configure your test environment: You will need to install and configure the necessary tools and dependencies on your test environment to run automated tests. This will typically involve installing the Acumatica testing framework and any other tools required for your specific testing needs.
- Set up a deployment environment: You will need a separate environment for deploying your code to production. This can be a physical or virtual machine.
To implement CI/CD for Acumatica development projects, it is important to assess the current state of development practices and tools. This includes understanding the use of source control for customization projects, the use of the Acumatica Test SDK for automated testing, and the use of CI/CD tools for deployment. The Acumatica Test SDK is a set of tools provided by Acumatica for creating automated tests for the UI of Acumatica applications. These tests can simulate user interactions with the UI and validate the behavior and functionality of the application.
GitHub Repository Structure
GitHub is a version control system that allows developers to track changes to their code over time and collaborate with other developers on projects. In the context of an Acumatica development project, a GitHub repository might include an Acumatica Extension Library, customization project artifacts, unit test projects, an Azure Pipelines YAML file, a NuGet config file, and additional scripts and command line tools to publish the customization package:
This sample repository can be found at https://github.com/VelixoSolutions/AcumaticaCIDemo
Acumatica Source Control Integration
Acumatica’s source control integration provides integration with a range of source control tools. It operates differently from Visual Studio and is not a direct link to any specific source control tool. Instead, it facilitates reading and writing to a local folder, that is linked/subscribed to a source control system such as Git.
For more information, see “Source Code and Automation for Acumatica Developers” from the Acumatica Virtual Developer Conference 2019
Link: /media/2019/07/2019-Acumatica-DevCon-Source-Control-Automation.pdf
Building the Customization Package
Building the customization package is the process of creating a package of code and resources that can be deployed to an Acumatica instance to add customizations or extensions to the application.
What’s in a customization package?
Since our goal is to automate this process, we have to rely on a command line tool to build this for us. PX.CommandLine.exe is a tool that ships with Acumatica and that is commonly used to build customization packages for Acumatica, but it has limitations making its use difficult in the context of a CI/CD pipeline:
- It requires a full Acumatica instance to be installed
- It is slow – the Acumatica instance has to start before the package can be built
- It does not work when run in the context of a build agent.
As an alternative, I built a simple command line app that does this for you, without any added baggage. It provides options for specifying the customization path, the package filename, and a description of the customization project. To build a customization package using CustomizationPackageTools.exe, developers might use a command like this:
You can find the source code of this tool here: https://github.com/VelixoSolutions/AcumaticaCIDemo/tree/main/CustomizationPackageTools
The code is MIT Licensed – please fork and improve!
Publishing the Customization Package
Publishing the customization package is the process of deploying the package to an Acumatica instance and making the customizations or extensions contained in the package available to users. The Acumatica Service Gate API is a web service API located at /api/ServiceGate.asmx and based on SOAP that can be used to publish customization packages to an Acumatica instance, but it can be difficult to use with a CI/CD platform like Azure Pipelines. Azure Pipelines can’t call a web service API, but it can run any command-line app or PowerShell script. I have extended the same command-line app that I presented earlier, to allow it to publish projects as well.
To publish a customization package using CustomizationPackageTools.exe, developers might use a command like this:
Testing: Taking Advantage of the Acumatica Testing Tools & Frameworks
Acumatica provides a set of testing tools and frameworks for verifying the functionality and performance of customizations and extensions to the Acumatica application. The Acumatica Test SDK is a set of libraries built on the Selenium WebDriver framework that allows developers to write automated tests for the user interface of the application. The Acumatica unit testing framework is a set of libraries and tools designed specifically for testing business logic and other components of the application. By using these testing tools and frameworks, developers can create automated tests that help ensure the quality and reliability of their code.
The Acumatica Test SDK is a set of tools and libraries that allow developers to create automated tests for the user interface (UI) of the Acumatica software. These tests verify the functionality of custom UI elements and can be run on different versions of the Acumatica software to ensure compatibility. The Test SDK is built on the Selenium WebDriver framework and provides tools for interacting with the Acumatica UI, defining and grouping test cases, and setting up and tearing down test data. To create a user interface test, developers typically install the Test SDK libraries, create a new test project using a provided template, write test code using the provided tools, and run the tests to verify the functionality of custom UI elements. Using the Test SDK helps ensure the quality and reliability of custom code.
A sample UI test
The Acumatica unit testing framework is a set of tools and libraries that allow developers to create automated unit tests for the Acumatica software. These tests verify the functionality of small, isolated units of code, such as custom business logic and other components of the application. The unit testing framework is built on the .NET framework and includes a library called PX.Tests.Unit.dll, as well as tools for creating and running unit tests. To create a unit test, developers typically install the framework libraries, create a new test project using a provided template, write test code using the provided tools, and run the tests to verify the functionality of the custom code. You can learn more about the Acumatica unit testing framework by reviewing the course T280 – Testing Business Logic with the Acumatica Unit Test Framework on the Acumatica Open University.
A sample unit test
Putting it All Together – the Azure Pipeline YAML File
In Azure DevOps, the CI/CD pipeline is defined using a YAML configuration file, which specifies the steps involved in the process, such as building the code, running tests, and deploying to different environments. Build artifacts are the outputs of the build process, which are stored in a central location and can be used in later stages of the pipeline. Continuous deployment is a variation of continuous delivery that automatically deploys every passing code change to production, eliminating the need for manual intervention.
You can see a sample YAML file for a sample Acumatica CI/CD project here:
https://github.com/VelixoSolutions/AcumaticaCIDemo/blob/main/azure-pipelines.yml
Azure Release Pipelines
Azure Release Pipelines are a tool in Azure DevOps that allow you to automate the deployment process for your applications.
A release pipeline defines the steps involved in releasing an application, including deploying code to various environments. Release pipelines can have multiple stages and gates, which allow you to create a multi-environment deployment process and control the flow of code changes based on conditions such as time or manual approval.
For example, you could wait for 3 days after deployment to your staging environment, and if no new work items have been created you automatically deploy to production.
Conclusion
In conclusion, implementing a continuous integration and continuous delivery (CI/CD) process can greatly improve the speed and reliability of customizing Acumatica, a cloud-based enterprise resource planning (ERP) system. A key part of this process is using a source control system to manage your codebase, as well as the Acumatica test framework and unit testing to automate the testing of your customizations. By using a CI/CD tool, you can automate the build, test, and deployment process, allowing you to consistently and quickly deliver updates to your Acumatica instance. Keep in mind that the specific steps and tools you use for your CI/CD process will depend on your specific requirements and may require some experimentation to find the best fit for your team. Overall, implementing CI/CD for Acumatica customization can bring numerous benefits and is worth considering for any development team.
Happy learning!
Reference and Additional links
- Deploy your Acumatica customizations and applications with confidence – CI/CD with Acumatica – video recording from Acumatica Summit 2022: https://www.youtube.com/watch?v=o_Ma4_C2b2w
- GitHub repository used in this session: https://github.com/VelixoSolutions/AcumaticaCIDemo/
- The Product Manager’s Guide to Continuous Delivery and DevOps:
https://www.mindtheproduct.com/ - Deploy an Azure Pipelines Agent on Windows: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-windows?view=azure-devops
- Getting Started with Acumatica Test SDK (VLOG by Robert Waite, Acumatica MVP): https://www.youtube.com/watch?v=LiqTwe_Zhgk
- T280 DEVELOPMENT: TESTING BUSINESS LOGIC WITH THE ACUMATICA UNIT TEST FRAMEWORK 2021 R2: https://openuni.acumatica.com/courses/development/t280-development-testing-business-logic/
