• Customization Menu and Sessions
• Understanding the Publication of a Project • Managing Multiple Projects
• Updating a Customization Project • Deleting a Customization Project
Content of a Customization Project
This topic covers the most important themes that concern the internal and external Acumatica Customization Project content.
Typical Customization Project Content
Each project has specific content that depends on the task to be resolved within the project and on the using customization technology. You can see the internal part of this content through the Customization Projects webpage, while the external files are represented by assemblies, .aspx pages, and other files that are created either during the development of an add-on solution or by implementing a customization of the application.
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 included in the customization project.
The full content of a customization project, including external files, is stored in the database of the appropriate application instance after you have saved the content to the database. Customization project content is automatically saved to the database before you start the validation process prior to publishing the project or right before you publish the project without validation. Also, you can save the content by selecting Save Project to Database on the Customization menu.
To explore the internal content of an existing project of an Acumatica ERP application, you should start this application, navigate to System > Customization > Manage > Customization Projects, and select Project Name. The details table of this webpage displays the content of the selected customization project through records of different object types.
| Acumatica Customization Project | 103
All the actions illustrated below can be performed without starting a customization session (for details, see
Customization Sessions; that is, you shouldn't open a project. Instead, you select the required project in the Project Name field.
If you need to publish multiple customization projects, just open the Publish Customization webpage, select the required projects, and validate and then publish them. You can also publish any selected project by using the Customization Projects webpage. In both cases, you shouldn't open the customization project before starting to publish it. (For details, see Managing Multiple Projects and Final Testing and Deployment Stage.)
The screenshot below illustrates the add-on project, with three external files have been placed in: the add-on assembly, and also the .aspx and .aspx.cs files that represent the new added webpage. Notice the site map modifications under the header of the Data-type object.
The system will create two other objects (also shown in the following screenshot) as a result of the object-adding actions described in the next section:
• An object of the Report type that was added from the database
• An object of the Sql type with the code that describes the structure of the new database table used within the add-on assembly
Figure: Exploring the object of the Sql type of the add-on project
The screenshot below illustrates a simple customization project implemented with user interface customization and functional customization by using the Acumatica Customization Engine (ACE) . The project resolves these basic tasks: declaring the KeyWords field within the data access class (DAC), adding the appropriate database table column to which this new field is bound, adding the corresponding UI input field onto the form area of the Stock Items webpage, changing the name of the existing input field in the form area, and making a column mandatory for data entry in the details table of the tab area.
| Acumatica Customization Project | 104
Figure: Exploring the content of the object with the Page type
Notice the content records of four objects:
• Two objects of the Code File (DAC) type, which represent the additional code of the DACs. The first object belongs to the DAC used on the form area of the page, and the second one belongs to the DAC used within the details table on the tab area of the page.
• One object of the Page type, which is the changeset to the .aspx code and includes the properties of the additional field.
• One object of the Table type, with the code that defines the properties of the new database table column to which the new DAC field is bound.
The screenshot below illustrates a more complicated customization project, implemented by using UI customization and the Acumatica Extensibility Framework (AEF), that alters both the UI and the business logic of the Stock Items webpage. This project resolves the following tasks: declaring the UsrAdditionalDescr field within the DAC, adding the database table column to which this field is bound and the corresponding control onto the form area of the Stock Items webpage, and validating the UsrAdditionalDescr DAC field values.
| Acumatica Customization Project | 105
Figure: Exploring the content of the object with the File type
The content record of an object with the File type represents the assembly, which is the extension library solution created when you use MS Visual Studio or another development environment and which is intended to be used by the AEF at run time. This file resides in the Bin folder of the website, as you can see from the path expression within the content of the File-type object in the screenshot above. The system created the following objects as a result of performing the actions described in the next section:
• One object of the Page type that is the changeset to the .aspx code and includes the properties of the additional field
• One object of the Table type that describes the properties of the new database table column to which new DAC field is bound
Managing the Content of a Customization Project
By using the Customization Projects webpage, you can analyze and manage the content of any in- progress or completed customization project on the current application instance.
| Acumatica Customization Project | 106
Figure: Noting the menu items of the Add button
The screenshot above shows the commands of the Add menu, which you can use as follows: • If you click File from File System, the Add Files dialog appears with all the external files
that have been placed in the folder of the website. To include any needed file in the current customization project, select the check box left of the file name and click Save. (As a result, the system creates at least one object of the File type with the File name and the relative path to the application folder. The system encloses this new content in
<File/>
tags.)• If you click New Graph, DAC, Code File, the Create Code File dialog appears. Select PXGraph, IBqlTable, or Code File as the File Template and type the Class Name to generate the code of the business logic controller (BLC, also referred to as a graph), DAC, or class template; you can generate the DAC code template or the DAC code based on a user database table if you select the Generate Members from Database check box. (As a result, the system creates an object of the Codetype with the graph, DAC, or class template code. The system encloses this new content in
<Graph/>
tags.)• If you click Generic Inquiry, you can prepare for export the needed set of saved conditions on the Generic Inquiry webpage. (As a result, the system creates an object of the Export type. The system encloses the exporting code in
<Export/>
tags.)• If you click Site Map, the Site Map pop-up window appears with the altered (added, modified, or removed) site map items. To include an updated site map item in the current customization project, you can select the check box left of the site map record. (As a result, the system creates an object of the Data type. The system encloses the new node and position numbers in
<Data/>
tags.)• If you click Report from Database, the Select Report dialog appears; you can select the report in the Name lookup UI field. (As a result, the system creates an object of the Report type. The system encloses the report structure in
<Report/>
tags.)| Acumatica Customization Project | 107
• If you click Database Table or Script, the Edit Sql Script dialog appears. You select the DBObject Name from the DBObjectName lookup window (and select the Import Table Schema from Database check box if needed) and then click OK. You can manually add (or paste from your clipboard) the SQL script, which will be executed every time the customization project is published, into the Custom Script text area. You must select the DBObject Name so that the record will be added to the currently selected customization project. (As a result, the system creates an object of the Sql type. The system encloses the new content with the SQL script in
<Sql/>
tags.)• If you click Database Table Field, the Edit UsrField to Database Table dialog appears. You can select the table name from the Table Name lookup window, type the Field Name, and select the Field Type from the drop-down list. (As a result, the system creates an object of the Table type with the set of properties for the database column to be added. The system encloses this content in
<Table/>
tags.)If you click Edit XML, you will see all the inner customization code in XML format. The system encloses the content of each object in the appropriate tags.
You can see this XML code structure within the appropriate tags on the Customization Projects webpage, but in the window that this webpage contains, the content of each object is displayed separately under each type of object, as fragments of the whole customization content. See the next section for details.
When other customization tasks are resolved, the system creates the following objects:
• Page type objects if you are working with UI customization tools and facilities (for instance, see
Adding Columns to a Selector). The system encloses this content in <Page/> tags.
• DAC-type objects if you are using the Create Data Field designer (for instance, see Customizing DAC Attributes) or DataField Attributes window of ACE. The system encloses this content in <DAC/
> tags.
• Code-type objects for the customization BLC code files (for instance, see Extending Business Logic) created by using the tools and facilities of ACE. The system encloses this content in <Graph/> tags.
You can manually edit any currently selected customization project record.
However, manual editing of the content is not recommended, because you can change the content more reliably by using Acumatica Framework tools and facilities. If you select a record with the File, Code, Data, or Sql type and click Edit, the appropriate pop-up window or webpage appears. You can modify the selected record and save the changes to the customization project.
We strongly recommend that you 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.
We also recommend that you click Check in Files before you start the validation of a project if you have made changes to any external file included in the project or file created in the Caches subfolder of the App_Code folder of the website that contains changes made with ACE. Otherwise, you will get the Some files have been modified manually by the user on the file system. Please resolve conflicts message, which will redirect you automatically to the Check in Files dialog.
| Acumatica Customization Project | 108
Figure: Initializing the process of checking in files
In the Check in Files dialog (see the screenshot above), 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 of the website that is included in the project. To update these files, you should select the Selected check box for the appropriate records and then click Check in Files. If you do not want to update some files with conflicts, do not select them for check- in. After check-in, click Remove all Conflicts. Make sure you update appropriate files with conflicts before removing all remaining conflicts. After you click Remove all Conflicts, you won't get any customization project conflicts until a file included in the customization project is modified again.
Customization Menu and Sessions
You use the Customization menu, along with the Customization Projects webpage (see Content of a Customization Project), to manage customization projects. You can access this menu if you open any Acumatica ERP webpage.
Every time you log in and then open (or create and open) a customization project, the system starts a new customization session or continues a temporarily interrupted session. During a customization session, you can extend or alter an Acumatica ERP application to your specific business requirements by employing appropriate customization tools and facilities.
The Customization Menu
By using the Customization menu, you can perform such actions as opening and closing customization projects, selecting the project manager (represented by the Customization Projects webpage),
initializing various kinds of customization tools, and saving the content of a customization project to a database or reloading its content from a database to roll back the project to the previous state. You can access the Customization menu on an opened Acumatica ERP webpage if you have the Administrator or Customizer role (for details, see Granting User Access Rights for Customization). You can use the following menu commands to resolve customization tasks.
Customization Menu Commands
Command Description
Save Project to Database Saves to the database the current content of the customization project—that is, modifications that you have made during all previous customization sessions. (See the more thorough description of a customization session in the next section of this topic.)
Reload Project from
Database Reloads the content of the customization project from the database.If you haven't saved new modifications to the database within the complete or temporarily interrupted customization session, your
| Acumatica Customization Project | 109
Command Description
current modifications will be replaced by the most recent modifications that had been saved.
Open Customization
Project Gives you the option to open the existing customization project or tocreate a new one. Close Project Closes the current project: ends the whole or temporarily interrupted
current customization session and returns you to working with the Acumatica ERP application with the last published changes implemented. If you want to avoid losing your most recent changes, save these changes before closing the project by saving the project to the database or by using the validation process.
Enter Page Design Mode Enters page design mode and provides access to the UI customization designers and facilities (such as Create control, Advanced control, and Aspx Control Tree). To modify multiple webpages, you can open each required webpage in page design mode. (See Page Design Mode.) Exit Page Design Mode Exits page design mode for only the current page without losing UI
changes. To end the whole or temporarily interrupted customization session and return to working with the application, you should close the current project. (Do not forget to save your changes before closing the project.)
Validate and Publish Validates current changes and publishes the project to the application (if you click Publish after successful validation). The content of the current project is automatically saved to the database before the validation process begins. You do not need to manually save the content of the project before selecting this option.
View Published
Customization XML Displays the published customization content in XML format. Thecontents of all published customization projects are placed within the common XML code.
Undo Publish Removes the customization from the application, and restores its original state. This action discards the published modifications of not only the current project but also every published project. All of the published project names are listed in parentheses after this menu item name, such as Undo Publish (GL_01, SO_03, AEF_Demo).
View Customization
Manager Opens the Customization Projects webpage, where you can explore,manually edit, and remove (if needed) all changes within the content of the current project.
View Source Code Opens the Source Code browser, which displays the original source code of the current webpage and its BLC. You view source code to analyze the application code before you make customization changes. (See Exploring the Source Code.)
Code Editor Opens the Custom Code editor so that you can add or manually change the business logic controller (BLC) code by using the Acumatica Customization Engine technology.
| Acumatica Customization Project | 110
Command Description
Aspx Editor Opens the Aspx Pages editor so that you can manually change the .aspx code of the current page.
Customization Sessions
You perform most customization actions during a customization session. The customization session is a set of time ranges within a workday during which you perform customization steps (see the next section of this topic) to resolve the specified customization task within the particular customization project. You must open the project to perform UI customization steps and some functional customization steps by using the Acumatica Customization Engine (ACE). But before testing the results of any completed step at run time, you should close the project; if necessary, you can open it again after testing. A customization session includes the testing time, when the customization project is temporarily closed. A customization session can also include time ranges when you perform customization by using the Acumatica Extensibility Framework (AEF) without opening the project.
When we speak of a customization session, we are talking only about the development stage of customization. For details, see Customization Stages.
Some actions related to a customization project can be performed after the interruption of the current customization session—that is, when the project is closed—but are still parts of the customization session. These actions include the following:
• Developing extension libraries with AEF • Testing customization project changes
Other actions related to a customization project concern the project but are executed outside of customization sessions, such as the following:
• Developing add-on solutions
• Performing customization actions by using the tools and facilities of the auxiliary customization scope
• Publishing the customization project by using the Customization Projects webpage
• Publishing a group of customization projects or unpublishing all previously published ones by using the Publish Customization webpage
As a rule, you resolve only a part of a customization task within a workday session so that the whole customization within a particular project may be fulfilled during multiple workday customization sessions. The number of workday sessions needed to resolve the task depends on its complexity.