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

• Composer 2
• Node.js 16.18.1
• NPM 8.9
• PHP 8.1
• PHP-FPM
• PHP GD Extension
• PHP ImageMagick Extension
• PHP IMAP Extension
• Nginx
• MySql 8.0
• Redis
• Docker

Install

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

1. Download and unzip a version from the releases page https://github.com/ProcessMaker/processmaker/releases
2. 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
3. CD into the folder and run composer install
4. Run the installer php artisan processmaker:install and follow the instructions
5. Edit the .env file to update any server specific settings
6. Install javascript assets npm install
7. Compile javascript assets npm run dev
8. Configure laravel echo server in a separate shell npx laravel-echo-server init using the following settings:
   1. Do you want to run this server in development mode? Yes
   2. Which port would you like to serve from? 6001
   3. Which database would you like to use to store presence channel members? redis
   4. Enter the host of your Laravel authentication server. Enter your instance's url
   5. Will you be serving on http or https? http
   6. Do you want to generate a client ID/Key for HTTP API? No
   7. Do you want to setup cross domain access to the API? No
   8. What do you want this config to be saved as? laravel-echo-server.json
9. Then run laravel echo server npx laravel-echo-server start
10. Run horizon in a separate shell php artisan horizon
11. 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

Automated Tests

When ever you open or update a PR, the test suite is run with all packages installed.

If your PR requires branches in other packges or core, you can specify the branch anywhere in the PR body with this tag:

ci:< package name >:< branch name>

For example, if you open a PR in core that requires a bugfix branch in connector-send-email, put this in your core PR body text:

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

This works in package PRs as well. To specify a branch in core, use:

ci:processmaker:my-branch-in-core

If no branches are specified in the PR body, the develop branch of each package will be used.

Release Branches and Packages

If your PR is based on a release branch (for example release-2024-fall <-- feature/123), then all packages will be installed using the corresponding base branch (release-2024-fall). No need to add additional ci: tags.

However, if your PR has an intermediate branch, for example (epic/abc <-- feature/123), where epic/abc is branched off the release-2024-fall branch, you will need to add ci:release-branch:release-2024-fall to your PR body so the CI builder knows what branch to use for packages.

CI Server

A full working instance can be built by adding the tag ci:deploy to your PR description. A link will be posted in the PR comments when it's ready. Note that this currently takes 10 to 30 minutes before the instance is ready.

The instance will stay active until the PR is merged.

You can wipe the database on the CI Server by adding the tag ci:db:clean. Remember to remove the tag from your PR description or the DB will be wiped clean every time the PR is updated.

Environment Variables

You can add or overwrite environment variables on the deployed server using this syntax in your PR body

ci:MY_ENVIRONMENT_VARIABLE=value

Or with double quotes if the value has spaces

ci:MY_ENVIRONMENT_VARIABLE="custom value"

Specify the K8S Distribution Branch

The CI Builder uses the pm4-k8s-distribution repository for building and deploying your PR branch in a CI server.

By default, the branch of pm4-k8s-distribution used for the build will be the same as the release branch (see "Release Branches and Packages" above).

If you are testing updates to pm4-k8s-distribution, you can specify a branch in your PR body with 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:

1. In your-repository-root/storage/ssl, double-click on processmaker.local.processmaker.com.crt
2. Click on "Add" to add it to your login keychain
3. In the Keychain Access window click on the Certificates category on the bottom left.
4. Double-click on the processmaker certificate
5. Open the Trust section. For "When using this certificate", select "always trust"
6. 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