ProcessMaker 4 Documentation

Overview

ProcessMaker is an open source, workflow management software suite, which includes tools to automate your workflow, design forms, create documents, assign roles and users, create routing rules, and map an individual process quickly and easily. It's relatively lightweight and doesn't require any kind of installation on the client computer. This file describes the requirements and installation steps for the server.

Getting Started

If you are new to ProcessMaker 4 and would like to load the software locally, we recommend you download the Dockerized version from https://github.com/ProcessMaker/pm4core-docker

System Requirements

Install

Before installing, Nginx needs to be configured to use php-fpm and point to the public folder

Download and unzip a version from the releases page https://github.com/ProcessMaker/processmaker/releases
Configure Nginx to use php-fpm and point to the public folder in the unzipped code. See https://laravel.com/docs/8.x/deployment#nginx
CD into the folder and run composer install
Run the installer php artisan processmaker:install and follow the instructions
Edit the .env file to update any server specific settings
Install javascript assets npm install
Compile javascript assets npm run dev
Configure laravel echo server in a separate shell npx laravel-echo-server init using the following settings:
Do you want to run this server in development mode? Yes
Which port would you like to serve from? 6001
Which database would you like to use to store presence channel members? redis
Enter the host of your Laravel authentication server. Enter your instance's url
Will you be serving on http or https? http
Do you want to generate a client ID/Key for HTTP API? No
Do you want to setup cross domain access to the API? No
What do you want this config to be saved as? laravel-echo-server.json
Then run laravel echo server npx laravel-echo-server start
Run horizon in a separate shell php artisan horizon
If you change any settings, make sure to run php artisan optimize:clear and restart horizon

Installing and upgrading an enterprise instance hosted on AWS

https://processmaker.atlassian.net/wiki/spaces/PM4/pages/480149598/Server+Deployment

Using ProcessMaker 4

The online documentation for usage of ProcessMaker 4 can be found by clicking the link below.

https://docs.processmaker.com/

Testing

All PRs for PM4 and it's packages should be accompanied by a test.

CI/CD

Put ci: tags anywhere in the pull request body. Separate tags with whitespace; one tag per line is the easiest. Editing the PR body re-runs CI.

Automated Tests

Opening or updating a PR builds an image with enterprise packages installed and runs the PHPUnit suite. Tests run whether or not you deploy an instance.

Package and Core Branches

Point CI at a branch of another package, or of core, with:

ci:<package>:<branch>

For example, a core PR that needs a connector-send-email branch:

ci:connector-send-email:bugfix/FOUR-5059

From a package PR, pin core the same way:

ci:processmaker:my-branch-in-core

The repository that owns the PR always builds from that PR's head branch.

When many packages share one branch name, set a wildcard. Each package that has the branch uses it. Packages that do not have it fall back to the release branch:

ci:*:epic/FOUR-12345

An explicit ci:<package>:<branch> tag wins over the wildcard.

@processmaker JavaScript dependencies are built from the same branch rules. Name one to build a feature branch, for example ci:modeler:my-branch. Packages with their own bundle step are modeler, screen-builder, vue-form-elements, and vue-multiselect. processmaker-bpmn-moddle is linked into modeler when its branch is set.

A ci:<package>:<branch> tag for a normal processmaker/* dependency that is not in the enterprise list still installs that package.

Branch selection order:

ci:<package>:<branch>
ci:*:<branch>, when that branch exists on the package
The release branch (develop)

Package Source

PHP packages and script executors are installed from private Packagist as dev-<branch>.

ci:use-github-branches clones those branches from GitHub instead.

ci:use-packagist-versions keeps the versions already pinned in core composer.json. When both source tags are present, this one is used.

CI Server

ci:deploy builds a full instance and comments the URL on the PR when it is ready. The Helm install allows up to 75 minutes.

The hostname comes from the repository and branch:

Multitenancy, the default: https://tenant-1.ci-<id>.engk8s.processmaker.net
ci:single-tenant: https://ci-<id>.engk8s.processmaker.net

The instance is removed when the PR is closed. ci:redeploy deletes the current instance, builds, and deploys a new one. CI then removes ci:redeploy from the PR body so later edits leave the new instance in place. The Harbor image is kept across a redeploy and deleted when the PR is closed.

ci:skip-redeploy skips the Helm install or upgrade. The workflow still comments the instance URL. Use it when an instance already exists and should stay as it is.

ci:skip-build skips the Docker image build and push. Later jobs use the image already stored for this PR.

ci:db:clean wipes and re-seeds the database every time the instance starts. Remove the tag when data should persist. Leaving it in the body wipes the database on later updates and pod restarts.

ci:no-octane serves the instance with PHP-FPM. Octane (FrankenPHP) is the default.

ci:pmai_dev points the instance at the dev PMAI service.

ci:api-test runs the API test suite after a successful deploy and comments the results. It requires ci:deploy or ci:redeploy. With no extra tags, every suite runs. Limit the run with one or more of:

ci:api-test-saved-searches-results
ci:api-test-saved-searches-charts
ci:api-test-tasks-closed
ci:api-test-requests-show
ci:api-test-cases-started
ci:api-test-cases-participated

ci:api-test-iterations:<n> sets the iteration count. The default is 5.

ci:run-testbench runs testbench against the deployed instance after a successful deploy. It also requires ci:deploy or ci:redeploy.

Environment Variables

Add or overwrite environment variables on the deployed server from the PR body:

ci:MY_ENVIRONMENT_VARIABLE=value

Use double quotes when the value has spaces:

ci:MY_ENVIRONMENT_VARIABLE="custom value"

Specify the K8S Distribution Branch

The CI builder uses pm4-k8s-distribution to build and deploy the PR. That checkout uses the release branch described above.

To test a different k8s distribution branch:

ci:k8s-branch:some-other-branch

PHPUnit Tests

We use PHPUnit for both integration and unit testing. Most of our PHPUnit tests are integration tests that use the framework and database.

Run the entire testsuite with phpunit

If phpunit is not in your $PATH, you can use vendor/bin/phpunit ...

To run the entire suite faster using parallel tests, run

PARALLEL_TEST_PROCESSES=6 vendor/bin/paratest -p 6

The environment variable and the -p argument must be the same number of parallel processes.

To run an individual test, run

phpunit tests/path/to/testTest.php

Running phpunit will populate a test database first, which is slow. After the first run, you can skip populating the database with POPULATE_DATABASE=0 phpunit ... to run tests much faster.
All test file names must end in Test.php

Package tests should be saved in the package repository but must be run from processmaker core:

phpunit vendor/processmaker/package-name/tests/...

It is considered a best practice to write a failing test first. Then, modify the code until the test passes

Development

System Requirements

You can develop ProcessMaker as well as ProcessMaker packages locally. In order to do so, you must have the following:

Virtualbox 5.2 or above
Vagrant 2.2.0 or above
PHP 8.1 or above
- Windows users can install XAMPP
Composer 2
Node.js 16.18.1 or above

Steps for Development Installation

Clone the repository into a directory
Perform composer install to install required libraries. If you are on windows, you may need to run composer install --ignore-platform-reqs due to Horizon requiring the pcntl extension. You can safely ignore this as the application runs in the virtual machine which has the appropriate extensions installed.
Perform npm install in the project directory
Perform npm run dev to build the front-end assets
Modify your local /etc/hosts add 192.168.10.10 processmaker.local.processmaker.com. On Windows, this file is located at C:\Windows\System32\Drivers\etc\hosts.
- If you need to change the ip address to something else to avoid conflicts on your network, modify the Homestead.yaml file accordingly. Do not commit this change to the repository.
Execute vagrant up in the project directory to bring up the laravel homestead virtual machine
Execute vagrant ssh to ssh into the newly created virtual machine
Execute php artisan processmaker:install in /home/vagrant/processmaker to start the ProcessMaker Installation
- Specify localhost as your local database server
- Specify 3306 as your local database port
- Specify processmaker as your local database name
- Specify homestead as your local database username
- Specify secret as your local database password
- Specify https://processmaker.local.processmaker.com as your application url
Check your .env file to ensure the PROCESSMAKER_SCRIPTS_DOCKER variable has the right Docker installation path, especially if you are under macOS (Docker on macOS installs under /usr/local/bin/docker).
Visit https://processmaker.local.processmaker.com in your browser to access the application
- Login with the username of admin and password of admin

When developing, make sure to turn on debugging in your .env so you can see the actual error instead of the Whoops page.

APP_DEBUG=TRUE

Optionally, trust the self-signed certificate on your host machine so you don't get the "Not Secure" warnings in chrome and postman.

For macOS:

In your-repository-root/storage/ssl, double-click on processmaker.local.processmaker.com.crt
Click on "Add" to add it to your login keychain
In the Keychain Access window click on the Certificates category on the bottom left.
Double-click on the processmaker certificate
Open the Trust section. For "When using this certificate", select "always trust"
Close the window. You will be asked for your password. Close and reopen the processmaker tab in chrome.

If you choose not to install the certificate, you should access the socket.io js file in your browser to allow unsafe connections from it. Otherwise, real-time notifications may not work in your development environment.

https://processmaker.local.processmaker.com:6001/socket.io/socket.io.js

Customize Logos

Add images to resources/img/
Add The following variables to the .env file

MAIN_LOGO_PATH={{EXPANDED LOGO PATH HERE}}
ICON_PATH_PATH={{ICON LOGO PATH HERE}}
LOGIN_LOGO_PATH={{LOGIN PAGE LOGO PATH HERE}}

Run npm run dev

Scheduled tasks/events

To run time based BPMN events like Timer Start Events or Intermediate Timer Events, the laravel scheduler should be enabled. To do this open a console and:

Execute crontab -e
Add to the cron tab the following line replacing the upper cased text with the directory where your proyecto is located :

* * * * * cd YOUR_BPM_PROJECT && php artisan schedule:run >> /dev/null 2>&1

API

The ProcessMaker API is documented using OpenAPI 3.0 documentation and can be viewed at /api/documentation. The documention is generated by adding annotations to Models and Controllers.

You should add annotations to all models and controllers that you create or modify because it's how we generate the SDKs that are used when running scripts.

When developing, make sure to add this to your .env file so that any changes you make to the annotations are automatically turned into documentation when you reload the /api/documentation page:

L5_SWAGGER_GENERATE_ALWAYS=TRUE

At the comment block at the top of the model, add an @OA annotation to describe the schema. See ProcessMaker/Models/Process.php for an example.

To keep things dry, you can define 2 schemas. One that inherits the other.

/**
 * ...existing comments above...
 *
 * @OA\Schema(
 *   schema="ProcessEditable",
 *   @OA\Property(property="process_category_uuid", type="string", format="uuid"),
 *   @OA\Property(property="name", type="string"),
 *   @OA\Property(property="description", type="string"),
 *   @OA\Property(property="status", type="string", enum={"ACTIVE", "INACTIVE"}),
 * ),
 * @OA\Schema(
 *   schema="Process",
 *   allOf={
 *       @OA\Schema(ref="#/components/schemas/ProcessEditable")
 *       @OA\Schema(
 *           type="object",
 *           @OA\Property(property="user_uuid", type="string", format="uuid"),
 *           @OA\Property(property="uuid", type="string", format="uuid"),
 *           @OA\Property(property="created_at", type="string", format="date-time"),
 *           @OA\Property(property="updated_at", type="string", format="date-time"),
 *       ),
 *   },
 *
 * )
 */
class Process extends ProcessMakerModel implements HasMedia
{
...

Now you can use the reference to the schema when annotating the controllers. See ProcessMaker/Http/Controllers/Api/ProcessController.php for an example.

    /**
     * @OA\Get(
     *     path="/processes",
     *     summary="Returns all processes that the user has access to",
     *     operationId="getProcesses",
     *     tags={"Process"},
     *     @OA\Parameter(ref="#/components/parameters/filter"),
     *     @OA\Parameter(ref="#/components/parameters/order_by"),
     *     @OA\Parameter(ref="#/components/parameters/order_direction"),
     *     @OA\Parameter(ref="#/components/parameters/per_page"),
     *     @OA\Parameter(ref="#/components/parameters/"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="list of processes",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                 property="data",
     *                 type="array",
     *                 @OA\Items(ref="#/components/schemas/Process"),
     *             ),
     *             @OA\Property(
     *                 property="meta",
     *                 type="object",
     *                 allOf={@OA\Schema(ref="#/components/schemas/metadata")},
     *             ),
     *         ),
     *     ),
     * )
     */
    public function index(Request $request)
    {
    ...

And for a show method

    /**
     * @OA\Get(
     *     path="/processes/{processUuid}",
     *     summary="Get single process by ID",
     *     operationId="getProcessByUuid",
     *     tags={"Process"},
     *     @OA\Parameter(
     *         description="ID of process to return",
     *         in="path",
     *         name="processUuid",
     *         required=true,
     *         @OA\Schema(
     *           type="string",
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="Successfully found the process",
     *         @OA\JsonContent(ref="#/components/schemas/Process")
     *     ),
     */
    public function show(Request $request, Process $process)
    {
    ...

NAYRA

Please add/change the next configuration in .env file to define the message broker driver that is used for Nayra

Message broker driver, possible values: rabbitmq, kafka, this is optional, if not exists or is empty, the Nayra will be work as normally with local execution

MESSAGE_BROKER_DRIVER=rabbitmq

Rabbit MQ connection, only when you use RabbitMQ

RABBITMQ_HOST=127.0.0.1 RABBITMQ_PORT=30672 RABBITMQ_LOGIN=guest RABBITMQ_PASSWORD=guest

Kafka connection, only when you use Kafka

KAFKA_BROKERS=127.0.0.1:30092

Notes

operationId will be the method name of the generated code. It can be anything camel cased but should be named some intuitive.

Testing with Swagger UI

Reload the swagger UI at api/documentation page in your browser to see the results and debug any errors with the annotations.

By default, Swagger UI will use your processmaker app auth. So as long as you're logged into the app you should be able to run API Commands from Swagger UI as your logged in user.

You can also create a personal access token to see the API results as a specific user would.

$user->createToken('Name it here')->accessToken;

Copy the token. In api/documentation, click on the Authenticate button on the top right and enter it in the pm_api_bearer value field.

More Info

Detailed examples can be found at https://github.com/zircote/swagger-php/tree/master/Examples/petstore.swagger.io

Full OpenAPI 3.0 specification at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

Testing with Laravel Dusk

When testing in Laravel Dusk, make sure to turn off debugging mode in your .env so you can use the whole page and screens executing functional tests. Then, change appenv value to develop in the same file:

APP_DEBUG=FALSE
APP_ENV=develop

Execute vagrant ssh to ssh into the newly created virtual machine.

Execute php artisan dusk in /home/vagrant/processmaker to execute Laravel dusk test cases.

Execute php artisan dusk:make newTest to generate a new Dusk test. The generated test will be placed in the tests/Browser directory.

More Info

Detailed installation can be found at https://laravel.com/docs/6.x/dusk#installation

To interact with web elements https://laravel.com/docs/6.x/dusk#interacting-with-elements

List of available assertions https://laravel.com/docs/6.x/dusk#available-assertions

ICONS

Please follow the steps:

Execute the command in root processmaker

npm install

Add the new svg icon file in the /processmaker/resources/devhub/pm-font/svg

/processmaker/resources/devhub/pm-font/svg/my-new-icon.svg

3.Run the follow command

npm run font

4.Run the follow command

npm run dev

5.To use your new icon, in any template or component, add the icon as follows:

<i class="fp-my-new-icon" />

RECOMMENDATIONS ABOUT ICONS

We recommend using the file name with '-' for example:

"left-arrow.svg"

To use the icon, we should use the same name of the file, for example:

File name: "my-jonas-custom-icon.svg"
How to use icon: <i class="fp-my-jonas-custom-icon" />

To check all the icons

npm run dev-font

Case Retention Tier (CASE_RETENTION_TIER)

The case retention policy controls how long cases are stored before they are automatically and permanently deleted. The CASE_RETENTION_TIER environment variable determines which retention periods customers can select when configuring a process. Each tier exposes a different set of options in the UI; options for higher tiers are visible but disabled so users see what is available at higher tiers.

Supported tiers

Tier	Retention options available
1	Six months, One year
2	Six months, One year, Three years
3	Six months, One year, Three years, Five years

Set the variable in your .env file:

CASE_RETENTION_POLICY_ENABLED=true
CASE_RETENTION_TIER=1

Use 1, 2, or 3. The default is 1 if not set. The default retention period shown in the UI for Tier 1 is one year.

Prometheus and Grafana

This guide explains how to install and run Prometheus and Grafana using Docker. Both tools complement each other: Prometheus collects and monitors metrics, while Grafana visualizes them with interactive dashboards.

Local Development with docker compose

Prometheus & Grafana

Go to the metrics directory

cd metrics

Make sure the ports 9090 and 3000 on the host are not already in use.

Edit prometheus.yml and update the target hostname with your local processmaker instance. You might also need to change the scheme if you are using https.

Run docker compose up -d

Check that prometheus can connect to your local instance at http://localhost:9090/targets

Go to Grafana at http://localhost:3000/

When you are finished, run docker compose down. To delete all data, run docker compose down -v

Use the Facade in Your Application

Now you can use the Metrics Facade anywhere in your application to manage metrics.

1. Counter

A Counter only increases over time or resets to zero. It is used for cumulative events.

Total number of HTTP requests:

$counter = Metrics::counter('http_requests_total', 'Total HTTP requests', ['method', 'status']);
$counter->inc(['GET', '200']);
$counter->incBy(2, ['GET', '200']);

Number of system errors (e.g., HTTP 5xx).

2. Gauge

A Gauge can increase or decrease. It is used for values that fluctuate over time.

Current number of active jobs in a queue:

$gauge = Metrics::gauge('active_jobs', 'Number of active jobs', ['queue']);
$gauge->set(10, ['queue1']);

Memory or CPU usage.

3. Histogram

A Histogram measures value distributions by organizing them into buckets. It is ideal for latency or size measurements.

Duration of HTTP requests:

$histogram = Metrics::histogram('http_request_duration_seconds', 'HTTP request duration', ['method'], [0.1, 0.5, 1, 5, 10]);
$histogram->observe(0.3, ['GET']);

File sizes or request durations.

Each type serves a specific role depending on the data being monitored.

Example: Incrementing a Counter

In a controller:

namespace App\Http\Controllers;

use ProcessMaker\Facades\Metrics;

class ExampleController extends Controller
{
    public function index()
    {
        //use metrics counter
        $counter = Metrics::counter('http_requests_total', 'Total HTTP requests', ['method', 'status']);
        $counter->inc(['GET', '200']); // Incrementa el contador para GET y estado 200.

        return response()->json(['message' => 'Hello, world!']);
    }
}

To make things even easier, you can run Metrics::counter('cases')->inc(); or Metrics::gauge('active_tasks')->set($activeTasks) anywhere in the code.

You can provide an optional description, for example Metrics::gauge('active_tasks', 'Total Active Tasks')->...

Import Grafana Dashboards

Go to Grafana and import the dashboards from the resources/grafana folder. Each JSON file represents a configured dashboard that can be imported into Grafana to visualize metrics and data.

Multitenancy

ProcessMaker can now be set up as a multitenant application.

Requirements

Create an empty datbase named landlord. Your DB_USERNAME should have permission to write to this table.

Transition your dev instnace to multitenancy

Run the following command to enable multitenancy

php artisan tenants:enable --migrate

This command will

Setup the landlord database. Make sure you create the empty landlord database first.
Set your existing database as the tenant database
Copy your existing storage folder to storage/tenant_1
Copy your existing resources/lang folder to resources/lang/tenant_1
Enable multitenancy in your .env

Using `valet share` for the script microservice

In the landlord tenant's table you will need to set the domain to the ngroc domain (without https://) and, in the config, column you will need to set the app.url to the ngroc domain (including the https://)

Add another tenant

For local development, you will need add another domain to your nginx config. To do this with Valet, run:

valet link another-tenant.test

Run the following command to create another tenant:

php artisan tenants:create --domain="another-tenant.test" --name="Another Tenant" --database="another_tenant"

This command will

Create the required folder structure
Create the tenant database

You will need to run migrations, seeders, and package installers with the environment variable prefix TENANT={id}

`tenants:transition` command

Move multiple instnaces in bulk to a single multitenancy instance.

If this is your local development environment, it's easier to use tenants:enable --migrate above.

Create a folder storage/transitions if it doesn't exist.

For each instance you want to transition into this multitenancy instance, copy the .env file into the transitions folder and add the instnace name to the file name. For example .env.my-instance

Run the following command to migrate the instance(s) to a tenant:

php artisan tenants:transition

This command will create a new tenant for each .env file in the storage/transitions folder.

You must move the tenants storage folder and the resources/lang folder manually

License

Distributed under the AGPL Version 3

ProcessMaker C 2002 - 2020 ProcessMaker Inc.

For further information visit: http://www.processmaker.com/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

ProcessMaker 4 Documentation

Overview

Getting Started

System Requirements

Install

Installing and upgrading an enterprise instance hosted on AWS

Using ProcessMaker 4

Testing

CI/CD

Automated Tests

Package and Core Branches

Package Source

CI Server

Environment Variables

Specify the K8S Distribution Branch

PHPUnit Tests

Development

System Requirements

Customize Logos

Scheduled tasks/events

API

NAYRA

Message broker driver, possible values: rabbitmq, kafka, this is optional, if not exists or is empty, the Nayra will be work as normally with local execution

Rabbit MQ connection, only when you use RabbitMQ

Kafka connection, only when you use Kafka

ICONS

RECOMMENDATIONS ABOUT ICONS

Case Retention Tier (CASE_RETENTION_TIER)

Supported tiers

Prometheus and Grafana

Local Development with docker compose

Prometheus & Grafana

Use the Facade in Your Application

1. Counter

2. Gauge

3. Histogram

Example: Incrementing a Counter

Import Grafana Dashboards

Multitenancy

Requirements

Transition your dev instnace to multitenancy

Using valet share for the script microservice

Add another tenant

tenants:transition command

License

Using `valet share` for the script microservice

`tenants:transition` command