Project Publication: General Information

When you have made all the needed changes to an MYOB Acumatica instance, you can deploy your customization project to another instance.

You can implement planned changes in different customization projects, with related changes grouped in the same project. You can publish multiple customization projects in one instance of MYOB Acumatica.

Learning Objectives

In this chapter, you will learn how to do the following:

• Create a deployment package for the customization project
• Export the package to a target system
• Publish the customization project in the target system
• Publish multiple customization projects simultaneously

Applicable Scenarios

You deploy a customization project to another instance in the following cases:

• You need to copy the changes caused by the customization project from the testing MYOB Acumatica instance to the production MYOB Acumatica instance.
• You need to deploy another MYOB Acumatica instance, and you want to make the same changes to it as you have to an existing instance that has a customization project published.

You publish multiple customization projects when you have been working on separate customization projects in your company, and you need to apply the changes from these projects to a single MYOB Acumatica instance.

Deployment of a Customization Project to Another Environment

As you customize the system, you usually need to use three different environments:

• A development environment: Your local environment, in which you create customization items, publish the customization project being developed, and perform initial tests related to the customization items
• A staging (or pre-production) environment: A copy of the production environment in which you will perform final testing of the completed customization project before applying it to the production environment
• A production environment: The target environment of the system that must be customized

You develop customization projects in the development environment. After you have added all customization items to the customization project and done preliminary testing, you prepare a deployment package to distribute the customization project to the staging or production environment, as shown in the following diagram.

A deployment package of a customization project is a redistributable ZIP file that includes the full content of the project. The deployment package consists of the project.xml file and any custom files that you have added to the project, such as external assemblies. The ZIP file has the same name as the exported customization project does.

Publication of Multiple Projects to the Same Instance

When you publish more than one customization project, the MYOB Acumatica Customization Platform merges the contents of all projects into a single customization project. If different projects include customization items for the same object, the platform tries to merge the changes by using the following approach:

• If the changes can be merged, the platform merges them. For example, the platform can merge different properties of the same control in an ASPX page.
• If the changes cannot be merged—for example, if the same report has been added to different customization projects—the platform stops the process and displays an error message.

The process of publishing multiple projects to the same instance is similar to the process of publishing a single project.

You start the publication on the Customization Projects (SM204505) by selecting the customization projects you need to publish and clicking Publish on the More menu. You can also open this form while you are working in the Customization Project Editor by clicking Publish > Multiple Projects on the main menu.

The system opens the Compilation pane, which displays the progress of publishing. First, the system performs the validation of the projects. After the validation is complete, you need to click Publish in this pane. Note that at this stage, all current users will be signed out.

After the publication is complete, you can view the content of the merged customization project by clicking the View Published on the More menu of the Customization Projects form. (See To View a Published Customization for details.)

Changes to the Application and Database

During the publication, the platform applies the changes to the application and database objects and updates the files in the website folder as follows:

• The custom layout is applied to the forms of MYOB Acumatica.
• The .cs files with the DAC extension code for the existing data access classes are generated and placed in the file system.
• The .cs files with the BLC extension code for the existing business logic are generated and placed in the file system.
• The .cs files with the custom code (Code items) are generated and placed in the file system.
• The custom files of the project are added to the website folder.
• The custom tables are created in the database, and custom SQL scripts are executed.
• The custom generic inquiries, reports, site map nodes, system locales, integration scenarios, shared reusable filters, access rights, wikis, web service endpoints, and analytical reports are added to the database.

We recommend that you back up the database before you publish customization projects, because canceling publication does not revert the changes made to the database. See Unpublishing Customization Projects for details.

After the publication is complete, the application domain always restarts if the project includes assemblies, which are placed in the /Bin folder of the website. If you have no assemblies in the project, you can enable run-time compilation, and the publication will not cause a restart.

If a published customization project contains classes derived from the CustomizationPlugin class, the platform launches the implemented custom processes after website files were updated and after the website was restarted. (See Custom Processes During Publication of a Customization for details.)

After you have published the customization project, the files with the customization code are updated in the file system, and you can work with them in MS Visual Studio. The .cs files with code are placed in the App_RuntimeCode folder of the website.

Validation of Customization Code

While the MYOB Acumatica Customization Platform processes the publication of a customization project, the platform validates the customization code included in the project. This validation of the code provides not only checking for syntax and semantics but also checking of the compatibility of the code included in the customization project with the original application code.

If there are any compatibility errors, the platform displays the warning and error messages in the Compilation window and stops the publication process. See CodeCustomization_Validation_Errors.html for detailed information.

Merging of Form Personalizations

Suppose that you have created a shared personalization of a form. (That is, you’ve modified a form in Form Configuration mode and clicked Apply to All on the Form Configuration pane, as described in Modern UI: Site-Wide Personalization.) Later, your ISV has given you another customization project that contains personalization of the same form. After reviewing it, you’ve decided that it would be beneficial to apply changes from both projects.

In the Modern UI, you simply publish both projects—or any number of projects. The system merges the changes if they’re compatible, such as adding two different user-defined fields to the same fieldset.

Some changes can't be merged, however—for example, when a tab or a table column is hidden in one project and visible in another. The system displays an error (shown below) and asks you to specify different priority levels for the projects.

To do this, you assign the highest level to the most important changes on the Customization Projects (SM204505) form, as shown below, and start the publication again. A level is a whole number; the greater this number, the higher the level of the customization project is. We recommend that you use higher values for more important changes. If you do not specify any level, the default value is 0.

The system applies to the form the changes from the project with a higher level and displays a message about the merging of changes (see below).

The publication then completes in the usual manner (shown below).

When certain changes are added based on the level of a customization project, you can manually reintroduce them. To do this, add the updated form personalization to the higher-level project and publish this project.

If you later unpublish the project, the form personalization stays in place. You can reverse these modifications only in Form Configuration mode (by clicking Reset to Default on the Form Configuration pane).

Check for Duplicate Records

The system checks for duplicate records during the publication of customization projects. Suppose that an item in a customization project has the same key (the primary key, the unique index, or the unique key) as the records that exist in the system. When you publish such a project, the system displays a warning and overwrites the existing records with the item from the project (see the following screenshot).

For details on XML format, see Implementing the XML Import and Export Functionality in a Custom Form.