T300 Acumatica Customization Platform

Transcription

1 T300 Acumatica Customization Platform

2 Contents 2 Contents 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 Developing an Add-On Solution Scopes of the Acumatica Customization Platform User Interface Customization...31 Acumatica Customization Engine...43 Acumatica Extensibility Framework...62 Customization Stages Source Code Browser Exploring the Source Code Development Stage Developing a Customization Project...90 Granting User Access Rights for Customization Final Testing and Deployment Stage...98 Acumatica Customization Project Content of a Customization Project Customization Menu and Sessions Understanding the Publication of a Project Managing Multiple Projects Updating a Customization Project Deleting a Customization Project UI Customization Performing UI Customization Page Design Mode Aspx Pages Editor PXLayoutRule Components Placing UI Elements in Multiple Rows and Columns and Widening these Elements Setting Label Width and Aligning UI Elements Horizontally Creating a Group of UI Elements and Hiding Their Labels Creating Nested Input Controls Setting Widths and Sizes of UI Elements Adding Items Adding Advanced Controls Nested Advanced Controls

3 Contents 3 Acumatica Extensibility Framework In Detail AEF Extensibility Generic Classes Creating an Extension Library Solution by Using the Bespoke Approach DAC Extensions Customizing DAC Attributes Creating a DAC Extension of an Extension DAC Extension Model Extension Tables Using an Extension Table Extension Table Declaration BLC Extensions Modifying a BLC Data View Declaring or Altering a BLC Data View Delegate Extending BLC Initialization Creating a BLC Extension of an Extension BLC Extension Model Adding or Altering BLC Event Handlers AEF Event Handler Model Altering BLC Virtual Methods Accessing Customization Objects Customization Best Practices Using Numbering Sequences Overriding a BLC Data View Overriding a BLC Data View Delegate Adding a Button onto the Form Control Adding Buttons to the Grid Control Calculating Unbound DAC Fields at Run Time Extending the Base Business Logic Extending the Multi-Level Document Workflow Extending the Persist() Method Extending the Release Operation

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 Getting Started with the Acumatica Customization Platform 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 valueadded 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. This topic defines and briefly describes an Acumatica Customization Project.

7 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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) New records in the site map indicating the position and properties of the new webpage

9 Getting Started with the Acumatica Customization Platform 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 Download the deployment package

10 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Content of the Customization Project with Modified External Files below.

13 Getting Started with the Acumatica Customization Platform 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. After all the described actions have been fulfilled, download the deployment package.

14 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 CR 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 Getting Started with the Acumatica Customization Platform 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 6. Analyze the generated DAC code in the TaskTemplates.cs file (see the screenshot below).

17 Getting Started with the Acumatica Customization Platform 17 Figure: Analyzing the generated DAC code Modify the DAC code as follows. namespace using using using using using CRMAddOn System; PX.Data; PX.Objects.CR; PX.Objects.EP; 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 Getting Started with the Acumatica Customization Platform 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)] public virtual string Descr

19 Getting Started with the Acumatica Customization Platform 19 get set return this._descr; 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( typeof(search<epeventcategory.categoryid>),

20 Getting Started with the Acumatica Customization Platform 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 public abstract class createddatetime : PX.Data.IBqlField

21 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Title: Task Templates Url: ~/Pages/CR/CR 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 Getting Started with the Acumatica Customization Platform 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 addon solution for the remote application, 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. 2. Click Add and select File from File System, as the following screenshot illustrates.

26 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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 Getting Started with the Acumatica Customization Platform 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