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...................................................................................7Customization Planning.....................................................................................................7Customization Development.............................................................................................10Customization Deployment.............................................................................................. 11

Granting User Access Rights for Customization......................................... 14

Working on a Project................................................................................. 16

Acumatica ERP Customization Tools.......................................................... 21

UI Customization........................................................................................31Classifying UI Objects.....................................................................................................31Adding Input UI Elements............................................................................................... 32Customizing Properties....................................................................................................36

Functional Customization........................................................................... 43Adding a Data Event Handler.......................................................................................... 43Other Methods of Functional Customization....................................................................... 47

Examples of Customization........................................................................ 48Adding a TextEdit Input Field onto a Form........................................................................ 48Adding Selector Fields onto a Form..................................................................................51

Adding the Account Class Selector Field...................................................................52Adding the Business Account Selector Field..............................................................56Adding the Contact Selector Field........................................................................... 60

Adding a Combo Box onto a Form................................................................................... 66Adding a Column to a Grid Control.................................................................................. 72Adding a Column to a Lookup Window............................................................................. 76Generating a DAC Using a Database View Object...............................................................80Implementing a Custom Event.........................................................................................88Validating 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 consentof ProjectX International, Ltd.

4030 Lake Washington Blvd NE, Suite 100Kirkland, WA 98033

Restricted Rights

The product is provided with restricted rights. Use, duplication, or disclosure by the United StatesGovernment is subject to restrictions as set forth in the applicable License and Services Agreementand in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS252.227-7013 or subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software-RestrictedRights at 48 CFR 52.227-19, as applicable.

Disclaimer

ProjectX International, Ltd. makes no representations or warranties with respect to the contents or useof this document, and specifically disclaims any express or implied warranties of merchantability orfitness for any particular purpose. Further, ProjectX International, Ltd. reserves the right to revise thisdocument and make changes in its content at any time, without obligation to notify any person or entityof such revisions or changes.

Trademarks

Acumatica is a registered trademark of ProjectX International, Ltd. All other product names and servicesherein 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 CustomizationGuide

With Acumatica ERP web-based customization tools, you can change the look and functionality offorms. By using these tools, you can create, configure, and maintain custom user interface elementsfor Acumatica ERP applications, as well as the functionality of the modules developed with AcumaticaFramework (see Acumatica Framework Overview).

This guide describes the process of choosing the best customization approach to satisfy specificapplication requirements.

Who Should Read this Guide

We designed this guide primarily to serve consultants and IT professionals who handle the deploymentand 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 termsused throughout this guide.

Customization Project

A project is a set of steps designed to customize either Acumatica ERP or another application developedin 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 propertiesof 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 (seeGranting 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 customizationrequirements that your company's managers have defined. By the time you complete a project, you willhave developed the customization code and updated the production application, merging customizationcode 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 existingelements. You can bind newly added elements with data fields simultaneously added to an appropriatedatabase table.

You can change the locations of UI elements on the selected area (main form, grid control, or tab) of aform 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 addUI elements onto the form templates.

You can program a form to react to certain events—for example, when the user clicks buttons to invokeappropriate pop-up forms. Also, you can change the UI elements and properties of pop-up forms. Whenyou 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 customcode 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 anew customization session. When each customization session begins, new customization code is createdor the existing customization code is opened for editing. (With existing code, Page Design mode startsautomatically, right after you select the project name, for all the forms already changed within all of theprevious customization sessions.)

During a customization session, you can change the appearance of Acumatica ERP forms by addingor removing UI elements. You can also alter system behavior with custom events, add and modifysystem objects, change objects' properties, and add custom code fragments to the application. Thesystem automatically updates the customization code of the project when you use the Acumatica ERPcustomization tools to make changes to the application. You can also manually edit the customizationcode during the current customization session and save these changes.

The customization session ends when you close the current project. When you continue thecustomization 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 customizationsessions. After you open a project in Page Design mode, you can view and edit all changes made to theapplication within the project by customizers. Multiple customizers may not publish the same projectsimultaneously.

| Customization Stages | 7

Customization Stages

Using customization tools, you can fit an Acumatica ERP application to your specific businessrequirements. To make the customization process consistent, controllable, and predictable, werecommend that you divide the customization into the following key stages:

• The planning stage involves defining the scope of the customization and assigning theCustomizer role to the appropriate Acumatica ERP users.

• The development stage entails splitting the customization into steps within the customizationproject 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) inthe 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 theproduction Acumatica ERP application with a customized version) and testing the results ofthe customization at runtime

In This Section

• Customization Planning

• Customization Development

• Customization Deployment

Customization PlanningThe customization planning stage starts with identifying the changes you want to make to the currentversion of the Acumatica ERP application and defining the requirements of those changes. Afteranalyzing 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 listof 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 studyyour business processes to find the gap between existing and new business processes. This informationwill help you identify changes you want to make to the current version of the application. Before youplan any changes to the application, you should fully understand the logic implemented in the currentversion 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 andidentify differences between the changed business requirements and the possibilities that the currentapplication version gives users. To begin your business process review, identify all relevant businessprocesses. 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. Splitthe customization planning into the following steps:

Step Description

Identifying Changes inData Presentation

To plan changes to the presentation of data, first compare the datainvolved in the business process and the data provided by the currentversion of Acumatica ERP application to users. To identify necessarychanges to the application, you should answer the following questions:

• What data do application users need to work with, if any, that thecurrent version of the application doesn't provide?

• What data, if any, does the current version of the Acumatica ERPapplication display to users that you don't want the application todisplay?

Identifying Changes inWorkflow Rules

In this step, you compare the operations performed by the users whoparticipate in the business process and the capabilities provided by thecurrent version of the Acumatica ERP application. To identify the necessarychanges to the application, answer the following questions:

• Does the business process include any operations performed undercertain conditions that are not implemented in the Acumatica ERPapplication? If so, what are these?

• What data verifications does the business process require that arenot performed in the application? What specific data should beverified?

• Which constraints influence the way the users perform the operationsinvolved in the business process, and the data required to performthese operations?

Analyze the answers to these questions, which will help you estimate thechanges required to add the necessary facilities to the Acumatica ERPapplication.

Identifying Changes inUser Access Rights

Depending on your planned changes to the workflow rules, you may needto define access rights to system objects for users who participate in partsof the workflows. To identify the necessary changes in the user accessrights, 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, willbe required to perform some steps within the changed businessprocesses?

You will also need to define appropriate access rights for users involved incustomization 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 ERPapplication, you might decide to change the data structure and make the required data available foruser entry and viewing on the application forms.

Before adding new logic to the application, you might need to again examine the existing code by usingthe Source Code Browser. Before making changes to the user interface (UI), you should list changes indata presentation for each form of the current application version that requires changes. Estimate andallocate 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 foradding new forms to the Acumatica ERP application. If some new forms are necessary, you can developthem within Acumatica Framework and bind them to the product application as an add-on. See AcumaticaFramework 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 removedfrom 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 UIelements onto a form. Because most form modifications involve adding UI elements onto a form andlinking 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 newUI 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 theAcumatica ERP application.)

When you're performing a more complex customization and the necessary data is not provided by thedata member object associated with the current form, you can add a new UI element onto the form andassociate the data member object with it, or add custom code that changes the structure of the datatables associated with the Acumatica ERP application forms. The customizations may include changesto the data management classes and attributes. The facility, named Code Editor, facilitates this type ofcustomization.

Planning Changes in Workflow Rules

In addition to changes made to the Acumatica ERP application data structure and UI elements, you canadd custom logic and functions that meet the changed business requirements. These rules should beformalized before you develop new code.

To formalize rules, describe the new functions, conditions, data verifications, and constraints that arerequired in the customized version of the Acumatica ERP application. For best results when you addcustom code, map the code to the application forms and check that the added code will not break thecurrent application version or interfere with application features that should not be affected by thecustomization. For this purpose, you should carefully review the existing code of the Acumatica ERPapplication by using the Source Code Browser.

You can add new events, functions, data verifications, and constraints to the application to implementthe new business logic in the customized version. These modifications involve by using the Code Editorincluded 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 theelement. Use the visual customization tools accessible from the Acumatica ERP forms in Page Designmode, 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 thecustomizations. First, divide the customization process into preparing the customization code (as arule, 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'sown application instance, except for the requirements of not publishing more than one projectsimultaneously, 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, butwe recommend that you have no more than two customizers per instance. As for customizers who workon 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 themthe built-in Customizer role.

• The users who will be granted the Customizer role must be authorized Acumatica ERP internalusers.

• You should keep the list of customizers as short as possible to avoid significant systemperformance degradation.

For information about granting customization privileges to a user, see Granting User Access Rights forCustomization.

Customization DevelopmentDuring this stage, you will develop the customization, which involves implementing your plannedchanges by using Acumatica ERP customization tools. Whether on your own or with other membersof the Customizer role (see Granting User Access Rights for Customization), you will modify theappearance and logic of the Acumatica ERP application to meet the defined requirements. Usually, eachcustomization 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 thedevelopment process:

• Create the customizer's application instance, which represents a standard installation ofAcumatica ERP with the same release that the company's application uses, and consists of thewebsite 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. Thecompany'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 alreadycustomized it, you must unpublish the project and make all needed new customization steps part of thesame 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, orchanging the properties and locations of elements. The visual customization tools automate theprocesses of adding elements onto the form, changing properties, and removing elements fromthe form.

• Performing the Functional Customization: Functional customization entails changing the structureof data fields associated with the form, adding custom events, or modifying the AcumaticaERP application business logic associated with the customized form. To perform functionalcustomizations, you usually add custom code to the application by using the Acumatica ERPCustomization Tools tool.

• Checking the performed customization for errors (validation): To ensure that the changes madeto the UI are error free, compile the Acumatica ERP application code, incorporating the changesmade to the UI and business logic of the form.

• Saving the customization project to the database: You save the current project to persist itand make the customization data available for use in the future. You can also download theproject customization code to an XML file—for instance, to have an archive copy or to uploadcustomization data to another customizer's application instance or to the company's productionapplication.

• Removing any unsuccessful customization code: To remove the code, you can edit thecustomization code and manually delete the erroneous data. Alternatively, you can upload thecode saved in the external file to continue the customization process from a point when theproject'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 bysaving the customization project's code. By using Acumatica ERP customization tools, you can removechanges 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 theCustomization Data Editor section of the Acumatica ERP Customization Tools article.

• Restore the last compiled customization by reloading the customization code of the project fromthe last successful compilation. You can use this option when the customization performed withina customization step fails code compilation. To restore the last compiled customization, chooseRestore Project from Database from the Customization menu.

• Upload the customization code of the project from the external file saved after the last successfulcustomization step.

Customization DeploymentDuring customization deployment, the customizer applies all the changes made to the Acumatica ERPapplication version by using an application instance: a local instance of the application with a separatedatabase. 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'sapplication 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 localapplication instance to test the results of the project. If the test results are successful, the customizerdownloads the project code to an external XML file, uploads the code to the company's productionapplication, and validates and publishes the uploaded project. (The customizer could instead send thisfile to another specialist who performs this final work.)

The customizer begins customization deployment by downloading validated, published, and testedcustomization 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 publishedcustomization was unsuccessful or the current customization project code is to be replaced withanother 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 thecustomization changes do not conflict with the current application version. During this step, you mergethe Acumatica ERP application code with the project customization code, so that the changes madeduring development will take effect. The system reports any errors that occur during validation. If thecustomization 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 applicationinstance, perform the following actions:

• To start validation, on the Customization menu, select Validate and Publish. The validationresults window shows the code compilation results.

• To view the validation results, browse the opened window. If the customization validation fails, thewindow 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 projectcustomization code through the Project Editor, Customization Data Editor, or Code Editor.

After successful validation, you can publish the customization project, which adds the customizationcode 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. Toensure that the local application has been customized correctly, you should thoroughly test theapplication.

Downloading the Project to an External XML File

After you test the finished customization project, you must download the customization code toan external XML file for uploading this code to the company's production application. Use theCustomization 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 onwhich it was developed. Thus, after you have developed and thoroughly tested a customization withyour application instance, you can deploy it to the production instance (or to multiple instances) withthe same application configuration; for Acumatica ERP, the customizer's instance and the productioninstance must have the same release number. To deploy the customization, use the external XML filecreated in the previous step.

If the customizer's application instance for Acumatica ERP has another release number than the company'sproduction application to be customized, you should upgrade the application with the earliest releasedate. You can upgrade any customized application without invoking the Undo Publish procedure, which isperformed automatically. If the upgrade finishes successfully, the Validate and Publish procedure startsafter the first website opening. Invoke the Undo Publish procedure only if validation fails, which can happendue to incompatibility of the customization and the new Acumatica ERP version code. In this case, youshould 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 customizationcode with the main application code) on the target application and make it available for users ofthe 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 thecustomization. To do this, select Undo Publish on the Customization menu. The customization codeis not deleted, but the application does not use it. If necessary, you can then partially or completelyremove the unpublished customization code from the production application through the Project Editorwindow.

| 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 usersthe 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 GuestAccount 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 theUser Roles (SM.20.10.05) form. In the screenshot below, notice two roles with the Guest Rolecheck 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 CustomizationRole 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 theInternal 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 applicationinstance 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 informationabout 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 databasestructure, 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 samerelease 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 sameconfiguration.

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 workin ways that best meet the company's needs. For example, each customizer can work on the sameproject within the common application instance, while the project includes some steps to graduallycustomize the application. The customizers would divide among themselves these steps, according tothe 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 youuse 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 formelements, and adding code that changes some application logic. In this case, several customizers maywork within the same project. However, we don't recommend that customizers work simultaneouslyon one customizer's application instance within the same project, to avoid situations when multiplecustomizers 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 systemautomatically invokes Page Design mode for all previously changed forms and starts a newcustomization session. The system automatically updates the customization project after you performchanges. You can easily customize Acumatica ERP applications by using visual tools to change theproperties and behavior of UI elements on the selected form. You can create and edit the customizationcode 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 inAcumatica ERP Customization Tools). You can access the code of the current customization projectin any of these windows.

You can simultaneously open multiple forms within the same project in Page Design mode. Eachcustomizer who enters Page Design mode within the same project can view changes made to theseforms, 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 thefollowing actions:

• To create the new project, on the Customization menu, select OpenCustomization Project (see the first screenshot below).

• In the Select Working Project window that appears, click New (as shown inthe second screenshot, near the red 1).

• In the New Project window that appears, type the new project name (seeitem 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 addthe new project.

• To work in Page Design mode, open the form you want to change, and on theCustomization 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 addedfield and select Control Tree to specify the properties of the field. The firstscreenshot below (under the Exiting Page Design Mode subsection) illustratesthe process of adjusting the added input field properties.

ExistingProject

To customize an Acumatica ERP application form within an existing project, do thefollowing:

• On the Customization menu, select Open Customization Project. The systemautomatically opens in Page Design mode forms in the project that have beenchanged.

• To work in Page Design mode for a form included in the project but not yetchanged, open it on the Customization menu and select Enter Page DesignMode.

• Perform the required customization actions within each step on forms tobe changed. In Page Design mode, you can access the Acumatica ERPcustomization tools on the Customization menu and the pop-up menu on thecustomized form; two items of the pop-up menu were described above.

You can use visual customization tools, invoked on the pop-up menu, toperform a Functional Customization. To change system logic and functionality,use the Code Editor facility to add custom code to the Acumatica ERPapplication.

Existing PageDesign Mode

To exit Page Design mode for all the forms included in the project, on theCustomization menu, select Close Project (see the second screenshot below, item3). When you exit Page Design mode, all the changed data is automatically savedto the database as the current content of the customization project. To publish thechanges of the project, you should compile and validate them to exclude programerrors.



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 forcustomization.

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 formyou want to customize, and enter Page Design mode. (If the project already exists, previouslycustomized 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 PageDesign 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 updatedcustomization code to an external file.

You can later upload data from the downloaded file, either to the current customizer's applicationinstance 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, youcan upload the project's changes to the main application. When you're ready to apply the changesperformed within a customization session to the application, publish the customization. You mayalso 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 Designmode.

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 ReloadProject from Database on the Customization menu.

Changes within the current session are saved automatically when you exit Page Design mode (forthe 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 sessionby clicking Save to database in the Customization Data Editor window.

• Remove the changes partially, if they have been already saved to the database, by manuallyediting the customized forms or customization project. You can remove any changes within theselected project.

You can act upon all the changes of the project, including those made in previous customizationsessions, 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 returnedto its initial state. The customization project data will not be removed; it can be corrected andsupplemented for further validation and publication.

• Removed from the database: Use the Project Editor to delete from the appropriate customizationproject 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 ITprofessionals who handle application deployment and maintenance. To give Acumatica ERP users thenecessary access rights to perform the customizations, assign these users the Customizer role (seeGranting User Access Rights for Customization) so that they can use the Acumatica ERP customizationtools.

If you have been assigned the Customizer role, when you open a form you need to customize, you canaccess 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 functionalcustomizations of system objects.

• Save changes made during the project customization sessions to the database or an external XMLfile.

• 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 theapplication 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 becomeoutdated; 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, userswere not pleased with customization changes.

Customization Code

Within each project, the system maintains customization code that holds data about customizations thathave been performed. The customization code, initially created within a customization session, is usedfor the whole project. You can download the customization code to an external XML file and publish itin 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 thecustomizer'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 thenote 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; seethe 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 customizationcode.


• The customization body placed between the opening and closing <Customization> tags. The bodyincludes the tags specifying the system objects that should be changed and the data describingchanges to be made.

The XML-file heading and the <Customization> tags are required parts of an external customizationfile; if you remove them, the application will not work properly.

The system stores the customization code in the customization sections as structured data describingthe 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 accesscomponents, database table structure changes, and database scripts. Physically, the description ofmodifications 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 ViewCustomization Manager, as the screenshot below illustrates. You can manually edit, add and edit, ordelete each layer from the database table. When you start the first customization session of a selectedproject, the system creates a new customization code; if you start a previously customized project, youcan 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. Seebelow for descriptions of these operations.


Action Description

Editing Customization Code You can edit the customization code of a project to partially removethe customization changes, modify properties of the objects added orchanged within the customization session, and change or delete thefragments of custom code.

Saving Customization Codeto the Database

After you edit the customization code, it must be saved manually orautomatically. The system performs automatic saving when you closethe current project.

When the customization code is saved to the database, all thechanges made to the code are applied to the session of the currentproject. After you start a session of a new project, the customizationprocess continues from the point when the customization code of theproject was saved.

The system stores the XML content of the customization code in thesystem database.

Downloading theCustomization Code of aProject

You can download the customization code to an external file,to make the code available for uploading customization datalater. When you download the customization code, changesmade in the manual editing mode before saving are not appliedto the customization session of the current project, and thecustomization process continues from the point where it was whenthe customization code was last saved to the database.

Deleting Customization DataFrom the System

You can discard customization changes (for the whole project orin part) before you publish the customization to the productionAcumatica ERP system. To delete the customization data relatedto the customization project, you can open the XML content of thecustomization code and manually remove the code body data from it,or you can delete the saved customization code or some of its layersfrom the database table by using the Project Editor.

To allow saving and loading of the customization code, the AcumaticaERP 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 themenu 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 windowswith 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 quickcontext search.

• Managing changes performed within the customization sessions of the project.

• Validating customization projects and publishing successful customization projects to anAcumatica ERP application.

As mentioned earlier, we recommend that only one project be published. All other projects canbe validated but cannot be published until you have invoked the Undo Publish command for thecurrently published project.


• Canceling changes applied to the Acumatica ERP application, by using Undo Publish, after youhave published a customization project.

In the Acumatica ERP application, you can access the Customization menu on an opened form. Youcan 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 thedatabase. If you haven't saved modifications to the database manuallywithin the current customization session, the modifications will bereplaced 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 sessionand returns you to working with the Acumatica ERP applicationversion, with the last published changes implemented. The systemautomatically saves all the changes to the database, if you haven'tsaved them before closing the project.

Enter Page Design Mode Enters Page Design mode and provides access to the Acumatica ERPcustomization facilities (such as DataField Attributes, Control creating,Aspx Control tree). You can also use the visual customization tools tomodify Acumatica ERP forms opened in Page Design mode. To modifymultiple forms, you can open all the required forms in Page Designmode—sequentially or at once. All the modifications belong to thecurrent project.

Exit Page Design Mode Exits Page Design mode only for the current form. The systemautomatically saves to the database changes involving the currentform, in case you haven't saved them before exiting Page Designmode. To end the customization session and return to working with theAcumatica ERP application, you must also close the current project.

Validate and Publish Validates the finished or intermediate customization and publishes itto the Acumatica ERP application (if you click Publish after successfulvalidation).

View Published CustomizationXML

Displays the published customization code in XML format. Provides theprocesses of downloading to and uploading from an external XML file.

Undo Publish Removes the last published project customization version from theapplication, and restores the previous Acumatica ERP applicationversion. This action discards published modifications from the currentproject, but the customization code of each existing project remains inthe database.

View Customization Manager Opens the Project Editor window and (in the left pane) the SystemManagement navigation menu with the Customization Managementtree. In the Project Editor window, you can see, edit, and remove (ifneeded) all changes within the current project involving .aspx forms,data access classes (DACs), scripts, and graphs—that is, businesslogic containers (BLC)—code as layers of the customization code of


Command Description

the project. You can also select another existing project to manage itscustomization layers.

View Source Code Displays the existing source code of the selected object. You canuse this command to analyze the application code before you makecustomization changes, during the planning or development stage ofcustomization.

Code Editor Opens the Code Editor window so you can add or change the codeconcerning the appropriate customization code section (layer) of thecurrent form.

Aspx Editor Opens the Aspx Editor window so you can add or change the .aspxcode concerning the current form.

The Customization Data Editor

The Customization Data Editor gives you direct access to the customization code of the project so youcan modify customization data. You can view the current version of the code, remove some sectionsfrom its body, or change some properties of elements added within customization sessions. You can alsodownload and upload the code.

By using the Customization Data Editor, you can open, view, and modify the customization code. Youcan save the new version of the customization code to the database and download it to the externalXML file. To modify customization code in the Customization Data Editor, perform the following basicsteps:

1. Start a new customization session or continue the current session.

2. On the Customization menu, select View Customization Manager to open the CustomizationProjects 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), makenecessary changes to the customization code of the project.

5. Click Save to database, also shown in the screenshot below, to save the modifiedcustomization code.

You can more easily open the Customization Data Editor window, if your project has beenpublished already: Just select View Published Customization XML. As a rule, the purpose to openthe Customization Data Editor window in this case—to download the published project to theexternal 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 ofthe external archive file with the .zip extension is displayed in the upper part of the pop-upwindow.)

• 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 beable to select the location path and the name of the file, depending on your web browser. You don't need tounzip the file before uploading it.


You can upload the customization code that was previously downloaded. When you upload thecustomization code from the external file, the uploaded code replaces the code of the last version of theproject with the same name. Proceed as follows to upload the customization code of a project from theexternal file:



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 savedcode is now the control point of the project customization code—that is, the point to which youcan roll back the customization project or from which you can move forward if some unforeseenloss of data takes place.

The Code Editor

By using the Code Editor, you can view the customization code of the project, add new custom codelines, validate the added code, and incorporate the changed code into the customized version of theAcumatica ERP application. You use the Code Editor to perform functional customizations. You canvalidate 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 theCode Editor on the form available for customization; by default, the Code Editor displays the initialgraph code, which can be created. As a rule, this code consists of the group of namespace operatorsusing, 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 andthen 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 thepop-up menu, or select Code Editor on the Customization menu.

The system stores the customization code related to modifications performed with the Code Editor inthe 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 sessionsconcerning the UI elements of the selected form. To open the Source Code Browser, select View SourceCode on the Customization menu. You can also navigate to the Source Code form: On the Systemtab, click Customization, and in the left pane, navigate to Explore > Source Code. In this case, tosee code on the Page aspx tab, you must manually select the form ID in the lookup window. You canalso select any BLC and DAC object (including the object created during customization sessions) to seeits 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 asgraph 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 thatdefines the structure of data stored in the database tables represented by one or more dataaccess classes in the application code. To see the code of a DAC, select the object name that isreferenced 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 andcustomization 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 .aspxfile associated with the selected form. The changes related to the customization of the form arehighlighted 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 youcan add, edit, and compile custom code by using the .aspx code of the project. You can open the AspxEditor by clicking Aspx Editor on the Customization menu. Alternatively, you can open the Aspx Pagesform 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 lookupwindow.

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 editthe original .aspx code lines.

• Save the appended or modified code to the database by clicking Checkin (see the screenshotbelow).

Figure: The Custom Code Tab

| UI Customization | 31

UI Customization

As your business processes change, you might want to make corresponding changes to the userinterface (UI) of Acumatica ERP applications so that users can work more efficiently. With AcumaticaERP customization tools, you can easily perform UI customizations, such as changing the look andbehavior of forms, tweaking the design of forms, and expanding the necessary input data range (forinstance, by changing data types or digit capacity).

If you are working with an Acumatica ERP application, explore changes to subsequent releases ofAcumatica ERP before you start to customize UI elements. You may not need to customize the applicationafter you upgrade it, if appropriate UI changes have been made to fit your requirements. See IdentifyingChanges to the Acumatica ERP Application for additional information.

By using Acumatica ERP customization tools, you can perform the following UI customization tasks withease 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 addedelements

• 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 ObjectsThis article summarizes basic concepts of using and classifying user interface (UI) objects. If youunderstand how to classify UI objects that must be customized, you can more easily assess thecomplexity 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 toan 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 fieldassociated with the bound object. Changes made to data field properties affect all the UI elements thatare 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 addedan unbound object onto the form, you customize the properties of the object only on the UI level. Noother 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 UIobjects are called advanced controls.

To use buttons, you should add an event handler that will react on mouse clicks and will performcommands, which are provided by customization code. To use a descriptor for a selector field, you haveto 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 implementthese objects into customization code by performing functional customization. Most properties of unboundobjects (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 unboundfield properties are stored in .aspx pages.) Bound UI objects are bound with both database tables andappropriate system objects. For example, after you add a UI field, new code lines with the field (havingthe same name as in the database table) and its attributes are added to the code of the relevant DACautomatically.

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 orunbound. Most input (text, numeric, Boolean, and date) fields, as well as check boxes and groupboxes, 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 simpleunbound objects; you can add them and take no further actions.

• Complex objects: You must adjust these UI elements after you have added them onto theform (whether they are bound or not). Selectors, combo boxes, and descriptors are complexbound objects. You can bind selectors to multiple referenced database tables by adding attributeparameters or BQL expressions to the corresponding DAC code. To use combo boxes, you mustadd 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 ElementsAs noted in Classifying UI Objects, input UI elements are bound UI objects—that is, the elements mustbe linked to fields of appropriate database tables. This article describes data field types and input UIelement 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 anappropriate data field type to link the UI element with a system object—data access class (DAC) orbusiness 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 withthe integer data type.

DBBool(bit) Links an input field to a new or existing database table column withthe Boolean data type.


Data Field Type Description

DBLong(bigint) Links an input field to a new or existing database table column withthe 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 withthe decimal data type (fixed precision and scale numbers). Whenmaximum 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 withthe datetime data type (a fixed-length string that represents either aspecific date and time or an interval).

DBGuid(uniqueidentifier) Links an input field to a new or existing database table column withthe uniqueidentifier data type (a 32-character hexadecimal string thatis stored as a 128-bit integer).

DBDouble(real) Links an input field to a new or existing database table column withthe 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 withthe nvarchar data type, which means that data in the database fieldsis 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 withthe nchar data type, which means that data in the database fields isstored as fixed-length character strings of Unicode characters. You candefine the maximum length of the string.

String Links an input field to a system object storing and retrieving the dataas string values. You can define the length of the string.

Int Links an input field to a system object storing and retrieving the dataas integer values.

Bool Links an input field to a system object storing and retrieving the dataas Boolean values.

Long Links an input field to a system object storing and retrieving the dataas 32-bit signed integer values.

Decimal Links an input field to a system object storing and retrieving the dataas 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 dataas 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 datawith the datetime data type (a fixed-length string that representseither a specific date and time or an interval).

Guid Links an input field to a system object storing and retrieving thedata as a 32-character hexadecimal string that is stored as a 128-bitinteger.


Types of Input UI Elements

Acumatica ERP users use input UI elements to enter, view, or select data on forms. By using theAcumatica ERP Customization Tools, you can add UI elements onto Acumatica ERP forms and link themto the database fields or system objects that store the entered values. You can also set the visualproperties 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 UIelement 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 optionspredefined in the business logic or data access class, with the possibility to type data into theediting 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 inputfield; the masking rules, which define the input format, can be set individually for each segmentof the input string.

• LinkEdit: The user enters a webpage URL within the input field; the entered data is verified for thecorrect URL format.

• MailEdit: The user enters an email address within an input field; the entered data is verified forhaving 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 tablefield in the database or to a system object. By using Acumatica ERP customization tools, you can linknew input UI elements to the relevant sources of data either by linking a new UI element to the existingdata field, or by creating a new data field (illustrated in this section). To add any UI element onto aform, perform the following instructions:

1. In Page Design mode, right-click the area where you need to add the element, and select AddInput 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 insteadopen the lookup window by clicking the Magnifier icon of the Data field box and selecting therequired 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 screenshotbelow): Field Name, Display Name, Field Type, and Length &Precision (which appears ifyou 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 tothe database (and thus is a bound object). Otherwise, the system will extend the appropriate dataaccess class (DAC) with this UI element, but the element will not be bound to the database (and isan unbound object). The Mapped to database check box (also shown in the second screenshot) isautomatically 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 thenew added data field has been renamed, with the Usr prefix automatically added to the namepreviously defined as a field name.


5. Click OK. Once the form is reloaded, the new UI element and its label will be added onto theform.

6. Right-click the added UI element and select Control Tree. This brings up the Aspx Control Treewindow, so that you can adjust the added UI element and its label positions. Then you can dragthe element and its label to the needed place.

Figure: Selecting the type of the adding input field

Customizing PropertiesYou can set properties for new user interface (UI) elements and modify the properties of existingelements. Depending on the end result you want and the objects affected by the property changes, youdefine UI elements to customize.

Based on the type of the UI element (described in Adding Input UI Elements), the system displaysthe applicable property types in the Aspx Control Tree window, which you open after right-clicking theappropriate 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 visualproperties of the UI element. By adjusting these properties, you can change the visibility ofthe UI element on the form and the user's ability to enter a value in it. You can also control thealignment of UI elements and set the tab index to manage the order in which elements gain focusas the user presses Tab or Enter.

• The PXSelector type includes properties analogous to those of the PXEdit type, as well asproperties 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 thethree 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 adjustingproperties of the PXMaskEdit type, for example, you can define or change the complex input maskfor the account field. As a rule, customization values are manually added to the Customizedvalue 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 seeall 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 thiswindow for the selected UI element, click Aspx in the upper area of the Aspx Control Tree window. By usingthe 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 andPXSegmentMask 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 forcheck boxes.

• The PXGroupBox type includes properties analogous to those of the PXCheckBox type (see thescreenshot below).

Figure: The PXGroupBox type properties

You use the PXGroupBox type along with the PXRadioButton type, which you can access fromthe corresponding subnode of the PXGroupBox node, if you have expanded the subnode in thenavigation 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 defaultvalue 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 callbackproperties of the UI element. By adjusting these properties, you can determine how the systemreacts to data input by the user. For example, the value entered into the specified field canchange values of other fields (which usually have bigger tab index values than the edited UIelement has). These values are added automatically.

The following tables summarize the main UI element properties you can adjust. (Properties of a fewauxiliary property types, such as the Style and GridProperties types, as well as those of basic typeswhose 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 fromthe form. You can also adjust this value in the relevant DAC, if you add thisproperty and its value for the PXUIField attribute.

Enabled Enables or disables the user's ability to select and edit the UI element. Whenthe property is set to True, users can select and edit the element; setting thisproperty value to False disables the element for users. You can also adjustthis value in the relevant DAC, if you add this property and its value for thePXUIField 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 tothe element; if it is set to False, users do not need to enter data for the UIelement. You can also adjust this value in the relevant DAC, if you add thisproperty and its value for the PXUIField attribute.

TabIndex Determines the precedence of the UI element in the order in which the usermoves among form elements by pressing the Tab or Enter key. To keep the UIelement from accepting keyboard focus, set this property to -1.

MaxLength Determines the maximum number of characters the edit box can accept whenthe 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 thisproperty 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 thedata to be saved in the database when the user selects a value. Thevalue saved to the database when the user selects a value may bedifferent from the data that is displayed to the user on the screen.This property, along with the TextField property, defines the namesof the data source fields used to display data in the list in the lookupwindow and saves the new value in the database.

TextField Along with the ValueField property, defines the names of the datasource fields used to display data in the lookup window and savesthe new value in the database.

HintField Provides the hint about the data displayed to the user in the listbox; this property is usually used along with the ValueField andTextField properties.

AutoRefresh Indicates that the list of fields in the lookup window should not becached in the browser but should instead be refreshed from theserver each time.

AutoGenerateColumns Indicates whether bound fields are automatically created for eachfield in the data source. If the value is True, bound fields arecreated, and if the value is False, bound fields are not created.

AutoAdjustColumns Enables (if set to True) or disables (if set to False) automatic columnwidth adjustment in the grids.

AllowEdit Gives the user the ability to edit the referenced page by using a newwindow, 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 toedit the referenced page by using a new window, after the userclicks 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 beentered into the edit box of the UI element.

MaxLength Limits the number of characters for the input UI element. If multiple UI elementson form are linked to a single data field, changes to this data field property willaffect 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 changewithin 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 propertyis used along with the Target and Command parameters.

Target Specifies the target of performing the command of the AutoCallBack property. Theadded property value depends on the required result and on where the adjustingUI element is on the form, tab, or grid. This property can be set to ds (default datasource), 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 containercontrol. This property can have various predefined values; the main values areSave, 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 commandexecution. When it is requested for the container control, the Save action updates theDAC 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 aDatabase View Object as an example), or change code fragments for the application business logic, youare planning to perform a functional customization.

If you are working with an Acumatica ERP application, before you begin a functional customization, explorechanges to subsequent releases of Acumatica ERP. You may not need to make changes after you upgradethe application if appropriate functionality has been added to fit your requirements. See Gap Analysis foradditional information.

As a rule, before you begin to add customization code lines, you need to look through the relevantfragments of the existing application code (source code). For complicated changes, you should reviewthe source code to get information, such as SQL expressions and names of classes and fields, you needto 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 HandlerAs 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 thecustomization 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 eventhandler, 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 whichdata access class (DAC) supports the form with the event handler you want to add, what kind of datais represented by code lines of the views used in the appropriate business logic container (BLC) file, orwhat 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, andso on), row handlers (such as RowInserting, RowInserted, and RowUpdating), and special handlers(CommandPreparing, ExceptionHandling, and CacheAttached). Depending on the kind of handler youplan to implement, you could analyze the appropriate source code fragments to find the relationshipsamong fields and rows, or to understand, for example, how to create the required exception code or how tooverride 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 customizationfacilities:

• 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 thatis used in the appropriate BLC, as well as name of the DAC that contains the selected field nameas an attribute. The original names of one or more fields may also be needed if, for instance, thecustomization must include a handler to verify a field value or calculate the difference between fieldvalues and then validate and constrain it (for instance, to prevent employment of a person youngerthan 16 years). To open this window, right-click each required field (if a row handler is to be added andthe form contains more than one underlying DACs) or the field that must be verified by using a fieldhandler, and select Attributes. In the upper area of this window, note the View Name (the primaryview is displayed after the colon), Cache Type (symbols to the right of the rightmost period representthe DAC name), and Field Name values. The lines defining the original field attributes, which areshown 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 eventhandler code. You can open a separate window with the Source Code Browser by navigating to theform 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 whileanalyzing the DataField Attributes window), or by using any function or attribute names (if you hadnot opened the DataField Attributes window). The found items are displayed with the appropriate codefragments; each item also contains the name of the found object and the code line number, as thescreenshot below illustrates. You can thus review key code fragments before you begin to create theevent 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 anew 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 hadbeen created within the current application instance. The Source Code Browser window contains the BLCcode 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 namespacedeclarations 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'texist), and enter Page Design mode.

2. Right-click the appropriate area of the form and select Add Data Event, as shown in the firstscreenshot 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. TheCode 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 asfollows:

1. In the Code Editor window, add the code lines of the event handler to the BLC, by usinginformation 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 implementedcorrectly.

Other Methods of Functional CustomizationIn addition to performing functional customization to add an event handler, you can develop advancedcustomization code to satisfy different requirements. These requirements can range from implementingcomplicated logic and through creating a new form and providing fields on it whose values arecalculated using new algorithms. (The second case represents combination of UI and functionalcustomization.)

The basic steps of this functional customization are similar to the steps described in Adding a DataEvent 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 theexamples 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 FormIn 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 newdatabase 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 belowillustrates 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 screenshotbelow), 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 (item3).

• Click OK to close the New Project window (item 4); click OK again to close the SelectWorking Project window (item 5) and create the new project.

• If your customization application instance includes a published project already, werecommend that you select the Unpublish Existing Customization check box, whichappears in the New Project window in this case, to automatically start the Undo Publishprocedure before creating the new project. See the caution in The Project Workflow fordetails.

2. On the Customization menu, select Enter Page Design Mode (item 6, no screenshot). Now youcan 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).


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 thescreenshot 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 bebound to the database. Otherwise, the system will only extend the DAC with a field, but the addedfield 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 suggestedControl Type, TextEdit, and click OK (see item 11 on the screenshot below). Once the form isreloaded, the new text edit field and its label will be added onto the form.


Figure: Adding the new field onto the form

• The label of the field added onto the form becomes visible after publishing the project.

• You can drag and drop the field to change its placement, but you should do this with accuracyso that not to replace the existing fields; moreover, if necessary, you can move or replaceany field, as well as change its size by dragging the left side of the selected field.

• During a UI customization, the automatic alignment is supported by the system—the left sideof an added or moved field and its label is aligning to the nearest field column of the upperarea of the form (if enough free space exists within this column).

• If you want to restore the original view of the form before you close the project, that is, ifyou decided to reject the results or part of unsaved results of adding UI text field, you shouldclick Reload Project from Database item on the Customization menu.

7. On the Customization menu, select Validate and Publish (item 17, no screenshot). TheCompilation window appears, and the application validation process begins immediately.

8. When the validation process has been completed successfully, click Publish within the validationwindow (see item 18 in the screenshot below); otherwise, view the build output and eliminatethe cause of the problem.


Figure: Publishing the customization project

9. Once the Journal Transactions form is reloaded after publishing, close the project and refresh thepage. The new text field, Short Note, appears on the form and can be used.

Figure: The added text field

Adding Selector Fields onto a FormIn the topics referenced by the section below, you will add three selector fields onto the JournalTransactions (GL.30.10.00) form. You will link the selector fields to new data fields related to thesystem database fields, within one common project.

The selectors will use the data access classes (DACs) to manipulate the data and access the systemdatabase. You will define the DACs that are used by the selector fields by setting the appropriateattributes for the fields.

We recommend that you perform customization steps in the order in which the articles (listed below)appear.


Creating the Project and Entering Page Design Mode

Before performing customization steps, create a new project (name it as GL2) and then enter PageDesign mode (see the definition of the Page Design Mode) by performing two first instructions of thefirst example topic—Creating a New Project.

In This SectionYou can perform three customization examples within the common project in the order that is listedbelow:

• Adding the Account Class Selector Field

• Adding the Business Account Selector Field

• Adding the Contact Selector Field

Adding the Account Class Selector FieldIn this example, you will add the Account Class selector field onto the Journal Transactions(GL.30.10.00) form. You will create a new data field to store and display the selected data. TheAccountClassID key will be used to access the data in the relevant system database table.

To add the Account Class selector field onto the form, you will perform two general steps: adding theuser interface (UI) element onto the form, and setting the field attributes. After that, you will use thedescr DAC attribute (the descr field exists in the appropriate database table) to set the HintFieldproperty of the added selector field. Finally, you will validate the customization changes and save themto an external file as an archive copy in case the next customization step fails, and then publish theproject.

Adding the UI Element onto the Form

Navigate to Finance > General Ledger > Enter to select the Journal Transactions form and aftercreating the new project, GL2 (see as an example Creating a New Project), proceed as follows to addthe UI element of the Account Class selector field onto the form:

1. On the Customization menu, select Enter Page Design Mode. Now you can begin thecustomization of the form.

2. In the Batch Summary area, right-click near the place where the new field should be located,and select Add Input Control.

3. In the Create control window that appears, click Add to add a new data field.

4. In the Create data field window that appears (see the screenshot below), enter the followingvalues:

• Field Name: AccountClass

• Display Name: Account Class


For the type, make sure that you select DBString rather than String. The DB prefix indicates thatit will be bound to the database. If you don't use the prefix, the system will extend the DAC with afield, but the added selector field will not be bound to the database.


Figure: Selecting the properties of the new field

5. Click OK to again view the Create control window. Define the ControlType value as Selector,and click OK. Once the form is reloaded, the new selector field (without its label at the moment)will be added onto the form.


• You can drag and drop the field to change its placement, but you should do this with accuracy so thatnot to replace the existing fields; moreover, if necessary, you can move or replace any field, as wellas change its size by dragging the right side of the selected field. To move a field, click and hold itsleft side and drag.

• During a UI customization, the automatic alignment is supported by the system—the left side of anadded or moved field and its label is aligning to the nearest field column of the upper area of theform (if enough free space exists within this column).

• If you want to restore the original view of the form before you close the project, that is, if youdecided to reject the results or part of unsaved results of adding UI text field, you must click ReloadProject from Database on the Customization menu.

Setting the Field Attributes and Validating the Project

To set the attributes of the selector, perform the following actions:

1. Right-click the added Account Class selector field, and select Attributes.

2. Edit the original expression to include the attributes of the selector field, as the screenshot belowshows) by setting the PXSelector, DescriptionField, and Substitute Key attributes. Thenclick OK to save the changes and close the DataField Attributes window. The code lines belowillustrate the final code of the DAC field with the selector field property.

[PXDBString(10, IsKey=false, BqlTable=typeof(PX.Objects.GL.Batch), IsFixed=false, IsUnicode=true)][PXUIField(DisplayName="Account Class")][PXSelector(typeof(PX.Objects.GL.AccountClass.accountClassID), DescriptionField=typeof(PX.Objects.GL.AccountClass.descr), SubstituteKey=typeof(PX.Objects.GL.AccountClass.descr) )]


Figure: Adding DAC fields to the selector field expression

If you add code lines for this field for the first time, keep the How to Apply parameter value as Append to Original, otherwise you should select Replace Original. (See the screenshot above)

3. On the Customization menu, select Validate and Publish. In the Compilation window thatappears, the validation process begins immediately.

4. When the validation process has completed successfully, the Publish action button appearswithin the validation window (see the screenshot below), but it is soon to publish the projectchanges. Close the Compilation window.

Figure: Validation results are correct

In this case, you may first publish the project's code and then perform downloading of the archivefile. Considering such an order of actions is useful within more complicated projects, when each


internal step needs to be validated and archived not to spoil the whole project's code during thenext step.

5. On the Customization menu, select Save Project to Database (GL2) to save intermediatecustomization changes to the database.

Saving the Current State and Publishing the Project

To make it possible for you to return to this customization step if the next step fails, you will save thecurrent customization data to an external file. Open the Customization Data Editor and save this data asfollows:



3. In the Customization Data Editor that appears within the new browser window, click DownloadPackage, select Save File, and click OK, as shown in the screenshot below, to save the currentstate of the customization project to the external file.

Figure: Downloading the current project state to the file

4. Close the Customization Data Editor window.

5. On the Customization menu, again select Validate and Publish. In the Compilation window thatappears, the validation process begins.

6. When the validation process has completed successfully, click the Publish action button topublish the project.

7. After the project has been published, select Close Project on the Customization menu. Noticethe new Account Class selector field on the form; click the Magnifier icon at the right end ofthis field to open the lookup window with the account classes items with descriptions. (See thescreenshot below.)


Figure: Opening the lookup window of the new added selector field

Now that you have finished the instructions above, you will add another selector field onto the sameform, as described in Adding the Business Account Selector Field.

Adding the Business Account Selector FieldIn this example, you will add the Business Account selector field, which will display information aboutthe business account, to the Journal Transactions (GL.30.10.00) form. In the process, you will create anew data field to store and display the selected data. The bAccountID key will be used to access datain the relevant system database table.

To add the Business Account selector field, you will perform two general steps: adding the userinterface (UI) element onto the form, and setting the attributes of the selector. Finally, you will validatethe customization changes and download them to an external file, in the case the next customizationstep fails, and then publish the project.


Navigate to Finance > General Ledger > Enter to select the Journal Transactions form, if this form isnot active at the moment. To add the UI element of the Business Account selector field onto the form,do the following:

1. On the Customization menu, select Open Customization Project to open the existing project,GL2, if it had been closed. Since this project has the UI customization code (see the previousexample), the Page Design Mode activates with the Journal Transactions form automatically.

You may skip cancelling the publication (that is, not to invoke the Undo publish procedure) of theproject's code published in the previous example. The project's code will be updated by the codelines of the current example, and then you will again be able to publish the project. But you shouldhave the downloaded archive XML file, obtained in previous example to roll back the project to thechecked existing code in the case you make errors and the second validation localizes them.

2. On the Journal Transactions form, click the Batch Summary (upper) area to select it, right-clicknear the place where you want to place the new field, and select Add Input Control.

3. In the Create control window, click Add to add a new data field (see the screenshot below).

4. In the Create data field window that appears (also shown in the screenshot), enter thefollowing values:


• Field Name: bAccountID

• Display Name: bAccount

• Field Type: DBInt(int)

Make sure that you select the DBInt type, rather than Int. DB in front of the type indicates that thefield will be bound to the database. If the prefix is absent, the system will extend the DAC with afield, but the added selector field will not be bound to the database.

Figure: Entering the properties of the second selector field

5. Click OK to again view the Create control window. Select Selector as the ControlType andclick OK. Once the form is reloaded, the new selector field will be added onto the form.


• You can drag and drop the field to change its placement, but you should do this with accuracy sothat not to replace the existing fields; moreover, if necessary, you can move or replace any field,as well as change its size by dragging the right side of the selected field (see, for instance, the lastscreenshot of this topic, and notice that the width of the Description field had been decreased inthis example). To move a field, click and hold its left side and drag.

• During a UI customization, the automatic alignment is supported by the system—the left side of anadded or moved field and its label is aligning to the nearest field column of the upper area of theform, if enough free space exists within this column; in this example, we are able to place the addedselector field above the Description field by moving this field down (see again the last screenshot ofthis topic).

• If you want to restore the original view of the form before you close the project, that is, if youdecided to reject the results or part of unsaved results of adding UI text field, you should click ReloadProject from Database on the Customization menu.

Setting the Field Attributes and Validating the Project

To set the attributes of the selector, perform the following actions:

1. Right-click the bAccountID field and select Attributes.


2. In the Custom attributes area of the DataField Attributes window that appears (see thescreenshot below), enter the following code to define the attributes of the bAccount selectorfield:

[PXSelector(typeof(PX.Objects.CR.BAccount.BAccountID), SubstituteKey=typeof(PX.Objects.CR.BAccount.acctCD) )]

If you add code lines for this field for the first time, keep the How to Apply parameter value as Append to Original, otherwise you should select Replace Original.

3. Click OK to save the changes and close the DataField Attributes window.

Figure: Adding the expression of the selector field

4. On the Customization menu, select Validate and Publish, which brings up the Compilationwindow and starts the application validation process immediately.

5. When the validation process has completed successfully, the Publish action button appearswithin the validation window (see the screenshot below), but it is soon to publish the projectchanges. Close the Compilation window.


Figure: Validation results are correct

In this case, you may first publish the project's code and then perform downloading of the archivefile. Considering such an order of actions is useful within more complicated projects, when eachinternal substep needs to be validated and archived not to spoil the whole project's code during thenext step.

6. On the Customization menu, select Save Project to Database(GL2) to save intermediatecustomization changes to the database.

Saving the Current State and Publishing the Project

To make it possible for you to return to this customization step if the next step fails, you will save thecurrent customization data to an external file. Open the Customization Data Editor and save this data asfollows:



3. In the Customization Data Editor that appears within the new browser window, click DownloadPackage, click Save File, and click OK to save the customization project to the external file.

4. Close the Customization Data Editor window.

5. On the Customization menu, select Validate and Publish again. In the Compilation window thatappears, the validation process begins.

6. When the validation process has completed successfully, click the Publish action button topublish the project.

7. After the project has been published, select Close Project on the Customization menu. Noticethe new Account Class selector field on the form; click the Magnifier icon at the right end ofthis field to open the lookup window with the account classes records. (See the screenshotbelow.)


Figure: The new added selector field and its lookup window

Now that you have finished the instructions above, you should add one last selector field onto the sameform. See the instructions in Adding the Contact Selector Field.

Adding the Contact Selector FieldIn this example, you will add the Contact selector field, which will display additional information aboutbusiness accounts to the Journal Transactions (GL.30.10.00) form. In the process, you will create a newdata field to store and display data selected by using this field, and use the ContactID key to accessdata in the relevant system database table. The selector field will use a parameterized query to displayrecords from the BAccount table whose ContactID values match the BAccountID values.

To add the Contact selector field onto this form, you will perform two general steps: adding the userinterface (UI) element for the field, and setting the attributes of the field. After that, you will create theparameterized query for the added selector field. Finally, you will validate the customization changes,publish them as a finalized project, and save them to an external file (for example, to upload theproject's code to another application instance or for the real production application).


Navigate to Finance > General Ledger > Enter to select the Journal Transactions form, if this formis not active at the moment. To add the UI element of the Contact selector field onto the JournalTransactions form, do the following:

1. On the Customization menu, select Open Customization Project to open the existing project,GL2, if it had been closed. Since this project has the UI customization code (see two previousexamples), the Page Design Mode activates with the Journal Transactions form automatically.

You may skip cancelling the publication (that is, not to invoke the Undo publish procedure) of theproject's code published in the previous example. The project's code will be updated by the codelines of the current example, and then you will again be able to publish the project. But you shouldhave the downloaded archive XML file, obtained in two previous examples to roll back the project tothe checked existing code in the case you make errors and the third validation localizes them.

2. On the Journal Transactions form, click the Batch Summary (upper) area to select it, right-clicknear he location where you want to place the label of the new selector field, and select Add InputControl.

3. In the Create control window, click Add to add a new data field (see the screenshot below).


Figure: Adding the third selector field

4. In the Create data field window that appears, enter the following values:

• Field Name: ContactID

• Display Name: Contact ID


• Length: 25

The exact value you add for the Length parameter is not so important, because the systemautomatically sets this value with discrete size steps—from small (s) to extra-large (xl), dependingon the field length in symbols entered by you. You can adjust this value further manually.

5. Click OK, and you will again be viewing the Create control window. Select Selector as theControl Type (see the screenshot below) and click OK. Once the form is reloaded, the newselector field will be added onto the form.


• You can drag and drop the field to change its placement, but you should do this with accuracyso that not to replace the existing fields; moreover, if necessary, you can move or replaceany field, as well as change its size by dragging the right side of the selected field (see, forinstance, the last screenshot of this topic, and notice that the width of the Description fieldhad been decreased in this example). To move a field, click and hold its left side and drag.

• During a UI customization, the automatic alignment is supported by the system—the left sideof an added or moved field and its label is aligning to the nearest field column of the upperarea of the form, if enough free space exists within this column; in this example, we are ableto place the added selector field above the Description field by moving this field down (seethe last screenshot of this topic again).

• If you want to restore the original view of the form before you close the project, that is, ifyou decided to reject the results or part of unsaved results of adding UI text field, you mustclick Reload Project from Database on the Customization menu.

Setting the Field Attributes

To set the attributes of the selector field, perform the following steps:

1. Right-click the added Contact selector field, and select Attributes.


2. In the Custom attributes area of the DataField Attributes window that appears (see thescreenshot below), enter the following additional code to define the attributes of the contactIDselector field:

[PXSelector(typeof(Search<PX.Objects.CR.Contact.contactID, Where<Optional<PX.Objects.GL.Batch.usrBAccountID>, Equal<PX.Objects.CR.Contact.bAccountID>>>))]

If you add code lines for this field for the first time, keep the How to Apply parameter value as Append to Original, otherwise you should select Replace Original. (See the screenshot below)

3. Click OK to save the changes and close the DataField Attributes window.

Figure: Adding the selector field expression

4. Open the Customization Data Editor, and save the customization project to an external filebefore performing instructions of the next step.

Setting Query Parameters for the Field

To set additional limitations on the data displayed by the Contact selector field, define parameters forthe query used for the data selection:

1. Right-click the Contact selector field on the form, and select Control Tree.

2. In the Aspx Control Tree window that appears, select Parameters in the tree, and on the Addmenu, select Add Item, as shown in the screenshot below.


Figure: Starting to add the selector field parameters

3. In the New Item window that appears, ensure that Parameters is displayed in the Collectionbox and PXControlParam in the Item Type box, and then click OK, as shown in the screenshotbelow.

Figure: Selecting types of parameters

4. Select PXControlParam in the tree, and select the All Props item on the drop-down list ofthe small window located above the parameter table. The property list for PXControlParam isdisplayed, as shown in the screenshot below. Use All Props selection to have the possibility tosee all the parameters.


Figure: Displaying the parameters

5. Define the query parameters by performing the following steps:

• Set the PropertyName customized value in the tree, as follows:

• Select UsrBAccountID:PXSelector and copy to the clipboard the ID customizedvalue, as shown in the screenshot below.

Figure: Copying the SelectorID customized value

• Select the PXControlParam in the tree, and add as a customized valueDataControls[BAccount_selector_ID].Value for the PropertyName. In thisexpression, you need to paste the ID customized value from the clipboard instead ofthe BAccount_selector_ID expression.

• Add form as the ControlID and Batch.usrBAccount as the Name customized values, asshown in the screenshot below.


Figure: Adjusting the customized property values

Validating and Publishing the Customization Project

To validate the customization and publish it on the Acumatica ERP application, perform the followingsteps:

1. On the Customization menu, select Validate and Publish. The Compilation window appears andthe validation process begins immediately. When the validation process has been successfullycompleted, the appropriate message is displayed in the window.

2. If no errors has encountered, click the Publish button that appears within the Compilationwindow.

3. After the project has been published, select Close Project on the Customization menu.

4. View the updated version of the Acumatica ERP application website, and test the implementationresults of the customization project (see the screenshot below):

a. Add a new record by clicking Add New Record.

b. In the Account Class box, select an item (COGS, for instance) and add it to the form.

c. In the bAccount box, select an item (RAPIDBYTE, for instance) and add it to the form.

d. Notice the new Contact ID selector field on the form; click the Magnifier icon at theright end of this field to open the lookup window with the possible contact data; this datacorresponds to the entered bAccount value, as shown in the screenshot below.


Figure: The final view of the Journal Transactions form after publishing the whole project

5. If this project had been developed for the real production application, you should download thefinal customization code to the XML file that will represent the archived distributive unit for theupdate procedure. To prepare this distributive unit, do as follows:

a. On the Customization menu, select View Customization Manager to open theCustomization Projects form.

b. Click the Edit XML button in upper part of the form, on the main toolbar.

c. In the Customization Data Editor that appears within the new browser window, clickDownload Package, click Save File, and click OK to save the customization project tothe external file.

d. Close the Customization Data Editor window.

To use the distributive unit, open the Customization Data Editor on the target (real) application instanceand upload the project's code to this real production application after specifying archive name ofthe XML file and its path. (You shouldn't unzip an external zipped XML file.) Validate and publish thecustomization code. Now the real production application has been updated.

Adding a Combo Box onto a FormIn this example, you will add the Level of Benefit combo box to the Opportunities (CR.30.40.00) form.Classifying opportunities in this way can help users to sort and filter preferred potential contracts, andspecial reports based on this information can be generated for your company's top management.

When they use this customized form, users can then select an appropriate level of benefit for eachopportunity, based on criteria established by company management. In this example, we will use Low,Middle, High, and Very High as the benefit levels. You can, of course, implement different levels.

You could develop an algorithm to automatically define the benefit level depending on the EffectiveAmount value. We don't want to complicate this customization example, but you can develop thisalgorithm independently.


Creating a New Project

1. Create a new project (see a project's definition in Customization Project). The screenshot belowillustrates the consecutive actions you need to take:

• Navigate to Organization > Customer Management > Enter to select the Opportunitiesform, and on the Customization menu, select Open Customization Project.

• In the Select Working Project window that appears, click New to add the new project.

Figure: Creating a new project

• In the New Project window that appears, add the project name—for instance, CR1.

• Click OK to close the New Project window; click OK again to close the Select WorkingProject window and create the new project.

If your customization application instance includes a published project, we recommend that you select theUnpublish 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 TheProject Workflow for details.

Adding the Combo Box onto the Form

Proceed as follows to add the Level of Benefit combo box onto the form:

1. On the Customization menu, select Enter Page Design Mode. Now you can begin thecustomization of the form.

2. In the Opportunity Summary area, right-click near the place where the new combo box shouldbe placed (under Effective Amount), and select Add Input Control.

3. In the Create control window that appears, click Add to add a new UI element.

4. In the Create data field window that appears, enter the following values (see also thescreenshot below):

• Field Name: BenefitLevel

• Display Name: Level of Benefit



• Length: (may be empty)

Figure: Adding the new UI element

Make sure that you select the DBString type, rather than String. DB in front of the type indicatesthat the field will be bound to the database. If the prefix is absent, the system will extend the DACwith a field, but the added selector field will not be bound to the database.

5. Click OK to again view the Create control window. Select the Control Type as ComboBox, andclick OK. Once the form is reloaded, the new selector field will be added onto the form.


• You can drag and drop the field to change its placement, but you should do this with accuracyso that not to replace the existing fields; moreover, if necessary, you can move or replaceany field, as well as change its size by dragging the right side of the selected field. To move afield, click and hold its left side and drag.

• If you want to restore the original view of the form before you close the project, that is, ifyou decided to reject the results or part of unsaved results of adding UI text field, you mustclick Reload Project from Database on the Customization menu.

Creating the PXStringList Attribute and Activating the AllowEdit Property

To prepare the list of benefit levels for the created combo box, you must edit the CROpportunity DACcode that had been automatically added along with the combo box. Do the following steps:

1. Right-click the added combo box and select Attributes.

2. In the DataField Attributes window that appears, type (within the Custom attributes entrybox) the following additional code lines, also shown in the screenshot below.


Figure: Adding the PXStringList attribute

[PXStringList(new string[] { "L", "M", "H", "VH" }, new string[] { "Low", "Middle", "High", "Very High" })][PXDefault("M")]

If you add code lines for this field for the first time, keep the How to Apply parameter value as Appendto Original, otherwise you should select Replace Original.

Optionally, you can allow the user not only to select an existing benefit level item from the drop-downlist but also to add another level of benefit (which won't be displayed on the created drop-down list oflevels but will be saved to the database and displayed after the user defines the different value andsaves the form); with this purpose you should also activate the AllowEdit property for the combo boxas follows:

1. Click OK to save the added code lines in the CROpportunity DAC, right-click the combo boxagain, and select Control Tree.

2. In the Aspx Control Tree window that appears (the UsrBenefitLevel:PXDropDown node isallocated), set the All Props criteria from the drop-down list of the small window located abovethe property table, set the AllowEdit property (of the PXDropDown type) to True, and clickApply to Page, as shown in the screenshot below.


Figure: Activating the AllowEdit property

Note that you defined in the added code lines not only the list of benefit level values but also the defaultvalue (M for Middle) of the combo box.

Publishing the Project and Testing the Results

Now the customization code for the project must be validated and tested. Do the following:

1. Optionally: If you want to make some other changes, you should save before the current projectcode; to do this, on the Customization menu, select Save Project to Database (CR2) to savethe customization changes to the database. If your new changes will be erroneous, you canrestore the project's code, obtained during performing instructions of the current example byusing the Reload Project from Database item of the customization menu.

2. On the Customization menu, select Validate and Publish. The Compilation window appears andthe validation process begins immediately.

3. When the validation process has been completed successfully, click Publish. (The screenshotbelow illustrates the end of the publishing process.)


Figure: Validating and publishing the project

4. Close the project. You can see the added combo box, Level of Benefit, in the OpportunitySummary area. Notice that the Middle level is displayed by default.

5. In the Opportunity ID box, select any existing opportunity. Then open the Level of Benefitdrop-down list, select the appropriate level, and click Save, as shown in the screenshot below.

Figure: Selecting the benefit level

6. Select another or add a new opportunity, type a level that is not displayed in the drop-down list,and click Save, as shown in the screenshot below.


Figure: Typing another value of the benefit level

If the benefit level values have been saved successfully, your customization task has been completed.

Adding a Column to a Grid ControlIn this example, you will add a new selector column to the Transaction Details grid control of theJournal Transactions (GL.30.10.00) form. The new column must use an appropriate data accessclass (DAC) to access the system database and manipulate data. You will define this DAC by settingappropriate attributes for the selector column.

Adding the Selector Column

By using the selector column, Customer's Email, the Acumatica ERP application user can select aclient email address to use it as a contact on the details of a transaction. To add a new selector columnto the Transaction Details grid control, do the following:

Navigate to Finance > General Ledger > Enter to select the Journal Transactions form and aftercreating the new project, GL3 (see as an example Creation a New Project), proceed as follows to addthe UI element of the Account Class selector field onto the form:

1. On the Customization menu, select Enter Page Design Mode. Now you can begin thecustomization of this form.

2. Click the Transaction Details grid control to select it, right-click any place within the gridcontrol header area, and select Control Tree.

3. In the Aspx Control Tree window that appears, on the Add menu, select Add Column to Grid(see item 1 in the screenshot below).


Figure: Adding the new selector column to the grid control

4. In the Add Grid Column window that appears, click Add to add a new data column (item 2).

5. In the Create data field window that appears, enter the following values (as item 3 shows):

• Field Name: CustMail

• Display Name: Customer's Email


• Length: 50

Make sure that you select the DBString type, rather than String. DB in front of the type indicatesthat the column will be bound to the database. If the prefix is absent, the system will extend theDAC with a field, but the added selector column will not be bound to the database.

6. Click OK (item 4) to again view the Create control window. Select Selector in the ColumnEditor box (see item 5 in the screenshot below), and click OK (item 6) to save the entered data.


Figure: Saving the selector column

7. In the Aspx Control Tree window that appears again, click Apply to Page (see item 7).

Setting Attributes and Publishing the Project

To set the attributes of the selector column, perform the following actions:

1. On the Aspx Control Tree, click Attributes.

2. In the DataField Attributes window that appears, add the following code line to the Customattributes area: [PXSelector(typeof(PX.Objects.CR.CRMassMail.mailTo))]. ClickOK (see the screenshot below).

If you add code lines for this field for the first time, keep the How to Apply parameter value as Append to Original, otherwise you should select Replace Original.


Figure: Adding the selector column expression

3. Optionally: If you want to make some other changes, you should save before the current projectcode: to do this, on the Customization menu, select Save Project to Database (GL3) to savethe customization changes to the database. If your new changes will be erroneous, you canrestore the project's code, obtained during performing instructions of the current example byusing the Reload Project from Database item of the customization menu.


5. When the validation process has been completed successfully, click Publish.

6. Close the project and refresh the page. You can see the new selector column, Customer'sEmail, in the grid control (see the screenshot below). You can begin to enter a new line to seethe lookup window that can be opened from the new selector column. (If the MailTo columnvalues of the CRMassMail table contain null values, the lookup window will be empty.)


Figure: The selector column added in the grid control

If you cannot see the new column, click Fit to Screen (as shown highlighted in the screenshot above)in the navigation bar above the grid control. The widths of the columns will become narrower, and theCustomer's Email column must appear on the screen as the rightmost column of the grid control.

Adding a Column to a Lookup WindowThis example illustrates adding to the Order Nbr lookup window on the Sales Orders (SO.30.10.00)form a column that displays internal sales order numbers used by sales managers. You will alsoimplement the quick search by setting the appropriate lookup property.

Adding the Column to the Lookup Window

To add this column to the lookup window, proceed as follows:

1. Create a new project (see a project's definition in Customization Project) by doing the followingactions:

a. Navigate to Distribution > Sales Orders > Enter to select the Sales Orders form, andon the Customization menu, select Open Customization Project.

b. On the Select Working Project window that appears, click New to add the new project.

c. On the New Project window that appears, add the project name, such as SO1.

d. Click OK to close the New Project window; then click OK again to close the SelectWorking Project window and create the new project.

If your customization application instance includes a published project, we recommendthat you select the Unpublish Existing Customization check box, which appears in theNew Project window in this case, to automatically start the Undo Publish procedure beforecreating the new project. See the caution in The Project Workflow for details.

2. On the Customization menu, select Enter Page Design Mode to begin the form customization.

3. Right-click the Order Nbr field and select Control Tree.

4. In the Aspx Control Tree window that appears, on the Add menu, select Add Column toSelector, as shown in the screenshot below.


Figure: Starting to add a column to the selector

5. In the Add Selector Column window that appears, click Magnifier and select from the list offields CustomerOrderNbr, as shown in the screenshot below.

Figure: Adding the selector column

6. Click OK to add the column for the OrderNbr lookup window. (This column is shown in thescreenshot below as a tree item.)


Figure: The added column within the existing lookup columns

7. Click Apply to Page to save the new column and close the Aspx Control Tree.


9. When the validation process has been completed successfully, click Publish (see the screenshotbelow).


10. Close the project and open the lookup window of the Order Nbr box. Check that the CustomerOrder column is there as the rightmost column of the lookup window.

11. If you want to change the position of the added column, you can drag its header to the requiredposition, as shown in the screenshot below.


Figure: The new column in the lookup window

To keep the new column's position (as well as widths of this and all the other columns) in thelookup window, you should click the leftmost column's header (icon), and in the column adjustmentwindow, click Save layout, as shown in the screenshot below. (The order of columns in the columnadjustment window shouldn't correspond to the order of columns in lookup window; drag columnheaders to change any column's position before saving the layout.)

Figure: Saving the order and width of the new added column

Testing the Quick Context Search

To test the current adjustment of the facility that enable the user to rapidly find the required customer'sorder number, do as follows:

1. Reopen the project.

2. Right-click the Order Nbr field, and select Control Tree again. (Keep the set by default BaseProps item value on the drop-down list of the small window located above the parameter table.)


Use Base Props selection by default to quickly find the parameters with the current value differentfrom Null; select the Base Props instead of Show All to see, in particular, all the adjustedproperties of the selected section.

3. In the Aspx Control Tree window that appears, notice the Current value of theFastFilterFields property of the OrderNbr:PXSelector section: CustomerOrderNbr, as shownin the screenshot below.

Figure: Analyzing the current value of the FastFilterFields property

4. Close the project and open the Order Nbr lookup window. In the search window (in the lowerleft corner of the lookup window), try to type any full or partial order number, and ensure thatsearch settings are applied to the new Customer Order column, as well as to the Order Nbr,because this is the single key column. The screenshot below illustrates an example of the quicksearch.

Figure: Testing the quick context search

Quick context search in key columns of a lookup field is always possible by default; search for othercolumns can be implemented after the appropriate adjustment of the FastFilterFields property. In thedemo ERP project this property had been set to use quick context search also in the Customer Ordercolumn.

Generating a DAC Using a Database View ObjectIn this example, you will add a new data access class (DAC) after creating the OppByStage databaseview object. This view includes opportunities that the company anticipates from new contacts withpotential buyers, along with the estimated revenue of each opportunity (specified as the OpportunityTotal on the Opportunities (CR.30.40.00) form). Because the probability of the opportunity dependson the stage, the SQL expression of the view object contains the grouping section with the StageID


field. During analysis, users can consider the probability of each stage to calculate the total estimatedrevenue from all the contacts.

By using the Generic Inquiry (SM.20.80.00) form, you will adjust an inquiry form based on theaforementioned DAC. Users can view this information and perform downloading it to an external .xlsfile, if necessary.

Creating the Database View Object

To create the database view object, you should use the MS SQL Server Management Studio querywindow or an analogous SQL console facility. Once you connect to the database, open the querywindow, type and execute the following SQL expression (see also the screenshot below).

create view OppByStage as select CompanyID, SUM(amount) Amount, StageID from cropportunity where status <> 'C'group by CompanyID, StageID

Figure: Creating the database view object

Generating the DAC Code

You generate the DAC code as follows by using the Opportunities (CR.30.40.00) form as a startingpoint:

1. Navigate to Organization > Customer Management > Enter to select the Opportunitiesform, and on the Customization menu, select Open Customization Project.

2. Try to find the appropriate customization project, and then create the new project instead (see aproject's definition in Customization Project).

The appropriate customization project does not exist. We instruct you to simulate a search for anexisting project to familiarize you with the structure of the lookup window.

Perform the following actions:

a. On the Customization menu, select Open Customization Project.

b. On the Select Working Project window that appears, click the Magnifier icon. Thelookup window appears with the list of existing projects, as shown in the screenshotbelow. Close the lookup window, since you have not found the corresponding project.


Figure: Trying to find the required project

Notice the Screen Names column of the lookup window, which shows the forms that have beencustomized by each project. (If the project is used for the UI customization of more than one form,the second and all the next form is also displayed within the Screen Names column separated bycomma. As a rule, projects created only for functional customization have no entries in this column.

• On the Select Working Project window, click New to add the new project.

• On the New Project window that appears, add the project name, such as CR2.

• Click OK to close the New Project window; then click OK again to close the SelectWorking Project window. The new project has been created.

3. On the Customization menu, select View Customization Manager.

4. In the Project Editor (SM.20.45.10) form that is opened in a separate window, on the Add menu,select Database Table or Script, as shown in the screenshot below.

Figure: Starting to add the script of the view object

5. In the Edit Sql Script window that appears, click the Magnifier icon in the DBObject Name editbox. The lookup window appears with the list of object names from the database, as shown in


the screenshot below. You can type a string into the quick search box (lower left) to rapidly findthe required object name (also shown in the screenshot below).

Figure: Searching for the existing view object name

6. Select the OppByStage view object name as the DBObject Name value.

7. Open MS SQL Server Management Studio again, right-click OppByStage, and select Script Viewas, DROP And CREATE To, and then Clipboard to copy the script to the clipboard, as shown inthe screenshot below. (This script will be used during publication for dropping and repeatedlycreating the view object in the database.)

Figure: Copying the script to the clipboard

8. Return to the Edit Sql Script window, and paste into the Custom Script area the script fromthe clipboard, as shown in the screenshot below. Click Save.


Figure: Pasting the script to the project code

9. Return to the original window with the Opportunities form. On the Customization menu, selectCode Editor.

10. In the Code Editor form that is opened in a separate window, click New File. (See thescreenshot below.)

11. In the Create Code File dialog that appears, select IBqlTable as the file template and typeOppByStage as the class name; then select the Generate Members from Database check boxand click OK, as shown in the screenshot below.

Figure: Generating the new DAC

12. Ensure that the generated DAC code is added on the Code Editor form (see the screenshotbelow), and then add the key property for the StageID DAC field attribute: [PXDBString (1,IsKey = True, IsFixed = True, InputMask = "")]. Click Save.

The key field for the StageID DAC field attribute is necessary for preparing reports by using thisDAC.


Figure: Correcting and saving the generated DAC code

13. Click Validate and Publish. (You can instead invoke this action by using the Opportunitiesform: Return to the form and select Validate and Publish on the Customization menu.)

14. When you see the Validation finished successfully message in the Compilation window, clickPublish, as shown in the screenshot below.


Constructing the Inquiry Form by Using the DAC

By using the Generic Inquiry Designer form, you can construct SQL expressions to select data storedin the database by using DACs or business logic containers (BLCs). The constructed SQL expressions


may be saved as templates accessible for users. To construct an inquiry form with data stored in thedatabase by using the created DAC, proceed as follows:

1. Navigate to System > Customization > Manage to select the Generic Inquiry form,.

2. Click Add New Record. In the Inquiry Summary area of the form, enter OppByStage as theInquiry Title of the inquiry form being created. Enter values in the Parameters Area Title(optional) and Results Grid Title boxes. See the screenshot below.

The Select Top value, which defines the quantity of selected records, must be empty. TheArrange parameters in value may be equal to the default value, because in this example, noselect parameters are to be used.

3. In the Tables tab of the lower area of the form, click Add Row. By using the lookup window,select the name of the generated DAC as the value of the Table Name column. Type thealias value of the object (such as OBS), which is optional, in the next column (see again thescreenshot below).

Figure: Adding the name of the generated DAC

4. In the Results Grid tab, by using Add Row, add two records. Enter the column values of eachrecord as follows:

• First record:

• Active: Selected

• Object: OBS

• Data Field: Amount

• Schema Field: OBS.Amount

• Visible: Selected

• Second record:

• Active: Selected


• Object: OBS

• Data Field: StageID

• Schema Field: OBS.StageID

• Visible: Selected

The two columns with the selected field names will be displayed as the column headers on theinquiry being created. The screenshot below also illustrates the values to be entered for eachrecord.

Figure: Adding the fields of the generated DAC

5. Click View Inquiry on the navigation panel of the inquiry designer.

6. On the OppByStage result form that appears, click Fit to Screen to adjust column widths. Youcan see the Amount and Stage ID column headers, and the calculated opportunity amountsgrouped by stage IDs, as the screenshot below illustrates. You can download this data to anexternal .xls file by clicking Export.

Figure: Analyzing data by using the generated DAC

To obtain more data records, you can add several new opportunities by using the Opportunities form,making sure you specify opportunity IDs and total amounts, as well as any other applicable settings foreach opportunity.


Implementing a Custom EventIn this example, you will implement a custom event for the Journal Transactions (GL.30.10.00) form.Implementing the event provides the ability to make sure the transaction is correct. If the CreditTotalvalue does not equal the DebitTotal value, the this.OutOfBalance boolean variable is set to true.

To implement this event, perform the following steps:


a. Navigate to Finance > General Ledger > Enter to select the Journal Transactions form,and on the Customization menu, select Open Customization Project.


c. On the New Project window that appears, add the project name, such as GL4.


If your customization application instance includes a published project, we recommendthat you select the Unpublish Existing Customization check box, which appears in theNew Project window in this case, to automatically start the Undo Publish procedure beforecreating the new project. See the caution in The Project Workflow for details.

2. On the Customization menu, select Enter Page Design Mode to begin the form customization.

3. Right-click the upper area of the form, and select Add Data Event on the pop-up menu.

4. In the Add Event Handler dialog that appears, select FieldUpdated as the Event Type, selectCreditTotal as the Field Name, and click OK, as shown in the screenshot below.

Figure: Saving the event handler

5. In the Code Editor, which appears in a separate browser window (as shown in the screenshotbelow), you can see the following code template, which has been added to the code edit area forthe form.


Figure: The code of the added event handler

#region Event Handlers protected void Batch_CreditTotal_FieldUpdated(PXCache sender, PXFieldUpdatedEventArgs e) { var row = (Batch)e.Row; // var CreditlTotal = row.CreditTotal; } #endregion

6. Edit the custom event code so that the resulting code will be the following:

using System;using System.Collections;using System.Collections.Generic;using System.Text;using System.Text.RegularExpressions;using PX.Data;using PX.Objects.CS;using PX.Objects.CM;using PX.Objects.CA;using PX.Objects.GL.Overrides.PostGraph;using PX.Objects.PM;using PX.Objects;using PX.Objects.GL;

namespace PX.Objects.GL{ [PXCustomization] public class Cst_JournalEntry: JournalEntry {

#region Event Handlers bool OutOfBalance = false; protected void Batch_CreditTotal_FieldUpdated(PXCache sender, PXFieldUpdatedEventArgs e) { var row = (Batch)e.Row; var CreditTotal = row.CreditTotal; if ((Batch)e.Row)DebitTotal != row.CreditTotal { this.OutOfBalance = true;


} } #endregion

}}

7. Click Validate and Publish in the upper side of the Code Editor window.

8. After successful completion of the validation process, click Publish to publish the customizationcode of the project.

The value of this variable can be further displayed on the form if you add a field onto it. The field mustbe bound with the variable.

Validating Field Values Using a Custom EventIn this example, a custom event will be used for the Employees (EP.20.30.00) form to ensure that theemployee date of birth has been specified and that the employee is 16 years of age or older.

You will also learn how to work with the original source code of Acumatica ERP to get the requiredresult.

Creating the New Project

Take the following actions to start creating validation logic:


a. Navigate to Organization > Organization Structure > Manage to select theEmployees form, and on the Customization menu, select Open Customization Project.


c. On the New Project window that appears, add the project name, such as EP1.


2. On the Customization menu, select Enter Page Design Mode to begin to customize the form.

Setting AutoCallBack Properties

First, you should set AutoCallBack properties for the Hire Date field so that the form sends datato the server after each modification of the field value. This invokes validation logic that will beimplemented for the form and stored in the server. Perform the following actions:

1. Right-click the Hire Date field, and select Control Tree.

2. In the Aspx Control Tree window that appears, select the All Props item on the drop-down listwhich is opened through the small window located above the property table.

3. Into the Customized value column, add the following AutoCallBack properties (see also thescreenshot below):

• Enabled: True

• Target : form

• Command: Save


Figure: Setting AutoCallBack properties

4. Click Apply to Page to save the customized property values and close the Aspx Control Treewindow.

Starting to Add Validation Logic

Proceed as follows to add validation logic:

1. Right-click area of the General Info tab and select Add Data Event.

2. In the Add Event Handler window that appears, select RowPersisting as the event type, keepEPEmployee as the table name, and click OK, as shown in the screenshot below.

Figure: Selecting the event type

3. In the Code Editor form, which appears in a separate browser window, you can see the followingtemplate, which has been added to the code edit area for the form (see the code fragment).

.................................. #region Event Handlers protected override void EPEmployee_RowPersisting(PXCache sender, PXRowPersistingEventArgs e) { base.EPEmployee_RowPersisting(sender, e);


var row = (EPEmployee)e.Row; // } #endregion.................................

Analyzing the Source Code

To get optimal validation results, you must first analyze the corresponding original source codefragments to find out which data access classes (DACs) contain the fields that are to be validated, aswell as how these fields are bound with one another within the appropriate business logic container(BLC) views. Proceed as follows:

1. Return to the Employees form, right-click the Date Of Birth field, and select Attributes. In theDataField Attributes window that appears, note the exact Field Name value (DateOfBirth).Also notice the View Name, which is the primary view name of this BLC, and Cache Type fieldvalues, as the screenshot below illustrates. Click Cancel to close the window.

Figure: Attributes of the Date Of Birth field

The primary view is displayed after the colon within the View Name field value, while symbols tothe right of the rightmost period of the Cache Type field value represent the name of the DAC.

2. On the Employees form, right-click the Hire Date field and select Attributes. In the DataFieldAttributes window that appears again, note the exact Field Name value (HireDate); also noticethe View Name and Cache Type field values, as the screenshot below illustrates.


Figure: Attributes of the Hire Date field

3. Click Cancel to close the window.

4. On the Employees form, by using the Customization menu, select View Source Code.

5. In the Source Code Browser form, which appears in the separate window with the Businesslogic tab active, open the Select Declarations region of the PX.Objects.EP.EmployeeMaint nameof the current BLC (which was automatically defined when the Source Code Browser form wasopened and is displayed within the upper left lookup box, named Graph Name), and find viewdeclarations where the aforementioned field names are used, as shown in the screenshot below.The two view definitions are selected with red rectangles. The second view definition is the mostimportant, because by use of this view definition, you can find out how the fields of the twoDACs are bound with one another. The definition code of the view is shown below.

public PXSelect<Contact, Where<Contact.bAccountID, Equal<Optional< EPEmployee.parentBAccountID>>, And<Contact.contactID, Equal <Optional<EPEmployee.defContactID>>>>> Contact;

Figure: The view definitions

6. Optional: Click the Find in Files tab. In the Find Text box, type DateOfBirth, and click Find. Dothe following actions:


• In the search results table, note the shortened name of the basic DAC (without the projectand module names, separated by the periods)—that is, the name of the DAC where theDateOfBirth field had been defined. The DAC name is Contact, as the screenshot belowillustrates. (The other DACs are auxiliary.)

Figure: Searching for the DateOfBirth field records

• In the Find Text small window, type HireDate, and click Find again. In the search resultstable, note the shortened name of another basic DAC, in which the HireDate field hadbeen defined; the DAC name is EPEmployee, as the screenshot below illustrates.

Figure: Searching for the HireDate field records

Actually, to customize the application within this project, you need to know only the DAC names thatinclude the validating fields, and the BLC name with the appropriate business logic. However, analyzing BLCview expressions can be useful in many other customization tasks.

Implementing the Validation Logic

To implement the validation logic, proceed as follows:

1. In the Code Editor window, edit the custom event code so that the resulting code will be thefollowing.

using PX.Objects.AP;using PX.Objects.GL;using PX.SM;using PX.TM;using PX.Common;using System;using System.Collections;using PX.Data;using PX.Objects.CS;using PX.Objects.CR;using PX.Objects.CA;using PX.Objects.CM;using System.Collections.Generic;using PX.Objects.AR;


using PX.Objects.PM;using PX.Objects;using PX.Objects.EP;

namespace PX.Objects.EP{ [PXCustomization] public class Cst_EmployeeMaint: EmployeeMaint {

#region Event Handlers protected override void EPEmployee_RowPersisting(PXCache sender, PXRowPersistingEventArgs e) { PXDefaultAttribute.SetPersistingCheck<Contact.dateOfBirth> (sender, e.Row, PXPersistingCheck.NullOrBlank); DateTime birth = (DateTime)this.Contact.Current.DateOfBirth; EPEmployee row = (EPEmployee)e.Row; DateTime alloweddate = new DateTime(birth.Year + 16, birth.Month, birth.Day); DateTime hire = (DateTime)row.HireDate; if (hire != null &&((DateTime)hire) < alloweddate) throw new PXSetPropertyException("The employee's hire date must be " + "at least 16 years after his or her birthdate."); }

#endregion

}

}

Within the RowPersisting event code, two methods of a field validation are used: ThePXDefaultAttribute.SetPersistingCheck method, which is used to remind the user to enter theappropriate date of birth. The following code lines, which (along with the PXSetPropertyExceptionmethod) checks the condition to warn the user if the new employee is younger than 16. Thesevalidation methods prevent a record from being saved if at least one of the aforementionedconditions is true. If the date of birth is null or empty, the common error message is displayed(such as Nullable object must have a value), but you can use the PXSetPropertyException methodto declare your own detailed error message by using the second validation version.

2. Click Validate and Publish. After the validation process has been finished successfully, clickPublish to publish the customization project (see the screenshot below).



Testing the Results

Now you should test the results of the implemented validation logic to ensure that the logic worksproperly. Perform the following actions:

1. Return to the Employees form, close the project, and try to add a new employee record withoutentering the Date Of Birth value. Enter values for all the other required fields (allocated by theasterisk at the left of the name), as shown in the screenshot below.

Figure: Adding a record with no Date of Birth value


2. Click Save: The error message appears that the nullable object must have a value, and therecord is not saved.

As was mentioned in the hint in the previous section, to define a more exact error message, youcan add on your own a few more customization code lines to the EmployeeMaint BLC code lines thatcontain the appropriate condition check and error message text.

3. Add the date of birth so that the difference between it and the hire date is less than 16 years,and the second error message appears. This is the message text added by you to the event codeas a parameter of the PXSetPropertyException method.

4. Make the hire date at least 16 years later than the date of birth, and click Save. The new recordhas been saved.

acumatica erp 4.1 customization guide

Software

ui customization

customization stages

examples of customization

acumatica framework

contact selector field

field values

account class selector

custom event