2.x - FTP Monitor

Release Notes | Downloadable Release Notes | Old Versions

 Plugin Version: 1.4.40

Introduction

FTP Monitor is a plugin which creates new cases by periodically checking an FTP or Shared/Local directory. For each new file in that directory, a new case is created in ProcessMaker.

How the plugin works

The FTP Monitor needs to have access to a valid FTP or Shared/Local directory. For each file uploaded to that directory, a new case will automatically be created and automatically routed to the second task in the process. That file is added as an Input Document file in the new case. For this reason, the process needs to include an initial task which will automatically be skipped by the FTP Monitor and an Input Document. The FTP Monitor checks for new files in the directory when ProcessMaker's cron.php file is executed. To ensure that FTP Monitor is regularly checking the directory, a cron job in Linux/UNIX or a Scheduled Task in Windows should be created to periodically execute ProcessMaker's cron.php file.

In addition, if an XML file is placed in the directory with the same filename as the file that initiated the case, than its XML data will be parsed and added as case variables in the new case. The passed variables can be used in fields in DynaForms, case variables in triggers, conditions and evaluation routing rules or in the variables to assign users to tasks.

Requirements

ProcessMaker Requirements

• ProcessMaker v. 2.5.X + available hotfix (2.5.2.4 - 2.5.2.5) and Enterprise Plugin v2.0.17 or higher

  or

• ProcessMaker Enterprise Edition v. 2.8.0 or higher

Browser Compatibility

Tested with the following browsers:

• Mozilla Firefox v. 33.

• Google Chrome v. 38.

• Internet Explorer v. 10.

Installation and Configuration

• Login with a user such as "admin" who has the PM_SETUPADVANCE permission in his/her role and then go to ADMIN > Plugins > Enterprise Manager. Either install the FTP Monitor plugin by clicking on Install from File and uploading the plugin file or by clicking on its Install Now button in the list of available plugins.

• After installing the plugin, make sure that the FTP Monitor plugin is  enabled.

Creating an FTP Monitor Connection

Once the plugin is enabled, go to ADMIN > Plugins and the  FTP Monitor option will be available in the sidebar. Click on it and all the available connections will be listed:

In connection list, the menu offers the following options:

• New: Create a new FTP or SHARED/LOCAL connection by clicking on  New.

• Edit: Edit a created connection, by choosing one in the list and clicking on Edit.

• Disable: Disable an existing connection, by choosing one in the list and clicking on Disable.

• Enable: Enable an existing connection, by choosing one in the list and clicking on Enable.

To create a new connection, click on  New, and define the properties of the new connection:

Select whether the Connection Type is FTP or SHARED (named LOCAL in version 1.4.23 and later). Depending on the selection, different properties will need to be defined.

In version 1.4.23 and later, there is a new interface to define an FTP monitor connection which divides the form in two sections and provides a Test connection button to check whether the connection is correct:

FTP Connection Properties

Creates cases from a specific directory in an FTP server

Basic Information FTP

- Host: The server address where the FTP server is located.

- Port: The server port for FTP. Leave blank to use the default port (21 for FTP or 22 for SSH).

- User: Enter the username if FTP server needs authentication. Otherwise, leave it blank.

- Password: The password if the FTP server needs authentication. Otherwise, leave it blank.

- Path: Specify the directory where files will be uploaded to initiate new ProcessMaker cases.

- Search Pattern: Use glob pattern matching to specify which files will be used to initiate new cases. Use * to match any number of characters (including zero), ? to match any single character, [xyz] to match one of the specified characters and \ (backslash) to escape a character so it won't be treated as a wildcard. For example, * would accept all files, *.doc would except only Word documents, *invoice* would accept any files that have the word "invoice" in the filename, and [aeiou]*.pdf would accept any PDF files that start with a vowel in the filename.

- Pass Variables in an XML file: Mark this option if variables in an XML file will be added as case variables in the new cases. See XML File Format for more information.

Process Information

• Process: Select the process (in the current workspace) in which new cases will be created.

• Task: Select the initial task where the new case will begin.

• User: Select the user who will be designated to work to the initial task in the case. Only users who are assigned to the selected initial task are available to be selected.

• Input Document: Choose the Input Document which the uploaded file will be attached to.

• Active: Select this option if the connection will be used, otherwise unselect it to deactivate the connection so the directory will not be monitored and new cases will not be created.

Shared/Local Connection Properties

(Formerly named Shared, but changed to Local in version 1.4.23 and later)

A local directory located on the server where ProcessMaker is installed (or a NAT addressable from the local directory structure) is used to initiate new ProcessMaker cases.

This option does not require authentication, but make sure that this directory can by read by Apache which is running ProcessMaker. On Linux/UNIX systems, the user running Apache (apache in Red Hat/Fedora, www-data in Debian/Ubuntu, and wwwrun (or the www group) in SuSE/OpenSUSE) should have read access to the directory.

XML File Format

To automatically create case variables in the new case, an XML file can be placed in the specified directory to initiate new cases. The XML file must have the following structure:

Where filename.ext is the filename of the file initiating the case, and field1 and field2 will become case variables in the new case, which can be used in DynaForm fields or in Trigger code. Note that variable names are case sensitive and that all values will be treated as strings and can contain spaces and new lines. If the value will be used in a ProcessMaker date field, the date should be in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format, such as 2014-12-31 or 1970-01-25 18:59:00. If the value is a number that will be used in a mathematical calculation by ProcessMaker, it should not have a thousands separator and "." (dot) should be used as the decimal point. For example, 123456 (integer) or 89797.99 (floating point number).

The XML file must have the same filename as the file which is used to initiate the new case. Otherwise, the FTP Monitor won't recognize XML file and associate its data with the right case.

For example, if starting a case with a file named clientAcmeConsulting.pdf, then its XML file should be named clientAcmeConsulting.xml. If creating a new case with the case variables "clientFirstName", "clientLastName", "address" and "contractAmount", then the following XML file could be used:

Examples Creating Cases

Using an FTP Connection

Uploading images into the Server

This first example will show how to create cases from image files uploaded to an FTP server.

Step 1 - Creating the connection: Create a FTP connection in order to specify the location where the image files will be uploaded:

Note that in this example, the FTP Monitor will only create new cases, but will not create case variables in those cases, since the the option Pass variables in an XML file was not selected.

Step 2 - Upload Images: Upload image files to the FTP directory:

Step 3 - Execute cron.php: After creating the FTP Monitor connection, configure the server to periodically execute the cron.php file.

It is a good idea to manually execute the cron.php file at least on time to make sure that new cases are being created correctly. When cron.php executes, it will report how many new files were found in the directory to initiate new cases. In the following example, six files were found to initiate new cases.

The second part of the execution details information about each case created with its corresponding case number:

In ProcessMaker six new cases were created in the Inbox:

Step 4 - Route the case: Choose a case and open it to see its image file which initiated the case was attached as an Input Document file:

Using an XML file and conditional routing

The following example will show how to start a case from a file and a corresponding XML file, which passes variables to the case to automatically fill fields in a DynaForm. One of the passed variables named "billToCountry" is used in a conditional routing rule to route the case to the second task in the process.

Step 1 - Create a process with a conditional routing rule: Create a process whose first task is named Dummy Task, since this task will automatically be executed by the FTP Monitor and route onto the next task using a evaluation routing rule. This routing rule will choose between 3 possible tasks, which terminate the process.

The evaluation routing rule will select whether to go to the "USA", "Canada" or "Unrecognized Country" tasks, based upon the value in the @@billToCountry case variable, which comes from the XML file.

Step 2 - Create DynaForm: Create the following DynaForm which contains the fields which are filled from data in the XML file.

Set this DynaForm as a step in the second tasks "USA", "Canada" and "Unrecognized Country", so the user can view the data when running a case. Remember that all steps in the initial task are automatically skipped by FTP Monitor when it initiates a case.

Step 3 - Create the connection: Create an FTP Monitor connection and mark the Pass variables in an XML file option and include as a search pattern *invoice* so that only files with the word "invoice" can initiate cases.

Step 4 - Create the XML data file: For every case which will be initiated by the FTP Monitor, create an XML file with the following structure:

Each field name in the XML file must be the same field names in the DynaForm. Remember that field names are case sensitive.

This XML can be automatically created, using a database trigger when a new invoice is added to the database or using a stored procedure which is periodically executed. For example the following MySQL query in the INVOICES table would create an XML data file for a specified invoice number:

Another way to automatically create the XML file is to use a script, such as the following PHP code which creates an XML file for every record in the INVOICE table whose field CASE_START_DATE is set to NULL (no data). The script uses the ftp_connect() and ftp_login() functions to connect to the FTP server and login. It also uses mysqli to connect to a MySQL database.

Set the above script to be periodically executed as a cron job in Linux/UNIX or as a Scheduled Task in Windows.

Step 5 - Upload files: Now upload the XML file and the PNG image files which have the same filenames to the directory monitored both of them with the same name as the image below:

Step 6 - Execute cron.php: Execute cron.php to start cases for each file uploaded to the monitored directory: