Acumatica Customization Helper

A bash script (acumaticahelper.sh) that manages Acumatica ERP customization projects through the official CustomizationApi web API.

Script location: acumaticahelper.sh (run from its own directory)

Configuration

The script reads acumatica.conf from the same directory as the script. Copy acumatica.conf.example to acumatica.conf and fill in your values:

ACUMATICA_URL=http://host/instance    # base URL — no trailing slash
ACUMATICA_USERNAME=admin              # must have the Customizer role
ACUMATICA_PASSWORD=secret

Optional tuning (add to acumatica.conf or export as env vars):

Note: OAuth 2.0 is NOT supported by the CustomizationApi. Cookie-based session auth is used (/entity/auth/login / /entity/auth/logout).

Commands

list

List all published customization projects and their items.

./acumaticahelper.sh list

API: POST /CustomizationApi/getPublished

export

Export a project as a local ZIP file. Validates the zip before saving and auto-resolves file system conflicts.

./acumaticahelper.sh export <project-name> [output-dir]
# output-dir defaults to current directory

API: POST /CustomizationApi/getProject

import

Import a ZIP file as a customization project. Derives project name from the filename if not specified. Replaces an existing project of the same name.

./acumaticahelper.sh import <file.zip> [project-name] [description]

API: POST /CustomizationApi/import

validate

Validate one or more projects without publishing them. Polls until complete.

./acumaticahelper.sh validate <project-name> [project-name2 ...]

API: POST /CustomizationApi/publishBegin (with isOnlyValidation: true) then polls POST /CustomizationApi/publishEnd

publish

Publish one or more projects. Polls until complete.

./acumaticahelper.sh publish <project-name> [project-name2 ...]

Important: publishEnd must be called to complete publication — it triggers plug-in execution. The script handles this automatically.

API: POST /CustomizationApi/publishBegin → polls POST /CustomizationApi/publishEnd

unpublish

Unpublish all projects. tenantMode controls scope.

./acumaticahelper.sh unpublish [Current|All]
# defaults to Current

API: POST /CustomizationApi/unpublishAll

delete

Delete an unpublished project from the database.

./acumaticahelper.sh delete <project-name>

Warning: The project must be unpublished first. Deletion removes project and item data but does NOT remove files/objects added to the site (e.g. site map nodes, reports).

API: POST /CustomizationApi/delete

status

One-shot poll of publishEnd to check the current publish/validation state.

./acumaticahelper.sh status

API: POST /CustomizationApi/publishEnd

maintenance-on / maintenance-off

Enable or disable maintenance mode (Lock endpoint V1).

./acumaticahelper.sh maintenance-on
./acumaticahelper.sh maintenance-off

API: PUT /entity/Lock/1/ApplyUpdate/scheduleLockoutCommand (on) PUT /entity/Lock/1/ApplyUpdate/stopLockoutCommand (off)

API Endpoints Reference

Requirements

• bash 4+
• curl — HTTP requests
• jq — JSON building and parsing
• base64 — encode/decode project ZIPs
• python3 — ZIP validation on export (import zipfile)

Common Workflows

Backup before an upgrade:

./acumaticahelper.sh export MyProject ./backups

Promote from dev to prod:

# On dev — export
./acumaticahelper.sh export MyProject ./release

# On prod — import then publish
./acumaticahelper.sh import ./release/MyProject.zip
./acumaticahelper.sh publish MyProject

Safe publish with maintenance window:

./acumaticahelper.sh maintenance-on
./acumaticahelper.sh publish MyProject
./acumaticahelper.sh maintenance-off

Clean slate — unpublish everything then delete:

./acumaticahelper.sh unpublish Current
./acumaticahelper.sh delete MyProject