When you upgrade to a newer version of the Acumatica ERP application, you generally need to update the published customization projects of the application instance. Updating a published customization project involves making changes to the customization project or to your add-on solutions to make the common customization content compatible with the upgraded version of Acumatica ERP. These changes may be minor, and in some cases no changes may be needed. However, in some cases, especially when you upgrade a very old version of the application, you will have to update the common customization content of this project.
The common customization content is the joined content of all the published customization projects and add-ons. The common customization content was generated and stored in the database when the application was last successfully customized and published before the upgrade took place.
The upgrade process negates the common customization content by restoring the original application state but keeping the customization changes to the database, including the table structure and the changes made through the auxiliary customization tools. The first time the upgraded application instance is started, the system validates and applies the common customization content from the database.
| Acumatica Customization Project | 117
If the validation process fails, you should perform the appropriate actions, which depend on the type of error that occurred. To find out which of the customization projects contain issues to be fixed, you should first activate the Undo Publish procedure and then validate and publish the appropriate customization projects one by one.
Notice that the system stores in the database not only the common customization content, but also the content of each project, including content that had not been published. Therefore, through the
Customization Projects webpage you can see content of any project if it hadn't been deleted. (For details,
see Deleting a Customization Project.) After the successful publishing of a project, the system adds the content of this published project to the common customization content.
You can use the following procedures, described in the sections of this topic, to fix the issues that have appeared after the application upgrade:
• Convert Layout, which you use as the starting point to fix issues in the .aspx code.
• Publish without Validation, which you use if the validation of a project that was created by employing the Acumatica Customization Engine (ACE) fails.
Convert Layout
You need to convert the layout only if you have used Acumatica ERP 3.0 or lower (or had published an add-on solution with pages created by employing old page layout technology) and now have upgraded the application to 4.0 or higher.
You proceed slightly differently in each of these cases:
1. You (or any other developer) created webpages by using the add-on solution with the old page layout technology, and this solution had been published.
2. You (or any other developer) customized webpages for the version of the application that supported the old page layout technology, and the customizion project had been published. In the first case, you navigate to System > Customization > Explore > Source Code and open the Page Aspx tab of the Source Code webpage.
Click the Magnifier button of the Screen ID field, select one of the pages created in the add-on solution, and click Convert Page, as shown in the screenshot below. The conversion procedure changes the .aspx code of the page so that it fits the new page layout technology. Repeat this conversion procedure for all pages that you (or any other developer) created.
| Acumatica Customization Project | 118
Figure: Starting to convert the page created in add-on solution
During the upgrade process, all the original pages are automatically replaced by the new ones. You must convert only pages that were created within an add-on solution. You may have to alter the design of the converted pages in Visual Studio. If you do, don't forget to check in the changes of the .aspx files to the appropriate customization projects.
In the second case (you customized webpages for the older version of the application and the customization project had been published), you have to navigate to System > Customization > Explore > Customization Projects and click the Convert Layout button on the Customization Projects webpage (shown below, in the next section).
When you click this button, all the page changesets related to the current project content objects of the Page type are converted. After the conversion procedure has completed, you can see the new changeset for each page in the lower window of the Customization Projects webpage. You should then check each of the customized pages. You may need to open the appropriate customization project and then make minor changes to the design of the customized pages in page design mode.
Publish Without Validation
If the failing of the upgrade validation takes place, which is automatically performed (during the first start of application after the upgrade) for a project that you (or any other developer) created by using ACE, to address issues through additional deep testing, you can publish the project without validation. The screenshot below illustrates the Customization Projects webpage with the Convert Layout button (described in the previous section) and the Publish without Validation option of the Validate and Publish menu. In this case, you select a project that should be published to the upgraded application and click Publish without Validation. After publishing the project, you should fix the issues found within it and test the results. When all of these issues are fixed and the changes to the code files are checked in to the project, you should start working on the next project. Continue this process until all projects are successfully published and tested.
| Acumatica Customization Project | 119
Figure: Viewing the Customization Projects webpage
You may need to publish the customization project without validation in some other cases—for instance, if the project fails validation when you use ACE, but you want to publish it anyway to save the data access class (DAC) and business logic controller (BLC) files and then correct their code by using MS Visual Studio.