Acumatica Customization Management

Manage Acumatica ERP customization projects via the CustomizationApi web API. Use this skill whenever the user wants to export, import, publish, validate, un...

Security Scan

The skill is internally consistent with its stated purpose: it is a bash helper that calls an Acumatica instance (CustomizationApi) and requires local credentials in a config file; nothing in the files suggests hidden endpoints or unrelated credential access.

Purpose & Capability

The name, description, SKILL.md, README, and acumaticahelper.sh all align: the script calls only Acumatica API endpoints (derived from the official CustomizationApi docs) and exposes commands for list, export, import, validate, publish, unpublish, delete, status, and maintenance. No unrelated services, binaries, or credentials are requested.

Instruction Scope

Most runtime instructions stay on-task (they read a local acumatica.conf, perform authenticated requests against ACUMATICA_URL, write exported ZIPs locally, and clean up a session cookie). Minor inconsistency: README/SKILL.md say optional tuning can be provided via exported env vars, but the script immediately errors if acumatica.conf is missing — so in practice the helper requires the config file to exist in the script directory. Otherwise, instructions are explicit and do not instruct the agent to access unrelated files or external endpoints.

Install Mechanism

No install spec and no downloads — this is an instruction-only skill with a single helper script. That is the lowest-risk install model.

Credentials

The skill requires Acumatica credentials (username/password) and an ACUMATICA_URL, but these are supplied via a local acumatica.conf file rather than declared environment variables in the registry metadata. Requiring plaintext credentials for an API client is proportionate, but the registry metadata lists no required env/config points while the script actually requires the config file to exist. Also, the README warns about plaintext credentials; store the file securely and .gitignore it.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system-wide privileges. It writes a temporary cookie file in /tmp during a session and exported ZIPs to the user's chosen output directory; it does not modify other skills or system config.

Assessment

This skill is coherent with its stated purpose, but review these before installing: 1) The helper requires a local acumatica.conf in the script directory containing ACUMATICA_URL, ACUMATICA_USERNAME, and ACUMATICA_PASSWORD — the registry metadata does not declare these, so the config file is mandatory. 2) acumatica.conf contains plaintext credentials; add it to .gitignore, set restrictive permissions (chmod 600), and prefer a least-privilege Acumatica account (Customizer role as suggested). 3) Verify ACUMATICA_URL points to a trusted instance — the script only talks to that host. 4) You can inspect the included acumaticahelper.sh (which is provided) and run it in a controlled environment; the skill does not perform unexpected network calls or exfiltration. 5) If you require env-var-based configuration or stricter secrets handling, consider adapting the script (or wrapping it) so you don't keep credentials in plaintext files.

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

Variable	Default	Description
PUBLISH_POLL_INTERVAL	30	Seconds between publishEnd polls
PUBLISH_MAX_ATTEMPTS	10	Max 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.

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

Endpoint	Method	Used by
/entity/auth/login	POST	all commands
/entity/auth/logout	POST	all commands
/CustomizationApi/getPublished	POST	list
/CustomizationApi/getProject	POST	export
/CustomizationApi/import	POST	import
/CustomizationApi/publishBegin	POST	validate, publish
/CustomizationApi/publishEnd	POST	validate, publish, status
/CustomizationApi/unpublishAll	POST	unpublish
/CustomizationApi/delete	POST	delete
/entity/Lock/1/ApplyUpdate/scheduleLockoutCommand	PUT	maintenance-on
/entity/Lock/1/ApplyUpdate/stopLockoutCommand	PUT	maintenance-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:

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