Tutorial on how to develop and debug PHP scripts in Processmaker tasks

Question

I am trying to develop a workflow in Processmaker 4 community that require some scripted tasks to be executed but I am facing in issues in things that should be simple such as:

1. How to debug the code in Processmaker scripts. Is there access to stdout and sterr somehow?
2. How to access request variables form the PHP script.
3. How to access the files that have been uploaded to a process from the PHP script.

Does anyone know of a good resource explaining in detail how to create PHP scripts in Processmaker?

So far I have found the following documentation https://github.com/ProcessMaker/docker-executor-php/tree/develop/docs/sdk which certainly seems to open the door on how to access files and Processmaker information but I am still struggling trying to find a way to properly debug fairly complex scripts.

Answer 1

You can debug your script using the Script Editor (at /designer/scripts edit your script) by inserting echo statements at within the code. These statements will be displayed in the "Output" panel, helping you track the script's progress and identify any issues. Additionally, you can access request variables using the $data variable. For testing purposes, you can enter sample values in the "Sample Input" panel and observe how the script handles them.

Please consider that writing to STDOUT in a script task will result in a runtime exception, since it is not permitted. The use of STDOUT is intended solely for debugging purposes. Exercise caution while employing it to avoid unexpected errors during script execution.

The following is an simple example:

<?php
// Adding two numbers with debugging code

// Define two numbers to add
$num1 = $data['num1'];
$num2 = $data['num2'];

// Debug code to display the initial numbers
echo "Initial numbers: ";
echo "Number 1: " . $num1 . " ";
echo "Number 2: " . $num2 . "  ";

// Function to add two numbers and return the result
function addNumbers($a, $b) {
    $sum = $a + $b;

    // Debug code to display the sum of the numbers
    echo "Inside the function: ";
    echo "Sum: " . $sum . "  ";

    return $sum;
}

// Call the function and store the result
$result = addNumbers($num1, $num2);

// Debug code to display the final result
echo "Final result: ";
echo "Sum of " . $num1 . " and " . $num2 . " is: " . $result . " ";

return [
    'result' => $result,
];

For this Sample Input:

Will return the following output:

Answer 2

There is a bug in the code to return data for a specific process request. See comments below. This code will return the value of request variables for in-flight requests.

<?php 
// Get Process Request data
/*  
 *  Welcome to ProcessMaker 4 Script Editor 
 *  To access Environment Variables use getenv("ENV_VAR_NAME") 
 *  To access Request Data use $data 
 *  To access Configuration Data use $config 
 *  To preview your script, click the Run button using the provided input and config data 
 *  Return an array and it will be merged with the processes data 
 *  Example API to retrieve user email by their ID $api->users()->getUserById(1)['email'] 
 *  API Documentation https://github.com/ProcessMaker/docker-executor-php/tree/master/docs/sdk 
 */


$apiInstance = $api->processRequests();

$processRequestId = 39;
$processRequest = $apiInstance->getProcessRequestById($processRequestId);

$result = [
    'status' => $processRequest->getStatus(),
    'processId' => $processRequest->getProcessId()
];

// Include data, participants, and user that started the request
// $include = 'data,participants,user';
// NOTE: user is a bad parameter
// Code from here is wrong...https://github.com/ProcessMaker/docker-executor-php/blob/develop/docs/sdk/ProcessRequests.md

$include = 'data,participants';
$result = $apiInstance->getProcessRequestById($processRequestId, $include);

$result = [
    'status' => $result->getStatus(),
    'data' => $result->getData(),
    'user' => $result->getUser()['username'],
    'participants' => array_map(function($user) {
        return $user['username'];
    }, $result->getParticipants()),
];

return ['processRequest' => $result];

Answer 3

Additionally, you access request variables using $data.

$academicPeriodIdIn = $data["academicPeriodId"]??"";
$selectedStudentIdIn = $data["selectedId"]??"";