Acumatica ERP 4.1 Customization Guide

CUSTOMIZATION GUIDE
Acumatica ERP 4.1

| Contents | 2
Contents
Copyright......................................................................................................3
Introduction to Acumatica ERP Customization Guide................................... 4
Acumatica ERP Customization: Basic Concepts............................................ 5
Customization Stages...................................................................................7
Customization Planning.....................................................................................................7
Customization Development.............................................................................................10
Customization Deployment.............................................................................................. 11
Granting User Access Rights for Customization......................................... 14
Working on a Project................................................................................. 16
Acumatica ERP Customization Tools.......................................................... 21
UI Customization........................................................................................31
Classifying UI Objects.....................................................................................................31
Adding Input UI Elements............................................................................................... 32
Customizing Properties....................................................................................................36
Functional Customization........................................................................... 43
Adding a Data Event Handler.......................................................................................... 43
Other Methods of Functional Customization....................................................................... 47
Examples of Customization........................................................................ 48
Adding a TextEdit Input Field onto a Form........................................................................ 48
Adding Selector Fields onto a Form.................................................................................. 51
Adding the Account Class Selector Field...................................................................52
Adding the Business Account Selector Field..............................................................56
Adding the Contact Selector Field........................................................................... 60
Adding a Combo Box onto a Form................................................................................... 66
Adding a Column to a Grid Control.................................................................................. 72
Adding a Column to a Lookup Window............................................................................. 76
Generating a DAC Using a Database View Object...............................................................80
Implementing a Custom Event.........................................................................................88
Validating Field Values Using a Custom Event....................................................................90

| Copyright | 3
Copyright
© 2013 ProjectX International, Ltd.
ALL RIGHTS RESERVED.
No part of this document may be reproduced, copied, or transmitted without the express prior consent
of ProjectX International, Ltd.
4030 Lake Washington Blvd NE, Suite 100
Kirkland, WA 98033
Restricted Rights
The product is provided with restricted rights. Use, duplication, or disclosure by the United States
Government is subject to restrictions as set forth in the applicable License and Services Agreement
and in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS
252.227-7013 or subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software-Restricted
Rights at 48 CFR 52.227-19, as applicable.
Disclaimer
ProjectX International, Ltd. makes no representations or warranties with respect to the contents or use
of this document, and specifically disclaims any express or implied warranties of merchantability or
fitness for any particular purpose. Further, ProjectX International, Ltd. reserves the right to revise this
document and make changes in its content at any time, without obligation to notify any person or entity
of such revisions or changes.
Trademarks
Acumatica is a registered trademark of ProjectX International, Ltd. All other product names and services
herein are trademarks or service marks of their respective companies.
Software Version - 4.1
Last updated: August 19, 2013

| Introduction to Acumatica ERP Customization Guide | 4
Introduction to Acumatica ERP Customization
Guide
With Acumatica ERP web-based customization tools, you can change the look and functionality of
forms. By using these tools, you can create, configure, and maintain custom user interface elements
for Acumatica ERP applications, as well as the functionality of the modules developed with Acumatica
Framework (see Acumatica Framework Overview).
This guide describes the process of choosing the best customization approach to satisfy specific
application requirements.
Who Should Read this Guide
We designed this guide primarily to serve consultants and IT professionals who handle the deployment
and maintenance of Acumatica ERP applications to meet the custom business requirements of clients.
In This Guide
• Acumatica ERP Customization: Basic Concepts
• Customization Stages
• Granting User Access Rights for Customization
• Working on a Project
• Acumatica ERP Customization Tools
• UI Customization
• Functional Customization
• Examples of Customization

| Acumatica ERP Customization: Basic Concepts | 5
Acumatica ERP Customization: Basic Concepts
This article describes the basic concepts of Acumatica ERP customization, as well as some key terms
used throughout this guide.
Customization Project
A project is a set of steps designed to customize either Acumatica ERP or another application developed
in Acumatica Framework and used by a company. A step might be, for instance, adding a user interface
(UI) element on a form. Within a project, you can customize UI and form elements and the properties
of elements, and you can implement additional program code that changes some application logic.
Specialists who will work on customization projects should be assigned the Customizer role (see
Granting User Access Rights for Customization) so they can use Acumatica ERP customization tools.
You can optimize various UIs and business processes within a project, following customization
requirements that your company's managers have defined. By the time you complete a project, you will
have developed the customization code and updated the production application, merging customization
code with the existing application code.
For detailed information about projects, see Working on a Project.
Page Design Mode
You use Page Design mode when working with a form to adjust the properties of UI form elements
(input fields, check boxes, panels, and buttons), add new elements onto the form, and hide existing
elements. You can bind newly added elements with data fields simultaneously added to an appropriate
database table.
You can change the locations of UI elements on the selected area (main form, grid control, or tab) of a
form template, as well as the quantity and location of tabs and grids.
A form template is one of the form structures predefined by Acumatica ERP developers. You can easily add
UI elements onto the form templates.
You can program a form to react to certain events—for example, when the user clicks buttons to invoke
appropriate pop-up forms. Also, you can change the UI elements and properties of pop-up forms. When
you enter Page Design mode, the system also makes these pop-up forms available for UI customization.
In Page Design mode, you can also perform a functional customization, which means adding custom
code that changes the business logic and database structure of the application.
Customization Session
Every time you log in, open a customization project, and enter Page Design mode, the system starts a
new customization session. When each customization session begins, new customization code is created
or the existing customization code is opened for editing. (With existing code, Page Design mode starts
automatically, right after you select the project name, for all the forms already changed within all of the
previous customization sessions.)
During a customization session, you can change the appearance of Acumatica ERP forms by adding
or removing UI elements. You can also alter system behavior with custom events, add and modify
system objects, change objects' properties, and add custom code fragments to the application. The
system automatically updates the customization code of the project when you use the Acumatica ERP
customization tools to make changes to the application. You can also manually edit the customization
code during the current customization session and save these changes.
The customization session ends when you close the current project. When you continue the
customization process and start a new customization session, the system automatically loads the

| Acumatica ERP Customization: Basic Concepts | 6
customization code of the project, which includes saved changes from all previous customization
sessions. After you open a project in Page Design mode, you can view and edit all changes made to the
application within the project by customizers. Multiple customizers may not publish the same project
simultaneously.

| Customization Stages | 7
Customization Stages
Using customization tools, you can fit an Acumatica ERP application to your specific business
requirements. To make the customization process consistent, controllable, and predictable, we
recommend that you divide the customization into the following key stages:
• The planning stage involves defining the scope of the customization and assigning the
Customizer role to the appropriate Acumatica ERP users.
• The development stage entails splitting the customization into steps within the customization
project and performing the customization requirements in each step.
• The deployment stage involves the following actions:
• Checking the customization code of the project for errors (validation)
• Publishing the project (merging the customization code with the source application code) in
the customizer's application instance
• Testing the results of the customization on the customizer's application instance
• Downloading the validated and tested project customization code to an external XML file
• Uploading the project code to the company's production application
• Publishing the customization code in the production application (that is, updating the
production Acumatica ERP application with a customized version) and testing the results of
the customization at runtime
In This Section
• Customization Planning
• Customization Development
• Customization Deployment
Customization Planning
The customization planning stage starts with identifying the changes you want to make to the current
version of the Acumatica ERP application and defining the requirements of those changes. After
analyzing the defined requirements, your customization team should estimate the customization scope.
In the process, you will identify the components of the application to be changed, make a detailed list
of changes, and split the changes into customization steps.
This article provides a general overview of the planning process.
Gap Analysis
To define the customization scope, first thoroughly review the Acumatica ERP application and study
your business processes to find the gap between existing and new business processes. This information
will help you identify changes you want to make to the current version of the application. Before you
plan any changes to the application, you should fully understand the logic implemented in the current
version of the Acumatica ERP application and review the source code. To view the application code,
use the Source Code Browser capability, which is included in the Acumatica ERP customization tools.
To estimate the customization scope, you need to carefully review your current business processes and
identify differences between the changed business requirements and the possibilities that the current
application version gives users. To begin your business process review, identify all relevant business
processes. For each, identify the following:

• The user roles that participate in this process.
• The operations that users perform within this process (in the proper order).
• The data that users add, view, select, and modify when performing these operations.
• The workflow rules—including conditions, constraints, and necessary data verifications performed
—when users fulfill these operations.
Identifying Changes to the Acumatica ERP Application
Next, start planning necessary changes to the current version of the Acumatica ERP application. Split
the customization planning into the following steps:
Step Description
Identifying Changes in
Data Presentation
To plan changes to the presentation of data, first compare the data
involved in the business process and the data provided by the current
version of Acumatica ERP application to users. To identify necessary
changes to the application, you should answer the following questions:
• What data do application users need to work with, if any, that the
current version of the application doesn't provide?
• What data, if any, does the current version of the Acumatica ERP
application display to users that you don't want the application to
display?
Workflow Rules
In this step, you compare the operations performed by the users who
participate in the business process and the capabilities provided by the
current version of the Acumatica ERP application. To identify the necessary
changes to the application, answer the following questions:
• Does the business process include any operations performed under
certain conditions that are not implemented in the Acumatica ERP
application? If so, what are these?
• What data verifications does the business process require that are
not performed in the application? What specific data should be
verified?
• Which constraints influence the way the users perform the operations
involved in the business process, and the data required to perform
these operations?
Analyze the answers to these questions, which will help you estimate the
changes required to add the necessary facilities to the Acumatica ERP
application.
User Access Rights
Depending on your planned changes to the workflow rules, you may need
to define access rights to system objects for users who participate in parts
of the workflows. To identify the necessary changes in the user access
rights, you should answer the following questions:
• What changes to the current user access rights are required?
• What new Acumatica ERP user roles or user groups, if any, will
be required to perform some steps within the changed business
processes?
You will also need to define appropriate access rights for users involved in
customization development and deployment.

Planning Changes in Data Presentation
If any data required in the business process is not available in the current version of the Acumatica ERP
application, you might decide to change the data structure and make the required data available for
user entry and viewing on the application forms.
Before adding new logic to the application, you might need to again examine the existing code by using
the Source Code Browser. Before making changes to the user interface (UI), you should list changes in
data presentation for each form of the current application version that requires changes. Estimate and
allocate the needed changes in the volume of data available for Acumatica ERP application users.
At the moment of writing this guide, Acumatica ERP customization tools do not provide any means for
adding new forms to the Acumatica ERP application. If some new forms are necessary, you can develop
them within Acumatica Framework and bind them to the product application as an add-on. See Acumatica
Framework Overview for more information.
When planning the changes in data presentation, you need to determine the following:
• Acumatica ERP forms that need to be modified.
• UI elements—input fields, check boxes, panels, or buttons—that need to be added or removed
from the forms.
• Changes in data sets associated with these forms and UI elements.
By using Acumatica ERP customization tools, you can change the data structure when you add new UI
elements onto a form. Because most form modifications involve adding UI elements onto a form and
linking them to new data fields, you can add UI elements to a form more easily (see UI Customization).
You can easily customize the UI because of the visual customization tools, which facilitate adding new
UI elements onto Acumatica ERP forms and linking them to the data source.
If you need to remove a UI element from the user's view, you can hide the element on the form.
(You cannot completely delete a UI element that was available on a form in the original version of the
Acumatica ERP application.)
When you're performing a more complex customization and the necessary data is not provided by the
data member object associated with the current form, you can add a new UI element onto the form and
associate the data member object with it, or add custom code that changes the structure of the data
tables associated with the Acumatica ERP application forms. The customizations may include changes
to the data management classes and attributes. The facility, named Code Editor, facilitates this type of
customization.
Planning Changes in Workflow Rules
In addition to changes made to the Acumatica ERP application data structure and UI elements, you can
add custom logic and functions that meet the changed business requirements. These rules should be
formalized before you develop new code.
To formalize rules, describe the new functions, conditions, data verifications, and constraints that are
required in the customized version of the Acumatica ERP application. For best results when you add
custom code, map the code to the application forms and check that the added code will not break the
current application version or interfere with application features that should not be affected by the
customization. For this purpose, you should carefully review the existing code of the Acumatica ERP
application by using the Source Code Browser.
You can add new events, functions, data verifications, and constraints to the application to implement
the new business logic in the customized version. These modifications involve by using the Code Editor
included in the Acumatica ERP customization tools. To control the user data input to the UI elements,
you can add input masks by changing the properties or attributes of the data field associated with the
element. Use the visual customization tools accessible from the Acumatica ERP forms in Page Design
mode, covered in Acumatica ERP Customization Tools.

Delegating Customization Role Privileges to Acumatica ERP Users
Finally, decide which users will access the Acumatica ERP customization suite tools and perform the
customizations. First, divide the customization process into preparing the customization code (as a
rule, within a customizer's application instance) and updating the company's production application.
(We do not recommend that customization development be performed on a production application.)
No constraints are needed when a customization project is being developed in the customizer's
own application instance, except for the requirements of not publishing more than one project
simultaneously, as well as not publishing the same project simultaneously by more than one customizer
(See Development Guidelines for details.)
In each customizer's application instance, you can grant customizer privileges to many customizers, but
we recommend that you have no more than two customizers per instance. As for customizers who work
on a company's production application, one to three users with the Customizer role is usually enough,
depending on the customization scope and the company's scale.
Consider the following common requirements:
• You can grant customization privileges to Acumatica ERP application users only by assigning them
the built-in Customizer role.
• The users who will be granted the Customizer role must be authorized Acumatica ERP internal
users.
• You should keep the list of customizers as short as possible to avoid significant system
performance degradation.
For information about granting customization privileges to a user, see Granting User Access Rights for
Customization.
Customization Development
During this stage, you will develop the customization, which involves implementing your planned
changes by using Acumatica ERP customization tools. Whether on your own or with other members
of the Customizer role (see Granting User Access Rights for Customization), you will modify the
appearance and logic of the Acumatica ERP application to meet the defined requirements. Usually, each
customization step involves the customization of one form, and you may have multiple steps per form,
depending on the scope of the changes.
Development Guidelines
For a verifiable, manageable, and predictable customization process, follow these guidelines during the
development process:
• Create the customizer's application instance, which represents a standard installation of
Acumatica ERP with the same release that the company's application uses, and consists of the
website and the database. All further actions must be performed on this instance.
• Split every form customization into elementary steps, such as adding a user interface (UI)
element or creating a new event.
• Validate the changes performed after completion of every step.
• Save the validated changes to an external file before you move on to the next step.
• Remove the unsuccessful customization, if necessary.
You cannot publish more than one project for each application instance used by a customizer. The
company's production version of the application, too, cannot have more than one customization project.
If you need to further customize the production version of the application after the project has already
customized it, you must unpublish the project and make all needed new customization steps part of the
same project. For more details on publishing customization projects, see Customization Deployment.

Customizing a Form
You will use the Acumatica ERP Customization Tools to perform the steps of the customization project.
You use these tools to modify the appearance, behavior, and logic of Acumatica ERP application forms.
To begin working with these tools, you create a new customization project or open the existing one.
The customization of a form is usually split into the following steps:
• Performing the UI Customization: This step might involve adding or removing the elements, or
changing the properties and locations of elements. The visual customization tools automate the
processes of adding elements onto the form, changing properties, and removing elements from
the form.
• Performing the Functional Customization: Functional customization entails changing the structure
of data fields associated with the form, adding custom events, or modifying the Acumatica
ERP application business logic associated with the customized form. To perform functional
customizations, you usually add custom code to the application by using the Acumatica ERP
Customization Tools tool.
• Checking the performed customization for errors (validation): To ensure that the changes made
to the UI are error free, compile the Acumatica ERP application code, incorporating the changes
made to the UI and business logic of the form.
• Saving the customization project to the database: You save the current project to persist it
and make the customization data available for use in the future. You can also download the
project customization code to an XML file—for instance, to have an archive copy or to upload
customization data to another customizer's application instance or to the company's production
application.
• Removing any unsuccessful customization code: To remove the code, you can edit the
customization code and manually delete the erroneous data. Alternatively, you can upload the
code saved in the external file to continue the customization process from a point when the
project's customization changes had been verified (validated) and established.
Saving and Restoring Customization Data
As mentioned, you can preserve changes you made to an Acumatica ERP form during customization by
saving the customization project's code. By using Acumatica ERP customization tools, you can remove
changes performed in one customization step or multiple steps.
You can manage the customization code of the project in any of these ways:
• Save the code to the database. Select Save Project to Database from the Customization menu,
or use the relevant options available in the Acumatica ERP Customization Tools or Code Editor.
• Download the code to an external file. For details about uploading and downloading, see the
Customization Data Editor section of the Acumatica ERP Customization Tools article.
• Restore the last compiled customization by reloading the customization code of the project from
the last successful compilation. You can use this option when the customization performed within
a customization step fails code compilation. To restore the last compiled customization, choose
Restore Project from Database from the Customization menu.
• Upload the customization code of the project from the external file saved after the last successful
customization step.
Customization Deployment
During customization deployment, the customizer applies all the changes made to the Acumatica ERP
application version by using an application instance: a local instance of the application with a separate
database. This instance, including the database structure, must have the same application configuration

as the production application where the project customization will be deployed. The customizer's
application instance should be a standard installation of Acumatica ERP with the same release.
After finishing the customization project, the customizer validates and publishes it in the local
application instance to test the results of the project. If the test results are successful, the customizer
downloads the project code to an external XML file, uploads the code to the company's production
application, and validates and publishes the uploaded project. (The customizer could instead send this
file to another specialist who performs this final work.)
The customizer begins customization deployment by downloading validated, published, and tested
customization code to an external XML file. Within the company's production application, the customizer
(or another specialist with the Customizer role) does the following:
• Uploading the XML-file code to the application
• Validating and publishing the customization project; updating the current application version
• Removing the customization project from the company's application, if the published
customization was unsuccessful or the current customization project code is to be replaced with
another one
From this point forward, we will assume that you are a customizer who will be involved in deployment.
Validating and Publishing the Project Locally
You perform the essential validation step in your local application instance to ensure that the
customization changes do not conflict with the current application version. During this step, you merge
the Acumatica ERP application code with the project customization code, so that the changes made
during development will take effect. The system reports any errors that occur during validation. If the
customization fails validation, you must troubleshoot the customization or delete it from the database.
To validate the changes of the customization project and publish the changes in your application
instance, perform the following actions:
• To start validation, on the Customization menu, select Validate and Publish. The validation
results window shows the code compilation results.
• To view the validation results, browse the opened window. If the customization validation fails, the
window displays the list of errors. The screenshot below illustrates an example of error messages.
Figure: Project step validation has failed
To fix errors, do either of the following:

• To return to the customization code from the last successful customization, refuse the publication;
then upload the appropriate XML file by using the Customization Data Editor.
• To discard the customization changes, refuse the publication. Then correct or delete the project
customization code through the Project Editor, Customization Data Editor, or Code Editor.
After successful validation, you can publish the customization project, which adds the customization
code to the current version of application instance, yielding a new version with the validated changes.
To publish the validated customization project, on the validation results window, click Publish. To
ensure that the local application has been customized correctly, you should thoroughly test the
application.
Downloading the Project to an External XML File
After you test the finished customization project, you must download the customization code to
an external XML file for uploading this code to the company's production application. Use the
Customization Data Editor to perform the download and upload actions.
Uploading the XML-file Code and Updating the Production Application
You can update and use the project customization code in only the same application configuration on
which it was developed. Thus, after you have developed and thoroughly tested a customization with
your application instance, you can deploy it to the production instance (or to multiple instances) with
the same application configuration; for Acumatica ERP, the customizer's instance and the production
instance must have the same release number. To deploy the customization, use the external XML file
created in the previous step.
If the customizer's application instance for Acumatica ERP has another release number than the company's
production application to be customized, you should upgrade the application with the earliest release
date. You can upgrade any customized application without invoking the Undo Publish procedure, which is
performed automatically. If the upgrade finishes successfully, the Validate and Publish procedure starts
after the first website opening. Invoke the Undo Publish procedure only if validation fails, which can happen
due to incompatibility of the customization and the new Acumatica ERP version code. In this case, you
should revise the customization code of the project to eliminate the incompatibility issues.
To deploy a successful customization to a production application instance, do the following:
• Upload the customization file on the target application where you must deploy the customization,
by using the Customization Data Editor.
• Validate and publish the customization to apply the customization (merging the customization
code with the main application code) on the target application and make it available for users of
the Acumatica ERP application.
Removing an Unsuccessful Customization from the Production Application
If the published customization was unsuccessful (for example, it doesn't meet user requirements)
or you must replace the code of the customization project, you should cancel the publication of the
customization. To do this, select Undo Publish on the Customization menu. The customization code
is not deleted, but the application does not use it. If necessary, you can then partially or completely
remove the unpublished customization code from the production application through the Project Editor
window.

| Granting User Access Rights for Customization | 14
Granting User Access Rights for Customization
To make it possible for Acumatica ERP users to customize Acumatica ERP applications, grant these users
the appropriate access rights to system objects by assigning them the built-in Customizer role.
You cannot assign a user to the Customizer role if either of the following conditions occurs:
• The user has a guest account—that is, for the user on the Users (SM.20.10.10) form, the Guest
Account check box is selected on the Options tab.
• The user is assigned to a guest role: a role for which the Guest Role check box is selected on the
User Roles (SM.20.10.05) form. In the screenshot below, notice two roles with the Guest Role
check box selected: Anonymous and Guest.
Including a User in the Customizer Role
If you have administrative rights within the application to be customized (see Delegating Customization
Role Privileges to Acumatica ERP Users), you can assign the Customizer role to a user. To do this,
proceed as follows (see the screenshot below):
1. Navigate to the Configuration > User Security > Manage > Internal Users to open the
Internal Users form.
2. In the Username box, select the Acumatica ERP user to whom the role should be assigned.
Figure: Granting the Customizer role to a user
3. To assign this user to the Customizer role:
• On the Membership tab, click Add Row.
• In the Role Name field, select Customizer, as shown in the figure above.
4. On the Form toolbar, click Save to save the changes to this user.

| Granting User Access Rights for Customization | 15
If the specialist handles development of the customization project and update of the production application
(deployment), you must grant the Customizer role to the specialist in both the specialist's application
instance and the production application instance. See The Project Workflow for details.

| Working on a Project | 16
Working on a Project
This article describes the customization process with Acumatica ERP, and provides practical information
about getting started.
The Project Workflow
As a rule, the customizer uses an application instance—the local application with a separate database—
while developing the customization. This instance must have the same configuration, including database
structure, as the production application where the project customization will be deployed.
The customizer's application instance is usually a standard installation of Acumatica ERP with the same
release as the production application has; the instance consists of the website and the database. Thus,
both the customizer's application instance and the production application to be customized have the same
configuration.
As described in the Customization Project definition, each project consists of a series of steps.
Depending on the application to be customized and the steps involved, customizers can share work
in ways that best meet the company's needs. For example, each customizer can work on the same
project within the common application instance, while the project includes some steps to gradually
customize the application. The customizers would divide among themselves these steps, according to
the customization plan.
You may not publish more than one customization project in a customizer's application instance; otherwise,
problems of code compatibility can take place. If a project is not too complicated, we recommend that you
use a separate application instance for each project and a single customizer for each project.
As another example, imagine that a project includes customizing the user interface (UI) and form
elements, and adding code that changes some application logic. In this case, several customizers may
work within the same project. However, we don't recommend that customizers work simultaneously
on one customizer's application instance within the same project, to avoid situations when multiple
customizers try to publish the same customization or download it for publishing in another application;
unpredictable consequences can take place.
The whole project must be successfully validated before it is published.
In the rest of this article, we will assume that you are assigned the Customizer role.
Customizing a Form Within a Project
Because you have been assigned the Customizer role, every time you open a project, the system
automatically invokes Page Design mode for all previously changed forms and starts a new
customization session. The system automatically updates the customization project after you perform
changes. You can easily customize Acumatica ERP applications by using visual tools to change the
properties and behavior of UI elements on the selected form. You can create and edit the customization
code in either of the following ways:
• Automatically for UI form elements and their properties—by visually adding and managing them,
as well as specifying the properties of elements by using Aspx Control Tree.
• Manually in the Code Editor, Project Editor, or Customization Data Editor window (described in
Acumatica ERP Customization Tools). You can access the code of the current customization project
in any of these windows.
You can simultaneously open multiple forms within the same project in Page Design mode. Each
customizer who enters Page Design mode within the same project can view changes made to these
forms, which are saved in the body of the customization code of the project.

Scenario Description
New Project To customize an Acumatica ERP application form within a new project, perform the
following actions:
• To create the new project, on the Customization menu, select Open
Customization Project (see the first screenshot below).
• In the Select Working Project window that appears, click New (as shown in
the second screenshot, near the red 1).
• In the New Project window that appears, type the new project name (see
item 2 in the second screenshot below) and then click OK (item 3).
• In the still-opened Select Working Project window, click OK (item 4) to add
the new project.
• To work in Page Design mode, open the form you want to change, and on the
Customization menu, select Enter Page Design Mode.
Figure: Opening a new customization project

Figure: Assigning a name to a new project
• Perform the required customization actions within each step. For instance,
right-click the upper area of the form (the main form of the form template)
and select Add Input Control. Add the input field. Right-click the added
field and select Control Tree to specify the properties of the field. The first
screenshot below (under the Exiting Page Design Mode subsection) illustrates
the process of adjusting the added input field properties.
Existing
Project
To customize an Acumatica ERP application form within an existing project, do the
following:
• On the Customization menu, select Open Customization Project. The system
automatically opens in Page Design mode forms in the project that have been
changed.
• To work in Page Design mode for a form included in the project but not yet
changed, open it on the Customization menu and select Enter Page Design
Mode.
• Perform the required customization actions within each step on forms to
be changed. In Page Design mode, you can access the Acumatica ERP
customization tools on the Customization menu and the pop-up menu on the
customized form; two items of the pop-up menu were described above.
You can use visual customization tools, invoked on the pop-up menu, to
perform a Functional Customization. To change system logic and functionality,
use the Code Editor facility to add custom code to the Acumatica ERP
application.
Existing Page
Design Mode
To exit Page Design mode for all the forms included in the project, on the
Customization menu, select Close Project (see the second screenshot below, item
3). When you exit Page Design mode, all the changed data is automatically saved
to the database as the current content of the customization project. To publish the
changes of the project, you should compile and validate them to exclude program
errors.

Figure: Adjusting the properties of the input field
Figure: Exiting Page Design mode and closing the project
If you select Exit Page Design Mode (see item 2 in the second screenshot above),
only the current form will exit this mode while the other forms stay ready for
customization.
Starting and Finishing a Customization Session
To start a new customization session, follow the instructions below:
1. Create a new project (or select the name of the existing one), open the Acumatica ERP form
you want to customize, and enter Page Design mode. (If the project already exists, previously
customized forms will be opened in Page Design mode automatically.)
2. Perform all necessary changes.

3. To check the changes for errors, validate each customization step that you performed.
4. If you need to add another form to the current customization project, open the form, enter Page
Design mode, and start customization.
5. Repeat instructions 2–4 for the new customized form.
6. Save the customization changes of the validated project. You can also download the updated
customization code to an external file.
You can later upload data from the downloaded file, either to the current customizer's application
instance or to the company's production application (as a distributive unit of sorts). For example,
after you create, validate, and test your project on a local copy of the main working application, you
can upload the project's changes to the main application. When you're ready to apply the changes
performed within a customization session to the application, publish the customization. You may
also publish intermediate versions of the project customization code to test changes. After testing,
you shouldn't invoke the Undo Publish action to continue with developing the customization project.
To finish the customization session, close the project, which closes all the forms opened in Page Design
mode.
You can handle changes made within the customization session in any of the following ways:
• Discard the changes, if they were not yet saved to the database manually, by selecting Reload
Project from Database on the Customization menu.
Changes within the current session are saved automatically when you exit Page Design mode (for
the current form) and when you close the project (for all customized forms and for other changes,
including functional changes). You can also manually save changes within the current project session
by clicking Save to database in the Customization Data Editor window.
• Remove the changes partially, if they have been already saved to the database, by manually
editing the customized forms or customization project. You can remove any changes within the
selected project.
You can act upon all the changes of the project, including those made in previous customization
sessions, as follows:
• Validate and publish: On the Customization menu, select Validate and Publish.
• Published without validation: This option is not recommended.
• Unpublished: Select Undo publish on the Customization menu, and the application will be returned
to its initial state. The customization project data will not be removed; it can be corrected and
supplemented for further validation and publication.
• Removed from the database: Use the Project Editor to delete from the appropriate customization
project saved changes that you no longer deem necessary.

| Acumatica ERP Customization Tools | 21
Acumatica ERP Customization Tools
Acumatica ERP can be customized by consultants, experienced Acumatica ERP users, and IT
professionals who handle application deployment and maintenance. To give Acumatica ERP users the
necessary access rights to perform the customizations, assign these users the Customizer role (see
Granting User Access Rights for Customization) so that they can use the Acumatica ERP customization
tools.
If you have been assigned the Customizer role, when you open a form you need to customize, you can
access the customization tools on the Customization menu. These tools let you do the following:
• Create and manage customization projects.
• Start the project customization sessions and select Acumatica ERP system objects (webpages,
data access classes, business logic containers, and database scripts) to be customized.
• Customize the user interface of the Acumatica ERP application and perform functional
customizations of system objects.
• Save changes made during the project customization sessions to the database or an external XML
file.
• Edit the customization code, which holds the customization changes of the project.
• Upload the customization code.
• Validate the customization changes and publish them to a production instance of the application.
• Remove the customization changes from the application after publishing, to restore the
application to the version that existed before the publication of customizations (Undo Publish).
This option might be needed, for instance, to improve customization code that has become
outdated; after adding all necessary corrections, you can validate and publish the project again.
• Deleting any customization code or its separate layers from the database if, for instance, users
were not pleased with customization changes.
Customization Code
Within each project, the system maintains customization code that holds data about customizations that
have been performed. The customization code, initially created within a customization session, is used
for the whole project. You can download the customization code to an external XML file and publish it
in the company's production application to update this application (see Customization Deployment).
The downloaded code represents a distributive unit, because it usually must be downloaded from the
customizer's application instance and uploaded to a production instance of the application. For example,
after you create, validate, and test your project on a copy of the production application (see also the
note in the Starting and Finishing a Customization Session section of the Working on a Project topic),
you can upload the changes to the production instance of the application.
In the customization code window, you can view information about the changes to the application; see
the first screenshot below (under The Project Editor section) for a code fragment of typical changes.
The Code Structure of a Project
The structure of customization code, much like that of an XML file, consists of the following:
• The standard XML-file heading.
• The opening and closing <Customization> tags pointing to the start and end of the customization
code.

• The customization body placed between the opening and closing <Customization> tags. The body
includes the tags specifying the system objects that should be changed and the data describing
changes to be made.
The XML-file heading and the <Customization> tags are required parts of an external customization
file; if you remove them, the application will not work properly.
The system stores the customization code in the customization sections as structured data describing
the necessary modifications in the data presentation components (forms and UI elements—input fields,
check boxes, panels, or buttons), business layer components (graphs, events, and views), data access
components, database table structure changes, and database scripts. Physically, the description of
modifications is split between the application layers and includes the following:
• Changes made to the .aspx forms and aspx.cs files responsible for data presentation to the users.
• Changes made to events associated with the system objects defined for the Acumatica ERP forms.
(These can include form elements and data access components.)
• Changes made to the Acumatica ERP system objects.
• Scripts performing the necessary modifications to the data structure in the database.
The Project Editor
To see the application layers in the Project Editor window, on the Customization menu, select View
Customization Manager, as the screenshot below illustrates. You can manually edit, add and edit, or
delete each layer from the database table. When you start the first customization session of a selected
project, the system creates a new customization code; if you start a previously customized project, you
can open the existing customization code for making new changes.
Figure: Layers of the customization code
Operations with the Customization Code
You can perform operations to edit, save, download, or delete the customization code of a project. See
below for descriptions of these operations.

Action Description
Editing Customization Code You can edit the customization code of a project to partially remove
the customization changes, modify properties of the objects added or
changed within the customization session, and change or delete the
fragments of custom code.
Saving Customization Code
to the Database
After you edit the customization code, it must be saved manually or
automatically. The system performs automatic saving when you close
the current project.
When the customization code is saved to the database, all the
changes made to the code are applied to the session of the current
project. After you start a session of a new project, the customization
process continues from the point when the customization code of the
project was saved.
The system stores the XML content of the customization code in the
system database.
Downloading the
Customization Code of a
Project
You can download the customization code to an external file,
to make the code available for uploading customization data
later. When you download the customization code, changes
made in the manual editing mode before saving are not applied
to the customization session of the current project, and the
customization process continues from the point where it was when
the customization code was last saved to the database.
Deleting Customization Data
From the System
You can discard customization changes (for the whole project or
in part) before you publish the customization to the production
Acumatica ERP system. To delete the customization data related
to the customization project, you can open the XML content of the
customization code and manually remove the code body data from it,
or you can delete the saved customization code or some of its layers
from the database table by using the Project Editor.
To allow saving and loading of the customization code, the Acumatica
ERP customization tools use the Customization Data Editor.
The Customization Menu
By using the Customization menu, you can use the Acumatica ERP customization tools. By using the
menu commands, you can perform such tasks as the following:
• Creating new customization projects.
• Starting and ending customization sessions (for example, after entering Page Design mode).
• Accessing the facilities of the Acumatica ERP customization tools. By using special windows
with menus and buttons, you can perform various actions, such as adding or changing code,
downloading and uploading the customization code of the current project, and making a quick
context search.
• Managing changes performed within the customization sessions of the project.
• Validating customization projects and publishing successful customization projects to an
Acumatica ERP application.
As mentioned earlier, we recommend that only one project be published. All other projects can
be validated but cannot be published until you have invoked the Undo Publish command for the
currently published project.

• Canceling changes applied to the Acumatica ERP application, by using Undo Publish, after you
have published a customization project.
In the Acumatica ERP application, you can access the Customization menu on an opened form. You
can use the following commands to perform customization tasks.
Customization Menu Commands
Command Description
Save Project to Database Saves the current version of the customization code (that is,
modifications you have made during the current customization session)
to the database.
Reload Project from Database Reloads the current version of the customization code from the
database. If you haven't saved modifications to the database manually
within the current customization session, the modifications will be
replaced by the last modifications that had been saved earlier.
Open Customization Project Opens the existing customization project or creates a new one.
Close Project Closes the current project: ends the current customization session
and returns you to working with the Acumatica ERP application
version, with the last published changes implemented. The system
automatically saves all the changes to the database, if you haven't
saved them before closing the project.
Enter Page Design Mode Enters Page Design mode and provides access to the Acumatica ERP
customization facilities (such as DataField Attributes, Control creating,
Aspx Control tree). You can also use the visual customization tools to
modify Acumatica ERP forms opened in Page Design mode. To modify
multiple forms, you can open all the required forms in Page Design
mode—sequentially or at once. All the modifications belong to the
current project.
Exit Page Design Mode Exits Page Design mode only for the current form. The system
automatically saves to the database changes involving the current
form, in case you haven't saved them before exiting Page Design
mode. To end the customization session and return to working with the
Acumatica ERP application, you must also close the current project.
Validate and Publish Validates the finished or intermediate customization and publishes it
to the Acumatica ERP application (if you click Publish after successful
validation).
View Published Customization
XML
Displays the published customization code in XML format. Provides the
processes of downloading to and uploading from an external XML file.
Undo Publish Removes the last published project customization version from the
application, and restores the previous Acumatica ERP application
version. This action discards published modifications from the current
project, but the customization code of each existing project remains in
the database.
View Customization Manager Opens the Project Editor window and (in the left pane) the System
Management navigation menu with the Customization Management
tree. In the Project Editor window, you can see, edit, and remove (if
needed) all changes within the current project involving .aspx forms,
data access classes (DACs), scripts, and graphs—that is, business
logic containers (BLC)—code as layers of the customization code of

Command Description
the project. You can also select another existing project to manage its
customization layers.
View Source Code Displays the existing source code of the selected object. You can
use this command to analyze the application code before you make
customization changes, during the planning or development stage of
customization.
Code Editor Opens the Code Editor window so you can add or change the code
concerning the appropriate customization code section (layer) of the
current form.
Aspx Editor Opens the Aspx Editor window so you can add or change the .aspx
code concerning the current form.
The Customization Data Editor
The Customization Data Editor gives you direct access to the customization code of the project so you
can modify customization data. You can view the current version of the code, remove some sections
from its body, or change some properties of elements added within customization sessions. You can also
download and upload the code.
By using the Customization Data Editor, you can open, view, and modify the customization code. You
can save the new version of the customization code to the database and download it to the external
XML file. To modify customization code in the Customization Data Editor, perform the following basic
steps:
1. Start a new customization session or continue the current session.
2. On the Customization menu, select View Customization Manager to open the Customization
Projects form.
3. Click the Edit XML button in upper part of the form, on the main toolbar.
4. In the Customization Data Editor window that appears (see the screenshot below), make
necessary changes to the customization code of the project.
5. Click Save to database, also shown in the screenshot below, to save the modified
customization code.
You can more easily open the Customization Data Editor window, if your project has been
published already: Just select View Published Customization XML. As a rule, the purpose to open
the Customization Data Editor window in this case—to download the published project to the
external XML file (see the next optional instruction).

Figure: Working in the Customization Data Editor window
1. Optional: To download customization data to an external file, proceed as follows:
• Click Download Package (shown in the screenshot above).
• In the pop-up window, click Save File, as shown in the screenshot below. (The name of
the external archive file with the .zip extension is displayed in the upper part of the pop-up
window.)
• Click OK. You can then unzip the XML file and view it by any standard archiving program,
as shown in the screenshot below.
Figure: Opening the downloaded XML file
The application server archives the XML file and then translates the zipped file to the client. You may be
able to select the location path and the name of the file, depending on your web browser. You don't need to
unzip the file before uploading it.

You can upload the customization code that was previously downloaded. When you upload the
customization code from the external file, the uploaded code replaces the code of the last version of the
project with the same name. Proceed as follows to upload the customization code of a project from the
external file:
1. On the Customization menu, select View Customization Manager to open the Customization
Projects form.
2. Click the Edit XML button in upper part of the form, on the main toolbar.
3. Click Browse to select the appropriate zip file that contains the required XML file for uploading.
4. Click Upload Package to update the customization code with code of the XML file.
5. Optional: Apply the changes to the current session by clicking Save to database. The saved
code is now the control point of the project customization code—that is, the point to which you
can roll back the customization project or from which you can move forward if some unforeseen
loss of data takes place.
The Code Editor
By using the Code Editor, you can view the customization code of the project, add new custom code
lines, validate the added code, and incorporate the changed code into the customized version of the
Acumatica ERP application. You use the Code Editor to perform functional customizations. You can
validate the source code added to the application—that is, check the code for errors—and publish it.
Generally, functional customizations are bound to particular Acumatica ERP forms. You can open the
Code Editor on the form available for customization; by default, the Code Editor displays the initial
graph code, which can be created. As a rule, this code consists of the group of namespace operators
using, declaration of the class whose name is compound (the basic DAC name of the form with the Cst_
prefix and the maint suffix), and the empty Event Handlers region. You can modify this initial code and
then publish the modified code.
To access the Code Editor, perform the following instructions:
1. Start a customization session of the project (or continue the current session).
2. With the form opened in Page Design mode, right-click any area and select Code Editor on the
pop-up menu, or select Code Editor on the Customization menu.
The system stores the customization code related to modifications performed with the Code Editor in
the appropriate section of the project.
The Source Code Browser
The Source Code Browser displays by default the .aspx code for the selected form and its Graph (BLC)
and DAC. The .aspx code includes all the modifications performed during the customization sessions
concerning the UI elements of the selected form. To open the Source Code Browser, select View Source
Code on the Customization menu. You can also navigate to the Source Code form: On the System
tab, click Customization, and in the left pane, navigate to Explore > Source Code. In this case, to
see code on the Page aspx tab, you must manually select the form ID in the lookup window. You can
also select any BLC and DAC object (including the object created during customization sessions) to see
its code.
The Source Code Browser displays the code in various views on the different tabs:
• The Business Logic tab (see the screenshot below) displays the BLC code, also referred to as
graph source code, associated with the selected form.

Figure: The Business logic tab
• The Data Table Declaration tab (see the screenshot below) shows the source code that
defines the structure of data stored in the database tables represented by one or more data
access classes in the application code. To see the code of a DAC, select the object name that is
referenced to the database table associated with the selected form on the lookup window.
Figure: The Data Table Declaration tab
• On the Find in Files tab (shown in the screenshot below), you can find application and
customization code fragments that contain the text you type into the Find Text box.

Figure: The Find in Files tab
• The Page Aspx tab (see the screenshot below) displays the current source code of the .aspx
file associated with the selected form. The changes related to the customization of the form are
highlighted in yellow.
Figure: The Page Aspx tab
The Aspx Editor
The Aspx Editor (see the screenshot below) displays visual elements of the selected form, and you
can add, edit, and compile custom code by using the .aspx code of the project. You can open the Aspx
Editor by clicking Aspx Editor on the Customization menu. Alternatively, you can open the Aspx Pages
form as follows: On the System tab, click Customization, and in the left pane, navigate to Edit >

Aspx Pages. To access .aspx code, type or select the virtual path of the required form in the lookup
window.
By using the Aspx Editor, you can perform the following tasks:
• Manually add or edit the custom code appended to the Acumatica ERP application, as well as edit
the original .aspx code lines.
• Save the appended or modified code to the database by clicking Checkin (see the screenshot
below).
Figure: The Custom Code Tab

| UI Customization | 31
UI Customization
As your business processes change, you might want to make corresponding changes to the user
interface (UI) of Acumatica ERP applications so that users can work more efficiently. With Acumatica
ERP customization tools, you can easily perform UI customizations, such as changing the look and
behavior of forms, tweaking the design of forms, and expanding the necessary input data range (for
instance, by changing data types or digit capacity).
If you are working with an Acumatica ERP application, explore changes to subsequent releases of
Acumatica ERP before you start to customize UI elements. You may not need to customize the application
after you upgrade it, if appropriate UI changes have been made to fit your requirements. See Identifying
Changes to the Acumatica ERP Application for additional information.
By using Acumatica ERP customization tools, you can perform the following UI customization tasks with
ease and flexibility:
• Adding advanced controls (form views, grids, tabs, panels, and buttons) onto forms
• Adding input UI elements onto forms
• Customizing the properties of existing UI elements and adjusting the properties of added
elements
• Hiding existing UI elements and removing added elements
• Adding new forms based on Acumatica Framework templates
In This Section
This section covers the following topics:
• Classifying UI Objects
• Adding Input UI Elements
• Customizing Properties
Classifying UI Objects
This article summarizes basic concepts of using and classifying user interface (UI) objects. If you
understand how to classify UI objects that must be customized, you can more easily assess the
complexity of the customization project and work more efficiently.
Bound and Unbound Objects
You can classify each UI element added to a form as either bound or unbound.
Bound objects are UI objects—input fields, check boxes, group boxes, combo boxes, and selectors—
linked to database fields. When you define bound objects, you must use data types with the DB prefix
(for instance, DBString or DBDecimal). All bound UI objects are input UI elements.
To connect a bound object to its data source, you add the object onto the form and link the object to
an existing data field (or a new data field you create). You can then modify the behavior, appearance,
and visibility of the object by changing its properties, which changes the properties of the data field
associated with the bound object. Changes made to data field properties affect all the UI elements that
are linked to this data field. Unbound objects are UI objects—form views, grids, tabs, panels, buttons,
field labels, and descriptors—that have no connection to the database. As a rule, after you have added
an unbound object onto the form, you customize the properties of the object only on the UI level. No
other customization is involved, except for adjusting such property values as width, height, font style,

background color, and top and left positions of the object's upper left edge. In this guide, unbound UI
objects are called advanced controls.
To use buttons, you should add an event handler that will react on mouse clicks and will perform
commands, which are provided by customization code. To use a descriptor for a selector field, you have
to add the DescriptionField parameter value to the PXSelector attribute.
You can consider as unbound objects non-UI objects, such as events and primary views. You implement
these objects into customization code by performing functional customization. Most properties of unbound
objects (except for panels) are stored in the code of data access classes (DACs), business logic containers
(BLCs), or .aspx pages. (For instance, unbound field label names are stored in DACs or BLCs while unbound
field properties are stored in .aspx pages.) Bound UI objects are bound with both database tables and
appropriate system objects. For example, after you add a UI field, new code lines with the field (having
the same name as in the database table) and its attributes are added to the code of the relevant DAC
automatically.
Simple and Complex Objects
You can also classify UI objects as simple and complex:
• Simple objects: You do not need to adjust these UI elements (or you might change them slightly,
such as for location and size) after you add them onto the form. Simple objects can be bound or
unbound. Most input (text, numeric, Boolean, and date) fields, as well as check boxes and group
boxes, are simple bound objects, which can use data fields as the data source. Form views, grids,
tabs, panels, and group captions (which logically group the UI elements on the form) are simple
unbound objects; you can add them and take no further actions.
• Complex objects: You must adjust these UI elements after you have added them onto the
form (whether they are bound or not). Selectors, combo boxes, and descriptors are complex
bound objects. You can bind selectors to multiple referenced database tables by adding attribute
parameters or BQL expressions to the corresponding DAC code. To use combo boxes, you must
add appropriate customization code to the relevant BLC. To use descriptors for the selector fields,
you have to add the appropriate parameter values to the code of the corresponding DAC.
Adding Input UI Elements
As noted in Classifying UI Objects, input UI elements are bound UI objects—that is, the elements must
be linked to fields of appropriate database tables. This article describes data field types and input UI
element types, as well as the process of adding a new input field onto the form.
Data Field Types
A data field type defines how the data associated with the UI element will be stored or retrieved.
Depending on the data type requirements, you can create a new field in the database or use an
appropriate data field type to link the UI element with a system object—data access class (DAC) or
business logic container (BLC)—that stores the corresponding data as a value.
Only data field types with the DB prefix can be used to store data in and retrieve data from the database.
In the Field Type box, you can select one of the data field types listed in the following table.
Data Field Type Description
DBInt(Int) Links an input field to a new or existing database table column with
the integer data type.
DBBool(bit) Links an input field to a new or existing database table column with
the Boolean data type.

Data Field Type Description
DBLong(bigint) Links an input field to a new or existing database table column with
the bigint data type—that is, an integer containing values from –263
through (263 – 1).
DBDecimal(decimal) Links an input field to a new or existing database table column with
the decimal data type (fixed precision and scale numbers). When
maximum precision is used, valid values range from (–1038 + 1)
through (1038 – 1).
DBDate(datetime) Links an input field to a new or existing database table column with
the datetime data type (a fixed-length string that represents either a
specific date and time or an interval).
DBGuid(uniqueidentifier) Links an input field to a new or existing database table column with
the uniqueidentifier data type (a 32-character hexadecimal string that
is stored as a 128-bit integer).
DBDouble(real) Links an input field to a new or existing database table column with
the real data type—a floating precision number from (–3.40E + 38)
through (3.40E + 38).
DBString(nvarchar) Links an input field to a new or existing database table column with
the nvarchar data type, which means that data in the database fields
is stored as variable-length character strings of Unicode characters.
You can define the maximum length of the string.
DBString(nchar) Links an input field to a new or existing database table column with
the nchar data type, which means that data in the database fields is
stored as fixed-length character strings of Unicode characters. You can
define the maximum length of the string.
String Links an input field to a system object storing and retrieving the data
as string values. You can define the length of the string.
Int Links an input field to a system object storing and retrieving the data
as integer values.
Bool Links an input field to a system object storing and retrieving the data
as Boolean values.
Long Links an input field to a system object storing and retrieving the data
as 32-bit signed integer values.
Decimal Links an input field to a system object storing and retrieving the data
as signed 128-bit (16-byte) values representing 96-bit (12-byte)
integer numbers scaled by a variable power of 10.
Double Links an input field to a system object storing and retrieving the data
as signed floating precision values from (–3.40E + 38) through (3.40E
+ 38).
Date Links an input field to a system object storing and retrieving the data
with the datetime data type (a fixed-length string that represents
either a specific date and time or an interval).
Guid Links an input field to a system object storing and retrieving the
data as a 32-character hexadecimal string that is stored as a 128-bit
integer.

Types of Input UI Elements
Acumatica ERP users use input UI elements to enter, view, or select data on forms. By using the
Acumatica ERP Customization Tools, you can add UI elements onto Acumatica ERP forms and link them
to the database fields or system objects that store the entered values. You can also set the visual
properties of the UI element.
You can add the following types of input UI elements onto forms:
• TextEdit: The user enters text in an input field.
• NumberEdit: The user enters a number in an input field.
• Selector: The user selects a value from a list of elements in the database.
• Selector with Description: The user selects a value from a list of elements in the database; the UI
element description is based on the data selected from a specific database field.
• ComboBox: The user selects a value from a list of elements composed of a set of options
predefined in the business logic or data access class, with the possibility to type data into the
editing combo box.
• CheckBox: The user selects or clears the option.
• MaskEdit: The user enters values (text or numbers) with the predefined format in the input field.
• SegmentMask: The user enters values (text or numbers) with the predefined format in the input
field; the masking rules, which define the input format, can be set individually for each segment
of the input string.
• LinkEdit: The user enters a webpage URL within the input field; the entered data is verified for the
correct URL format.
• MailEdit: The user enters an email address within an input field; the entered data is verified for
having the correct email address format.
• GroupBox: This element is used to visually group a set of buttons.
• DateTimeEdit: The user selects the date by using a visual tool.
• ImageUploader: The user can upload an image file to the selected area of a form.
Adding an Input UI Element onto a Form
To add an input UI element onto a form, you create a new element and then link it to the relevant table
field in the database or to a system object. By using Acumatica ERP customization tools, you can link
new input UI elements to the relevant sources of data either by linking a new UI element to the existing
data field, or by creating a new data field (illustrated in this section). To add any UI element onto a
form, perform the following instructions:
1. In Page Design mode, right-click the area where you need to add the element, and select Add
Input Control, as shown below.

Figure: Starting to add a UI element
2. In the Create control window, click Add. (To use an existing data field, you should instead
open the lookup window by clicking the Magnifier icon of the Data field box and selecting the
required data field name. Select the needed ControlType value, and click Save. )
3. In the Create data field window that appears, define the following values (see the screenshot
below): Field Name, Display Name, Field Type, and Length &Precision (which appears if
you select a field type that requires entering these values, such as String, DB String, Decimal,
and DBDecimal).
If you select the DBString rather than the String type, for instance, the UI element will be bound to
the database (and thus is a bound object). Otherwise, the system will extend the appropriate data
access class (DAC) with this UI element, but the element will not be bound to the database (and is
an unbound object). The Mapped to database check box (also shown in the second screenshot) is
automatically selected or cleared, depending on whether the data field type has the DB prefix.
Figure: Selecting a field type
4. Click OK to again view the Create control window. Select the required ControlType (that is,
the type of UI element you want to add), as shown in the screenshot below. Notice that the
new added data field has been renamed, with the Usr prefix automatically added to the name
previously defined as a field name.

5. Click OK. Once the form is reloaded, the new UI element and its label will be added onto the
form.
6. Right-click the added UI element and select Control Tree. This brings up the Aspx Control Tree
window, so that you can adjust the added UI element and its label positions. Then you can drag
the element and its label to the needed place.
Figure: Selecting the type of the adding input field
Customizing Properties
You can set properties for new user interface (UI) elements and modify the properties of existing
elements. Depending on the end result you want and the objects affected by the property changes, you
define UI elements to customize.
Based on the type of the UI element (described in Adding Input UI Elements), the system displays
the applicable property types in the Aspx Control Tree window, which you open after right-clicking the
appropriate UI element or any area of the form (see the screenshot below).
Figure: Opening the Aspx Control Tree window

This article covers the main property types:
• The PXEdit type (for instance, PXTextEdit, PXNumberEdit, and PXDateTimeEdit) includes visual
properties of the UI element. By adjusting these properties, you can change the visibility of
the UI element on the form and the user's ability to enter a value in it. You can also control the
alignment of UI elements and set the tab index to manage the order in which elements gain focus
as the user presses Tab or Enter.
• The PXSelector type includes properties analogous to those of the PXEdit type, as well as
properties used after the lookup window is opened (see the screenshot below).
Figure: The PXSelector type properties
• The PXSegmentMask type includes properties analogous to those of the PXSelector type (see the
three screenshots below).
Figure: The PXSegmentMask type properties

Figure: Adjusting the customization properties
This type is used along with the PXMaskEdit type (see the screenshot below). By adjusting
properties of the PXMaskEdit type, for example, you can define or change the complex input mask
for the account field. As a rule, customization values are manually added to the Customized
value column of the Aspx Control Tree window, as shown in the screenshot above.
Figure: The PXMaskEdit type properties
Notice that you can adjust property values after you select the appropriate node of the UI element. To see
all type properties, select All Props on the drop-down list located above the type property table.
By using the Aspx Source window (see the screenshot below), you can see the current property values
(either the existing values, displayed in gray, or the customized ones, displayed in red). To open this
window for the selected UI element, click Aspx in the upper area of the Aspx Control Tree window. By using
the Acumatica ERP Customization Tools, you can manually change the .aspx code of the form

Figure: Opening the Aspx Source window
• The PXDropDown type includes properties analogous to some of the PXSelector and
PXSegmentMask types. This type, as a rule, is used for combo boxes.
• The PXCheckBox type includes properties of Boolean UI elements. This type is generally used for
check boxes.
• The PXGroupBox type includes properties analogous to those of the PXCheckBox type (see the
screenshot below).
Figure: The PXGroupBox type properties
You use the PXGroupBox type along with the PXRadioButton type, which you can access from
the corresponding subnode of the PXGroupBox node, if you have expanded the subnode in the
navigation tree (see the screenshot below).

Figure: The PXRadioButton type properties
By adjusting properties of the PXMaskEdit type, you can define or change the name and default
value of each radio button—1 if it is selected, or 0 if it is not.
• The AutoCallBack type is a separate group of properties: Unlike all the aforementioned types,
this type is auxiliary, and the properties can be adjusted along with such types as PXTextEdit,
PXNumberEdit, PXSelector, and PXDropDown. The AutoCallBack type includes the callback
properties of the UI element. By adjusting these properties, you can determine how the system
reacts to data input by the user. For example, the value entered into the specified field can
change values of other fields (which usually have bigger tab index values than the edited UI
element has). These values are added automatically.
The following tables summarize the main UI element properties you can adjust. (Properties of a few
auxiliary property types, such as the Style and GridProperties types, as well as those of basic types
whose usage and adjustment rules are obvious, are not listed here.)
Property Description
Visible Displays (if set to True) or hides (if set to False) the selected UI element from
the form. You can also adjust this value in the relevant DAC, if you add this
property and its value for the PXUIField attribute.
Enabled Enables or disables the user's ability to select and edit the UI element. When
the property is set to True, users can select and edit the element; setting this
property value to False disables the element for users. You can also adjust
this value in the relevant DAC, if you add this property and its value for the
PXUIField attribute.
Required Enables or disables the user's ability to skip data entry to the UI element.
When the property value is set to True, users cannot skip data entry to
the element; if it is set to False, users do not need to enter data for the UI
element. You can also adjust this value in the relevant DAC, if you add this
property and its value for the PXUIField attribute.
TabIndex Determines the precedence of the UI element in the order in which the user
moves among form elements by pressing the Tab or Enter key. To keep the UI
element from accepting keyboard focus, set this property to -1.
MaxLength Determines the maximum number of characters the edit box can accept when
the user enters data. Setting this property affects only this UI element on

the form. You can also adjust this value in the relevant DAC, if you add this
property and its value for the PXDBString attribute.
The following properties are included in the PXSegmentMask and PXSelector property types.
ValueField Defines the name of the field in the data source, which contains the
data to be saved in the database when the user selects a value. The
value saved to the database when the user selects a value may be
different from the data that is displayed to the user on the screen.
This property, along with the TextField property, defines the names
of the data source fields used to display data in the list in the lookup
window and saves the new value in the database.
TextField Along with the ValueField property, defines the names of the data
source fields used to display data in the lookup window and saves
the new value in the database.
HintField Provides the hint about the data displayed to the user in the list
box; this property is usually used along with the ValueField and
TextField properties.
AutoRefresh Indicates that the list of fields in the lookup window should not be
cached in the browser but should instead be refreshed from the
server each time.
AutoGenerateColumns Indicates whether bound fields are automatically created for each
field in the data source. If the value is True, bound fields are
created, and if the value is False, bound fields are not created.
AutoAdjustColumns Enables (if set to True) or disables (if set to False) automatic column
width adjustment in the grids.
AllowEdit Gives the user the ability to edit the referenced page by using a new
window, if the property is set to True for the UI element.
AllowAddNew If it is set to True for the UI element, gives the user the ability to
edit the referenced page by using a new window, after the user
clicks the icon within the lookup window.
The following properties are included in the PXMaskEdit property type.
InputMask Holds the string expression that governs the format of the data that may be
entered into the edit box of the UI element.
MaxLength Limits the number of characters for the input UI element. If multiple UI elements
on form are linked to a single data field, changes to this data field property will
affect all these controls.
The main properties included in the AutoCallBack property type are described in the following table.
Enabled Enables or disables the AutoCallBack option. If this property is set to True, a change
within the edit box of the UI element initializes sending the contents from the form to

the server and waiting for the refreshing response data from the server. This property
is used along with the Target and Command parameters.
Target Specifies the target of performing the command of the AutoCallBack property. The
added property value depends on the required result and on where the adjusting
UI element is on the form, tab, or grid. This property can be set to ds (default data
source), form, tab, or grid. An external data source can be also used as a target.
Command Defines, along with the Target value, the behavior of the appropriate container
control. This property can have various predefined values; the main values are
Save, Cancel, and Refresh. When a form field is specified as the callback target,
for instance, the system posts container data to the server and requests command
execution. When it is requested for the container control, the Save action updates the
DAC associated with the container control with changed values.

| Functional Customization | 43
Functional Customization
When you need to add an event handler, generate a data access class (see Generating a DAC Using a
Database View Object as an example), or change code fragments for the application business logic, you
are planning to perform a functional customization.
If you are working with an Acumatica ERP application, before you begin a functional customization, explore
changes to subsequent releases of Acumatica ERP. You may not need to make changes after you upgrade
the application if appropriate functionality has been added to fit your requirements. See Gap Analysis for
additional information.
As a rule, before you begin to add customization code lines, you need to look through the relevant
fragments of the existing application code (source code). For complicated changes, you should review
the source code to get information, such as SQL expressions and names of classes and fields, you need
to optimally perform the customization task.
The following sections provide information about various types of functional customization:
• Adding a Data Event Handler
• Other Methods of Functional Customization
Adding a Data Event Handler
As a rule, the process of adding a data event handler includes the following steps:
• Analyzing the source code (that is, the existing application code lines that relate to the
customization task)
• Creating the code template of the event handler
• Implementing event logic
In simple cases, when you need no additional information from the source code to implement an event
handler, you can skip the first step.
You can reverse the order of the first two steps.
Analyzing the Source Code
Analyzing the source code might help you get optimal results if, for example, you don't know which
data access class (DAC) supports the form with the event handler you want to add, what kind of data
is represented by code lines of the views used in the appropriate business logic container (BLC) file, or
what field names are bound in the specified SQL expressions included in the views of the form.
The Event Model Overview used in Acumatica ERP represents the set of available event handlers,
which can be split into three groups: field handlers (FieldDefaulting, FieldUpdating, FieldVerifying, and
so on), row handlers (such as RowInserting, RowInserted, and RowUpdating), and special handlers
(CommandPreparing, ExceptionHandling, and CacheAttached). Depending on the kind of handler you
plan to implement, you could analyze the appropriate source code fragments to find the relationships
among fields and rows, or to understand, for example, how to create the required exception code or how to
override properties of an attribute by adding business logic code lines.
The example below illustrates the implementation of the RowPersisting event handler.
Depending on the customization objectives, you can use either or both of the following customization
facilities:
• The DataField Attributes window (see the screenshot below)

Figure: The DataField Attributes window
• The Source Code Browser (see the screenshot below)
Figure: The business logic tab of the Source Code Browser
By using the DataField Attributes window, you can get the primary view name of the form that
is used in the appropriate BLC, as well as name of the DAC that contains the selected field name
as an attribute. The original names of one or more fields may also be needed if, for instance, the
customization must include a handler to verify a field value or calculate the difference between field
values and then validate and constrain it (for instance, to prevent employment of a person younger
than 16 years). To open this window, right-click each required field (if a row handler is to be added and
the form contains more than one underlying DACs) or the field that must be verified by using a field
handler, and select Attributes. In the upper area of this window, note the View Name (the primary
view is displayed after the colon), Cache Type (symbols to the right of the rightmost period represent
the DAC name), and Field Name values. The lines defining the original field attributes, which are
shown in the middle of the window, can be also useful for developing the customization code.
By using the Source Code Browser, you can get information needed to correctly implement the event
handler code. You can open a separate window with the Source Code Browser by navigating to the
form to be customized and selecting View Source Code on the Customization menu. On the Find in

Files tab, you can search for required objects or fields by using their names (if you noted them while
analyzing the DataField Attributes window), or by using any function or attribute names (if you had
not opened the DataField Attributes window). The found items are displayed with the appropriate code
fragments; each item also contains the name of the found object and the code line number, as the
screenshot below illustrates. You can thus review key code fragments before you begin to create the
event handler.
Figure: Items including the found objects and code fragments
Before starting to analyze the data field attributes, you can navigate to the form to be customized, create a
new project, and enter Page Design mode. But it doesn't matter whether the new project has been created;
you can open the Source Code Browser from any form, even if all the projects are closed or no project had
been created within the current application instance. The Source Code Browser window contains the BLC
code that supports the form. See Working on a Project for other details.
Creating the Event Handler Code Template
The code template of the event handler represents the initial basic code, which includes namespace
declarations and a declaration of the event handler to be added, as shown in the first screenshot below.
To create a template, perform the following actions:
1. Navigate to the form to be customized, open the customization project (or create it, if it doesn't
exist), and enter Page Design mode.
2. Right-click the appropriate area of the form and select Add Data Event, as shown in the first
screenshot below.

Figure: Starting to add the data event handler
Figure: Selecting the event type
3. In the Add Event Handler dialog that appears, select the event type from the drop-down list,
keep the Data table name value, and click OK, as shown in the second screenshot above. The
Code Editor appears in a separate window with the code template.
Implementing Event Logic
Now you should develop the required event logic code and add it to the code template. Proceed as
follows:
1. In the Code Editor window, add the code lines of the event handler to the BLC, by using
information you obtained during the analysis step (see the screenshot below)..

Figure: The template event handler code
2. Click Save to store the customization code in the database.
3. Click Validate and Publish. (You can click this button anytime after you save the project code.)
4. If the validation has finished successfully, click Publish, which appears under the BLC code lines.
5. Perform a comprehensive set of tests to ensure that the event handler has been implemented
correctly.
Other Methods of Functional Customization
In addition to performing functional customization to add an event handler, you can develop advanced
customization code to satisfy different requirements. These requirements can range from implementing
complicated logic and through creating a new form and providing fields on it whose values are
calculated using new algorithms. (The second case represents combination of UI and functional
customization.)
The basic steps of this functional customization are similar to the steps described in Adding a Data
Event Handler:
• Analyze the source code.
• Consistently implement each required functional improvement.

| Examples of Customization | 48
Examples of Customization
This section consists of the references to the examples of Acumatica ERP customizations. Each of the
examples contains step-by-step instructions and explanation:
• Adding a TextEdit Input Field onto a Form
• Adding Selector Fields onto a Form
• Adding a Combo Box onto a Form
• Adding a Column to a Grid Control
• Adding a Column to a Lookup Window
• Generating a DAC Using a Database View Object
• Implementing a Custom Event
• Validating Field Values Using a Custom Event
Adding a TextEdit Input Field onto a Form
In this example, you will add a TextEdit input field to the upper area of the Journal Transactions
(GL.30.10.00) form. This field, which will contain a user-definable description, must be linked to a new
database field of the String type. To add the input field, do the following:
1. Create a new project (see a project's definition in Customization Project). The screenshot below
illustrates the consecutive actions you need to take:
• Navigate to Finance > General Ledger > Enter to select the Journal Transactions form,
click the Customization menu button (see the item above the red 1 in the screenshot
below), and select Open Customization Project.
• In the Select Working Project window that appears, click New to add the new project
(item 2).
• In the New Project window that appears, add the project name—for instance, GL1 (item
3).
• Click OK to close the New Project window (item 4); click OK again to close the Select
Working Project window (item 5) and create the new project.
• If your customization application instance includes a published project already, we
recommend that you select the Unpublish Existing Customization check box, which
appears in the New Project window in this case, to automatically start the Undo Publish
procedure before creating the new project. See the caution in The Project Workflow for
details.
2. On the Customization menu, select Enter Page Design Mode (item 6, no screenshot). Now you
can begin the customization of the form.
3. In the Batch Summary area, right-click near the place where the new field should be located,
and select Add Input Control (item 7, no screenshot).

| Examples of Customization | 49
Figure: Creating a new project
4. In the Create control window that appears, click Add to add a new data field (see item 8 in the
screenshot below).
5. In the Create data field window that appears, enter the following values (item 9):
• Field Name: Note
• Display Name: Short Note
• Field Type: DBString(nvarchar)
• Length: 30
For the type, make sure that you select DBString, not String. The DB prefix indicates that it will be
bound to the database. Otherwise, the system will only extend the DAC with a field, but the added
field will not be bound to the database.
Figure: Setting properties of the new field
6. Click OK (item 10). You will again be viewing the Create control window. Accept the suggested
Control Type, TextEdit, and click OK (see item 11 on the screenshot below). Once the form is
reloaded, the new text edit field and its label will be added onto the form.

Acumatica ERP 4.1 Customization Guide

Acumatica ERP 4.1 Customization Guide

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (7)

Similar to Acumatica ERP 4.1 Customization Guide

Similar to Acumatica ERP 4.1 Customization Guide (20)

Recently uploaded

Recently uploaded (20)

Acumatica ERP 4.1 Customization Guide