T300 Acumatica Customization Platform

(1)

(2)

| Contents | 2

How to Use the Training Course... 4

Getting Started with the Acumatica Customization Platform...5

What is an Acumatica Customization Project?...6

Add-On Solution... 8

Creating an Add-On Solution...10

Developing an Add-On Solution... 14

Scopes of the Acumatica Customization Platform... 30

User Interface Customization...31

Acumatica Customization Engine...43

Acumatica Extensibility Framework...62

Customization Stages...77

Source Code Browser... 77

Exploring the Source Code... 80

Development Stage... 88

Developing a Customization Project...90

Granting User Access Rights for Customization... 96

Final Testing and Deployment Stage...98

Acumatica Customization Project... 102

Content of a Customization Project...102

Customization Menu and Sessions... 108

Understanding the Publication of a Project... 112

Managing Multiple Projects... 115

Updating a Customization Project... 116

Deleting a Customization Project...119

UI Customization...123

Performing UI Customization...123

Page Design Mode...123

Aspx Pages Editor... 127

PXLayoutRule Components...129

Placing UI Elements in Multiple Rows and Columns and Widening these Elements...133

Setting Label Width and Aligning UI Elements Horizontally... 138

Creating a Group of UI Elements and Hiding Their Labels...141

Creating Nested Input Controls...144

Setting Widths and Sizes of UI Elements... 147

Adding Items... 153

Adding Advanced Controls... 157

(3)

| Contents | 3

Acumatica Extensibility Framework In Detail...180

AEF Extensibility Generic Classes... 182

Creating an Extension Library Solution by Using the Bespoke Approach... 183

DAC Extensions...185

Customizing DAC Attributes...185

Creating a DAC Extension of an Extension... 188

DAC Extension Model...190

Extension Tables...193

Using an Extension Table... 193

Extension Table Declaration... 198

BLC Extensions... 206

Modifying a BLC Data View... 207

Declaring or Altering a BLC Data View Delegate...208

Extending BLC Initialization... 210

Creating a BLC Extension of an Extension... 212

BLC Extension Model... 213

Adding or Altering BLC Event Handlers... 219

AEF Event Handler Model... 221

Altering BLC Virtual Methods... 226

Accessing Customization Objects... 228

Customization Best Practices... 238

Using Numbering Sequences...238

Overriding a BLC Data View... 277

Overriding a BLC Data View Delegate... 281

Adding a Button onto the Form Control... 288

Adding Buttons to the Grid Control... 294

Calculating Unbound DAC Fields at Run Time... 303

Extending the Base Business Logic... 308

Extending the Multi-Level Document Workflow... 321

Extending the Persist() Method... 333

(4)

| How to Use the Training Course | 4

How to Use the Training Course

The T300 Acumatica Customization Platform course is intended for application developers who start learning how to customize Acumatica ERP or other Acumatica Framework-based applications. It is required from you to previously work through the lessons of the T100 Introduction to Acumatica

Framework and the T200 Acumatica Framework Fundamentals courses and to pass certification tests on these courses.

The Acumatica Customization Platform course consists of six parts which take about 24 hours to complete.

Before starting to work with the T300 Acumatica Customization Platform course:

• Locally download the installer, and in the Acumatica Framework Configuration Wizard that appears, select the Deploy Acumatica Framework Tools item. For details, see ConfiguringDevEnvironment.pdf attached to the training materials.

• Locally download the Acumatica ERP installer, and in the Acumatica ERP Configuration Wizard that appears, by sequential selecting twice the Deploy New Application Instance item, create two Acumatica ERP instances—for customization and for final testing. For details, see Deploying an Acumatica ERP Instance.

• Before starting to perform instructions of the topics placed under UI Customization, upload the AdvUI.zip file attached to the training materials.

• Before starting to perform instructions of the topics placed under Acumatica Extensibility Framework In Detail, you may need to upload the IntroAEF.zip file attached to the training materials.

(5)

| Getting Started with the Acumatica Customization Platform | 5

Getting Started with the Acumatica

Customization Platform

The Acumatica Customization Platform is designed for the developers who have advanced experience of using Acumatica Framework and specialized in:

• Development of vertical and add-on solutions on top of Acumatica ERP or other Acumatica Framework-based software product as independent software vendors (ISVs).

• Delivering the customization of Acumatica ERP or other Acumatica Framework-based software product to the end user as value-added resellers (VARs).

Each customization task must be resolved within an Acumatica Customization Project. An Acumatica Customization Project is a set of changes and additional files that modifies Acumatica ERP or an Acumatica Framework-based application. To deliver the content of an add-on solution or customization of an Acumatica Framework-based software product, you should add all the changes and external files to the customization project and deploy it to the production application.

Specialists who will work on customization projects should be assigned the Customizer or Administrator role in the separate application instance that is to be customized and tested, as well as in the

production application that should be updated with the customization project. With this role assigned, the specialists can use the customization tools and facilities of the Acumatica Customization Platform, and upload and publish customization projects.

You can choose one of the following kinds of customization projects:

• Those that are based on an add-on solution, which is used, as a rule, when you must create new webpages

• Those that are based on the use of the tools and facilities of the Acumatica Customization Platform, which you use in most other cases

Add-On Solutions

To create new pages for the Acumatica ERP application or another Acumatica Framework-based application, you should create an add-on solution.

You use the standard interface of MS Visual Studio and the tools and facilities of Acumatica Framework for developing an add-on solution, as if you were developing a standalone application.

To deploy the paths to your new pages within the navigation pane, you need to place site map changes to the content of the current Acumatica Customization Project.

Depending on the set of tasks resolved within the customization project, you may need to perform the following actions:

• Adding new inquiry conditions to the Generic Inquiry system webpage

• Creating new reports or modifying existing ones by using the Acumatica Report Designer. Acumatica Customization Platform

Each customization task must be resolved within an Acumatica Customization Project. This means that you cannot make any customization without creating a new customization project or modifying an existing one. You can divide any customization task into three scopes: user interface (UI)

customization, functional customization, and auxiliary customization. Depending on the complexity of the particular customization task, you can use the tools and facilities of any or all of the customization scopes.

(6)

UI customization includes changing the look and behavior of webpages, tweaking webpage design, and manually editing the .aspx code. All UI modifications, except for manual editing of the .aspx code, are performed in page design mode. UI customization is always related to the .aspx code of the corresponding webpages and represents aspx changesets that are added to the existing .aspx code. Functional customization means various kinds of modifications of the data structure and original application business logic. All these modifications are related to the code of the appropriate data access classes (DACs) or business logic controllers (BLCs, also referred to as graphs). The Acumatica Customization Platform includes two technologies for functional customization: the Acumatica

Customization Engine (ACE) and the Acumatica Extensibility Framework (AEF). The ACE supports a set of tools and facilities designed for the consultants who implement customization of Acumatica ERP or other Acumatica Framework-based applications. AEF is designed primarily for independent software vendors (ISVs) that develop vertical and add-on solutions on top of Acumatica ERP or other Acumatica Framework-based applications, and want to extend or modify the base product behavior.

Auxiliary customization facilities, that are compatible with both add-on solutions and the tools and facilities of the Acumatica Customization Platform, are used to perform the following changes:

• Adding new inquiry conditions to the Generic Inquiry system webpage • Modifying the application site map by using the Site Map system webpage

• Creating new reports or modifying existing ones by using the Acumatica Report Designer The following underlying topics provide you an overview of the Acumatica Customization Platform and all main actions necessary to create and develop an add-on solution or resolve most common customization tasks by using different approaches and technologies:

• What is an Acumatica Customization Project? • Add-On Solution

• Scopes of the Acumatica Customization Platform

What is an Acumatica Customization Project?

An Acumatica Customization Project is a set of changes and additional files that modifies your Acumatica ERP application instance or another Acumatica Framework-based software product. Customization facilities are primarily designed for independent software vendors (ISVs) and value-added resellers (VARs) that either develop vertical and add-on solutions on top of Acumatica Framework-based software or deliver the customization of Acumatica Framework-based software products to the end users.

To deliver an add-on solution or an Acumatica Framework-based software product customization, you should add all the changes and additional files to the customization project and provide it as a deployment package to the end users. You can create as many customization projects as you need. Acumatica Framework provides the mechanism to publish, upgrade, or unpublish your customization project deployment packages at any time.

Each customization task must be resolved within an Acumatica Customization Project. This means that you cannot make any customization without creating a new customization project or modifying an existing one.

When you create an add-on project, you must use the customization project only for creating a deployment package.

(7)

Acumatica Customization Project

To deliver the content of an add-on solution or customization of an Acumatica Framework-based software product, you add all the changes and external files to the customization project and deploy it to the end users.

You can create any number of customization projects. Acumatica Framework provides the mechanism to upload, publish, upgrade, or unpublish (that is, cancel publishing) your customization project deployment packages at any time, either on the customizer or tester's application instance or on the real production application.

Each project has specific content that depends on the task resolved within the project. You can see and edit the internal part of this content by using the Customization Projects webpage, while the external files are most often represented by assemblies, .aspx pages, and images.

To explore the content of a project, you should first navigate to System > Customization > Manage > Customization Projects. The window under the details table of this webpage displays the content of the selected record. In the Customization Projects webpage, the whole content of a customization project represents a set of records of different object types. Once you have finished working on the project, you download it as a deployment package.

A deployment package is a zip file that includes both internal content and external files that were included in the customization project.

Specialists who will work on customization projects should be assigned the Customizer or Administrator role in the separate application instance that is to be customized and tested, as well as in the

production application that should be updated with the customization project (see Granting User Access Rights for Customization). With this role assigned, the specialists can use the customization tools and facilities of the Acumatica Customization Platform, and upload and publish customization projects. You can choose one of the following kinds of customization projects:

• Those that are based on an add-on solution (see Add-On Solution), which is used, as a rule, when you must create new webpages

• Those that are based on the use of the tools and facilities of the Acumatica Customization Platform (see Scopes of the Acumatica Customization Platform), which you use in most other cases

Auxiliary Customization Facilities

An add-on solution is used for the development of additional webpages, while the Acumatica Customization Platform provides user interface (UI) and functional customization. Both types of application improvement are compatible with the facilities of the auxiliary customization scope. Auxiliary customization provides the following changes:

• Adding new inquiry conditions to the Generic Inquiry system webpage • Modifying the application site map by using the Site Map system webpage

• Creating new reports or modifying existing ones by using the Acumatica Report Designer Because the scope of auxiliary customization includes different types of customization, each facility is used separately for the specified customization task or along with add-on solutions or tools and facilities of the Acumatica Customization Platform. You can use the following facilities:

• The Generic Inquiry system webpage. Also, the Add Generic Inq dialog of the Customization Projects system webpage is used, which supports adding selected new inquiries from the Generic Inquiry webpage to the content of the current customization project.

• The Site Map system webpage. Also, you can use the Add Site Map dialog of the Customization Projects system webpage, which supports adding selected site map changes to the content of the current customization project.

(8)

• Acumatica Report Designer, which enables you to modify existing reports or create new ones. Also, the Add Reports from database dialog of the Customization Projects system webpage supports adding selected reports (which were previously saved to the database) to the content of the current customization project.

Add-On Solution

To create new pages for the Acumatica ERP application or another Acumatica Framework-based application, you should create an add-on solution.

You employ the standard interface of MS Visual Studio and the tools and facilities of Acumatica Framework for developing an add-on solution, as if you were developing a standalone application. Depending on the complexity of the task and the number of developers to be involved in resolving it, you can choose one of the following development approaches:

• An approach that is based on the customization project with the preconfigured initial add-on solution. From this point, we will name this approach as the templated approach.

• An approach that is based on a manually created add-on solution. From this point, we will name this approach as the bespoke approach.

The templated approach can be used when a relatively simple task is to be resolved and only one developer is involved, while the bespoke approach is recommended for more complex tasks with two or more developers involved.

The first section of this topic describes a typical task that can be resolved by using either of the two approaches. The second section describes the templated approach, and the third section describes the bespoke approach.

A Typical Task that Is Resolved by Using an Add-On

Suppose that you need to create a new webpage that is based on a new database table.

As a final result of using either approach to resolve this task, the following items must be created (which have been added to the content of the customization project):

• The external files related to the add-on solution (assembly, .aspx, and aspx.cs) • The script that creates the new database table (see the screenshot below)

(9)

Figure: Exploring the content of the customization project

As a result of implementing the code of the add-on solution and modifying the site map of the current application instance, the Registry of Discounts webpage has been created, which uses the appropriate business logic. This webpage is accessible for possible users from the navigation pane. (The screenshot below shows the webpage with a few added data records.)

Figure: Analyzing the Registry of Discounts webpage

Templated Approach to the Add-On Development

To pursue this approach of add-on development, you should first create a customization project and then create the preconfigured add-on solution. (See Creating an Add-On Solution, which describes the whole cycle of developing a templated add-on solution and preparing the final deployment package.) You then perform all the necessary development steps, build the add-on project, map the new webpage to the site map, and include in the content of the project the site map changes, the compiled assembly, the code of the .aspx and .aspx.cs files, and the SQL script for the new database table. The screenshot above illustrates the content of the customization project (of the SQL-type object in this case).

Thus, to resolve the add-on task by using the first approach, you must perform the following steps: • Create the new customization project

• Create the preconfigured add-on solution

• Make necessary development actions, build the solution, and register the new page as a webpage • Add the solution to the content of the customization project

(10)

The main advantage of this approach is a simpler initial configuration in comparison with the bespoke approach, because the Acumatica Customization Platform preconfigures the original add-on so that you do not need to make references for project and application library files.

Bespoke Approach to the Add-On Development

With this approach of add-on development, you manually create an add-on solution, develop it, and add all the add-on changes to the content of the new customization project. (See Developing an Add-On Solution.)

To resolve the add-on task by using the bespoke approach, you must perform the following steps: • Manually create the add-on solution and set up all necessary references to the application

instance

• Make necessary development actions, build the solution, and register the new page as a webpage • Create the new customization project within this instance

• Add the solution to the content of the customization project • Download the deployment package

The main advantage of this approach in comparison with the templated one is that more complex tasks can be resolved and more than one developer can be involved in the process of developing the add-on solution.

Creating an Add-On Solution

As Add-On Solution described, before you create an add-on solution, you must choose the approach that best fits your customization task:

• A customization project based on the preconfigured add-on solution provided by Acumatica (templated approach)

• A manually created add-on solution (bespoke approach)

If you select the templated approach, to create an add-on solution for Acumatica ERP or another Acumatica-based application, you should first create a customization project and then start the system procedure, which gives you the ability to adjust the initial configuration of an add-on solution. The first section of this topic describes how to do this and what the preconfigured add-on solution is. When the development has been finished, you include the add-on solution in the created customization project, whose content is supplemented by the external files you created by using MS Visual Studio during the development steps. As a result, you have a deployment package, which comprises the whole content of the add-on solution that is encapsulated into the appropriate customization project.

With the bespoke approach, first you create and develop an add-on solution; after the development has been finished, you create the customization project and include in the content of this project the assembly, webpages, and other required files. Creating of a customization project is necessary to prepare a deployment package.

In both cases, you employ the standard interface of MS Visual Studio for developing an add-on solution, as if you were developing a standalone solution.

You can also use auxiliary customization facilities to make some additional application modifications. Don't forget to include these modifications in the content of this project.

The sections below describe actions that you have to perform if you use each approach to create and develop an add-on solution.

(11)

Using the Templated Approach

If you are using the templated approach listed above, first you create a customization project, and then you create the add-on solution.

To create an add-on solution for an Acumatica ERP application, perform the following actions: 1. Start the Acumatica ERP application.

2. Navigate to System > Customization > Manage > Customization Projects. 3. On the Customization Projects webpage, click New.

4. On the New Project dialog box that appears, type your project name, such as AddOn_Demo, and click OK.

5. Click Visual Studio, and select Create Add-on Project, as shown in the screenshot below.

Figure: Creating an add-on project

6. On the Opening OpenSolution.lnk dialog that appears, select Open with, select an integrated development environment such as MS Visual Studio, and click OK.

7. Build the AddOn_Demo project of the add-on solution.

MS Visual Studio is started with the solution that contains the AddOn_Demo project name (that is, the project name is the same as the name of the customization project). This project contains the Examples.cs file as the first step reference. You can use this file as a starting point or simply remove it from the project.

Notice that the AddOn_Demo project has predefined references to the PX.Common.dll,

PX.Data.dll, and PX.Objects.dll assemblies located in the Bin folder of the website; also, the

website has the reference to the AddOn_Demo project. When the AddOn_Demo.dll assembly is compiled, it's automatically copied to the Bin folder of the website (see the screenshot below).

(12)

Figure: Exploring the structure of the new project

8. Develop and test the add-on solution.

9. Return to the Acumatica ERP application, and reopen the Customization Projects webpage if it is closed.

You can again open the MS Visual Studio solution from the Customization Projects webpage after clicking Visual Studio and selecting Open Solution.

10. Click Add on the details table toolbar, and select File from File System.

11. On the Add Files pop-up window that appears, select check boxes left of the names of the created files (webpages, assembly files, and other external files) you want to add to the project, and click Save, as shown in the screenshot below.

Figure: Adding the external assembly file to the customization project

Use the Add Files option when you need to place additional external files into the customization project; to update the content of the customization project with changed external files, see the Updating the

(13)

If you upgrade the application instance, you may have to update the content of the customization project. (For details, see Updating a Customization Project.)

Using the Bespoke Approach

If you are using the bespoke approach listed above, you manually create an add-on solution.

To manually create an add-on solution for an Acumatica ERP application, perform the following actions: 1. Start MS Visual Studio, and create a new Class Library solution with a name of your choosing. 2. Manually add new add-on project references to the PX.Common.dll, PX.Data.dll, and

PX.Objects.dll assemblies located in the Bin folder of the customization application instance. 3. Manually add the reference to the created project from the website. (See MS Visual Studio

documentation.)

4. Build the project and ensure that the compiled assembly has been automatically copied to the Bin folder of the website.

5. When you finish the development of the add-on solution, start the Acumatica ERP application. 6. Navigate to System > Customization > Manage > Customization Projects.

7. On the Customization Projects webpage, click New.

8. On the New Project dialog box that appears, type your customization project name and click OK.

9. Click the Add button and select File from File System.

10. On the Add Files pop-up window that appears, select check boxes left of the names of the created files (webpages, assembly files, and other external files) you want to add to the project, and click Save.

Using the Auxiliary Customization Tools with an Add-On Solution

To deploy the paths to your new pages within the navigation pane, you need to make site map changes to the content of the current customization project as follows:

• Modify the site map of the locally installed application instance by using the Site Map system webpage (see Site Map).

• Open the Customization Project webpage, click Add on the details table toolbar, and select Site Map to open the Add Site Map dialog. Select and add site map changes to the content of the current customization project.

Depending on the set of tasks resolved within the customization project, you may need to perform the following actions:

• Adding new inquiry conditions to the Generic Inquiry system webpage (see Generic Inquiry). • Creating new reports or modifying existing ones by using the Acumatica Report Designer. Open the Customization Projects webpage. Depending on the type of auxiliary customization, perform the following actions:

• Click Add on the details table toolbar, select Generic Inq to open the Add Generic Inq dialog, select new or modified inquiries from the Generic Inquiry webpage, and save them to the content of the current customization project.

• Click Add on the details table toolbar, select Report from Database to open the Select Report dialog, select the new reports (which had been previously saved to the database), and save them to the content of the current customization project.

(14)

Updating the Content of the Customization Project with Modified External Files

If you have made changes to any file of the add-on solution placed within the customization project, you need to update the content of the customization project by clicking Check in Files before you download the project.

In the Check in Files dialog that appears, you can analyze and resolve content conflicts with the external files. For files with conflicts, the Conflict check box is selected. Content conflicts take place when you have modified any external file that is placed within the project. To update external files stored in the project, you should select the Selected check box for the appropriate conflict records and then click Check in Files. Only the selected files get updated within the project. If you do not want to update all of the files with conflicts, update appropriate external files with conflicts and then click Remove all Conflicts. After you click Remove all Conflicts, the system won't flag any customization project conflicts until an external file placed within the project is modified again.

We strongly recommend that you click RefreshDBTables on the details table toolbar every time you've made changes to any database table whose schema had been imported from the database to the customization project. Otherwise, you may encounter unpredictable results during the testing stage. The refreshing procedure regenerates the database scripts of the tables placed within the project with the selected Import Table Schema from Database option.

Developing an Add-On Solution

As was said earlier, to create new pages for the Acumatica ERP application or another Acumatica Framework-based application, you should create an add-on solution.

This topic describes in details an example of developing an add-on solution. The task is to create a new (user) database table and then add a page to the Acumatica ERP, generate a data access class (DAC) based on fields of the added user database table, and create a business logic controller (BLC, also referred to as graph), with a data view, which must support the new page registered as an application webpage.

Adding a User Database Table and Creating an Add-On Solution Install a new Acumatica ERP application instance.

First you should add the new (user) database table to the instance, TaskTemplate. To do this, perform the following SQL script for the application instance database.

SET ANSI_NULLS ON GO SET QUOTED_IDENTIFIER ON GO SET ANSI_PADDING ON GO

CREATE TABLE [dbo].[TaskTemplate]( [CompanyID] [int] NOT NULL,

[TemplateID] [int] IDENTITY(1,1) NOT NULL, [TemplateCD] [nvarchar](30) NOT NULL, [CaseClassID] [nvarchar](10) NOT NULL, [GroupID] [int] NOT NULL,

[Priority] [int] NULL, [Status] [char](2) NULL, [CategoryID] [int] NULL, [Descr] [nvarchar](255) NULL, [tstamp] [timestamp] NULL,

[CreatedByID] [uniqueidentifier] NOT NULL, [CreatedByScreenID] [char](8) NOT NULL, [CreatedDateTime] [datetime] NOT NULL,

[LastModifiedByID] [uniqueidentifier] NOT NULL, [LastModifiedByScreenID] [char](8) NOT NULL, [LastModifiedDateTime] [datetime] NOT NULL,

CONSTRAINT [CRTaskTemplate_PK] PRIMARY KEY CLUSTERED (

(15)

[CompanyID] ASC, [TemplateID] ASC

)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]

) ON [PRIMARY] GO

SET ANSI_PADDING OFF GO

ALTER TABLE [dbo].[TaskTemplate] ADD DEFAULT ((0)) FOR [CompanyID] GO

Then create the CRMAddOn add-on solution by using the bespoke approach. For details, see first four instructions in Using the Bespoke Approach. After creating needed references and building the added project to the solution, the Solution Explorer will get the structure, displayed in the following screenshot.

Figure: Viewing the structure of the CRMAddOn solution

Creating a BLC, Adding a Page, and Generating DAC Fields

Now you should create a BLC file to bind the page, which is to be added, to this BLC, and then to generate the DAC based on the user database table. After performing these actions, you should modify the BLC code to make its data view based on the generated DAC, then change DAC attributes, define the new page layout and, finally, register this page in the Site Map as the Task Template webpage. To do this, proceed as follows:

1. Add the TaskTemplateMaint BLC file based on the PXGraph template and build the project. 2. Add the CR206050.aspx page based on the FormView template to the CR subfolder of the

website.

3. Open the added page in Design mode and specify the TypeName by selecting CRMAddOn.TaskTemplateMaint from the drop-down list.

If the CRMAddOn.TaskTemplateMaint item is not displayed on the drop-down list, right-click the ds control and select Refresh, then open the drop-down list again.

4. Allocate the PXDataSource (ds) control and select the Generate Class item, as the following screenshot illustrates.

(16)

Figure: Specifying the TypeName and starting to generate the TaskTemplate DAC fields

5. In the Data Access Class Generator window that appears, select the TaskTemplate user table name from the Table Properties drop-down list (or type first few symbols of this name), and click Generate (see the following screenshot).

Figure: Generating fields of the TaskTemplate DAC

(17)

Figure: Analyzing the generated DAC code

Modify the DAC code as follows. namespace CRMAddOn { using System; using PX.Data; using PX.Objects.CR; using PX.Objects.EP; using PX.TM; [Serializable]

public class TaskTemplate : PX.Data.IBqlTable {

#region TemplateID

public abstract class templateID : PX.Data.IBqlField {

}

protected int? _TemplateID; [PXDBIdentity]

public virtual int? TemplateID { get { return this._TemplateID; } set { this._TemplateID = value; } } #endregion #region TemplateCD

public abstract class templateCD : PX.Data.IBqlField {

}

protected string _TemplateCD;

[PXDBString(30, IsUnicode = true, IsKey = true)] [PXDefault]

(18)

[PXUIField(DisplayName = "Template ID", Visibility = PXUIVisibility.SelectorVisible)]

public virtual string TemplateCD { get { return this._TemplateCD; } set { this._TemplateCD = value; } } #endregion #region CaseClassID

public abstract class caseClassID : PX.Data.IBqlField {

}

protected string _CaseClassID; [PXDBString(10, IsUnicode = true)] [PXDefault]

[PXUIField(DisplayName = "Case Class ID")] [PXSelector(

typeof(Search<CRCaseClass.caseClassID>),

DescriptionField = typeof(CRCaseClass.description))] public virtual string CaseClassID

{ get { return this._CaseClassID; } set { this._CaseClassID = value; } } #endregion #region GroupID

public abstract class groupID : PX.Data.IBqlField {

}

protected int? _GroupID; [PXDBInt()]

[PXDefault]

[PXUIField(DisplayName = "Default Workgroup", Visibility = PXUIVisibility.SelectorVisible)]

[PXSelector(

typeof(Search<EPCompanyTree.workGroupID>),

SubstituteKey = typeof(EPCompanyTree.description))] public virtual int? GroupID

{ get { return this._GroupID; } set { this._GroupID = value; } } #endregion #region Descr

public abstract class descr : PX.Data.IBqlField {

}

protected string _Descr;

[PXDBString(255, IsUnicode = true)]

[PXUIField(DisplayName = "Description", Visibility = PXUIVisibility.SelectorVisible)]

(19)

| Getting Started with the Acumatica Customization Platform | 19 { get { return this._Descr; } set { this._Descr = value; } } #endregion #region Priority

public abstract class priority : PX.Data.IBqlField {

}

protected int? _Priority; [PXDBInt()]

[PXDefault(1, PersistingCheck = PXPersistingCheck.Nothing)] [PXUIField(DisplayName = "Priority", Visibility =

PXUIVisibility.SelectorVisible)] [PXIntList( new int[] { 0, 1, 2 }, new string[] { "Low", "Normal", "High" })]

public virtual int? Priority { get { return this._Priority; } set { this._Priority = value; } } #endregion #region Status

public abstract class status : PX.Data.IBqlField {

}

protected string _Status; [PXDBString(2, IsFixed = true)] [PXUIField(DisplayName = "Status")] [ActivityStatusList]

public virtual string Status { get { return this._Status; } set { this._Status = value; } } #endregion #region CategoryID

public abstract class categoryID : PX.Data.IBqlField {

}

protected int? _CategoryID; [PXDBInt()]

[PXUIField(DisplayName = "Category", Visibility = PXUIVisibility.SelectorVisible)]

[PXSelector(

(20)

DescriptionField = typeof(EPEventCategory.description), SelectorMode = PXSelectorMode.DisplayModeText)]

public virtual int? CategoryID { get { return this._CategoryID; } set { this._CategoryID = value; } } #endregion #region tstamp

public abstract class Tstamp : PX.Data.IBqlField {

}

protected byte[] _tstamp; [PXDBTimestamp()]

public virtual byte[] tstamp { get { return this._tstamp; } set { this._tstamp = value; } } #endregion #region CreatedByID

public abstract class createdByID : PX.Data.IBqlField {

}

protected Guid? _CreatedByID; [PXDBCreatedByID()]

public virtual Guid? CreatedByID { get { return this._CreatedByID; } set { this._CreatedByID = value; } } #endregion #region CreatedByScreenID

public abstract class createdByScreenID : PX.Data.IBqlField {

}

protected string _CreatedByScreenID; [PXDBCreatedByScreenID()]

public virtual string CreatedByScreenID { get { return this._CreatedByScreenID; } set { this._CreatedByScreenID = value; } } #endregion #region CreatedDateTime

(21)

{ }

protected DateTime? _CreatedDateTime; [PXDBCreatedDateTime()]

public virtual DateTime? CreatedDateTime { get { return this._CreatedDateTime; } set { this._CreatedDateTime = value; } } #endregion #region LastModifiedByID

public abstract class lastModifiedByID : PX.Data.IBqlField {

}

protected Guid? _LastModifiedByID; [PXDBLastModifiedByID()]

public virtual Guid? LastModifiedByID { get { return this._LastModifiedByID; } set { this._LastModifiedByID = value; } } #endregion #region LastModifiedByScreenID

public abstract class lastModifiedByScreenID : PX.Data.IBqlField {

}

protected string _LastModifiedByScreenID; [PXDBLastModifiedByScreenID()]

public virtual string LastModifiedByScreenID { get { return this._LastModifiedByScreenID; } set { this._LastModifiedByScreenID = value; } } #endregion #region LastModifiedDateTime

public abstract class lastModifiedDateTime : PX.Data.IBqlField {

}

protected DateTime? _LastModifiedDateTime; [PXDBLastModifiedDateTime()]

public virtual DateTime? LastModifiedDateTime { get { return this._LastModifiedDateTime; } set { this._LastModifiedDateTime = value; } } #endregion

(22)

} }

7. Open the TaskTemplateMaint.cs file and modify the BLC code to create the Templates data view as follows and build the project (see also the screenshot below).

using PX.Data; namespace CRMAddOn {

public class TaskTemplateMaint : PXGraph<TaskTemplateMaint, TaskTemplate> {

public PXSelect<TaskTemplate> Templates; }

}

Figure: Modifying the initial BLC code

8. Open the new page in Design mode and set the PrimaryView property value of the ds control to Templates; select the form area of the page and also set to Templates the DataMember property value.

If the Templates item is not displayed on the drop-down list, right-click the ds control and select

Refresh, then open the drop-down list again.

9. Click the smart tag of the form area and select Edit Content Layout.

10. By using the Layout Editor that appears, open the Fields tab of the right window of the editor, select check boxes for all UI controls and click Generate, so they are added onto the FormView template of the new page.

11. Add two PXLayoutRule components to allocate UI controls within two columns, and, after opening the Properties tab of the right window of the editor, perform the following actions (see also the screenshot below):

(23)

Figure: Adding UI controls and adjusting their properties by using the Layout Editor

a. Select the header of the first column and specify the following properties through the appropriate drop-down lists:

• StartRow: True • ControlSize: M • LabelsWidth: SM

b. Add one more PXLayoutRule component and place it above the edDescr UI control to widen it by setting the ColumnSpan property so that its value equals 2.

c. Select the PXLayoutRule component to define the second column and specify the following properties through the appropriate drop-down lists:

• StartColumn: True • ControlSize: SM • LabelsWidth: XS

12. Click OK to close the Layout Editor. You can see the page with added controls, as shown in the following screenshot:

(24)

Figure: Viewing the layout of the new page

13. Navigate to System > Customization > Manage > Site Map and register the new added page as the Task Template webpage. To do this, select the Setup fourth level subnode of the Organization node in the site map tree, click the Add Row button, and manually enter the following values (see also the screenshot below):

• ScreenID: CR.20.60.50 • Title: Task Templates

• Url: ~/Pages/CR/CR206050.aspx

The system automatically assigns the Graph Type value by using the Type Name value of the specified page. The Expanded check box must be cleared, as it is by default.

(25)

Figure: Registering the added page as the Task Templates webpage

Click Save to save the registered webpage in the Site Map. Preparing the Content of the Customization Project

After you perform necessary actions within the add-on solution, you have to start the application instance, create a new customization project, and get the current content to this project, including appropriate external files. You need to do this, if you want to easily and reliably deploy the add-on solutiadd-on for the remote applicatiadd-on, which, for instance, represents the customer's enterprise application.

Proceed as follows:

1. Navigate to System > Customization > Manage > Customization Projects and click New on the form area of the Customization Projects webpage; add the new project name, such as CRMAddOn, that is, the name of the customization project is similar to one of the add-on project.

(26)

Figure: Starting to add the content of the new customization project

3. In the Add Files pop-up window, select .dll, .aspx, and .aspx.cs files, created during the development stage, and click Save, as the following screenshot illustrates.

Figure: Selecting external files for including them in the content of the customization project

As a result, the File type content objects have been included in the customization project, as the screenshot below illustrates.

(27)

Figure: Analyzing the added content of the customization project

4. Click Add and select Site Map.

5. In the Site Map pop-up window, select check box left of the Task Templates item, as the following screenshot illustrates. As the result, the Data type content object has been included in the customization project, with the new position of the Site Map.

Figure: Selecting the Task Templates item of the Site Map

6. Click Add and select Database Table or Script; in the Edit Sql Script dialog that appears, select TaskTemplate as the DBObject Name, select the Import Table Schema from Database check box, and click Save, as the following screenshot illustrates.

(28)

Figure: Adding the TaskTemplate Sql type object to the content of the customization project

You may perform the described set of actions of adding and updating the content of the

customization project only once, before starting the final testing and deployment stage. However, you may want to improve the content after its uploading by modifying the page layout, DAC attributes, data views, or business logic. After making any changes in the add-on solution and before creating the final deployment package, do not forget to perform the following actions in the

Customization Projects webpage:

• Select Check in Files; in the Check in Files pop-up window, the changed files are highlighted with the Selected and Conflict check boxes. If you want to update the current customization content, click Check in Files; otherwise, you can clear the Select check boxes for files, which content needn't to be updated that moment and then click Check in Files. • Click RefreshDBTables every time you have made changes to any database table whose

schema had been imported from the database to the customization project. Otherwise, you may encounter unpredictable results during the testing stage. The refreshing procedure regenerates the database script of the tables placed within the project with the selected

Import Table Schema from Database option.

Testing the Add-On Solution and Downloading the Deployment Package

Now you should test the new Task Templates webpage before preparing the deployment package of the add-on solution.

Navigate to Organization > Customer Management > Configuration > Setup > Task Templates and view the new webpage (see the screenshot below), try to open lookup windows, drop-down lists, and enter data to the webpage.

(29)

Figure: Analyzing the added webpage

To download the deployment package, return to the Customization Projects webpage and click Get Package on the form toolbar. In the Opening CRMAddOn.zip dialog that appears, select Save File (see the screenshot below), then specify path and change the zip-file name, if necessary, in the navigation window that appears, and click OK.

Figure: Downloading the deployment package

To observe the whole XML content of the customization project and download the package, return to the

Customization Projects webpage and click Edit XML on the form toolbar. In the window with the whole XML

content of the customization project (the name of the project is displayed in the upper part of the window), select Download Package. The next actions are the same (they have been described in the previous paragraph).

(30)

Figure: Downloading the deployment package

Scopes of the Acumatica Customization Platform

This topic describes the three scopes of the Acumatica Customization Platform, as well as gives the basic concepts of customization of Acumatica ERP or other applications developed with Acumatica Framework. The sections of this topic also describe user interface customization tools and facilities and key terms used throughout this guide, such as Acumatica Customization Engine and Acumatica Extensibility Framework.

Three Scopes of Customization

You can divide any customization task into three scopes: user interface (UI) customization, functional customization, and auxiliary customization. Depending on the complexity of the particular customization task, you can use the tools and facilities of any or all of the customization scopes.

UI customization includes changing the look and behavior of webpages, tweaking webpage design, and manually editing the .aspx code. All UI modifications, except for manual editing of the .aspx code, are performed in page design mode (see Page Design Mode). UI customization is always related to the .aspx code of the corresponding webpages and represents aspx changesets that are added to the existing .aspx code.

Functional customization means various kinds of modifications of the data structure and original

application business logic. All these modifications are related to the code of the appropriate data access classes (DACs) or business logic controllers (BLCs, also referred to as graphs).

Auxiliary customization is briefly described in Auxiliary Customization Facilities. The auxiliary customization facilities are compatible with both add-on solutions and the tools and facilities of the Acumatica Customization Platform.

Each scope involves the use of appropriate tools and facilities of the Acumatica Customization Platform. UI Customization Tools and Facilities

The tools and facilities for the UI customization are described in details in UI Customization Tools and Facilities.

(31)

By using UI customization tools and facilities, you can resolve UI customization tasks of any complexity level.

See also User Interface Customization .

Two Technologies of Functional Customization

The Acumatica Customization Platform includes two technologies for functional customization: the Acumatica Customization Engine (ACE) and the Acumatica Extensibility Framework (AEF). Both technologies have their own tools and facilities.

The Acumatica Customization Engine supports a set of tools and facilities designed for the consultants who implement customization of Acumatica ERP or other Acumatica Framework-based applications. You can use it to make some quick changes to the database structure and business logic.

The Acumatica Customization Engine is designed primarily for value-added resellers (VARs) that deliver the customization of Acumatica ERP or other Acumatica Framework-based software products to the end user and need to quickly modify the base product behavior.

When you use the Acumatica Customization Engine, you get the following key benefits:

• The ACE tools and facilities are available in your web browser; you don't need to have Microsoft Visual Studio installed.

• You can make changes to the database structure by using web-based visual designers. • You can review and modify source code at any time.

• ACE contains a mechanism that makes customization projects fairly resistant to upgrades. The tools and facilities for the functional customization by using ACE are described in details in Tools and Facilities of the Acumatica Customization Engine.

The Acumatica Extensibility Framework (AEF) is an integral part of the Acumatica platform. You can use it to create extensions and deploy them with minimal configuration required. AEF also lets you encapsulate code and avoid fragile hard dependencies.

AEF is designed primarily for independent software vendors (ISVs) that develop vertical and add-on solutions on top of Acumatica ERP or other Acumatica Framework-based applications, and want to extend or modify the base product behavior. Also, VARs can use AEF for implementing customization instead of ACE.

The Acumatica Extensibility Framework provides the following key benefits: • You can deploy multiple projects that extend DACs or BLCs.

• Extensions are precompiled, which provides a measure of protection for your source code and intellectual property.

• AEF provides an advanced level of control over the business logic and a multilevel extension model.

• AEF implements an auto-discovery mechanism, which makes the deployment and upgrade processes straightforward.

The tools and facilities for the functional customization by using AEF are described in details in Tools and Facilities of the Acumatica Extensibility Framework.

You can customize add-on solutions too. However, we don't recommend that you use both AEF customization and add-on solution within the same assembly because of possible complexity in maintenance and deployment. Instead, you should create a separate assembly for each approach.

User Interface Customization

As a rule, when we speak of user interface (UI) customization, we are implying the use of UI customization tools and facilities of the Acumatica Customization Platform. The result of the UI

(32)

customization is the cumulative changeset to the .aspx code encapsulated in the XML content of the customization project.

With UI customization, you can do the following:

• Manually drag controls on a page within their placeholders (container controls)

• Add controls of different types (such as NumberEdit, Selector, and ComboBox) onto a page • Add advanced controls (such as tab, panel, grid, and button) onto a page

• Manage the control layout of a page, including the capability to delete controls or hide their labels • Manually adjust a wide range of UI properties of controls

• Manually edit the .aspx code

The system adds the CST prefix to the ID of any webpage that had been customized (that is, if the .aspx code of a webpage had been modified with UI customization tools or facilities, or manually). You can see the webpage ID (or ScreenID) after opening the webpage and clicking Help in the upper part of the webpage.

The following screenshot illustrates the new ID of the Purchase Orders customized webpage.

Figure: Viewing the ID of the customized webpage

We mean under the customized webpage term the fact that the customization project, whose content includes the modified .aspx code, is published. If you still don't publish the project or cancel publishing the project (by using the Undo Publish procedure), the webpage has its original ID.

The underlying topics cover what capabilities the UI customization provides and which UI customization tools and facilities are used in the underlying topics:

• Dragging, Moving, and Deleting UI Controls and Grid Columns • Adding Columns to a Selector

Below given references to the other topics that also describe capabilities of UI customization tools and facilities:

• PXLayoutRule Components • Adding Items

(33)

Almost all UI customization actions, except for the manual editing of the .aspx code, are performed in page design mode. The topic Page Design Mode defines and briefly describes this mode. The Aspx Pages Editor describes how to manually edit the .aspx code.

The Acumatica Customization Engine (ACE) and Acumatica Extensibility Framework (AEF) technologies of functional customization are compatible with the UI customization tools and facilities. See Acumatica Customization Engine and Acumatica Extensibility Framework to gain knowledge about the functional customization tools and facilities.

Dragging, Moving, and Deleting UI Controls and Grid Columns

This topic describes in detail how to change the placement of UI controls by dragging them and how to use the facilities of the Aspx Control Tree to delete or move UI controls and grid columns.

Dragging and Dropping UI Controls Perform the following actions:

1. Navigate to Distribution > Inventory > Work Area > Manage > Stock Items, and on the Customization menu, select Open Customization Project.

2. On the Select Working Project dialog that appears, click New and add the new project name, such as IntroUI, to the Project Name field of the New Project dialog that appears, and then click OK.

3. On the Select Working Project dialog that appears again, select the Unpublish Existing Customization check box, if it is displayed, and click OK, as the following screenshot illustrates. (The Unpublish Existing Customization check box is being displayed on the Select

Working Project dialog only when the current application instance has at least one published customization project.)

Figure: Creating a new customization project

By selecting the Unpublish Existing Customization check box after adding a new customization project's name, you revoke the procedure that cancels publication of all previously published customization projects. You need this procedure to have possibility to work with a single application instance with different customization projects without any risk to meet issues related to possible incompatibility with published projects. This is important for training purposes only.

(34)

After the unpublish procedure, which can take rather long time, finishes, you possibly have to select

Open Customization Project again, select the created project name, and click OK to open the

project.

4. On the Customization menu, select Enter Page Design Mode. (For details, see Page Design Mode.) The appearance of the webpage changes to the webpage template, which is further named simply page.

Now you can start to manually move UI controls by dragging them. But you should note the following simple rules before:

• To move a UI control within a form area, you should click and hold the left button and then drag the element to the required place.

• You can move a UI control anywhere within its container control.

• Any UI control moved within a form area is automatically aligned according to the nearest PXLayoutRule component placed above it (see PXLayoutRule Components).

By dragging UI controls, you can perform only restricted UI customization by moving UI controls within their placeholders. For more advanced UI movement customization, you should use the Aspx

Control Tree dialog box, illustrated in the next section.

On the Stock Items webpage, suppose that you want to move up the Is a Kit check box, to make it the first control in the first column of the General Settings tab area, as the following screenshot illustrates.

Figure: Viewing the webpage before dragging the UI control

Proceed as follows:

5. Click the Is a Kit check box on the General Settings tab, click and hold the left button, and then drag the element to the required place. In a few seconds (required for the page auto-refresh), the check box appears in the new position (see the following screenshot).

(35)

Figure: Noticing the new placement of the check box

6. On the Customization menu, select Close Project. If you don't save a customization project, you changes are lost (that is correct in this case).

If you want to save the changes, before closing the project, on the Customization menu, select Save Project to Database. If you want to continue UI customization without closing the project, you can save the intermediate changes to the project to have possibility to rollback to the previously saved customization state by selecting Reload Project from Database on the

Customization menu.

Moving and Deleting UI Controls and Grid Columns

You use the Aspx Control Tree to implement advanced customization of a webpage—for instance, if you need to delete a UI control or table column from a page area, to shift a column within a grid, or to change the position of a UI control on a form while having the capability to change its original placeholder.

Suppose that you must customize the General Settings and Warehouse Details tabs of the Stock Items webpage as follows:

2. On the Select Working Project dialog that appears,select the IntroUI, the name of the earlier created project, to the Project Name field, and then click OK.

3. On the Customization menu, select Enter Page Design Mode.

If you performed the actions described in the first section of this topic and saved the UI customization data of the previous customization steps to the database, the page design mode would stars automatically for the customized webpage, which is the Stock Items webpage in this case, because the changeset for its aspx code had been already created and saved to the database.

Now you need:

• To delete the Auto-Incremental Value input UI field. (See the first screenshot below.) • To move down the Tax Category UI field so that it is placed under the Lot/Serial Class

(36)

• To move to the left the Status column of the details table so that it is placed at the right of the Default column, as shown in the second screenshot below).

Figure: Viewing the General Settings tab before changes

Figure: Viewing the details table of the Warehouse Details tab before changes

Proceed as follows:

4. Right-click the Auto-Incremental Value UI field on the General Settings tab, and select Control Tree, as shown in the following screenshot.

(37)

Figure: Opening the Aspx Control Tree

5. In the Aspx Control Tree that appears with the LotSerNumVal highlighted subnode, click Remove to delete the Auto-Incremental Value UI field name (LotSerNumVal subnode), as the screenshot below illustrates. The subnode disappears. Thus, you can delete any unnecessary control by selecting the corresponding subnode.

The expanded tab node PXTabItem corresponds to the General Settings tab, that contains the selected Auto-Incremental Value UI field (LotSerNumVal subnode).

Figure: Removing the subnode

6. Select the TaxCategoryID subnode and click twice the Down button, as shown in the screenshot below. Click Apply to Page to apply your changes and close the Aspx Control Tree.

By doing this you move down the TaxCategoryID subnode, which corresponds to the Tax

Category UI selector field, to place it under the LotSerClassID subnode, which corresponds to the Lot/Serial Class UI selector field.

(38)

Figure: Moving down the Tax Category field

7. Right-click the details table area of the Warehouse Details tab and select Control Tree to again open the Aspx Control Tree.

8. In the Aspx Control Tree that appears with the item tree and with the PXGrid node highlighted (this node corresponds to the Warehouse Details tab), expand the node, select the

SiteStatus subnode (which corresponds to the Status column), and click the Up button three times. It should now be placed under the IsDefault subnode (the Default column), as the screenshot below illustrates.

Figure: Moving the grid column to the left

9. Click Apply to Page to apply your changes and close the Aspx Control Tree.

Thus, to change the placement of a grid column, you select the appropriate subnode and use the Up or Down button to move the subnode to the left (Up) or right (Down).

You can move grid columns only in this way. However, you can move UI controls placed on forms and tabs in this way and by dragging them within their placeholders, as described above.

10. On the Customization menu, select Validate and Publish.

After the publishing process finishes successfully, you will see the modified General Settings tab on the Stock Items webpage, as the following screenshot illustrates.

(39)

Figure: Viewing the modified General Settings tab of the webpage

If you open the Warehouse Details tab of this webpage, you will see that the Status column of the details table has been moved to the left from its former position, as the screenshot below illustrates.

Figure: Viewing the moved column on the Warehouse Details tab

If you open the Customization Projects webpage, you can analyze the added content (changeset) of the current customization project (see the screenshot below).

(40)

Adding Columns to a Selector

If you add columns to a selector, you give the user the capability to see more information about each item in the lookup window so that the user can select the appropriate data record.

The screenshot below illustrates the original view of the Location lookup window (which is named selector in page design mode). Location is a column of the details table on the Vendor Details tab of the Stock Items webpage. The lookup window of this column includes two columns. The UI customization task is to add one more column to this window.

Figure: Viewing the current structure and content of the lookup window

To resolve this customization task, perform the following actions:

2. On the Select Working Project dialog that appears, select the IntroUI project that already exists, and click OK.

(41)

The page design mode starts automatically for the previously customized webpage, which is the

Stock Items webpage in this case, because its aspx code had been already modified (see Dragging, Moving, and Deleting UI Controls and Grid Columns).

3. Right-click the Vendor Details tab and select Control Tree.

4. In the Aspx Control Tree that appears, select the VendorLocationID subnode of the PXSegmentMask type (see the following screenshot).

The PXSegmentMask type extends the functionality of the UI controls of the PXSelector type.

Figure: Adding the column to the selector by using the Add Selector Column dialog

5. Click Add and select Add Column to Selector.

6. In the Add Selector Column dialog that appears, click the Magnifier icon, select the VBranchID item in the lookup window, and click OK to close the dialog.

7. In the Aspx Control Tree that appears again, click Apply to Page. 8. On the Customization menu, select Validate and Publish.

After the publishing process finishes successfully, you should open the Stock Items webpage, select the Vendor Details tab, click the Magnifier icon of the Location column, and view the lookup window. Notice the additional column, as shown in the screenshot below.

(42)

Figure: Viewing the modified structure and content of the lookup window

As you can see, the Receiving Branch column has been added. This column can help the user to select the appropriate Location ID item value, which might depend on the branch where this inventory item is being accepted.

On the Customization menu, select View Customization Manager. You can see the new Page type object, which contains the .aspx code changes, as the screenshot below illustrates.

On the Customization menu, select View Source Code. On the Page Aspx tab, you can see the fragment of the .aspx code that is highlighted in yellow, as the screenshot below illustrates. This changeset represents the result of the UI customization.