Fix script execution API error when data and config are sent as JSON arrays

[sanjacornelius]

Issue & Reproduction Steps

Executing a script through the API using the documented JSON payload format can result in a server error or an invalid request being sent to the script microservice.

Example request:

{
  "data": [{}],
  "config": [{}],
  "sync": true
}

When calling POST /api/1.0/scripts/execute/{script_id} (or the script preview endpoint) with an application/json request body, Laravel automatically parses the payload, causing data and config to be returned as arrays. The controller was always calling json_decode() on these values, assuming they were JSON strings, which results in the following error:

json_decode(): Argument #1 ($json) must be of type string, array given

Additionally, the API documentation defined data and config as arrays, while the script microservice expects object-shaped payloads. Requests containing list-shaped payloads such as:

{ "data": [{}], "config": [{}] }

or

{ "data": [{"key":"value"}], "config": [{}] }

could be forwarded to the script microservice and rejected with a 422 Unprocessable Entity response.

Solution

Updated the request handling and API documentation to ensure script payloads are processed consistently regardless of request format.

Changes include:

• Updated OpenAPI annotations in ScriptController to declare data and config as objects instead of arrays, aligning the API documentation with the expected payload structure.
• Added a getRequestArray() helper to normalize script inputs for both execute() and preview().
• Added support for decoding JSON string values to maintain backward compatibility with form encoded requests.
• Added support for detecting list shaped payloads and unwrapping single-element list objects ([{}] or [{"key":"value"}]) into associative objects before forwarding them to the script microservice.
• Added validation to return an empty array for unsupported payload formats.

This ensures both JSON and form encoded requests are handled consistently, prevents json_decode() type errors, avoids script microservice 422 responses caused by list shaped payloads, and aligns the implementation with the updated API documentation.

How to Test

1. Authenticate as a user with permission to execute scripts.
2. Select a script that can be executed.
3. Send a JSON request to:
   POST /api/1.0/scripts/execute/{script_id}

with the following payload:

{
  "data": [{}],
  "config": [{}],
  "sync": true
}

4. Verify the request completes successfully and the script executes (or queues) as expected.
5. Verify no json_decode() TypeError is thrown.
6. Verify the payload is normalized correctly before being sent to the script microservice.
7. Repeat the test with a payload such as:

{
  "data": [{"key":"value"}],
  "config": [{}],
  "sync": true
}

and verify the script microservice accepts the request without returning a 422 error.
8. Review the generated OpenAPI/Swagger documentation and confirm data and config are documented as objects.

Related Tickets & Packages

• FOUR-27789

ci:deploy

Code Review Checklist

• I have pulled this code locally and tested it on my instance, along with any associated packages.
• This code adheres to ProcessMaker Coding Guidelines.
• This code includes a unit test or an E2E test that tests its functionality, or is covered by an existing test.
• This solution fixes the bug reported in the original ticket.
• This solution does not alter the expected output of a component in a way that would break existing Processes.
• This solution does not implement any breaking changes that would invalidate documentation or cause existing Processes to fail.
• This solution has been tested with enterprise packages that rely on its functionality and does not introduce bugs in those packages.
• This code does not duplicate functionality that already exists in the framework or in ProcessMaker.
• This ticket conforms to the PRD associated with this part of ProcessMaker.

[Kookster310]

QA server K8S was successfully deployed https://ci-2f81f47e90.engk8s.processmaker.net

[Kookster310]

QA server K8S was successfully deployed https://ci-2f81f47e90.engk8s.processmaker.net

[processmaker-sonarqube]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarQube

[Kookster310]

QA server K8S was successfully deployed https://ci-2f81f47e90.engk8s.processmaker.net