Anatomy of an Acumatica Customization: New Screens, Existing Screens, DLLs, Modern UI, SQL, and Generic Inquiries

When people first encounter Acumatica customization, they often describe it as “a ZIP file that gets published.” That is not wrong, but it is far too shallow to be useful.

A real Acumatica customization is a packaged application layer. It can include business logic in C#, new screens, extensions to existing screens, navigation metadata, access-right definitions, Modern UI files, database schema items, publish-time setup logic, and inquiry definitions. If one of those parts is missing, the result is often incomplete: the DLL loads but the screen is not visible, the screen exists but Modern UI is missing, the Generic Inquiry imports but is not navigable, or the data objects exist but the module is not actually usable.

The most practical way to understand an Acumatica customization is to think of it as six coordinated layers:

• C# business logic in a DLL.
• UI assets for new screens.
• UI extensions for existing Acumatica screens.
• Navigation and security metadata.
• Database schema items and optional publish-time scripts.
• Metadata-driven artifacts such as Generic Inquiries.

Once you see those layers separately, the package stops looking like a mysterious ZIP and starts looking like what it really is: a deployable Acumatica module.

The package is the delivery format, not the whole system

An exported customization is usually delivered as a ZIP that contains a project.xml manifest and supporting files. A practical package often looks like this:

WarrantyRecovery.export.zip
├── project.xml
├── Bin/
│   └── MyCompany.Warranty.dll
├── Pages/
│   └── WC/
│       ├── WC301000.aspx
│       └── WC301000.aspx.cs
└── screens/
    ├── WC/
    │   └── WC301000/
    │       ├── WC301000.html
    │       └── WC301000.ts
    └── SO/
        └── SO301000/
            └── extensions/
                └── SO301000_MyCustomization_StockExtension.ts

That ZIP is not just a file container. It is a deployment package that tells Acumatica what must be installed, how screens should appear, which metadata belongs to which screen, and how the tenant-specific UI should be extended.

At the center of the package is project.xml. It acts as the customization manifest. It usually contains entries for files, pages, screen rights, site map nodes, schema items, inquiries, and other publishable elements.

A simplified example might look like this:

<Customization level="1" description="Warranty Recovery">
  <File AppRelativePath="Bin\MyCompany.Warranty.dll" />
  <File AppRelativePath="Pages\WC\WC301000.aspx" />
  <File AppRelativePath="Pages\WC\WC301000.aspx.cs" />
  <Page path="~/Scripts/Screens/SO301000.html" pageSource="..." />
  <PerTenantFile
      AppRelativePath="screens\WC\WC301000\WC301000.html"
      ScreenId="WC301000" />
  <PerTenantFile
      AppRelativePath="screens\WC\WC301000\WC301000.ts"
      ScreenId="WC301000" />
  <PerTenantFile
      AppRelativePath="screens\SO\SO301000\extensions\SO301000_MyCustomization_StockExtension.ts"
      ScreenId="SO301000" />
  <SiteMapNode>...</SiteMapNode>
  <ScreenWithRights>...</ScreenWithRights>
  <Sql>...</Sql>
</Customization>

The exact XML structure varies by Acumatica version and export path, but the architectural idea stays the same.

The DLL is the business-logic core

Most serious Acumatica customizations center around a compiled DLL. That assembly usually contains:

• DACs,
• Graphs,
• Graph Extensions,
• Cache Extensions,
• PXAction methods,
• event handlers,
• workflow logic,
• services and helper classes,
• optional publish-time plugin code.

In the package, the DLL is usually delivered as a file item:

<File AppRelativePath="Bin\MyCompany.Warranty.dll" />

This is the preferred home for business logic. It is easier to version, test, refactor, and review than inline code embedded directly in the customization manifest.

A useful rule of thumb is simple:

• put business logic in the DLL,
• put deployment metadata in the package,
• put UI rendering in the screen files,
• put setup logic in controlled publish-time artifacts.

New screens: what must exist for a screen to be real

A new screen in Acumatica is not just a graph and not just an ASPX page. A complete new screen usually requires all of the following:

• a DAC,
• a Graph,
• optionally child DACs or processing views,
• a classic ASPX page,
• a site map entry,
• screen access-right metadata,
• Modern UI files if the screen must work cleanly in the Modern shell.

Example DAC

using PX.Data;
using PX.Data.BQL;
[Serializable]
[PXCacheName("Vendor Claim")]