Overview

The following example REST application named "caselister" creates a web page which uses the cases endpoint in the ProcessMaker REST API to show how to get a list of the ProcessMaker cases found in the Inbox for a logged-in user.

Requirements

ProcessMaker v 2.8 or later

A server running Apache or a similar web server

If using a Linux server, root privileges are needed in order to create/copy files inside the Apache public directory which is often located at /var/www or configure Apache to use another directory. If using a Windows server, administrator privileges may be needed to edit the Apache configuration files if located under the Program Files directory.

Setup the server

In this example, a ProcessMaker server is installed at http://mypmserver.com and the example "caselister" application is installed on a separate server at http://mycaselister.com, which will use the ProcessMaker REST API.

The "caselister" application, however, can be run on the same server running ProcessMaker. The easiest way to do this is to create a caselister directory at <PROCESSMAKER-DIRECTORY>/workflow/public_html/caselister which will contain application's code. Then the "caselister" application can be accessed from the web browser at the address:

http://{pm-server}/caselister

If using Linux/UNIX, make sure to make the caselister directory is world readable and executable and all files inside it are world readable.

The second way to run the "caselister" application on the same server as ProcessMaker is to add another port to the Apache web server. For example, create the following file named caselister.conf to run the "caselister" application on port 8000:

Registering the application

First register the application in ProcessMaker, in order to request the access token, which in this example will be used to obtain access to the ProcessMaker Inbox list. Login to ProcessMaker as any user, then redirect the web browser to the following URL:

http://<PM-SERVER>/sys<WORKSPACE>/en/neoclassic/oauth2/applications

Click New and fill out the following form to register a new application:

Name: Enter a name to identify the application.

Description: Enter a description of the application.

Web Site: Enter a URL for the application's home page.

Callback URL: Enter the URL for the code to get the access token. The application will be redirected to this location after calling the {workspace}/oauth2/authorize endpoint.

When done filling out the form, click on Save Changes. Once the application has been successfully registered, its credentials are generated which are used by the external application to obtain access to ProcessMaker:

Copy the Client ID and Client secret which will be used by the external application to obtain authorization from ProcessMaker:

Create the caselister files

Create a directory named caselister in the server in a path which is web accessible, such as /var/www/caselister. Then create the following files inside the caselister folder, which will hold the code for the caselister and store the OAuth 2.0 credentials which are needed to obtain the access token:

This file will later be overwritten by code in grant.php to also include the access_token which is a code used to access ProcessMaker REST endpoints and a refresh_token which is used to acquire another access token, when the current access token expires.

home.html: Initial Page

Create the caselister/home.html file, which is the first page in the application. It contains a link to go to the access.html page to initiate authorization, so the caselister application can access the ProcessMaker REST.

access.html: Request application authorization

After registering the application, it is necessary to request an authorization to get access to the list of cases in the ProcessMaker Inbox. Create the caselister/access.html file containing the following code:

In this example, the access_token was successfully granted, which can be used to access ProcessMaker REST endpoints until the access token expires. expires_in lists in how many seconds the access token will expire. The scope is set to "*", meaning all scopes. Currently the scope is not used by ProcessMaker REST, but future versions may offer scopes to limit access to certain parts of the REST API, such as read-only cases endpoints or administration endpoints. If the token expires, the refresh_token can be used to request a new access token.

cases.html: Display case folders

Then, create the caselister/cases.html file which displays links to see the Inbox and Draft cases for the logged-in user:

When clicking on the Inbox option, it will redirect to the todo-list.html file, where all cases will be listed.

todo-list.html: List Inbox cases

Once the request has been accepted, this page will display the Inbox, which is a list of TO DO cases which are assigned to the logged-in user. Create the caselister/todo-list.html file with the following content:

Make sure to change the value of the apiserver variable to the direction of your ProcessMaker server.

This code downloads JQuery library, which contains a number of useful JavaScript functions for AJAX calls. When the page is done loading, it uses then jQuery.get() function to download the contents of the app-data.json file, which contains the access token and is necessary to access the ProcessMaker REST. Note that $ is an alias for jQuery.

Then the [jQuery.ajax() http://api.jquery.com/jquery.ajax] function calls the cases list endpoint at http://{pm-server}/api/1.0/{workspace}/cases to retrieve a list of TO DO cases for the logged-in user. If the TO DO list is successfully returned, the jQuery.each() function iterates through the list and prints each case number and its current task title.

Accessing the external application

Once all files are configured correctly, open a web browser and enter the address of the caselister application:

http://mycaselister.com/

The following page will display:

If no user is currently logged into ProcessMaker, then request an authorization to have access to that page:

Remember that those cases are coming from the ProcessMaker instance defined in the app.js file. By going to that ProcessMaker instance, the same cases as we were listed in the application, must be listed: