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:

ini

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):

VariableDefaultDescriptionPUBLISH_POLL_INTERVAL``30Seconds between publishEnd pollsPUBLISH_MAX_ATTEMPTS``10Max polls before timeout (10 × 30s = 5 min max)

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.

bash

./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.

bash

./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.

bash

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

API: POST /CustomizationApi/import

---

validate#

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

bash

./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.

bash

./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.

bash

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

API: POST /CustomizationApi/unpublishAll

---

delete#

Delete an unpublished project from the database.

bash

./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.

bash

./acumaticahelper.sh status

API: POST /CustomizationApi/publishEnd

---

maintenance-on / maintenance-off#

Enable or disable maintenance mode (Lock endpoint V1).

bash

./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#

EndpointMethodUsed by/entity/auth/loginPOSTall commands/entity/auth/logoutPOSTall commands/CustomizationApi/getPublishedPOSTlist``/CustomizationApi/getProjectPOSTexport``/CustomizationApi/importPOSTimport``/CustomizationApi/publishBeginPOSTvalidate, publish``/CustomizationApi/publishEndPOSTvalidate, publish, status``/CustomizationApi/unpublishAllPOSTunpublish``/CustomizationApi/deletePOSTdelete``/entity/Lock/1/ApplyUpdate/scheduleLockoutCommandPUTmaintenance-on``/entity/Lock/1/ApplyUpdate/stopLockoutCommandPUTmaintenance-off

---

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:

bash

./acumaticahelper.sh export MyProject ./backups

Promote from dev to prod:

bash

# 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:

bash

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

Clean slate — unpublish everything then delete:

bash

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