Please rate how useful you found this document: 
Average: 2.5 (2 votes)


Usually, when cases are created, all files/folders are stored at:


The storage capacity when generated/uploaded files are saved on the server is limited. This limitation is due to the type of file system of the server, some of them have limitations in the number of folders/files that can be stored in the same directory. The maximum number of subdirectories that can be contained in a single directory is:

  • Ext3 : 31,998
  • Ext4 : 63,998 (unlimited with: tune2fs -O dir_nlink)
  • NTFS : 4,294,967,295

If there are more than certain number of cases and all of them have Input/Output documents inside, neither folders or upload documents can be created.

New Folder Structure

ProcessMaker stores generated/uploaded files in the following path: <INSTALL-DIRECTORY>/processmaker/shared/sites/workspace-name/files

From ProcessMaker 3 on, to avoid the folders limitation issue, a new folder structure to store generated/uploaded files has been implemented.

The new structure stores the files of a case inside a structure of 4 sub-folders. For example, if the case's ID is "623504638574f33f152fd03055534796", when a file is uploaded/generated, a new structure of 4 sub-folders will be created with the case's ID split in 4 parts:

The main folder is split into 4 sub-folders:

  • First Folder: 623
  • Second Folder: 504
  • Third Folder: 638
  • Fourth Folder: 574f33f152fd03055534796

The wf_<workspace>.CONFIGURATION table

To check if a workspace is working under the new folder structure or not, a flag is added inside wf_<workspace>.CONFIGURATION table.

Go to the ProcessMaker database and look for the wf_<workspace>.CONFIGURATION table. The flag is stored in a field named ENVIRONMENT_SETTINGS.

When the structure is applied, directoryStructure will have a value of 2, otherwise it will have a value of 1. From ProcessMaker 3 on, the value of the flag is 2 by default.

Migrating case folders

To increase storage capacity, ProcessMaker has included a new command that helps to migrate the old folder structure into a new one, which will support the creation of more than 32,000 cases or 64,000 cases. This command only works in new installations because of compatibility with previous versions.

This command will distribute folders migrating the old structure where a folder was created per each case to a structure where that folder is divided into subfolders.


./processmaker migrate-cases-folders <workspace-name>


PHP-DIRECTORY\php.exe -f processmaker  migrate-cases-folders <workspace-name>

Replace <workspace-name> with the name of the selected workspace where the new structure will be created. If the workspace is avoided, the new structure will be applied to all available workspaces.

If the new structure has been applied to all the workspaces, any new workspace created will inherit the new structure by default.

To distinguish this, a flag is created in the wf_<workspace>.CONFIGURATION table that indicates which workspace is using this structure.

For example:

The structure when folders containing files of cases are created is the following:

There are two folders which belong to 2 different cases, the migration will be applied to the folder of the case "1638452215220c6f9d97f56037542450".

Open a terminal and go to the path where ProcessMaker is installed:


cd /opt/processmaker


cd INSTALL-DIRECTORY\processmaker

Then, run the following command:


./processmaker migrate-cases-folders workflow


PHP-DIRECTORY\php.exe -f processmaker  migrate-cases-folders workflow

The new structure will be applied to the folder of the case "1638452215220c6f9d97f56037542450" dividing it in a the following sub-folders as shown in the image below:

The main folder is split into 4 sub-folders:

  • First Folder: 163
  • Second Folder: 845
  • Third Folder: 221
  • Fourth Folder: 5220c6f9d97f56037542450

The new structure will be in the following path: <INSTALL-DIRECTORY>/processmaker/shared/sites/workflow/files

Accessing documents by using the new file structure

Once the migration is finished, path were files are located (Input Documents and Output Documents)will change, so it is necessary to change the path in order to redirect files to the new structure.

Use the following function in order to change the documents' path to be used with the new structure.

$g = new G();

That can be used inside a trigger or a plugin.

According with the structure applied, it will return the complete ID: 58090836853b71d23e8e253013331630 or 580/908/368/53b/71d/23e/8e2/530/133/316/30. Internally the function will automatically change every path. However if triggers or plugins were creating in order to obtain a path they have to be changed manually, otherwise they will stop working.

For instance, taking the following example in which the path is created in order to attach files using the old structure:

$aAttachFiles[$inDoc['FILENAME']] = PATH_DOCUMENT . $caseId . PATH_SEP . $inDoc['APP_DOC_UID'] . '_' .
         $inDoc['DOC_VERSION'] . '.' . pathinfo($inDoc['FILENAME'], PATHINFO_EXTENSION);

With the new structure change it to:

$g = new G();
$aAttachFiles[$inDoc['FILENAME']] = PATH_DOCUMENT . $g->getPathFromUID($caseId) . PATH_SEP . $inDoc['APP_DOC_UID'] . '_' .
         $inDoc['DOC_VERSION'] . '.' . pathinfo($inDoc['FILENAME'], PATHINFO_EXTENSION);