T200: MaintenanceForms

Version: 2025R1
Category: Technical

How to Use This Course

The Acumatica Cloud xRP Platform is the platform provided by Acumatica that is used to build the Acumatica ERP application itself, any customizations of Acumatica ERP, the mobile application for Acumatica ERP, and applications integrated with Acumatica ERP through the web services API. Acumatica Framework provides the platform API and web controls for the development of the UI and business logic of an ERP application. The platform API is used for the development of Acumatica ERP and any embedded applications (that is, customizations of Acumatica ERP). Acumatica Framework can also be used to develop an ERP application from scratch. Acumatica Customization Platform provides customization tools for the development of applications embedded in Acumatica ERP. Developers that work with Acumatica Customization Platform use the platform API provided by Acumatica Framework. The T200 Maintenance Forms course introduces to you the main concepts of Acumatica Framework and Acumatica Customization Platform based on examples of the creation of simple Acumatica ERP forms. The course is intended for application developers who are starting to learn how to customize Acumatica ERP. The course is based on a set of examples that demonstrate the general approach to customizing Acumatica ERP. In the process of completing the examples, you will gain ideas about how to develop your own embedded applications by using the customization tools. As you go through the course, you will start to develop the customization for a cell phone repair shop, which you will continue in the further courses of the T series. Aer you complete all the lessons of the course, you will be familiar with the basic programming techniques for the customization of Acumatica ERP.

         We recommend that you complete the examples in the order in which they are provided in the course,
         because some examples use the results of previous ones.

What the Course Prerequisites Are

To complete the course successfully, you should have the following required knowledge:

Proficiency with C#, including but not limited to the following features of the language:
Class structure
OOP (inheritance, interfaces, and polymorphism)
Usage and creation of attributes
Generics
Delegates, anonymous methods, and lambda expressions
Knowledge of the following main concepts of ASP.NET and web development:
Application states
The debugging of ASP.NET applications by using Visual Studio
The process of attaching to IIS by using Visual Studio debugging tools
Client- and server-side development
The structure of web forms
Experience with SQL Server, including doing the following:
Writing and debugging complex SQL queries (WHERE clauses, aggregates, and subqueries)
Understanding the database structure (primary keys, data types, and denormalization)
The following experience with IIS:
The configuration and deployment of ASP.NET websites How to Use This Course | 7
The configuration and securing of IIS

What Is in a Part

The first part of the course explains how to create a custom Acumatica ERP form by using the Customization Project
Editor and how to move the code to an extension library.
The second part of the course explains how to create a new form in Visual Studio and configure a substitute form.
Each part of the course consists of lessons you should complete.

What Is in a Lesson

Each lesson is dedicated to a particular development scenario that you can implement by using Acumatica ERP
customization tools and Acumatica Framework. Each lesson consists of a brief description of the scenario and an
example of the implementation of this scenario.
The lesson may also include Additional Information topics, which are outside of the scope of this course but may be
useful to some readers.
Each lesson ends with a Lesson Summary topic, which summarizes the development techniques used during the
implementation of the scenario.

Where the Source Code Is

You can find the source code of the customization described in this course and code snippets for the course in the
Customization\T200 folder of the Help-and-Training-Examples repository in Acumatica GitHub.

What the Documentation Resources Are

The complete Acumatica ERP documentation is available on https://help.acumatica.com/ and is included in the
Acumatica ERP instance. While viewing any form used in the course, you can click the Open Help button in the top
pane of the Acumatica ERP screen to bring up a form-specific Help menu; you can use the links on this menu to
quickly access form-related information and activities and to open a reference topic with detailed descriptions of
the form elements.

Which License You Should Use

For the educational purposes of this course, you use Acumatica ERP under the trial license, which does not require
activation and provides all available features. For the production use of this functionality, you have to activate the
license your organization has purchased. Each particular feature may be subject to additional licensing; please
consult the Acumatica ERP licensing policy for details.

Company Story and Customization Description | 8

Company Story and Customization Description

This topic describes the company story and explains what should be customized to meet the company's needs.

Company Story

The Smart Fix company specializes in repairing cell phones of several types. The company provides the following services:

Battery replacement: This service is provided on customer request and does not require any preliminary diagnostic checks.
Repair of liquid damage: This service requires a preliminary diagnostic check and a prepayment.
Screen repair: This service is provided on customer request and does not require any preliminary diagnostic checks. To manage the list of devices serviced by the company and the list of services the company provides, the Acumatica ERP instance of the Smart Fix company needs to be complemented with two maintenance forms: Repair Services and Serviced Devices. In this course, you will customize Acumatica ERP by developing these maintenance forms.

Database Schema

For the customization task, two new tables are required: a table containing information about repair services, and a table containing information about the serviced devices, as described in the previous section. You will add these tables to the database when you complete Initial Configuration.

         The design of database tables is outside of the scope of this course. For details, see Designing the
         Database Structure and DACs.

The table containing information about the provided services is called RSSVRepairService and contains the following custom columns:

ServiceID: Serves as a primary key identifying a service.
ServiceCD: Contains a service code. In Acumatica ERP, CD is used for natural keys (such as ServiceCD), which means keys that are human- readable and can have additional meaning. ID is used for surrogate keys (such as ServiceID), which are pure identifiers. For details, see Naming Conventions for Tables (DACs) and Columns (Fields).
Description: Contains a description of a repair service.
Active: Indicates whether a service is active at the moment.
WalkInService: Indicates whether a service is provided immediately aer a customer requested it.
PreliminaryCheck: Indicates whether a service is provided aer a preliminary diagnostic check.
Prepayment: Indicates whether a service requires prepayment. The table containing information about devices is called RSSVDevice and contains the following custom columns:
DeviceID: Serves as a primary key identifying the device.
DeviceCD: Contains the device code.
Description: Contains a description of the device.
Active: Indicates whether the device is being serviced at the moment.
AvgComplexityOfRepair: Contains one of three possible values indicating the level of complexity of the repair: Low, Medium, or High. Company Story and Customization Description | 9

The Repair Services Form

The Repair Services (RS201000) form, which you will develop, will be used to view the list of services provided by the Smart Fix company. By clicking buttons on the form toolbar, users will be able to add a new service, edit an existing service, and delete a service. The following screenshot shows what this form should look like.

Figure: Service list on the Repair Services form

The Repair Services form will use the RSSVRepairService table.

The Serviced Devices Form

You will also develop the Serviced Devices (RS202000) form, which will be used to view the list of devices that are serviced by the company. When a user brings up the form, the user will initially see a list of devices displayed in a grid. When the user selects a device in the grid, a detail view of the record will be displayed. (The following screenshots illustrate what these views look like.) Company Story and Customization Description | 10

Figure: List and detail views of the Serviced Devices form

The Serviced Devices form will use the RSSVDevice table. Getting Started | 11

Getting Started

In this part of the course, you will get an overview of application programming with Acumatica Framework.

Initial Configuration

You need to perform the prerequisite actions before you start to complete the course.

Step 1: Preparing the Environment You should prepare the environment for the training course as follows:

Make sure that the environment that you are going to use conforms to the System Requirements for the Acumatica ERP Installation.
Make sure that the Web Server (IIS) features that are listed in Configuration of IIS Web Server Features are turned on.
Install the Acuminator extension for Visual Studio.
Clone or download the customization project and the source code of the extension library from the Help- and-Training-Examples repository in Acumatica GitHub to a folder on your computer.

Install Acumatica ERP. On the Main Soware Configuration page of the Acumatica ERP Setup wizard, select the Install Acumatica ERP and Install Debugger Tools check boxes.

              If you have already installed Acumatica ERP without debugger tools, you should remove
              Acumatica ERP and install it again with the Install Debugger Tools check box selected. The
              reinstallation of Acumatica ERP does not aﬀect existing Acumatica ERP instances. You can
              also install the Acumatica ERP Tools separately. For details, see Acumatica ERP Installation On-
              Premises: To Install the Acumatica ERP Tools (Optional).

Step 2: Deploying the Needed Acumatica ERP Instance for the Training Course You deploy an Acumatica ERP instance and configure it as follows:

Open the Acumatica ERP Configuration wizard, and do the following: a. Click Deploy a New Acumatica ERP Instance for T-Series Developer Courses. b. On the Instance Configuration page, do the following: a. In the Training Course box, select T200 Maintenance Forms. b. In the Local Path to the Instance box, select a folder that is outside of the C:\Program Files (x86), C:\Program Files, and C:\Users folders. (We recommend that you store the website folder outside of these folders to avoid an issue with permission to work in these folders when you customize the website.) c. On the Database Configuration page, make sure the name of the database is SmartFix_T200. The system creates a new Acumatica ERP instance, adds a new tenant, and loads the data to it.
Sign in to the new tenant by using the following credentials:

Username: admin
Password: setup Change the password when the system prompts you to do so. Getting Started | 12

In the top right corner of the Acumatica ERP screen, click the username, and then click My Profile. The User Profile (SM203010) form opens. On the General Info tab, select YOGIFON in the Default Branch box; then click Save on the form toolbar. In subsequent sign-ins to this account, you will be signed in to this branch.
Optional: Add the Customization Projects (SM204505) and Generic Inquiry (SM208000) forms to your favorites. For details about how to add a form to your favorites, see Favorites: General Information.

Step 3: Creating the Database Tables Add the RSSVRepairService and RSSVDevice tables to the instance database by executing the Customization\T200\SourceFiles\DBScripts\T200_DatabaseTables.sql script, which you have downloaded from Acumatica GitHub. Before you can customize Acumatica ERP, tables for the instance database need to be designed and added to the database. For this course, the database scripts have been prepared in advance. This is why you needed to add them to the instance database.

         The design of database tables is outside of the scope of this course. For details on designing database
         tables for Acumatica ERP, see Designing the Database Structure and DACs.

Application Programming Overview

Acumatica Framework provides the platform and tools for developing cloud business applications. This topic explains the runtime structure of Acumatica Framework and introduces the main components of this platform.

Runtime Structure and Components

An application written with Acumatica Framework has n-tier architecture with a clear separation of the presentation, business, and data access layers, as shown in the following diagram. You can find details about each layer in the sections below. Getting Started | 13

Data Access Layer

The data access layer of an application written using Acumatica Framework is implemented as a set of data access classes (DACs) that wrap data from database tables or data received through other external sources (such as Amazon Web Services). The instances of data access classes are maintained by the business logic layer. Between requests, these instances are stored in the session. On a standalone Acumatica ERP server, session data is stored in the server memory. In a cluster of application servers, session data is serialized and stored in a high-performance remote server through a custom optimized serialization mechanism. For details about data storage in a session, see Session. For details on working with the data access layer, see Accessing Data. Getting Started | 14

Business Logic Layer

The business logic is implemented though the business logic controller (also called graph). Graphs are classes that you derive from the special API class (PXGraph) and that are tied to one or more data access classes. Each graph conceptually consists of two parts:

Data views, which include the references to the required data access classes, their relationships, and other meta information
Business logic, which consists of actions and events associated with the modified data. Each graph can be accessed from the presentation layer or from the application code that is implemented within another graph. When the graph receives an execution request, it extracts the data required for request execution from the data access classes included in the data views, triggers business logic execution, returns the result of the execution to the requesting party, and updates the data access classes instances with the modified data. For details on working with the business logic layer, see Implementing Business Logic.

Presentation Layer

The presentation layer provides access to the application business logic through the UI, web services, and Acumatica mobile application. The presentation layer is completely declarative and contains no business logic. The UI consists of ASPX webpages (which are based on the ASP.NET Web Forms technology) and reports created with Acumatica Report Designer. The ASPX webpages are bound to particular graphs. When the user requests a new webpage, the presentation layer is responsible for processing this request. Webpages are used for generating static HTML page content and providing additional service information required for the dynamic configuration of the web controls. When the user receives the requested page and starts browsing or entering data, the presentation layer is responsible for handling asynchronous HTTP requests. During processing, the presentation layer submits a request to the business logic layer for execution. Once execution is completed, the business logic layer analyzes any changes in the graph state and generates the response that is sent back to the browser as an XML document. For details on the configuration of ASPX webpages, see Configuring ASPX Pages and Reports.

Querying of the Data

Acumatica Framework provides a custom language called BQL (business query language) that developers can use for writing database queries. BQL is written in C# and based on generic class syntax, but is still very similar to SQL syntax. Acumatica Framework provides two dialects of BQL: traditional BQL and fluent BQL. We recommend that you use fluent BQL because statements written in fluent BQL are simpler and shorter than the ones written with traditional BQL. Further in this topic, the examples are written in fluent BQL.

          You can also use LINQ to select records from the database or to apply additional filtering to the data
          of a BQL query. For details on which approach to use, see Comparison of Fluent BQL, Traditional BQL,
          and LINQ.

BQL has almost the same keywords as SQL does, and they are placed in the same order as they are in SQL, as shown in the following example of BQL.

SelectFrom<Product>.Where<Product.availQty.IsNotNull.
        And<Product.availQty.IsGreater<Product.bookedQty>>>

Getting Started | 15

If the database provider is Microso SQL Server, the framework translates this expression into the following SQL query.

SELECT * FROM Product WHERE Product.AvailQty IS NOT NULL AND Product.AvailQty > Product.BookedQty

BQL extends several benefits to the application developer. It does not depend on the specifics of the database provider, and it is object-oriented and extendable. Another important benefit of BQL is compile-time syntax validation, which helps to prevent SQL syntax errors. Because BQL is implemented on top of generic classes, you need data types that represent database tables. In the context of Acumatica Framework, these types are called data access classes (DACs). As an example of a DAC, you would define the Product data access class as shown in the following code fragment to execute the SQL query from the previous code example.

using System; using PX.Data;

PXCacheName("Product") public class Product : PX.Data.PXBqlTable, PX.Data.IBqlTable { // The property holding the ProductID value in a record PXDBIdentity(IsKey = true) public virtual int? ProductID { get; set; } // The type used in BQL statements to reference the ProductID column public abstract class productID : PX.Data.BQL.BqlInt.Field { }

   // The property holding the AvailQty value in a record
   [PXDBDecimal(2)]
   public virtual decimal? AvailQty { get; set; }
   // The type used in BQL statements to reference the AvailQty column
   public abstract class availQty : PX.Data.BQL.BqlDecimal.Field<availQty> { }

   // The property holding the BookedQty value in a record
   [PXDBDecimal(2)]
   public virtual decimal? BookedQty { get; set; }
   // The type used in BQL statements to reference the BookedQty column
   public abstract class bookedQty : PX.Data.BQL.BqlDecimal.Field<bookedQty> { }

}

Each table field is declared in a data access class in two diﬀerent ways, each for a diﬀerent purpose:

As a public virtual property (which is also referred to as a property field) to hold the table field data
As a public abstract class (which is also referred to as a class field or BQL field) to reference a field in the BQL command

You will learn more about data access classes later in this course.

Querying Data in Acumatica Framework Part 1: Creating a Form with the Customization Project Editor | 16

MaintenanceForms