Install the open-source ProcessMaker Platform using Docker Desktop and Docker Compose. Before proceeding with the installation process, it is essential to have a basic understanding of Linux commands. Familiarity with common command-line operations such as navigating directories, executing commands, and editing files will greatly facilitate the installation process and troubleshooting.
Requirements
Before proceeding with the installation, ensure that you have met the following prerequisites.
Requirement
Function
Version
Installation Guide
WSL2 enables access to the command line for installing and accessing containers.
Latest
Docker provides the underlying technology to deploy containerized applications.
Latest
WSL2 (Windows Subsystem for Linux)
If you are using Microsoft Windows, then you can install ProcessMaker within WSL2.
Go to Microsoft's site and follow their instructions. It's very easy and quick.
If you are on Microsoft Windows, ensure to go into settings and enable the WSL2 integration.
Docker Compose
This installation procedure uses Docker Compose. The Docker Compose file is located in this GitHub repository. Issues, PRs and contribution are most welcome!
The Docker Compose File
Ensure you specify which branch or release of the ProcessMaker repository you wish to install and replace ${PROCESSMAKER_CORE_VERSION_INSTALL} with the desired version.
Open up your terminal for your platform:
Windows: Windows Terminal is a good option. Just make sure you don't go into CMD or PowerShell.
Macs: iTerm is a good option.
Other Unix-based operating systems: The native terminal should be more than adequate.
Oh My Zsh is a wonderful CLI tool that can help you with auto-completion within the terminal and syntax highlighting, convenience methods and much more.
Below is the default configuration parameters for the .env file (which will be env if cloning from the repo). You can copy-and-paste the snippet below into a new file. If you are using the repository, it should already be set there.
You may change any settings that you wish. Just make sure that the settings are valid and do not cause errors or issues.
In your terminal, run the following Docker command inside the folder where your Docker Compose file is:
docker-compose up
To spin down the environment, run the following Docker command:
docker-compose down
If this is your first time installing, it will take time for all the Docker images to download. At the end, you should see a message in your terminal that shows the Laravel Echo server is running and initial jobs should start running.
Did You Know?
The script adds a mounted folder for the ProcessMaker Platform installation and for Scripts, which is basically a good place to stick anything that is not purely ProcessMaker that you need as part of your application. For example, if you are developing a custom package or using Script Executors.
You may access the filesystem from outside the container. Just make sure to run any commands like composer update within the container (or send the command to it).
Troubleshooting
This section will be updated regularly as new issues and troubleshooting steps become known.
Feedback
If you got all the way down here, congratulations on being thorough! If you could kindly rate this page as helpful or unhelpful, that goes a long way towards improving our content.
Quick Start with Process Templates
Explore our ready-to-go Process Templates to kick-start your automation across several use cases and industries. Deploy into your Platform instance to spin up new processes and use as-is with all necessary assets included.
Overview
This guide will walk you through the steps to install and configure ProcessMaker Community using Bitnami on Amazon AWS cloud platform. By following this guide, you will have a fully functional instance of ProcessMaker Community, a powerful, open-source business process management (BPM) and workflow software.
Prerequisites
Please note that in order to set up a new instance, you will need an AWS account with sufficient permissions. It is important to ensure that your AWS account has the necessary privileges to create and configure instances, as well as manage associated resources.
Requirement
Function
Amazon AWS Account
AWS provides a highly scalable and reliable infrastructure, allowing users to access on-demand computing resources, storage, databases, and other functionalities.
Select the region where you wish to host ProcessMaker and initiate the deployment process.
Step 2: Configure your Instance
Specify the desired name for your instance, as illustrated in the example below. This name will help you easily identify and manage your instance within your cloud platform environment.
Choose the appropriate instance type that best suits your needs.
The instance type determines the computing resources allocated to your ProcessMaker installation, such as CPU, memory, and storage capacity. Carefully consider the requirements of your workload and select an instance type that provides optimal performance and scalability for your ProcessMaker deployment.
Ensure the security of your instance by selecting a Key Pair that will allow you to establish secure connections. Choose an existing Key Pair or create a new one to establish a secure connection.
A Key Pair consists of a public and private key, and it is essential for securely accessing and managing your instance.
Configure the network settings for your ProcessMaker instance. Ensure that the network settings align with your desired networking environment and security requirements to enable seamless communication and access to your ProcessMaker instance.
Choose your desired storage capacity.
Initiate the launch process for your instance. Click on the Launch instance button.
After launching your instance, locate and click on the instance ID associated with your ProcessMaker deployment.
The instance ID serves as a unique identifier for your instance within your cloud platform's management console. By clicking on the instance ID, you can access detailed information and perform various management tasks, such as monitoring resource usage, adjusting configurations, and troubleshooting any potential issues related to your instance.
Please allow a few minutes for the instance initialization process to complete. Once the Instance state transitions to "Running," it indicates that your ProcessMaker instance is ready for access.
Step 3: Retrieve your Credentials
Select your instance.
Navigate to the "Actions" menu and choose "Monitor and troubleshoot" or a similar option.
Look for the "Get system log" or a similar option within the available actions.
Click on "Get system log" to retrieve the system log information associated with your instance.
Examine the logs to find your ProcessMaker login credentials. These credentials will enable you to securely log in and begin utilizing the functionalities of ProcessMaker.
Step 4: Access your ProcessMaker Instance
Choose your instance from the list and locate the Public IPv4 DNS associated with it. Open the provided link in your web browser. You will be directed to the login page of your ProcessMaker instance. Enter your login credentials to gain access to ProcessMaker's interface and start taking advantage of the ProcessMaker capabilities.
This Public IPv4 DNS serves as the unique address that can be used to access your ProcessMaker instance from the internet.
Conclusion
Quick Start with Process Templates
In conclusion, by following the steps above we successfully set up a ProcessMaker instance in the AWS cloud platform using Bitnami. With the setup complete, you can now fully leverage the robust capabilities of ProcessMaker to enhance your business processes and drive operational efficiency.
Explore our ready-to-go Process Templates to kick-start your automation across several use cases and industries. Deploy into your Platform instance to spin up new processes and use as-is with all necessary assets included.
Overview
This guide provides instructions to deploy ProcessMaker on a Kubernetes cluster using Helm. This tutorial assumes a basic familiarity with Kubernetes concepts and commands. It is recommended to have a good understanding of concepts such as pods, deployments, services, and ingress. This knowledge will be beneficial for troubleshooting and managing the deployed application.
Prerequisites
Before proceeding with the installation, ensure that you have met the following prerequisites.
A running Kubernetes cluster: Ensure that you have a Kubernetes cluster set up and accessible. This can be a local development cluster, a cloud-based Kubernetes service, or any other Kubernetes environment of your choice.
Requirement
Function
Version
Installation Guide
Kubernetes
Kubernetes is a container orchestration platform that manages the deployment, scaling, and management of containerized applications.
1.19+
Helm
Helm is a package manager for Kubernetes that simplifies the deployment and management of applications. It allows you to define and manage application charts, which encapsulate all the necessary resources and configurations for your application.
3.12.0+
Please follow the steps outlined below to successfully deploy ProcessMaker on your Kubernetes cluster.
Repository Configuration
To begin, add the ProcessMaker chart repository to Helm by executing the following command:
This command ensures that you can access the ProcessMaker chart for installation.
Update Repository
Update the list of repositories to fetch the latest charts:
helm repo update
Install ProcessMaker on the Kubernetes Cluster
The following command deploys ProcessMaker on the Kubernetes cluster in the default configuration. The Parameters section lists the parameters that can be configured during installation.
This command deploys ProcessMaker on your Kubernetes cluster with the release name <my-app>. Replace <my-app> with a name of your choice. Also, set the appConfig.host parameter to your desired application host URL, such as my-app.example.com.
Verify the Installation
After the installation, you can verify the deployment by listing all releases using the following command:
helm list
This command displays a list of all Helm releases, including the ProcessMaker release you just installed.
Uninstall the ProcessMaker Deployment
If you need to uninstall or delete the ProcessMaker deployment, use the following command:
helm delete my-app
This command removes all the Kubernetes components associated with the ProcessMaker chart and deletes the release.
Additional Configuration Options
The ProcessMaker chart provides various configuration options that you can customize during the installation. To explore all configurable options along with detailed descriptions, you have the following options:
Review the values.yaml file: You can inspect the chart's values.yaml file, which contains all the available configuration options and their default values.
Use the helm show values command: Run the following command to view the configurable options with their descriptions:
helm show values processmaker/processmaker
This command displays a detailed list of configuration options that can be customized during the installation.
For further insights into the values.yaml file, we recommend exploring the following resources to deepen your understanding. Configuration Values
Conclusion
In conclusion, this guide offers a step-by-step approach to installing ProcessMaker on Kubernetes using Helm. By following the instructions outlined in this guide, users can quickly and efficiently set up ProcessMaker, leveraging the power and flexibility of Kubernetes orchestration.
Quick Start with Process Templates
Explore our ready-to-go Process Templates to kick-start your automation across several use cases and industries. Deploy into your Platform instance to spin up new processes and use as-is with all necessary assets included.
On-Premises Server Requirements
The following server requirements are only for a ProcessMaker Platform on-premises installation. Since ProcessMaker Platform is primarily an Enterprise cloud solution, these server requirements do not apply to cloud instances.
After you log on for the first time, you may begin managing user accounts and groups.
Starting a Request via REST API
Learn how to start an instance of a Process called a Request.
Overview
This guide walks you through the steps to create a new Process instance, called a Request, using the ProcessMaker 4 REST API programmatically. The guide assumes that you already have an access token for authenticating your API requests. If you need a refresher on obtaining an access token, you can refer to the previous guide here.
Pre-requisites
Requirement
Function
Version
Python
Dependencies:
requests
The programming language and modules we are using for this tutorial
Python 3+
Requests will install default latest version which is fine.
Access token
For authenticating with the API.
Step 1: Preparing Your Python Environment
Before starting, ensure that you have Python 3 and the requests library installed. You can verify your Python version by typing python --version in your command line. The requests library can be installed via pip, Python's package manager, with the command pip install requests.
If the command python returns an error, it may be installed as python3, depending on your environment.
Step 2: Setting Up Your API Request
The ProcessMaker 4 REST API uses HTTP protocols, and in this case, we will be sending a POST request to create a new request. For this, we must prepare the headers and the body of our request.
Preparing the Headers
The headers of an HTTP request provide additional parameters that the request needs to fulfill. In our case, we need to provide the Authorization header with our access token to authenticate our request.
In Python, headers are represented as a dictionary with the header names as keys and the corresponding values as dictionary values.
Replace {access_token} with your actual access token.
Preparing the Request Body
The body of a POST request contains the data we want to send to the server. In this case, we'll use a blank dictionary ({}) however this is dependent on your process, you may require to send additional parameters to be used as request data within the request.
Here's an example of a blank request body:
request_body = {}
Step 3: Sending the Request to the API
Now that we have our headers and request body ready, we can send our POST request to the ProcessMaker 4 REST API.
The URL for creating a new process instance is https://<your-instance>/api/1.0/process_events/<process_id>. Replace <your-instance> with your actual ProcessMaker instance and <process_id> with the ID of the process you want to start.
Here's how you can send the POST request and print the response:
# Make a request to the API to start a new process
response = requests.post(
'https://<your-instance>/api/1.0/process_events/<process_id>',
headers=headers,
json=request_body
)
# Print the response
print(response.json())
The response.json() function converts the server's response from a JSON format to a Python dictionary for easier handling.
That's it! You now know how to create a new process instance using the ProcessMaker 4 REST API in Python. Remember to replace <your-instance>, <your-access-token>, and <process_id> with actual values.
Requirement
Function
Version
Node.js
Dependencies:
axios
The programming language and modules we are using for this tutorial
Nodejs 8+
NPM 8-16
Note: this is the ProcessMaker compatible version, this tutorial should work with the latest versions as well.
Access token
For authenticating with the API.
Step 1: Preparing Your Node.js Environment
Before starting, ensure that you have Node.js and the axios library installed. You can verify your Node.js version by typing node --version in your command line.
Step 2: Setting Up Your API Request
The ProcessMaker 4 REST API uses HTTP protocols, and in this case, we will be sending a POST request to create a new request. For this, we need to prepare the headers and the body of our request.
Preparing the Headers
The headers of an HTTP request provide additional parameters that the request needs to fulfill. In our case, we need to provide the Authorization header with our access token to authenticate our request.
In JavaScript, headers are represented as an object with the header names as keys and the corresponding values as object values.
Replace ${access_token} with your actual access token.
Preparing the Request Body
Here's an example of an empty request body:
const requestBody = {};
The body of a POST request contains the data we want to send to the server. In this case, we'll use an empty object ({}), however, this is dependent on your process, and you may require to send additional parameters to be used as request data within the request.
Step 3: Sending the Request to the API
Now that we have our headers and request body ready, we can send our POST request to the ProcessMaker 4 REST API.
The URL for creating a new process instance is https://<your-instance>/api/1.0/process_events/<process_id>. Replace <your-instance> with your actual ProcessMaker instance and <process_id> with the ID of the process you want to start.
Here's how you can send the POST request and print the response:
This code will send the POST request and print the response data. If there's an error, it will print the error.
That's it! You now know how to create a new process request using the ProcessMaker 4 REST API in Node.js. Remember to replace <your-instance>, <your-access-token>, and <process_id> with actual values.
Requirement
Function
Version
Postman
The tool we will use to make API calls to ProcessMaker 4 REST API
Latest
Access token
For authenticating with the API.
Step 1: Open Postman
Start by opening Postman. If you haven't installed it yet, you can download it from the official Postman website.
Step 2: Create a New Request
In Postman, click on the "+" tab to create a new request.
Step 3: Configure the Request
In the new request tab, you will need to set up the following:
HTTP method: Choose POST from the dropdown menu next to the URL bar.
Request URL: The URL for creating a new process instance is https://<your-instance>/api/1.0/process_events/<process_id>. Replace <your-instance> with your actual ProcessMaker instance and <process_id> with the ID of the process you want to start.
Headers: Click on the "Headers" tab and add a new header. For the name, enter Authorization, and for the value, enter Bearer <your-access-token>. Replace <your-access-token> with your actual access token.
Body: Click on the "Body" tab and choose the raw and JSON format. Here you can enter the data you want to send as the request body. In this case, you can use an empty JSON object ({}), but depending on your process, you may need to send additional parameters to be used as request data within the request.
Step 4: Send the Request
Once you have configured the request, you can press the "Send" button to send the request to the ProcessMaker 4 REST API. The server's response will appear in the section below.
That's it! You now know how to create a new process instance using the ProcessMaker 4 REST API in Postman. Remember to replace <your-instance>, <your-access-token>, and <process_id> with actual values.
Pre-requisites
Requirement
Function
Version
Postman or a Terminal
The tool we will use to make API calls to ProcessMaker 4 REST API
Latest
Access token
For authenticating with the API.
Step 1: Setting Up Your API Request
The ProcessMaker 4 REST API uses HTTP protocols. In this case, we will be sending a POST request to create a new request.
<your-instance> with your actual ProcessMaker instance URL.
<process_id> with the ID of the process you wish to start.
<access_token> with your actual access token.
{"key1":"value1", "key2":"value2", ...} with your actual payload data.
Step 2: Review the Response
After executing the command, you should receive a response from the server. This will provide details about the process instance you've started or any potential errors.
Conclusion
Using the curl command directly from the command line offers a swift and efficient method to interact with the ProcessMaker 4 REST API. By following the steps outlined in this guide, you can seamlessly initiate a Process instance, termed a Request, without the need for intermediary scripts or tools. This approach not only simplifies the process but also enhances the speed at which developers can test and integrate with the API. Always ensure you handle your access tokens with care, as they are crucial for secure communication with the API.
Starting a Request via Web Hook
This guide discusses how to integrate ProcessMaker with web hooks into third-party web applications to initiate new requests.
Overview
In this guide, you will learn how to integrate the ProcessMaker app into third-party applications using web hooks to initiate new process requests. This integration allows you to seamlessly kick off workflow processes within the ProcessMaker environment from your own application.
By the end of this guide, you will have accomplished the following:
Prerequisites
Before proceeding with the guide, it's important to assess your skill level as a developer. The following skills and knowledge are highly recommended to ensure a smooth implementation: web hooks and API.
Requirement
Function
Version
ProcessMaker Platform
Access to the ProcessMaker app with administrative privileges.
4.6+
Code Editor
Choose a code editor of your choice that suits your preferences. Popular code editors for development include Visual Studio Code, Sublime Text, and Atom.
Your choice
Steps to Integrate ProcessMaker using Web Hooks
By following the steps below, seamlessly integrate your ProcessMaker's workflow/process into your application to initiate new requests.
Step 1: Configure Web Hook in ProcessMaker
To seamlessly integrate ProcessMaker workflow/processes using web hooks begin by generating the web hook. Follow this example to generate the ProcessMaker web hook.
Based on the screen/form variables that you've defined within the ProcessMaker platform for your process, ensure to adjust the below example with your defined ProcessMaker form variables.
Example that shows the JSON data you need to send to the webhook:
Below is an illustrative example demonstrating the utilization of the web hook through Postman to trigger the API and initiate a request.
Step 2: Integrate the Web Hook into Your Application
Now, that you have the web hook link, identify the appropriate location within your application to integrate the ProcessMaker workflow/process form. This could be a specific page, a modal window, or any other suitable area.
Below is a straightforward illustration showcasing how the integration can be implemented within a web application. Feel free to utilize the provided sample HTML code as a starting point:
Step 3: Customize the Form and Attributes (Optional)
You can customize the form attributes according to your requirements. For example, you can adjust the form fields, font size, and other attributes of the form to fit your application's design and layout.
Step 4: Test and Verify the Integration
Save your changes and reload your Web application. Ensure to change the web hook generated in the previous step inside the html template. Test the functionality of the form, such as submitting a new request to ensure that everything works as expected.
Output Preview: ProcessMaker Integration using web hooks into a third-party application
After you have completed the steps above, verify the form inside your application, initiate requests, and make sure it sends the information to the web hook.
Conclusion
By following the steps outlined in this guide, you can integrate the ProcessMaker's forms into your Web application using Web Hooks to initiate new requests.
Starting a Request via Anonymous Web Entry
This guide discusses how to embed ProcessMaker's actionable forms or web entries into third-party web applications.
Overview
This guide discusses the process of embedding ProcessMaker actionable forms or most commonly known as Web Entry into a web application using an iFrame to of your workflow/process on the ProcessMaker platform.
ProcessMaker are dynamic and actionable forms that are used to seamlessly integrate into third-party applications. These versatile forms not only merge smoothly with external platforms but also provide a wealth of interactive possibilities, empowering users to engage, input, and interact within their preferred applications effortlessly.
Steps to Embed Actionable Forms
By following the steps below, seamlessly integrate actionable forms into your application.
Step 1: Generate the Web Entry Link or Code Snippet
To seamlessly integrate an actionable form or web entry, begin by generating the web entry link. Follow these steps to get the . Below are examples of the web entry link or code snippet:
Step 2: Embed the Web Entry Link into Your Web Application
Identify the appropriate location within your Web application to embed the Web entry link. This could be a specific page, a modal window, or any other suitable area. Insert the provided web entry link, including the iFrame, into the desired location in your HTML file.
Let's embed the web entry link into the iFrame, use the following sample HTML code:
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ERP Website</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
<style>
/* CSS styles for the ERP website */
* {
box-sizing: border-box;
}
body {
margin: 0;
padding: 0;
font-family: Arial, sans-serif;
background-color: #f1f1f1;
}
header {
background-color: #ff6347; /* New color for the header */
color: #fff;
padding: 10px;
text-align: center;
}
.container {
display: flex;
max-width: 1200px;
margin: 0 auto;
}
.sidebar {
background-color: #f9f9f9;
width: 200px;
padding: 20px;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
.sidebar h3 {
margin-top: 0;
font-size: 1.2rem;
color: #555;
}
.sidebar ul {
list-style-type: none;
padding: 0;
margin: 10px 0;
}
.sidebar li {
margin-bottom: 5px;
}
.sidebar a {
text-decoration: none;
color: #333;
display: flex;
align-items: center;
}
.sidebar .material-icons {
margin-right: 5px;
}
.content {
flex-grow: 1;
padding: 20px;
}
.content-header {
display: flex;
align-items: center;
justify-content: space-between;
}
h1 {
margin: 0;
color: #ff6347; /* New color for the heading */
font-size: 2.5rem;
}
p {
font-size: 1.1rem;
line-height: 1.6;
color: #444;
}
.iframe-container {
position: relative;
width: 100%;
height: 100%;
}
iframe {
width: 100%;
height: 100%;
border: none;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
.action-button {
background-color: #ff6347; /* New color for the button */
color: #fff;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
}
</style>
</head>
<body>
<header>
<h1>Rocket ERP</h1>
</header>
<div class="container">
<!-- Sidebar -->
<div class="sidebar">
<h3>Menu</h3>
<ul>
<li>
<a href="#"><i class="material-icons">dashboard</i> Dashboard</a>
</li>
<li>
<a href="#"><i class="material-icons">inventory</i> Inventory</a>
</li>
<li>
<a href="#"><i class="material-icons">shopping_basket</i> Sales</a>
</li>
<li>
<a href="#"><i class="material-icons">add_shopping_cart</i> Purchases</a>
</li>
</ul>
</div>
<!-- Main Content Area -->
<div class="content">
<div class="content-header">
<h1>Rocket ERP</h1>
<button class="action-button">New Purchase Approval</button>
</div>
<p>You are logged into the ERP system, and here's a snapshot of the dashboard:</p>
<div class="iframe-container">
<!-- Replace the iframe content with your actual ERP system's URL or relevant content -->
<iframe src="https://veggiedonuts.training.processmaker.net/webentry/8/node_1" frameborder="0" style="height:1000px;"></iframe>
</div>
</div>
</div>
</body>
</html>
Step 3: Customize the iFrame Attributes (Optional)
You can customize the attributes of the iFrame according to your requirements. For example, you can adjust the width, height, frameborder, and other attributes of the iFrame to fit your application's design and layout.
Step 4: Test and Verify the Integration
Save your changes and reload your Web application. Ensure that the embedded actionable form is visible and functioning correctly within your application. Test the functionality of the actionable form, such as submitting a new request to ensure that everything works as expected.
Output Preview: Embedded ProcessMaker Actionable Form
After you have completed the steps above, verify ProcessMaker's Actionable Form or Web entry is embedded to your Web application.
Conclusion
By following the steps outlined in this guide, you can integrate the ProcessMaker's powerful Web entry or actionable form into your Web application using an iFrame to submit new requests.
Participating in a Workflow via Intermediate Web Entry (Anonymous)
This guide discusses how to embed ProcessMaker's actionable forms or intermediate web entry forms into third-party web applications.
Step 2: Embed the Intermediate Web Entry Link into Your Web Application
Identify the appropriate location within your Web application to embed the intermediate Web entry link. This could be a specific page, a modal window, or any other suitable area. Insert the provided web entry link, including the iFrame, into the desired location in your HTML file.
Let's embed the intermediate web entry link into the iFrame, use the following sample HTML code:
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ERP Website</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
<style>
/* CSS styles for the ERP website */
* {
box-sizing: border-box;
}
body {
margin: 0;
padding: 0;
font-family: Arial, sans-serif;
background-color: #f1f1f1;
}
header {
background-color: #ff6347; /* New color for the header */
color: #fff;
padding: 10px;
text-align: center;
}
.container {
display: flex;
max-width: 1200px;
margin: 0 auto;
}
.sidebar {
background-color: #f9f9f9;
width: 200px;
padding: 20px;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
.sidebar h3 {
margin-top: 0;
font-size: 1.2rem;
color: #555;
}
.sidebar ul {
list-style-type: none;
padding: 0;
margin: 10px 0;
}
.sidebar li {
margin-bottom: 5px;
}
.sidebar a {
text-decoration: none;
color: #333;
display: flex;
align-items: center;
}
.sidebar .material-icons {
margin-right: 5px;
}
.content {
flex-grow: 1;
padding: 20px;
}
.content-header {
display: flex;
align-items: center;
justify-content: space-between;
}
h1 {
margin: 0;
color: #ff6347; /* New color for the heading */
font-size: 2.5rem;
}
p {
font-size: 1.1rem;
line-height: 1.6;
color: #444;
}
.iframe-container {
position: relative;
width: 100%;
height: 100%;
}
iframe {
width: 100%;
height: 100%;
border: none;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
.action-button {
background-color: #ff6347; /* New color for the button */
color: #fff;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
}
</style>
</head>
<body>
<header>
<h1>Rocket ERP</h1>
</header>
<div class="container">
<!-- Sidebar -->
<div class="sidebar">
<h3>Menu</h3>
<ul>
<li>
<a href="#"><i class="material-icons">dashboard</i> Dashboard</a>
</li>
<li>
<a href="#"><i class="material-icons">inventory</i> Inventory</a>
</li>
<li>
<a href="#"><i class="material-icons">shopping_basket</i> Sales</a>
</li>
<li>
<a href="#"><i class="material-icons">add_shopping_cart</i> Purchases</a>
</li>
</ul>
</div>
<!-- Main Content Area -->
<div class="content">
<p>You are logged into the ERP system, and here's a snapshot of the dashboard:</p>
<div class="iframe-container">
<!-- Replace the iframe content with your actual ERP system's URL or relevant content -->
<iframe src="https://my-server.processmaker.net/webentry/request/3270/node_6" frameborder="0" style="height:1200px;width:100%;"></iframe>
</div>
</div>
</div>
</body>
</html>
Step 3: Customize the iFrame Attributes (Optional)
You can customize the attributes of the iFrame according to your requirements. For example, you can adjust the width, height, frameborder, and other attributes of the iFrame to fit your application's design and layout.
Step 4: Test and Verify the Integration
Save your changes and reload your Web application. Ensure that the embedded intermediate web entry form is visible and functioning correctly within your application. Test the functionality of the web entry form, such as approving/completing a request to ensure that everything works as expected.
Output Preview: Embedded ProcessMaker Intermediate Web Entry Form
After you have completed the steps above, verify ProcessMaker's intermediate web entry form is embedded into your Web application.
Conclusion
By following the steps in this guide, you can easily add ProcessMaker's powerful intermediate web entry form to your web application using an iFrame. This will help you complete requests seamlessly.
Getting an Access Token
This guide covers three OAuth 2.0 grant types: Authorization Code Grant, Password Grant, and Personal Access Tokens.
Overview
This guide walks you through the steps of obtaining an access token for making restful api calls to ProcessMaker. You will be able to obtain an access token and then consume the api. After you complete this document, you will want to go to the .
Don't forget to replace placeholders like <your-instance>, <your-client-id>, etc., with your actual values. Always protect your client secret, access tokens, personal access tokens, and user credentials.
Client Application
Choose Your Tutorial
Step 1: Install Necessary Python Libraries
Before starting, ensure you have the necessary Python libraries installed. You'll need requests for making HTTP requests and oauthlib for handling OAuth.
Install them via pip:
pip install requests oauthlib
Step 2: Set Up Your Client Application
If you came here before , you first need to do so. Otherwise, go to step 3 if you have your client id and client secret already.
Step 3: Use the Correct Grant Type
Authorization Code
This is used by web and mobile applications which involves the following:
Redirect the user to the authorization server (ProcessMaker).
The user accepts the application.
The application exchanges an authorization code for an access token.
import requests
from oauthlib.oauth2 import WebApplicationClient
# Initialize the OAuth client
client = WebApplicationClient(client_id='<your-client-id>')
# Generate the authorization URL
auth_url, _ = client.prepare_request_uri(
'https://<your-instance>.processmaker.net/oauth/authorize',
redirect_uri='<your-redirect-uri>',
scope='<your-scope>',
)
print(f'Please go to the following URL and authorize the app: {auth_url}')
# After the user has authorized the app, they will be redirected to the redirect URI
# with a code in the query string. Paste that code here.
code = input('Enter the authorization code: ')
# Exchange the authorization code for an access token
token_url = 'https://<your-instance>.processmaker.net/oauth/token'
token_data = client.prepare_request_body(
code=code,
client_id='<your-client-id>',
client_secret='<your-client-secret>',
redirect_uri='<your-redirect-uri>',
)
response = requests.post(token_url, data=token_data)
token_info = response.json()
print(f'Access token: {token_info["access_token"]}')
Password
This is used by applications that are highly trusted, like those installed on a personal device by the user. This involves the client application collecting the user's username and password and exchanging them directly for an access token.
import requests
from oauthlib.oauth2 import LegacyApplicationClient
# Initialize the OAuth client
client = LegacyApplicationClient(client_id='<your-client-id>')
# Prepare the request body for the token request
token_url = 'https://<your-instance>.processmaker.net/oauth/token'
token_data = client.prepare_request_body(
username='<your-username>',
password='<your-password>',
client_id='<your-client-id>',
client_secret='<your-client-secret>',
)
# Request an access token
response = requests.post(token_url, data=token_data)
token_info = response.json()
print(f'Access token: {token_info["access_token"]}')
Personal Access Tokens
A Personal Access Token (PAT) is an alternative to using a password for authentication to the API. The PAT is usually generated in the application's user interface and can be revoked at any time.
import requests
# Prepare the headers for the request
headers = {
'Authorization': f'Bearer <your-personal-access-token>',
}
# Make a request to the API
response = requests.get('https://<your-instance>.processmaker.net/api/<your-endpoint>', headers=headers)
print(response.json())
Step 4: Making API Requests
After you have your access token, you can use it to make authenticated requests to the API. Here's an example of how to do this:
import requests
# Prepare the headers for the request
headers = {
'Authorization': f'Bearer <your-access-token>',
}
# Make a request to the API
response = requests.get('https://<your-instance>.processmaker.net/api/<your-endpoint>', headers=headers)
print(response.json())
Replace <your-instance>, <your-access-token>, and <your-endpoint> with your actual values.
Remember: Always protect your client secret, access tokens, personal access tokens, and user credentials. These allow access to the API and should be treated like passwords.
That's it! You now have an access token that you can use to make authenticated requests to the API. Depending on the grant type used and the settings of the OAuth server, this token may expire after some time. If the token does expire, you will need to go through the flow again to get a new token.
Step 1: Setting up Node.js and required libraries
After installing Node.js, install the library required to make HTTP requests. Use the request library. Open your terminal and navigate to the directory where you'll be writing your code. Then, run the following command:
npm install request
This command tells npm (node package manager) to install the request library. It's like going to the store and buying a new tool for your toolbox!
Step 2: Set Up Your Client Application
Step 3: Writing the code
Now that you have your tools, you can start writing our code. Create a new JavaScript file named app.js. Inside this file, write the code to get our access token.
First, import the request library at the top of our file:
var request = require('request');
This line is like taking the tool out of the toolbox and laying it out on our workbench.
Now, define the details of our client application. These are like the blueprint for your project:
var clientId = 'YOUR_CLIENT_ID';
var clientSecret = 'YOUR_CLIENT_SECRET';
Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual client ID and secret provided by ProcessMaker.
Step 4: Making the request
Now you're ready to make our request to the API! This is the exciting part - it's like turning on the power drill and driving in the screw.
request({
url: 'https://MyOrganization.processmaker.net/oauth/token',
method: 'POST',
auth: {
user: clientId,
pass: clientSecret
},
form: {
grant_type: 'client_credentials'
}
}, function(err, res, body) {
if (err) {
console.log('Oops, something went wrong!', err);
} else {
var json = JSON.parse(body);
var accessToken = json.access_token;
console.log('Yay! We got an access token: ', accessToken);
}
});
This code sends a POST request to the ProcessMaker API to get an access token. If the request is successful, the access token logs to the console. If something goes wrong, the log records an error message.
And voila! You've just written a Node.js script to get an access token from the ProcessMaker API. You're now a certified API wrangler! Keep this script handy, as you'll need the access token for making authenticated requests to the API. Happy coding!
Step 1: Download and Install Postman
Step 2: Set Up Your Client Application
Step 3: Create a New Request
Open Postman, click on the + button to create a new tab, then click on the Authorization tab.
Step 4: Use the Correct Grant Type
For each grant type, select the type from the Type drop-down under the Authorization tab and fill in the necessary details.
Authorization Code Grant
Type: Choose OAuth 2.0 from the drop-down.
Add auth data to: Choose Request Headers.
Configure New Token:
Token Name: Any name for your reference.
Grant Type: Authorization Code.
Callback URL: The callback URL specified in your OAuth application.
Auth URL: The authorization URL of the OAuth server.
Access Token URL: The token URL of the OAuth server.
Client ID: The client ID of your OAuth application.
Client Secret: The client secret of your OAuth application.
Scope: The scope of the access request.
Client Authentication: Send as Basic Auth header.
Click Get New Access Token.
After the user authenticates and authorizes the application, the access token will be automatically filled in the Access Token field.
Password Grant
Type: Choose OAuth 2.0 from the drop-down.
Add auth data to: Choose Request Headers.
Configure New Token:
Token Name: Any name for your reference.
Grant Type: Password Credentials.
Access Token URL: The token URL of the OAuth server.
Username: The username of the user.
Password: The password of the user.
Client ID: The client ID of your OAuth application.
Client Secret: The client secret of your OAuth application.
Scope: The scope of the access request.
Client Authentication: Send as Basic Auth header.
Click Get New Access Token. The access token will be automatically filled in the Access Token field.
Client Credentials Grant
Type: Choose OAuth 2.0 from the drop-down.
Add auth data to: Choose Request Headers.
Configure New Token:
Token Name: Any name for your reference.
Grant Type: Client Credentials.
Access Token URL: The token URL of the OAuth server.
Client ID: The client ID of your OAuth application.
Client Secret: The client secret of your OAuth application.
Scope: The scope of the access request.
Client Authentication: Send as Basic Auth header.
Click Get New Access Token. The access token will be automatically filled in the Access Token field.
Step 5: Making API Requests
After obtaining the access token, Postman automatically adds the Authorization: Bearer <access-token> header to your requests. You can now make requests to the API with the access token.
Remember: Always protect your client secret, access tokens, and user credentials. These allow access to the API and should be treated like passwords.
That's it! You now know how to get an access token using OAuth 2.0 in Postman.
Step 1: Set Up Your Client Application
Step 2: Use the Correct Grant Type
Authorization Code
This is used by web and mobile applications and involves the following steps:
Redirect the user to the authorization server (ProcessMaker).
The user authorizes the application.
The application exchanges an authorization code for an access token.
# Redirect user to authorization URL
echo "Please go to the following URL and authorize the app: https://<your-instance>.processmaker.net/oauth/authorize?client_id=<your-client-id>&redirect_uri=<your-redirect-uri>&scope=<your-scope>"
# Exchange the authorization code for an access token
curl -X POST "https://<your-instance>.processmaker.net/oauth/token" \
-d "grant_type=authorization_code&code=<authorization-code>&client_id=<your-client-id>&client_secret=<your-client-secret>&redirect_uri=<your-redirect-uri>"
Password Grant
This is used by applications that are highly trusted, like those installed on a personal device by the user.
curl -X POST "https://<your-instance>.processmaker.net/oauth/token" \
-d "grant_type=password&username=<your-username>&password=<your-password>&client_id=<your-client-id>&client_secret=<your-client-secret>"
Personal Access Tokens
A Personal Access Token (PAT) is an alternative to using a password for authentication to the API.
curl -X GET "https://<your-instance>.processmaker.net/api/<your-endpoint>" \
-H "Authorization: Bearer <your-personal-access-token>"
Step 3: Making API Request
After obtaining your access token, you can use it to make authenticated requests to the API.
curl -X GET "https://<your-instance>.processmaker.net/api/<your-endpoint>" \
-H "Authorization: Bearer <your-access-token>"
Conclusion
Utilizing curl provides a straightforward and efficient method for interacting with the ProcessMaker API. By following the steps outlined in this guide, developers can seamlessly obtain access tokens and make authenticated requests to the API. As with all authentication methods, it's imperative to handle credentials with care, ensuring they remain confidential. With the power of curl at your fingertips, you're well-equipped to harness the capabilities of the ProcessMaker platform, driving innovation and efficiency in your workflows.
Part 0: Overview
Overview
For the best experience with this tutorial, review these requirements to make sure you have what you need to be successful.
Experience
This tutorial assumes that you have experience with the following:
Creating Web pages by editing the HTML directly.
Programming Web site content in JavaScript.
Reading Cascading Style Sheet (CSS) content and understanding how selectors are used.
Using command-line instructions to perform tasks on your computer.
(optional, nice to have) Some familiarity with .
Equipment
The tutorial can be completed by using a local installation of the Angular tools or by using in a Web browser. Local Angular development can be completed on Windows, MacOS or Linux based systems.
Concept Preview
This tutorial will create an Angular app that displays an inbox with the list of Requests assigned to the logged on user in ProcessMaker and renders the form as defined in the ProcessMaker form builder, complete with JavaScript and CSS.
Local Development Environment
Perform these steps in a command-line tool on the computer you want to use for this tutorial.
Step 1: Identify the Version of node.js that Angular Requires
From a Terminal window:
Run the following command: node --version.
Confirm that the version number displayed meets the requirements.
Step 2: Install the Correct Version of node.js for Angular
Step 3: Install the Latest Version of Angular
From a Terminal window run the following command:
npm install -g @angular/cli.
Step 4: Install Integrated Development Environment (IDE)
Use any tool you prefer to build apps with Angular. We recommend the following:
Review
In this part, you learned about the app that you build in this tutorial and prepared your local computer to develop Angular apps.
Next Steps
or Unix based OS
Go to https://localhost or the IP address/domain name you specified. Use the following credentials to :
instructions for obtaining from the page
If you need help obtaining the process id, you can look at the to get the id before making the request to initiate a new request.
instructions for obtaining from the page
If you need help obtaining the process id, you can look at the to get the id before making the request to initiate a new request.
instructions for obtaining from the page
instructions for obtaining from the page
Before starting this example, ensure Node.js installed. Node.js is a JavaScript runtime that allows us to run JavaScript on our server. Download Node.js from the .
If you came here before , you first need to do so. Otherwise, go to step 3 if you have your client id and client secret already.
and install Postman from their official website if you haven't already.
If you came here before , you first need to do so. Otherwise, go to step 3 if you have your client id and client secret already.
If you arrived here before , you first need to do so. Otherwise, proceed to step 2 if you have your client ID and client secret already.
Angular requires an active LTS or maintenance LTS version of Node. Let's confirm your version of node.js. For information about specific version requirements, see the engines property in the .
If you do not have a version of node.js installed, please follow the .
After node.js and npm are installed, install the which provides tooling for effective Angular development.
.
As an optional, but recommended step, you can further improve your developer experience by installing the .
Environment variables store configuration values and sensitive information for processes.
Get Environment Variables
This example demonstrates how to get all environment variables of your ProcessMaker instance.
Example
<?php
// Create an instance of the environmentVariables API class
$apiInstance = $api->environmentVariables();
// Call the getEnvironmentVariables() method to retrieve a list of environment variables
$result = $apiInstance->getEnvironmentVariables();
// Initialize an array to store the environment variable details
$envVars = [];
// Iterate over each environment variable in the result
foreach ($result->getData() as $envVar) {
// Extract the name and description of the environment variable
$envVars[] = [
'name' => $envVar->getName(),
'description' => $envVar->getDescription(),
];
}
// Return all the environment variables
return ['environmentVariables' => $envVars];
?>
Get Environment Variable by ID
This example illustrates how to retrieve a specific environment variable by its ID.
Example
<?php
// Retrieve a specific environment variable by ID
$apiInstance = $api->environmentVariables();
// Retrieve environment variable with ID 4
$envVar = $apiInstance->getEnvironmentVariableById(4);
// Return the name and description of the environment variable
return [
'name' => $envVar->getName(),
'description' => $envVar->getDescription(),
];
?>
Get Environment Variable by ID
This example demonstrates how to create a new environment variable.
Example
<?php
$apiInstance = $api->environmentVariables();
// Create a new editable environment variable object
$environment_variable_editable = new \ProcessMaker\Client\Model\EnvironmentVariableEditable();
// Define the name of your environment variable
$environment_variable_editable->setName('myNewVariable');
// Define the description of your environment variable
$environment_variable_editable->setDescription('My global variable');
// Set the value for your new environment variable
$environment_variable_editable->setValue('12345');
// Create the environment variable using the API
$newEnvVar = $apiInstance->createEnvironmentVariable($environment_variable_editable);
// Return the ID of the newly created environment variable
return ['newEnvVarId' => $newEnvVar->getId()];
?>
Update Environment Variable
This example showcases how to update an existing environment variable.
Example
<?php
$apiInstance = $api->environmentVariables();
// Retrieve the environment variable with ID 10
$envVar = $apiInstance->getEnvironmentVariableById(10);
// Update the properties of the environment variable
$envVar->setName('myVariable'); // Set a new name for the environment variable
$envVar->setDescription('My updated variable'); // Update the description of the environment variable
$envVar->setValue('123456'); // Update the value of the environment variable
// Call the updateEnvironmentVariable() method to update the environment variable
$apiInstance->updateEnvironmentVariable(
$envVar->getId(),
$envVar
);
// If no errors are thrown, the environment variable was successfully updated
return ['success' => true];
?>
Delete Environment Variable
This example demonstrates how to delete an existing environment variable.
Example
<?php
$apiInstance = $api->environmentVariables();
// Delete the environment variable with ID 10
$apiInstance->deleteEnvironmentVariable(10);
// The environment variable is successfully deleted
return ['success' => true];
?>
Files
Files can be associated with different processes in the ProcessMaker platform and contain relevant information or attachments.
Get Files
This example demonstrates how to retrieve all the list of files inside the instance.
Example
<?php
$apiInstance = $api->files();
$files = [];
// Retrieve all files in the system
$result = $apiInstance->getFiles();
// Iterate over each file and extract its details
foreach ($result->getData() as $file) {
$files[] = [
'id' => $file->getId(),
'file_name' => $file->getFileName(),
'model_type' => $file->getModelType(),
'model_id' => $file->getModelId(),
// Variable name in the request data
'data_name' => $file->getCustomProperties()['data_name'],
];
}
// Return the list of files
return ['files', $files];
?>
Get File
This example demonstrates how to retrieve information about a specific file in the ProcessMaker instance.
Example
<?php
$apiInstance = $api->files();
$fileId = 1; // ID of the file to retrieve information for
$file = $apiInstance->getFileById($fileId);
return [
'file' => [
'file_name' => $file->getFileName(),
'model_type' => $file->getModelType(),
'model_id' => $file->getModelId(),
'data_name' => $file->getCustomProperties()['data_name'],
],
];
?>
Groups
A group is a logical collection of users with similar roles, responsibilities, or permissions within an organization. It provides a convenient way to organize and manage users based on common attributes. By grouping users together, administrators can efficiently assign access rights, permissions, and privileges to multiple users simultaneously. This simplifies user management, enhances security, and improves overall administrative efficiency.
Get Groups
This example demonstrates how to retrieve information about all the groups in the ProcessMaker instance.
Example
<?php
$apiInstance = $api->groups();
$groups = [];
// Retrieve all groups
$result = $apiInstance->getGroups();
// Iterate over each group and extract its details
foreach ($result->getData() as $group) {
$groups[] = [
'id' => $group->getId(),
'name' => $group->getName(),
'description' => $group->getDescription(),
'status' => $group->getStatus()
];
}
// Optional: Filter and sort groups with additional arguments
$status = 'ACTIVE';
$filter = 'designers';
$order_by = 'name';
$order_direction = 'asc';
$per_page = 10;
$include = '';
$result = $apiInstance->getGroups($status, $filter, $order_by, $order_direction, $per_page, $include);
// Iterate over the filtered and sorted groups to extract their details
foreach ($result->getData() as $group) {
$groups[] = [
'id' => $group->getId(),
'name' => $group->getName(),
'description' => $group->getDescription(),
'status' => $group->getStatus()
];
}
// Return the list of groups
return ['groups', $groups];
?>
Get All Users in a Group
This example demonstrates how to retrieve information about all users belonging to a specific group.
Example
<?php
$apiInstance = $api->groups();
$users = [];
$groupId = 5; // ID of the group to retrieve users from
// Retrieve users belonging to the specified group
$result = $apiInstance->getGroupUsers($groupId);
// Iterate over each user and extract their details
foreach ($result->getData() as $user) {
$users[] = [
'id' => $user->getId(),
'name' => $user->getUsername(),
'email' => $user->getEmail(),
'status' => $user->getStatus(),
];
}
// Return the list of users in the group
return ['usersInGroup' => $users];
?>
Get Group
This example demonstrates how to retrieve information about a specific group.
Example
<?php
$apiInstance = $api->groups();
$groupId = 2; // ID of the group to retrieve information for
$group = $apiInstance->getGroupById($groupId);
// Return the Name, Description, and Status of the group
return [
'group' => [
'name' => $group->getName(),
'description' => $group->getDescription(),
'status' => $group->getStatus(),
],
];
?>
Create Group
This example demonstrates how to create a new group in the ProcessMaker instance.
Example
<?php
$apiInstance = $api->groups();
// Create a new editable group object
$group = new \ProcessMaker\Client\Model\GroupsEditable();
$group->setName("New group");
$group->setDescription("New group description");
$group->setStatus("ACTIVE");
// Create the group using the API
$newGroup = $apiInstance->createGroup($group);
// Return the ID of the newly created group
return ['newGroupId' => $newGroup->getId()];
?>
Update Group
This example demonstrates how to update an existing group in the ProcessMaker instance.
Example
<?php
$apiInstance = $api->groups();
$groupId = 9; // ID of the group to update
$group = $apiInstance->getGroupById($groupId);
$group->setName("Updated group name"); // Update the name of the group
$group->setDescription("Updated group description"); // Update the description of the group
$group->setStatus("INACTIVE"); // Update the status of the group
$apiInstance->updateGroup($groupId, $group);
// If no errors are thrown, the group was successfully updated
return ['success' => true];
?>
Delete Group
This example demonstrates how to delete an existing group in the ProcessMaker instance.
Example
<?php
$apiInstance = $api->groups();
$groupId = 9; // ID of the group to delete
$apiInstance->deleteGroup($groupId);
// If no errors are thrown, the group was successfully deleted
return ['success' => true];
?>
Process Categories
Process categories are an essential organizational tool that enables the grouping of processes based on specific criteria or common characteristics. They offer a convenient and efficient method to structure and manage processes within the ProcessMaker platform. This categorization system enhances overall process organization, providing users with an intuitive way to locate and access relevant processes efficiently.
Get Process Categories
This example demonstrates how to retrieve information about all process categories in your ProcessMaker instance.
Example
<?php
$apiInstance = $api->processCategories();
$processCategories = [];
$result = $apiInstance->getProcessCategories();
// Iterate over each process category and extract its details
foreach($result->getData() as $processCategory) {
$processCategories[] = [
'name' => $processCategory->getName(),
'status' => $processCategory->getStatus(),
];
}
// Return the list of process categories
return ['processCategories' => $processCategories];
?>
Get Process Category
This example demonstrates how to retrieve the category of a specific process.
Example
<?php
$apiInstance = $api->processCategories();
$processCategory = $apiInstance->getProcessCategoryById(2); // Set the process ID
// Return the details of the process category
return [
'name' => $processCategory->getName(),
'status' => $processCategory->getStatus(),
];
?>
Create Process Category
This example demonstrates how to create a new process category.
Example
<?php
$apiInstance = $api->processCategories();
// Create a new editable process category object
$process_category_editable = new \ProcessMaker\Client\Model\ProcessCategoryEditable();
$process_category_editable->setName('newCategory');
$process_category_editable->setStatus('ACTIVE');
// Create the process category using the API
$newProcessCategory = $apiInstance->createProcessCategory($process_category_editable);
// Return the ID of the newly created process category
return ['newProcessCategoryId' => $newProcessCategory->getId()];
?>
Update Process Category
This example demonstrates how to update an existing process category.
Example
<?php
$apiInstance = $api->processCategories();
// Retrieve the process category to be updated
$processCategory = $apiInstance->getProcessCategoryById(21);
// Update the name of the process category
$processCategory->setName("Procurement");
// Update the process category using the API
$apiInstance->updateProcessCategory($processCategory->getId(), $processCategory);
// If no errors are thrown, the process category was successfully updated
return ['success' => true];
?>
Delete Process Category
This example demonstrates how to delete an existing process category.
Example
<?php
$apiInstance = $api->processCategories();
// Delete the process category with the specified ID
$apiInstance->deleteProcessCategory(21);
// If no errors are thrown, the process category was successfully deleted
return ['success' => true];
?>
Process Requests
Process requests represent instances of processes that have been submitted or are in progress within the ProcessMaker application.
Get Process Requests
This example demonstrates how to retrieve all the requests of a logged-in user.
Example
<?php
$apiInstance = $api->processRequests();
$processRequests = [];
// Retrieve all process requests accessible to the user
$result = $apiInstance->getProcessesRequests();
foreach ($result->getData() as $processRequest) {
$processRequests[] = [
'id' => $processRequest->getId(),
'status' => $processRequest->getStatus(),
'processId' => $processRequest->getProcessId()
];
}
// Include additional data and associated process information
$type = null; // Specify the type of requests to retrieve (canceled|progress|completed|error)
$filter = null; // Filter results by a specific string (searches Name, Description, and Status)
$order_by = 'id'; // Field to order results by
$order_direction = 'asc'; // Order direction (asc|desc)
$per_page = null; // Number of results per page (default: null)
$include = 'process,data'; // Include data from related models in the payload (comma-separated list)
$result = $apiInstance->getProcessesRequests($type, $filter, $order_by, $order_direction, $per_page, $include);
foreach ($result->getData() as $processRequest) {
$processRequests[] = [
'id' => $processRequest->getId(),
'status' => $processRequest->getStatus(),
'processName' => $processRequest->getProcess()['name'],
'requestData' => $processRequest->getData(),
];
}
// Return the list of process requests
return ['processRequests' => $processRequests];
?>
Update Process Request
This example demonstrates how to update an existing process request.
Example
<?php
$apiInstance = $api->processRequests();
$processRequestId = 4; // ID of the process request to update
$include = 'data'; // Include the request data in the retrieved process request
$processRequest = $apiInstance->getProcessRequestById($processRequestId, $include);
$data = $processRequest->getData();
$data['newItem'] = 'test2'; // Modify the request data as desired
$processRequestEditable = new \ProcessMaker\Client\Model\ProcessRequestEditable();
$processRequestEditable->setData($data);
$apiInstance->updateProcessRequest($processRequestId, $processRequestEditable);
// If no errors are thrown, the process request was successfully updated
return ['success' => true];
?>
Delete Process Request
This example demonstrates how to delete an existing process request.
Example
<?php
$apiInstance = $api->processRequests();
$processRequestId = 4; // ID of the process request to delete
$apiInstance->deleteProcessRequest($processRequestId);
// If no errors are thrown, the process request was successfully deleted
return ['success' => true];
?>
Processes
Processes are essential components in the ProcessMaker application, as they represent the workflows designed and developed by business architects and developers. These workflows define the sequence of tasks, actions, and decisions required to accomplish specific business objectives.
Start a New Process Request
This example demonstrates how to start a new process request.
Example
<?php
$apiInstance = $api->processes();
$process_id = 1; // ID of the process to start
$event = 'node_1'; // Node ID of the start event
$body = new \stdClass; // Object to store request data
$body->foo = 'bar'; // Customize the request data as desired
$processRequest = $apiInstance->triggerStartEvent($process_id, $event, $body);
// Return the ID of the newly created process request
return ['newProcessRequestId' => $processRequest->getId()];
?>
Get Processes
This example demonstrates how to retrieve information about all the processes the user has access to.
Example
<?php
$apiInstance = $api->processes();
$processes = [];
// Retrieve all processes accessible to the user
$result = $apiInstance->getProcesses();
foreach ($result->getData() as $process) {
$processes[] = [
'id' => $process->getId(),
'name' => $process->getName(),
'process_category_id' => $process->getProcessCategoryId(),
'status' => $process->getStatus(),
];
}
// Optional Parameters
$filter = 'test'; // Filter results by a specific string
$order_by = 'id'; // Field to order results by
$order_direction = 'asc'; // Order direction (asc|desc)
$per_page = 5; // Number of results per page
$status = 'ACTIVE'; // Filter results by process status (ACTIVE or INACTIVE)
$include = 'category'; // Include data from related models in the payload (comma-separated list)
$result = $apiInstance->getProcesses($filter, $order_by, $order_direction, $per_page, $status, $include);
foreach ($result->getData() as $process) {
$processes[] = [
'id' => $process->getId(),
'name' => $process->getName(),
'categoryName' => $process->getCategory()['name'],
'status' => $process->getStatus(),
];
}
// Return the list of processes
return ['processes' => $processes];
?>
Get Process
This example demonstrates how to retrieve information about a specific process.
Example
<?php
$apiInstance = $api->processes();
$process = $apiInstance->getProcessById(12); // ID of the process to retrieve
// Return the details of the process
return [
'name' => $process->getName(),
'categoryName' => $process->getCategory()['name'],
'status' => $process->getStatus(),
];
?>
Delete Process
This example demonstrates how to delete an existing process.
Example
<?php
$apiInstance = $api->processes();
$process = $apiInstance->deleteProcess(81); // ID of the process to delete
// If no errors are thrown, the process was successfully deleted
return ['success' => true];
?>
Export Process
This example demonstrates how to export a process from your ProcessMaker instance.
Example
<?php
$apiInstance = $api->processes();
$process_id = 1; // ID of the process to export
$result = $apiInstance->exportProcess($process_id);
// Return the download URL of the exported process
return [
'downloadUrl' => $result->getUrl(),
];
?>
Import Process
This example demonstrates how to import a process into your ProcessMaker instance.
Example
<?php
$apiInstance = $api->processes();
$exportedProcess = 'https://my-server/my-process.json'; // URL of the exported process file
$tmpFile = '/tmp/my-process.json'; // Temporary file to store the downloaded process file
copy($exportedProcess, $tmpFile); // Download the process file
$result = $apiInstance->importProcess($tmpFile); // Import the process
// Return the ID of the imported process
return [
'importedProcessId' => $result->getProcess()['id']
];
?>
Screen Categories
Screen categories play a crucial role in the ProcessMaker application as they provide a structured way to organize screens, enabling users to maintain better control over their workflow processes.
Get Screen Categories
This example demonstrates how to retrieve information about screen categories.
Example
<?php
$apiInstance = $api->screenCategories();
$screenCategories = [];
$result = $apiInstance->getScreenCategories();
// Iterate over each screen category object returned by the API
foreach ($result->getData() as $screenCategory) {
$screenCategories[] = [
'id' => $screenCategory->getId(),
'name' => $screenCategory->getName(),
'status' => $screenCategory->getStatus(),
];
}
// Return an array of screen categories with its respective IDs, names, and statuses
return ['screenCategories' => $screenCategories];
?>
Get Screen Category
This example shows how to retrieve information about a specific screen category.
Example
<?php
$apiInstance = $api->screenCategories();
$screenCategory = $apiInstance->getScreenCategoryById(10); // ID of the screen category to retrieve
// Return the details of the screen category
return [
'name' => $screenCategory->getName(),
'status' => $screenCategory->getStatus(),
];
?>
Create Screen Category
This example demonstrates how to create a new screen category.
Example
<?php
$apiInstance = $api->screenCategories();
$screen_category_editable = new \ProcessMaker\Client\Model\ScreenCategoryEditable();
$screen_category_editable->setName('Procurement'); // Set the name of the new screen category
$screen_category_editable->setStatus('ACTIVE'); // Set the status of the new screen category
$newScreenCategory = $apiInstance->createScreenCategory($screen_category_editable);
// Return the ID of the newly created screen category
return ['newScreenCategoryId' => $newScreenCategory->getId()];
?>
Update Screen Category
This example demonstrates how to update an existing screen category.
Example
<?php
$apiInstance = $api->screenCategories();
$screenCategory = $apiInstance->getScreenCategoryById(20); // ID of the screen category to update
$screenCategory->setName("Healthcare"); // Set the new name for the screen category
$apiInstance->updateScreenCategory($screenCategory->getId(), $screenCategory);
// If no errors are thrown, then the screen category was successfully updated
return ['success' => true];
?>
Delete Screen Category
This example demonstrates how to delete a screen category.
Example
<?php
$apiInstance = $api->screenCategories();
$apiInstance->deleteScreenCategory(20); // ID of the screen category to delete
// If no errors are thrown, then the screen category was successfully deleted
return ['success' => true];
?>
Screens
Screens are essential components within the ProcessMaker application that facilitate interaction with end users and enable data capture. These web-based forms play a crucial role in gathering input and displaying information during workflow processes.
Get Screens
This example shows how to retrieve all the screens the user has access to.
Example
<?php
$apiInstance = $api->screens();
$screens = [];
// Get all screens
$result = $apiInstance->getScreens();
foreach ($result->getData() as $screen) {
$screens[] = [
'id' => $screen->getId(),
'title' => $screen->getTitle(),
'config' => $screen->getConfig(),
];
}
// Return the list of screens
return ['screens' => $screens];
?>
Get screen
This example demonstrates how to retrieve information about a specific screen.
Example
<?php
$apiInstance = $api->screens();
$screen = $apiInstance->getScreensById(63); // ID of the screen to retrieve
// Return the details of the screen
return [
'screen' => [
'title' => $screen->getTitle(),
'config' => $screen->getConfig(),
],
];
?>
Export screen
This example demonstrates how to export a screen from your ProcessMaker instance.
Example
<?php
$apiInstance = $api->screens();
$result = $apiInstance->exportScreen(14); // ID of the screen to export
// Return the download URL of the exported screen
return ['downloadUrl' => $result->getUrl()];
?>
Import screen
This example demonstrates how to import a screen into your ProcessMaker instance.
Example
<?php
$apiInstance = $api->screens();
$exportedScreen = 'http://my-server/my-screen.json'; // URL or local path of the exported screen file
$tmpFile = '/tmp/my-screen.json'; // Temporary file to store the exported screen
copy($exportedScreen, $tmpFile); // Download or copy the exported screen to the temporary file
$result = $apiInstance->importScreen($tmpFile);
// Return the import result status
return ['importResult' => $result->getStatus()];
?>
Tasks
Tasks represent specific activities or steps within a workflow process that require user action or intervention.
Get Tasks
This example demonstrates how to retrieve information about all the tasks of your instance.
Example
<?php
$apiInstance = $api->tasks();
$tasks = [];
// Returns all tasks that the user has access to
$result = $apiInstance->getTasks();
foreach ($result->getData() as $task) {
$tasks[] = [
'id' => $task->getId(),
'name' => $task->getElementName(),
'processRequestId' => $task->getProcessRequestId(),
'status' => $task->getStatus(),
'userId' => $task->getUserId(),
];
}
// Optional arguments
$process_request_id = 5; // int | Process request ID
$filter = 'Form Task'; // string | Filter by task ID, node name, or request data
$order_by = 'id'; // string | Field to order results by
$order_direction = 'asc'; // string | Order direction (ascending or descending)
$include = 'process,user'; // string | Include data from related models in payload. Comma-separated list.
$result = $apiInstance->getTasks($process_request_id, $filter, $order_by, $order_direction, $include);
foreach ($result->getData() as $task) {
$tasks[] = [
'id' => $task->getId(),
'name' => $task->getElementName(),
'status' => $task->getStatus(),
'userEmail' => $task->getUser()['email'],
'processName' => $task->getProcess()['name'],
];
}
// Return the list of tasks
return ['tasks' => $tasks];
?>
Get Task
This example demonstrates how to retrieve information about a specific task.
Example
<?php
$apiInstance = $api->tasks();
$taskId = 7; // ID of the task to retrieve
$task = $apiInstance->getTasksById($taskId);
// Return the details of the task
return [
'task' => [
'name' => $task->getElementName(),
'status' => $task->getStatus(),
'userId' => $task->getUserId(),
],
];
?>
Update Task
This example demonstrates how to update or complete a specific task.
Example
<?php
$apiInstance = $api->tasks();
$taskId = 130; // ID of the task to update
$task = $apiInstance->getTasksById($taskId);
$process_request_token_editable = new \ProcessMaker\Client\Model\ProcessRequestTokenEditable();
$process_request_token_editable->setStatus('COMPLETED');
$process_request_token_editable->setData(['addToRequestData' => 'a value']);
$result = $apiInstance->updateTask($taskId, $process_request_token_editable);
// If no errors are thrown, then the task was successfully updated
return ['success' => true];
?>
Users
Users are individuals who have access to the ProcessMaker application and can interact with workflow processes.
Get Users
This example demonstrates how to retrieve all the users of your ProcessMaker instance.
Example
<?php
$apiInstance = $api->users();
$users = [];
// Get all users
$result = $apiInstance->getUsers();
foreach ($result->getData() as $user) {
$users[] = ['username' => $user->getUsername(), 'email' => $user->getEmail()];
}
// Optional arguments
$status = 'ACTIVE'; // string | Filter results by status (ACTIVE or INACTIVE)
$filter = 'admin'; // string
$order_by = 'id'; // string | Field results by ID
$order_direction = 'asc'; // string | Order direction (ascending or descending)
$per_page = 1; // int | Number of users to retrieve per page
$include = ''; // string | Include data from related models in payload. Comma-separated list.
$result = $apiInstance->getUsers($status, $filter, $order_by, $order_direction, $per_page, $include);
foreach ($result->getData() as $user) {
$users[] = ['username' => $user->getUsername(), 'email' => $user->getEmail()];
}
// Return the list of users
return ['users' => $users];
?>
Get User
This example shows how to retrieve information about a specific user.
Example
<?php
$apiInstance = $api->users();
$user = $apiInstance->getUserById(5); // Set the user ID
// Return the details of the user
return [
'user' => [
'username' => $user->getUsername(),
'email' => $user->getEmail(),
'status' => $user->getStatus(),
],
];
?>
Create User
This example illustrates how to create a new user in your ProcessMaker instance.
Example
<?php
$apiInstance = $api->users();
$user = new \ProcessMaker\Client\Model\UsersEditable();
$user->setFirstname('John');
$user->setLastname('Due');
$user->setUsername('johndue');
$user->setPassword('Passcode123');
$user->setEmail('john.due@processmaker.com');
$user->setStatus('ACTIVE');
$newUser = $apiInstance->createUser($user);
// Return the ID of the newly created user
return ["newUserId" => $newUser->getId()];
?>
Update User
This example demonstrates how to update an existing user in your ProcessMaker instance.
Example
<?php
$apiInstance = $api->users();
$userId = 14;
$user = $apiInstance->getUserById($userId);
// Update user details
$user->setFirstname('John Waters');
$user->setEmail('john.waters@processmaker.com');
// Call the updateUser method to update the user
$result = $apiInstance->updateUser($userId, $user);
// If no errors are thrown, then the user was successfully updated
return ['success' => true];
?>
Delete User
This example demonstrates how to delete a user from your ProcessMaker instance.
Example
<?php
$apiInstance = $api->users();
// Set the user ID to be deleted
$userId = 14;
$apiInstance->deleteUser($userId);
// If no errors are thrown, then the user was successfully deleted
return ['success' => true];
?>
Conclusion
In conclusion, this guide provides developers with a wealth of practical examples to leverage the capabilities of ProcessMaker effectively. These examples cover a range of use cases, offering insights into best practices and time-saving techniques for process development. By incorporating these examples into the script tasks within the ProcessMaker platform, developers can enhance their productivity and streamline their workflow automation projects.
Establish hierarchy in your organization to be able to escalate Tasks to an assignee's manager, delegate work to another user, and schedule working hours for each user.
Overview
Use the Advanced User package to establish managerial and work-delegation relationships within your organization by configuring managers to users and groups. Set working schedules for each user, and configure to whom to delegate work when that user is out of the office or outside of scheduled working hours.
The Advanced User package has the following features:
Configure the manager for each manager and for each group. Form Task elements and Manual Task elements within Process models can then be configured to escalate to the manager for that Task assignee. For example, design a Process such that if the Task assignee does not complete a Task within a day of it being assigned, route that Process to the Task assignee's manager.
Use the Schedule status for each user to set the schedule for each user to be available to work on Tasks. In doing so, set which days of the week and hours of those days in 24-hour format each user is available. The Schedule status becomes that user's status when viewing users in the organization.
Use the Out of Office status for when a user is not available for work, such as when that user takes leave. The Out of Office status becomes that user's status when viewing users in the organization.
Configure for each user to whom to delegate work when that user is not available in the following circumstances:
That user has the Out of Office status: Newly assigned Tasks automatically reassign to the delegated user.
That user has the Scheduled status: Newly assigned Tasks automatically reassign to the delegated user when the initial Task assignee is not scheduled to work.
Select a Process Manager for each Process. The Process Manager understands the Process design and workflow dynamics to troubleshoot Request routing incidents. This user is assigned Tasks in that Process's Requests in which workflow would otherwise pause indefinitely when that Request's workflow cannot continue to a valid Task assignee for any of the following reasons:
The Request routes to a Task assignee whose user account is inactive.
The Request routes to the Task assignee's manager, but that user's account is not configured with a manager.
The Task assignee does not have a user account manager, and is a member of two or more groups which have different managers.
The Request routes to a Task assignee in which that user's account is set with the following statuses:
The user's account is set to Out of Office status, but not configured with a delegated user to assign new Tasks while with this status.
The user's account is set to Scheduled status, is not scheduled to work when the Task is assigned, and is not configured with a delegated user to assign new Tasks.
The Process Manager is assigned the Task in that Request, and may then indicate how to route that Request. The Process Manager may optionally cancel that Request if that user is among those selected to do so.
Assign a Task to the Process Manager when configuring Form Task elements and Manual Task elements.
Configure Form Task elements and Manual Task elements to escalate a Task to the Task assignee's manager.
Configure Form Task elements and Manual Task elements to allow a Task assignee to escalate the current Task to her or his manager.
Enable User Signals to broadcast Signals for specific user events. When a user account is created, deleted, read, and/or updated, optionally broadcast a Signal of that event. Signal-type BPMN 2.0 elements listening for Signal events in your Process models can then trigger. For example, each time a user account is created, enable the Create user Signal to trigger a Signal Start Event element in a Process model that starts a Request to onboard a new employee in your organization.
Add user extended properties to become settings in all user accounts. For example, to add user extended properties labeled "Employee ID" and "Hire Date" to enter each employee's ID number and hire date.
See the following topics regarding how to use the Advanced User package:
Participating in a workflow via Intermediate Web Entry (Authenticated)
This guide provides an in-depth of the process of seamlessly embedding ProcessMaker's authenticated intermediate web entry forms into external third-party web applications.
Step 3: Customize the iFrame Attributes (Optional)
You can tailor the attributes of the iFrame to seamlessly align with your specific needs and preferences. This affords you the opportunity to fine-tune elements like width, height, frameborder, and various other attributes, thereby ensuring a perfect integration of the iFrame within your application's overall design and layout scheme.
Step 4: Test and Verify the Integration
Remember to save all modifications before refreshing your web application. Confirm that the embedded intermediate web entry form is not only displayed but also operating seamlessly within your application's framework. Test the functionality of the embedded web entry form, such as approving/completing a request to guarantee a flawless user experience that aligns perfectly with your expectations.
Output Preview: Embedded ProcessMaker Intermediate Web Entry Form
After you have completed the steps above, verify ProcessMaker's intermediate web entry form is embedded into your Web application.
Conclusion
By following the step-by-step instructions outlined in this comprehensive guide, you'll be equipped to seamlessly incorporate ProcessMaker's dynamic authenticated intermediate web entry form into your own web application. This integration, facilitated through the utilization of an iFrame, empowers you to effortlessly manage and fulfill requests with enhanced efficiency and effectiveness.
ProcessMaker Platform Packages
Packages extend functionality from the ProcessMaker Platform Open-Source edition. None of these packages are available in the Open-Source edition. These are available only for the Enterprise edition.
What is a Package?
In the context of ProcessMaker Platform, a package is a stand-alone container to distribute and install a or to extend current functionality.
Technically, a package in ProcessMaker Platform is a compound from routes, controllers, models, and other assets that have a Provider class that functions as a union bridge between ProcessMaker Platform and the Laravel package from which ProcessMaker Platform is built.
Configure Password Authentication for the Client Application
Follow these steps to configure password authentication for the client application:
. The Auth Clients page displays.
Click the +Auth Client button. The Create Auth-Client screen displays.
In the Name setting, enter a name for the client authentication.
Select the grant type you will be using.
Click Save. A new authenticated client is created.
The authenticated client in the Auth Clients page contains the client secret, and the client id is the primary key of the table. In the example above, Passwrod Grant application has the client id of 3, and then click the Copy Client Secret to Clipboard icon.
That's it. You are now ready to attempt authenticating with the ProcessMaker REST API.
Collections Package
Create multiple sets of schema-less data records using Screens that do not require an external database.
Overview
Use the Collections package to maintain sets of schema-less data records using , each referred to as a . The Collections package has the following features:
An external database is not required to store Collections. Collections are maintained in the ProcessMaker instance.
A Collection is composed of a set of records. Similar to a relational database, a record is a grouping of fields that represent related data. Design the grouping of fields using Screens to represent this data, thereby making it easy for any user to view, create, or edit record data if they have the appropriate permission(s) to do so. Within a Collection, potentially use different Screens to create a record, edit a record, or view a record within that Collection. This provides greater control in how information within a Collection is consumed by various stakeholders in the Collection. Consider the following use case:
Create a record: Allow an assistant to create a record using Screen for this purpose, such as in a medical practice.
Edit a record: In the same medical practice, a dedicated Screen allows a nurse to edit patient information after the new patient has granted legal permission for medical staff to edit sensitive medical information (in compliance with HIPAA standards).
View a record: Use a third Screen that references identical record information, but limits the content and editing so that the medical practice complies with patient legal protections.
Collections are schema-less, meaning that any type or format of data may be stored in a Collection. Because Collections are schema-less, changing the thereby changes the types of information or data to all records within that Collection. You are not constrained by how you define a Collection when you create it. For example, if you want to allow Collection stakeholders to attach a file that becomes associated with a record, add a in the applicable Screen(s) that represent information in that Collection; the new File Upload control becomes available in all records in that Collection.
Determine which users and/or groups have permission to view, create, edit, or delete Collections by setting . These permissions are different than that specify which users and/or groups can manage records within an individual Collection.
into a Collection to simultaneously create multiple records from the CSV file's data records.
The Collections package integrates with the package. Use the Saved Searches package to save and share searches associated with a Collection. See Saved Searches Package. Use ProcessMaker Query Language () parameters to compose queries to . Furthermore, changes to a Collection may then be applied to Saved Searches associated with that Collection.
Establish . A Collection relationship links two Collections by designating one Collection as a parent Collection, the other as a child Collection, and defining data keys or columns linking both Collections. The Collection from which this relationship is created is automatically designated as the parent Collection. The relationship is a one-to-many relationship such that a record in the parent Collection can have multiple matching records in the child Collection.
An external database is not required to store Collections. Collections are maintained in the ProcessMaker instance.
The Collections package integrates with the Saved Searches and Data Connector packages:
Saved Searches package: Use the Saved Searches package to save and share searches. See .
Data Connector package: Access both Collection records and third-party data sources from any ProcessMaker asset, including Screens, Scripts, and Process models. See .
Auth Package
Use the Auth package to allow ProcessMaker users to log on using SSO, SAML, LDAP and SCIM authentication protocols.
Overview
Use the Auth package to authenticate ProcessMaker Platform users to log on using any of the following protocols:
Lightweight Directory Access Protocol (LDAP): Synchronize users from LDAP organization to ProcessMaker Platform.
Single sign-on (SSO): SSO is an identification system that allows users to log on to ProcessMaker Platform using any of the following third-party services:
products
SSO via Security Assertions Markup Language (SAML) 2.0: SAML is an open-standard format to exchange authentication and authorization data between parties when establishing a SSO session.
System for Cross-domain Identity Management (SCIM): SCIM is an open standard that allows for the automation of user provisioning.
The Auth package is based on framework, which is an open-standard protocol that describes how unrelated servers and services can securely authenticate access to their assets without sharing log on credentials.
Part 5: The Screen & Form Elements
Overview
Completed code: /
Step 1: ScreenComponent
The ScreenComponent serves as the primary component for our form interactions. While ProcessMaker permits several forms within a single Screen, each task should associate with one Screen that can encompass multiple forms. Any task should have a single Screen, but can have multiple forms. They will be contained within an array in the response payload when making the API request.
When we get the form part, we will use the FormComponent as well as others to ultimately render the form.
The ScreenComponent is passed the required data that will be passed down through to the individual elements on the form.
Template
app-screen.component.html
<!-- Use app-form-element to render form elements -->
<app-form
*ngFor="let screen of screens?.config"
[form]="screen"
[request]="request"
[css]="screens.custom_css"
[computed]="screens.computed">
</app-form>
Typescript
app-screen.component.ts
import { Component, Input, OnInit, Output, EventEmitter } from '@angular/core';
import { Router, ActivatedRoute } from '@angular/router';
import { TasksService, ProcessRequestsService } from 'api';
import { DbService } from 'src/app/services/db.service';
@Component({
selector: 'app-screen',
templateUrl: './app-screen.component.html',
})
export class ScreenComponent implements OnInit {
// Define the request object, type can be further specified
request: any;
// Define properties with appropriate types
exists: any; // Define the type as per your requirements
processRequestId: number | null = null; // Define the type as number or null
taskId: number | null = null; // Define the type as number or null
@Output() screens: any; // Define the type as per your requirements
data: any; // Define the type as per your requirements
response: any; // Define the type as per your requirements
screenConfig: any;
@Output() screenEvent: EventEmitter<any> = new EventEmitter(); // Define the type as per your requirements
constructor(
private route: ActivatedRoute,
private router: Router,
public requestApi: ProcessRequestsService,
public tasksApi: TasksService,
private db: DbService
) {}
ngOnInit(): void {
console.log(this);
// Parse the values as numbers, and handle the possibility of null values
// Convert processRequestId and taskId from string to number, handle null values
this.processRequestId =
Number(this.route.snapshot.paramMap.get('processRequestId')) || null;
this.taskId = Number(this.route.snapshot.paramMap.get('taskId')) || null;
// Check if taskId is not null before proceeding
if (this.taskId !== null) {
// Set the credentials for the tasks API
this.tasksApi.configuration.credentials['pm_api_bearer'] =
this.db.load('access_token') || '';
// Fetch the task by ID and include specific related data
this.tasksApi
.getTasksById(
this.taskId,
'processRequest,user,data,screen,definition,screenRef'
)
.subscribe(
(response) => {
// Assign the response to the request object
this.screens = response.screen;
this.request = response.data;
//console.log(this);
},
(error) => {
// Log any errors
}
);
}
}
handleScreenEvent(event: any) {
// Handle any screen-related event here
this.screenEvent.emit(event);
}
}
Step 2: FormComponent
Given that a Screen can associate with multiple forms, our design ensures minimal code adjustments to accommodate this.
The FormComponent passes through to the form element the request data and definitions for the different elements.
Template
app-form.component.html
<div class="container-fluid">
<div class="table-container mt-4">
<!-- create an html stylesheet block -->
<style>
{{ css }}
</style>
<form (ngSubmit)="submitForm()">
<!-- Use app-form-element to render form elements -->
<h4>{{ form.name }}</h4>
<div class="container">
<ng-container *ngFor="let element of form.items">
<app-form-element
[element]="element"
[request]="request"
[calcPropsValues]="calcPropsValues"></app-form-element>
</ng-container>
</div>
</form>
</div>
</div>
Typescript
app-form.component.html
import { Component, Input, OnInit } from '@angular/core';
import { Router, ActivatedRoute } from '@angular/router';
import { TasksService, ProcessRequestsService } from 'api';
import { DbService } from 'src/app/services/db.service';
import { environment } from 'src/environments/environment';
@Component({
selector: 'app-form',
templateUrl: './app-form.component.html',
})
export class FormComponent implements OnInit {
// Define the request object, type can be further specified
@Input() request: any;
// Define properties with appropriate types
exists: any; // Define the type as per your requirements
processRequestId: number | null = null; // Define the type as number or null
taskId: number | null = null; // Define the type as number or null
@Input() screens: any; // Define the type as per your requirements
@Input() data: any; // Define the type as per your requirements
@Input() response: any; // Define the type as per your requirements
@Input() element: any; // Define the type as per your requirements
isMultiColumn: boolean = false;
@Input() cols: any;
@Input() form: any;
@Input() css: any;
@Input() computed: any;
calcPropsValues: any = {};
// Constructor with necessary dependencies
constructor(
private route: ActivatedRoute,
private router: Router,
public requestApi: ProcessRequestsService,
public tasksApi: TasksService,
private db: DbService
) {}
ngOnInit() {
//console.log(this);
this.calcPropsValues = this.executeJavascripts(this.computed);
this.processRequestId =
Number(this.route.snapshot.paramMap.get('processRequestId')) || null;
this.taskId = Number(this.route.snapshot.paramMap.get('taskId')) || null;
if (environment.customCss === true) {
const styleEl = document.createElement('style');
styleEl.innerHTML = this.css;
document.head.appendChild(styleEl);
}
// add any custom css
// if (this.css.length > 0) {
// const sanitizedCSS = this.sanitizeCSS(this.css);
// if (sanitizedCSS) {
// // Inject CSS into the page
// const styleEl = document.createElement('style');
// styleEl.innerHTML = sanitizedCSS;
// document.head.appendChild(styleEl);
// } else {
// console.warn('CSS was sanitized out, nothing was injected.');
// }
// }
}
executeJavascripts(computed: any[]): { [key: string]: any } {
const result: { [key: string]: any } = {};
computed.forEach((computed) => {
if (computed.type === 'javascript') {
try {
const fn = new Function(computed.formula);
result[computed.property] = fn();
} catch (e) {
console.error(e);
}
}
});
return result;
}
/**
* Given a raw CSS string, sanitize it by stripping out
* non-conforming characters and properties.
*
* This approach uses a whitelist methodology, allowing only
* specific properties, values, and characters.
*
* @param {string} css Raw CSS string
* @returns {string} Sanitized CSS string
*/
sanitizeCSS(css: string) {
// 1. Strip out any comments
let cleanedCSS = css.replace(/\/\*[^*]*\*+([^/*][^*]*\*+)*\//g, '');
// 2. Split by braces to extract selectors and properties
const chunks = cleanedCSS.split('}');
cleanedCSS = chunks
.map((chunk) => {
const [selector, properties] = chunk.split('{');
// 2.1. Sanitize the selector
const sanitizedSelector = selector
.replace(/[^\w\s\.,\[\]='-]+/g, '')
.trim();
// 2.2. Sanitize the properties
let sanitizedProperties = '';
if (properties) {
const propList = properties.split(';');
propList.forEach((prop) => {
const [property, value] = prop.split(':').map((p) => p.trim());
sanitizedProperties += `${property}: ${value}; `;
});
}
return sanitizedSelector
? `${sanitizedSelector} { ${sanitizedProperties}}`
: '';
})
.join(' ');
return cleanedCSS;
}
// Function to handle form submission
submitForm() {
// Load access token from the database
const accessToken = this.db.load('access_token') as string | undefined;
// If access token exists, set it in the task API configuration
if (accessToken)
this.requestApi.configuration.credentials['pm_api_bearer'] = accessToken;
let payLoad = {
data: this.request,
status: 'COMPLETED',
};
// Call getTasks method from tasksApi with parameters null and 'ACTIVE'
this.tasksApi.updateTask(Number(this.taskId), payLoad).subscribe(
(response: any) => {
// Handle successful response
console.log(response); // Log the response to the console
this.router.navigate(['tasks']);
},
(error) => {
// Handle error response
console.log(error); // Log the error to the console
}
);
//console.log(this);
}
}
interface Javascript {
id: number;
name: string;
type: string;
formula: string;
property: string;
}
Step 3: FormElementComponent
Our application design emphasizes easy extensibility and customization. As of the time of this writing, the form elements are supported and shipped with the app. However, as you will see, it is relatively easy to add more elements.
Form Elements
The FormElementComponent is utilized to render varied components, managing logic via ngSwitch.
The main FormElementComponent class should be placed at src/app/components/form-element/app-form-element.component.ts and src/app/components/form-element/app-form-element.component.html, respectively.
The various form elements are contained with src/app/components/form-element/elements.
We need to add all the new components to our AppModule.
Typescript
app.module.ts
import { NgModule } from '@angular/core';
import '@angular/compiler';
import { AppRoutingModule } from './routing/app-routing.module';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { NgxPaginationModule } from 'ngx-pagination';
import { CommonModule } from '@angular/common';
import { RootComponent } from './components/root/app-root.component';
import { LoginComponent } from './components/login/login.component';
import { TasksComponent } from './components/tasks/app-tasks.component';
import { NavigationComponent } from './components/nav/navigation.component';
import { FormComponent } from './components/form/app-form.component';
import { ApiModule } from 'api';
import { FormElementComponent } from './components/form-element/app-form-element.component';
import { ScreenComponent } from './components/screen/app-screen.component';
import { MultiColumnComponent } from './components/form-element/elements/muti-column/app-multi-column.component';
import { InputComponent } from './components/form-element/elements/input/app-element-input.component';
import { AppElementDefaultComponent } from './components/form-element/elements/default/app-element-default.component';
import { ButtonComponent } from './components/form-element/elements/buttons/app-element-button.component';
import { AppBreadcrumbsComponent } from './components/breadcrumbs/app-breadcrumbs.component';
import { AppElementHtmlViewerComponent } from './components/form-element/elements/html-viewer/app-element-html-viewer.component';
import { AppElementImageComponent } from './components/form-element/elements/image/app-element-image.component';
import { AppElementUploadFileComponent } from './components/form-element/elements/upload-file/app-element-upload-file.component';
@NgModule({
declarations: [
RootComponent,
LoginComponent,
TasksComponent,
NavigationComponent,
FormComponent,
FormElementComponent,
ScreenComponent,
MultiColumnComponent,
InputComponent,
ButtonComponent,
AppBreadcrumbsComponent,
AppElementDefaultComponent,
AppElementHtmlViewerComponent,
AppElementImageComponent,
AppElementUploadFileComponent,
],
imports: [
BrowserModule,
AppRoutingModule,
HttpClientModule,
NgxPaginationModule,
FormsModule,
ReactiveFormsModule,
CommonModule,
ApiModule,
],
providers: [],
bootstrap: [RootComponent],
})
export class AppModule {}
Review
After your code finishes compiling, click on the "Next Task" button in the inbox (assuming you have open cases) and you should see your form, just as I have posted a screenshot below.
We recommend playing around with simple forms first, and then adding complexity as you get more comfortable.
If you liked this or found it helpful, please let us know by leaving a rating and sharing on social!
If not, please let us know!
PRs are always welcomed!
Part 3: Components
Overview
In this section, we'll explore the essential components of our application.
Completed code: /
(not technically a component but necessary)
Step 1: The Router
Before adding our components, we must configure the router and verify user authentication using our Guard.
Here is the updated code for the router.
The oauth/callback path is crucial for the OAuth 2.0 Authorization Flow.
The application will crash at this point, but that's ok! This is expected. We will fix it in a moment.
Step 2: RootComponent
Until now, we've used the default hello world template at src/app/components/app.component.ts. We'll remove this file, replacing it with the root component.
If you check the index.html file, you will see that there is an element app-root which is where the application will be embedded within.
Note how we have three new components in the root component.
app-navigation is where the top nav bar will be inserted.
app-breadcrumbs will show where you are in the application, right below the nav bar but above the main content section.
router-outlet is where the Angular router will inject the rest of the components dynamically, based on the logic we implement.
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app-root.component.html',
})
export class AppComponent {
title = 'pm4Angular';
constructor() {}
}
Step 2: LoginComponent
Let's craft our inaugural component: the login page. The flow will use Authorization Code grant_type. This will redirect the user to the ProcessMaker installation you created the client application in, where they login and are then redirected back to the application with the authorization code.
The components we will be creating will consist of two files: the template file and the typescript file.
import { Component, OnInit } from '@angular/core';
import { AuthService } from 'src/app/services/auth.service';
import { ActivatedRoute } from '@angular/router';
@Component({
selector: 'app-login',
templateUrl: './login.component.html',
})
export class LoginComponent implements OnInit {
// Injecting AuthService and ActivatedRoute to handle authentication and route parameters
constructor(
public authService: AuthService,
private activatedRoute: ActivatedRoute
) {}
ngOnInit() {
// Subscribing to query parameters to detect the authorization code
this.activatedRoute.queryParams.subscribe((params) => {
// Checking if the 'code' parameter is present
if (params['code']) {
// Calling getAccessToken method in AuthService to handle the OAuth token exchange
// No need for then or catch here as the AuthService method takes care of the response handling
this.authService.getAccessToken(params['code']);
}
});
}
// Method to initiate the login process by calling the login method in AuthService
login() {
this.authService.login();
}
// Method to initiate the logout process by calling the logout method in AuthService
logout() {
this.authService.logout();
}
}
Step 3: NavigationComponent
The navigation component houses the header logo and a logout button.
The ngIf="authService.authenticated" ensures the navbar displays only when the user is authenticated using our auth service.
import { Component } from '@angular/core';
import { AuthService } from 'src/app/services/auth.service';
import { DbService } from 'src/app/services/db.service';
import { ActivatedRoute, Router } from '@angular/router';
import { BrowserModule } from '@angular/platform-browser';
@Component({
selector: 'app-navigation',
templateUrl: './navigation.component.html',
})
export class NavigationComponent {
title: any;
homeCrumb: any;
currentCrumb: any;
constructor(
public authService: AuthService,
public db: DbService,
public route: ActivatedRoute,
public router: Router,
public browserModule: BrowserModule
) {}
// Method to log out the user by calling the logout method from the AuthService
logout() {
this.authService.logout();
}
}
import { Component, OnInit } from '@angular/core';
import { AuthService } from 'src/app/services/auth.service';
import { DbService } from 'src/app/services/db.service';
import { ActivatedRoute, Router } from '@angular/router';
import { BrowserModule } from '@angular/platform-browser';
@Component({
selector: 'app-breadcrumbs',
templateUrl: './app-breadcrumbs.component.html',
})
export class AppBreadcrumbsComponent implements OnInit {
title: any;
homeCrumb: any;
currentCrumb: any;
constructor(
public authService: AuthService,
public db: DbService,
public route: ActivatedRoute,
public router: Router,
public browserModule: BrowserModule
) {}
ngOnInit(): void {}
currentPageTitle() {
return (this.title = window.document.title);
}
homePageTitle() {
return (this.homeCrumb = 'Home');
}
}
Step 5: AppModule
The updated app.module.ts contains the dependencies:
Router
RootComponent
LoginComponent
NavigationComponent
AppBreadCrumbsComponent
app.module.ts
import { NgModule } from '@angular/core';
import '@angular/compiler';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { CommonModule } from '@angular/common';
import { AppRoutingModule } from './routing/app-routing.module';
import { RootComponent } from './components/root/app-root.component';
import { LoginComponent } from './components/login/login.component';
import { NavigationComponent } from './components/nav/navigation.component';
import { AppBreadcrumbsComponent } from './components/breadcrumbs/app-breadcrumbs.component';
@NgModule({
declarations: [
RootComponent,
LoginComponent,
NavigationComponent,
AppBreadcrumbsComponent,
],
imports: [
BrowserModule,
HttpClientModule,
FormsModule,
ReactiveFormsModule,
CommonModule,
AppRoutingModule,
],
providers: [],
bootstrap: [RootComponent],
})
export class AppModule {}
Review
By following the steps, navigating to http://localhost:4200/#/login should display the login page.
With the correct OAuth credentials and Client Application setup, logging into ProcessMaker should redirect you back to the login page, now displaying the navbar and breadcrumbs, indicating a successful login.
Next Steps
Part 4: The Inbox
Overview
With the core services and components in place, we'll now interface with the ProcessMaker API.
Completed code: /
Step 1: Environment Details
Ensure you have the subsequent details ready for this section:
Client ID
Client Secret
FQDN for your ProcessMaker installation
OAuth Token URL
OAuth Redirect URI
OAuth Authorization URL
You can see what a sample environment.ts file looks like below. This is where you will add the above information.
The TasksComponent relies on the ScreenComponent, which we'll address in the subsequent section. We'll omit it for now and reintroduce it when we're set to render the form.
// Import necessary Angular core modules
import { Component, OnInit } from '@angular/core';
// Import Angular routing modules
import { ActivatedRoute, Router } from '@angular/router';
// Import services related to ProcessRequests and Tasks
import { ProcessRequestsService, TasksService } from 'api';
// Import local database service
import { DbService } from 'src/app/services/db.service';
// Define the Task interface to represent the structure of a task
interface Task {
process_request_id: string; // ID of the associated process request
element_name: string; // Name of the element
advanceStatus: string; // Status of the task advancement
user: { firstname: string; lastname: string }; // User information
process_request: { name: string }; // Process request information
due_at: string; // Due date for the task
id: string; // Unique ID for the task
}
// Component metadata
@Component({
selector: 'app-tasks', // Selector used in templates
templateUrl: './app-tasks.component.html', // Path to the HTML template
})
// TasksComponent class definition
export class TasksComponent implements OnInit {
// Pagination properties
pagination = {
currentPage: 1, // Current page number
itemsPerPage: 10, // Number of items per page
lastPage: null, // Last page number
totalItems: null, // Total number of items
};
// Selected request and task properties
selectedRequest: Request | null = null;
selectedTask: Task | null = null;
userTasks: Task[] = []; // Array to hold user tasks
color = 'green'; // Color property (usage not shown in provided code)
// Constructor with dependency injection
constructor(
private requestApi: ProcessRequestsService, // Process request service
private tasksApi: TasksService, // Task service
private route: ActivatedRoute, // Activated route information
private router: Router, // Router service for navigation
private db: DbService // Database service
) {}
// ngOnInit lifecycle hook
ngOnInit() {
// Load access token from the database
const accessToken = this.db.load('access_token') as string | undefined;
// If access token exists, set it in the task API configuration
if (accessToken) {
this.tasksApi.configuration.credentials['pm_api_bearer'] = accessToken;
}
// Call getTasks method from tasksApi with parameters null and 'ACTIVE'
this.tasksApi.getTasks(undefined, 'ACTIVE').subscribe(
(response: any) => {
// Handle successful response
this.userTasks = response.data; // Assign user tasks from response data
// Create a new ScreenComponent instance
console.log(this.userTasks);
},
(error) => {
// Handle error response
console.log(error); // Log the error to the console
}
);
}
// Method to open a form with given processRequestId and taskId
openScreen(processRequestId: string, taskId: string) {
// Navigate to the 'form' route with parameters
this.router.navigate([
'screen',
{
processRequestId: processRequestId,
taskId: taskId,
},
]);
}
// Placeholder method for getting a user task by ID
getUserTask(id: string) {}
// Placeholder method for getting user tasks by ID
getUserTasks(id: string) {}
}
Step 3: Update the Router
Integrate the new components and their respective paths into the router. The following code demonstrates how to import these components and establish a route for the inbox view.
Now we just need to incorporate the TasksComponent into the AppModule declaration.
app.module.ts
import { NgModule } from '@angular/core';
import '@angular/compiler';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { CommonModule } from '@angular/common';
import { AppRoutingModule } from './routing/app-routing.module';
import { RootComponent } from './components/root/app-root.component';
import { LoginComponent } from './components/login/login.component';
import { NavigationComponent } from './components/nav/navigation.component';
import { AppBreadcrumbsComponent } from './components/breadcrumbs/app-breadcrumbs.component';
import { TasksComponent } from './components/tasks/app-tasks.component';
@NgModule({
declarations: [
RootComponent,
LoginComponent,
NavigationComponent,
AppBreadcrumbsComponent,
TasksComponent,
],
imports: [
BrowserModule,
HttpClientModule,
FormsModule,
ReactiveFormsModule,
CommonModule,
AppRoutingModule,
],
providers: [],
bootstrap: [RootComponent],
})
export class AppModule {}
Review
If you are following along with the tutorial, you should now be able to see your tasks, in your new Angular Inbox!
Next Steps
Part 2: Services & Dependencies
Overview
To achieve our application's desired functionality, we'll create two services. These services will manage the access token storage and facilitate communication with the ProcessMaker API via the SDK.
Completed code: /
Step 1: Create the OAuth Client App
Follow this step-by-step guide to create your OAuth application .
You MUST create the OAuth Client Application in order to consume the ProcessMaker API.
Step 2: Set Up
Main TS
main.ts
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
platformBrowserDynamic()
.bootstrapModule(AppModule)
.catch((err) => console.error(err));
In the above file, we are starting Angular. Note line 5: this is where we bring in our environment variables which we will use to contain all our sensitive information.
The .gitignore file already contains the rule to exclude your actual environment.ts file from any commits. Just make sure to copy and rename the example file!
We are utilizing getbootstrap.com, as that is what the ProcessMaker form builder is built with. Our forms utilize the 12 column grid system that bootstrap is so well known for, as well as other niceties that make our lives easier.
There are CDNs in the html file for fewer steps during installation, but if you prefer to have a local offline (if you are behind a corporate VPN perhaps), you can replace the CDN links.
Note: The current version of the application uses bootstrap version 4.1.3 and jquery 3.3.1.
AppModule
Next, we'll update the app.module.ts file from the previous section to incorporate the Angular router. This is going to tell the application what to render when a user does an action, such as opening the form.
This is the modified code.
app.module.ts
import { NgModule } from '@angular/core';
import '@angular/compiler';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { CommonModule } from '@angular/common';
import { AppComponent } from './components/app.component';
import { AppRoutingModule } from './routing/app-routing.module';
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
HttpClientModule,
FormsModule,
ReactiveFormsModule,
CommonModule,
AppRoutingModule,
],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
Router
Create the directory routing inside src/app/, and then add the file app-routing.module.ts. For now, we will just make it a very simple file since it will not be used yet, at least not until we have somewhere to route TO!
Right now, you will still see the Hello John on the webpage. We need to add a few more things before we will start seeing our application come together.
Guard
The Auth Guard is akin to a security checkpoint. Before navigating to a route (think of it as a destination within your application), this checkpoint checks if the user has the necessary permissions to access that route.
In more technical terms:
It's a service that implements a specific interface (CanActivate, for instance).
When a user tries to navigate to a route, the Auth Guard runs its logic.
If the logic returns true, navigation proceeds.
If it returns false, navigation is halted, often redirecting the user elsewhere.
For example, if you have a route that should only be accessible to logged on users, as is our case, an Auth Guard can check if the user is logged on. If they are, they can proceed to the inbox or form. If not, they will be redirected to the log on page.
Here is the code for our guard. Place it inside a new folder called guards and name is auth.guard.ts.
auth.guard.ts
import { Injectable } from '@angular/core';
import {
ActivatedRouteSnapshot,
CanActivate,
Router,
RouterStateSnapshot,
} from '@angular/router';
import { AuthService } from '../services/auth.service';
@Injectable({
providedIn: 'root',
})
export class AuthGuard implements CanActivate {
// Injecting AuthService to check authentication status and Router to navigate
constructor(private authService: AuthService, private router: Router) {}
// The canActivate method is called by Angular to determine if a route can be activated
canActivate(
route: ActivatedRouteSnapshot,
state: RouterStateSnapshot
): boolean {
// Perform additional authentication checks if needed
this.authService.checkAuthStatus();
// If the user is authenticated, allow the route activation
if (this.authService.authenticated) {
return true;
} else {
// If the user is not authenticated, redirect to the login page with the return URL
// and deny the route activation
this.router.navigate(['login'], {
queryParams: { returnUrl: state.url },
});
return false;
}
}
}
Step 3: Services
DB
This file interfaces with local storage for basic CRUD operations like saving the access token.
db.service.ts
import { Injectable } from '@angular/core';
@Injectable({
providedIn: 'root',
})
export class DbService {
constructor() {}
/**
* Method to save a key-value pair to the local storage.
* @param key - The key under which the value will be stored.
* @param value - The value to be stored.
*/
public save(key: string, value: string): void {
try {
// Attempt to save the key-value pair to the local storage
localStorage.setItem(key, value);
} catch (error) {
// Log an error message if the operation fails
console.error(
`Failed to save value for key "${key}" to local storage.`,
error
);
}
}
/**
* Method to load a value from the local storage by its key.
* @param key - The key of the value to be retrieved.
* @returns The value associated with the specified key, or null if the key does not exist.
*/
public load(key: string): string | null {
try {
// Attempt to retrieve the value associated with the specified key from the local storage
return localStorage.getItem(key);
} catch (error) {
// Log an error message if the operation fails
console.error(
`Failed to load value for key "${key}" from local storage.`,
error
);
return null;
}
}
/**
* Method to remove a key-value pair from the local storage by its key.
* @param key - The key of the value to be removed.
*/
public remove(key: string): void {
try {
// Attempt to remove the key-value pair associated with the specified key from the local storage
localStorage.removeItem(key);
} catch (error) {
// Log an error message if the operation fails
console.error(
`Failed to remove value for key "${key}" from local storage.`,
error
);
}
}
/**
* Method to clear all key-value pairs from the local storage.
*/
public clear(): void {
try {
// Attempt to clear all key-value pairs from the local storage
localStorage.clear();
} catch (error) {
// Log an error message if the operation fails
console.error('Failed to clear local storage.', error);
}
}
}
Auth
This file depends on the db service, as it needs it to store the access token.
There are four methods to this service:
login - This is the entry point for when the user will click on the login button.
logout - This erases the storage and the access token.
checkAuthStatus - This tells us if the user has an access token and is authenticated or not.
getAccessToken - This is the main method of the class. This is where we get our access token from ProcessMaker, and you can see we are using here the environment.ts variables.
auth.service.ts
import { HttpClient, HttpParams } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Router } from '@angular/router';
import { DbService } from 'src/app/services/db.service';
import { environment } from 'src/environments/environment';
@Injectable({
providedIn: 'root',
})
export class AuthService {
public authenticated: any;
constructor(
private http: HttpClient,
private router: Router,
private db: DbService
) {}
// Method to check the user's authentication status
checkAuthStatus() {
// Retrieve the access token from local storage
const token = this.db.load('access_token');
// Check if the token exists
if (token) {
// Optionally, you can add more logic here to validate the token, such as checking its expiration date
// If the token is valid, set the authenticated status to true
this.authenticated = true;
} else {
// If the token does not exist or is invalid, set the authenticated status to false
this.authenticated = false;
}
}
// Method to initiate the OAuth login process
login() {
// Define the OAuth parameters
const params = [
'response_type=code',
`client_id=${environment.clientId}`, // Use environment variable
'scope=*',
encodeURIComponent(`redirect_uri=${environment.redirectUri}`), // Use environment variable
];
// Redirect the user to the OAuth authorization endpoint
window.location.href =
environment.oauthAuthorizeUrl + '?' + params.join('&');
}
// Method to log out the user
logout() {
// Clear authentication status and local storage
this.authenticated = false;
this.db.clear();
// Redirect the user to the login page
this.router.navigateByUrl('login');
}
// Method to get the access token using the authorization code
getAccessToken(code: string) {
// Define the payload for the OAuth token request
const payload = new HttpParams()
.append('grant_type', 'authorization_code')
.append('code', code)
.append('client_secret', environment.clientSecret) // Use environment variable
.append('client_id', environment.clientId); // Use environment variable
// Make a POST request to the OAuth token endpoint
this.http
.post(
environment.oauthUrl, // Use environment variable
payload,
{
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
}
)
.subscribe(
(response) => {
// Check if the access token is present in the response
if ((response as any)['access_token']) {
// Save the access token and mark the user as authenticated
this.db.save('access_token', (response as any)['access_token']);
this.authenticated = true;
this.router.navigateByUrl('tasks');
} else {
// If the access token is not present, mark the user as unauthenticated
this.authenticated = false;
this.router.navigateByUrl('login');
}
},
(error) => {
// Handle any errors that occur during the request
console.error(
'An error occurred while fetching the access token:',
error
);
this.authenticated = false;
this.router.navigateByUrl('login');
}
);
}
}
Step 4: The ProcessMaker SDK
We will be utilizing the ProcessMaker SDK for Angular. ProcessMaker utilizes Swagger / OpenAPI for our documentation and API SDKs. Any of the supported SDKs are available to generate via the Artisan CLI tool.
If you want to learn how to use the swagger-based SDK, you can see a video tutorial here:
Below are the list of SDKs that can be generated via the command from within your root directory of your ProcessMaker application.
For convenience, the application already contains the SDK files that are necessary for the applications functions in the folder api which resides at the root of the application, sibling to the src directory.
Next Steps
Advanced Screens Package
Advanced Screens package is deprecated.
Notice
The Advanced Screens package deprecated in March 2021.
.
If you use the Advanced Screens package, please contact your Customer Success Manager.
Decision Tables Package
Design business rules within decision tables that affect Process routing. Decision tables can be reused in any Process model.
Overview
A Decision Table is a two-dimensional grid that outlines the different possible business conditions that can occur for a particular data output. The data output then affects the workflow routing for any Request that references that decision table. The Decision Table represents business rules from which to evaluate how to route Requests for a Process.
Decision Tables are Decision Model and Notation (DMN) files. DMN is a standard notation to model and run decisions in business contexts, used by business analysts, developers, and Process designers to manage complex decision-making scenarios.
Decision Tables provide the following benefits versus only use BPMN elements to determine workflow routing:
Design complex sets of business rules more easily and with greater readability and transparency than using Gateway-type elements with Sequence Flow elements to determine workflow routing.
Decision Tables require no coding experience, allow most Process designers to easily design business rules.
Unlike BPMN elements, Decision Tables function independently of Process models. Similarly to Scripts, Screens, and Collections, Decision Tables are referenced from within Process models, thereby making them reusable and more flexible than only using BPMN elements.
Decision Tables are referenced from Rule Task connectors in a Process model. One Rule Task connector may reference multiple Decision Tables to determine complex routing decisions.
The Decision Tables package provides the following functions:
Design Decision Tables: Design Decision Tables in Decision Table Editor that can be reused in any Process to create complex yet easily configurable business rules. See these topics:
Data Connector Package
Access both Collection records and third-party data sources from any ProcessMaker Platform asset, including Screens, Scripts, and Process models.
Overview
Use the Data Connector package to connect your ProcessMaker Platform assets, such as Screens, Scripts, and Collections to and from third-party data sources such as Application Program Interfaces (APIs). After a Data Connector is created, Process designers can reference the data source via the Data Connector from within their ProcessMaker Platform assets. Incorporating data from external data sources such as APIs helps you make business decisions from information outside of your ProcessMaker Platform instance.
Below are a few ways to use Data Connectors:
In Screen Builder, use the records in a Collection as Select List control options in a Screen.
In Screen Builder, use a Watcher to act on data from a Data Connector when the value of a Screen control changes.
While modeling a Process, place a Data Connector connector into your Process model to automatically access records from a Collection records or access external data from a third-party data source to incorporate new information into Requests started from your Process. After this external data has been incorporated into Requests, make business decisions based on that data.
The Data Connector package has the following components after it is installed:
Manage Data Connectors: from one place. After your Data Connectors are configured, your Process designers can access them from their ProcessMaker Platform assets.
Process model connector: A is a control that integrates into Process Modeler. Use the Data Connector connector as you would : drag and place the Data Connector connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
Screen Builder controls: Interact with Collection records and third-party data source directly from within specific Screen Builder controls, such as the and controls.
Conversational Forms Package
Design functional rule-based modern chat style forms using Screens in ProcessMaker Platform.
Overview
Use the Conversational Forms package to design functional rule-based modern chat style forms using with the -type Screen.
The Conversation Forms package has the following features and attributes:
When your Conversational-type Screen renders, that Screen displays as a streaming interactive form that supports rich text, text input, and multiple choice options that can be validated based on the reader's input.
Screen control labels and values create a conversational flow with the reader. As the form renders from top to bottom, each Screen control displays as a "chat style" instruction or question. The interactive form scrolls up the page and the next Screen control displays as the reader responds to each instruction or question. If an interstitial Screen is used, an animated GIF of dots displays as if someone is chatting with the reader.
Integrate Request variable values within the reader conversation as you would in Form-type Screens. For example, if the reader's name is known from a parent Request and stored in a Request variable, use to reference that Request variable's value within a Rich Text control to display that reader's name in a personalized message within the chat response.
Determine when the reader has deserted the chat experience. Each reader response to the chat experience resets a timeout counter. If the counter expires, a message displays Are you still there? and then begins a final countdown. If the timer expires or the reader navigates away from that page, then the accumulated chat content automatically submits and completes with a message This conversation has expired. with a button to restart the chat experience which reads Start Over.
After designing your Conversational-type Screen, embed it to a third-party site to provide site visitors an automated chat-style interaction.
C# Package
Develop Scripts using C# programming language.
Overview
Use the C# package to develop in using C# programming language.
See the following topics:
Actions By Email Package
Request participants can make decisions via email with the click of a button.
Overview
Use the Actions By Email package to send emails automatically during your Processes' Requests. During a Request, email recipients can make business decisions directly in the email by clicking on a button to indicate that decision. The email response returns to your ProcessMaker Platform instance to acknowledge the decision, then routes workflow for that Request. While an email may be sent to multiple recipients, only the first response is acknowledged to affect workflow in that Request.
The Actions By Email package has the Actions By Email connector that integrates into Process Modeler. Use the Actions By Email connector as you would BPMN elements: drag and place the Actions By Email connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
When the Actions By Email connector triggers during an in-progress Request, ProcessMaker Platform sends an email from the "no-reply@processmaker.net" email address to one email recipient so that this Request participant can make a decision as part of the Request. For example, this Request participant must make a decision to approve or deny a vacation request or for a purchase. The email recipient receives an email with buttons in the email to easily indicate the decision.
After the email recipient clicks a button to indicate the decision, ProcessMaker Platform receives the response and uses the indicated decision as part of the Request routing. For example, if you grant a leave request, the Request routes differently than if you deny that leave request.
Email design is subject to email client limitations and may not fully support HTML5 or CSS3 specifications. Test your emails in your supported client applications.
See the following for more information:
Comments Package
Comment in Task summaries with other users.
Overview
Use the Comments package to discuss Tasks with stakeholders in that Request. Add and reply to comments regarding Tasks for Form Task elements and Manual Task elements in a Process model.
Comments have the following attributes:
Comments are available in Form Task and Manual Task elements, and only if the Process containing that element is configured to use comments and the user or group member has the appropriate Commenting permission to do so. Enter comments into a Task's Screen prior to or while entering information into that Screen.
Comments may also be entered into Conversational-type Screens, though comments must be entered prior to entering information into that Task's Screen.
Comments display in these summaries:
Task summaries: Comments display below the Form tab of Task summaries. After an initial comment is created for a Task, replies to that comment display in chronological order from top to bottom in that comment thread.
Request summaries: Comments display in a Request's history in chronological order from top to bottom intermingled with events in that Request.
Tag users in comments to invite that user into the comment thread so that user can participate in the discussion. Tagged users receive a notification of the comment regardless of whether that user is currently a Request participant: that user automatically becomes a Request participant when tagged in a comment even if that user has not been assigned or participated a Task in that Request.
See the following topics regarding how to configure and use the Comments package:
Process configuration: may be used in Request summaries from a Process.
Request comments: .
Task comments: .
Configure user settings: for that user's manager, delegated user, and schedule.
Configure the manager for a group: for that group's manager.
Form Task element assignment options: .
Manual Task element assignment options: .
Set User Signal settings: .
Set user extended properties: .
If you want to dig deeper into client applications, you can see the .
If you need more details about which grant type to use, you can look at the relevant .
Decision Task connector: Use Decision Task connectors to run Decision Tables in your Processes. Specify which Decision Table(s) to run, thereby evaluating their business rules, and then map how data routes between variables in the Request to and from variables in the Decision Table(s). See for more information.
View translations of the ProcessMaker Platform user interface in German, Spanish, and French languages. Change the labels and messages throughout the ProcessMaker Platform user interface.
Overview
Display English- and Non-English Language Labels in the ProcessMaker Platform User Interface
The ProcessMaker Platform user interface by default is in English. However, ProcessMaker Platform provides the following translations of the ProcessMaker user interface:
German
Spanish
French
The Translations package displays each label and message in the ProcessMaker Platform user interface in these four languages. For each label or message, the Translations package displays the default English language as well as each non-English language. When the Language setting is changed in user profile or user account, ProcessMaker Platform displays the appropriate labels and messages for that selected language. Changing the Language setting only affects that selected user account.
If the Translations package is not installed, ProcessMaker Platform only displays the default English-language user interface labels and messages. Furthermore, the Language setting in user profiles and user accounts is not available.
Edit Labels and Messages in Your ProcessMaker Platform User Interface
Optionally, use the Translations package to edit the labels and messages that display. This may be useful for the following reasons:
Replace ProcessMaker Platform branding with our own: Your organization uses specific branding and/or terminology that you want displayed throughout your ProcessMaker Platform instance. In this regard, you are replacing ProcessMaker Platform's branding with your own.
ProcessMaker Platform is white-labeled: As a ProcessMaker partner using ProcessMaker Platform for your client, your client may want you to white-label ProcessMaker Platform: hide all ProcessMaker Platform branding and terminology and replace it with theirs.
When replacing ProcessMaker Platform branding and/or white-labeling ProcessMaker, customize the colors in the ProcessMaker Platform user interface to show your organization's or client's color palette.
Note that if you edit the default English-language labels and messages, you are responsible for ensuring that the non-English translations match your English-language revisions and are accurate.
See the following topics regarding configuring the language setting in a user profile:
See the following topics regarding white-labeling ProcessMaker Platform:
Manage dashboards that display BMI and KPI metrics for stakeholders. Manage top-level menus that link to often-used ProcessMaker Platform locations, custom links, and often-used Requests.
Overview
Use the Dynamic UI package to design custom experiences in the following ways:
Create dashboards that display business management information (BMI) and key performance indicators (KPIs) at a glance for business stakeholders. Dashboards created in ProcessMaker Platform are Display-type Screens that can contain Saved Search charts and information designed to show relevant BMI and KPIs.
Configure a dashboard to be the default homepage for specific users and/or groups. When these users log on to ProcessMaker Platform, the dashboard displays content by default so that stakeholders can act on ProcessMaker Platform business data and information quickly. For example, create one dashboard for your Sales team that displays sales KPIs and another for dashboard that displays KPIs for your Marketing team.
Replace the top-level menus that display in ProcessMaker Platform. Instead of the default menu options, customize them to link to often-used ProcessMaker Platform locations such as Collections and Saved Searches to which those users and/or group members have access, often-started Requests, external links in your organization, or any other hyperlink that your users can expect to have access. Providing custom menus simplifies how users access ProcessMaker Platform and specific uses. For example, create one menu for your Sales team members that provides links to the in-progress Requests location and their Saved Searches they use to monitor their KPIs, but another menu for all users to start Requests for often-used Processes and access Human Resources information.
In conjunction with the Custom UI feature, customize the logo, color scheme, and/or font that displays across the ProcessMaker Platform interface. By creating custom top-level menus, effectively white-label the user interface so that your clients and/or partners do not know that they are using ProcessMaker Platform when they log on.
Show or hide ProcessMaker Platform user interface components for members of a group, including the left sidebar, the +Request button to start Requests, and the breadcrumbs.
After creating the dashboards and custom menus for your business stakeholders, assign them to those users and/or group members the next time those users log on to ProcessMaker Platform:
DocuSign Package
Customize and send documents for signatures by fully integrating DocuSign’s eSignature functionality into your Processes.
Overview
Use the DocuSign package to customize and email your documents for signatures. DocuSign eSignature provides a service to digitally sign legally-binding documents including contracts, account openings, and invoices. ProcessMaker Platform uses DocuSign's eSignature API to allow Process designers to seamlessly integrate this functionality in a Process.
After the DocuSign package is installed, the DocuSign connector integrates into the Process Modeler. Use the DocuSign connector in your Process models as a BPMN element: drag and place the DocuSign connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
The DocuSign connector uses DocuSign templates and recipient roles to send documents for eSignatures. Documents are sent through email to internal and external users as part of a Process. During a Request, when the DocuSign connector triggers, workflow routing can be configured in one of the following ways:
The Request pauses until the assigned user signs the document.
The Request's workflow resumes independently of the document's signing status.
For information on DocuSign templates and recipient roles, refer to Working with Templates - DocuSign eSignature User Guide.
Using the DocuSign package is a multi-step process involving these user roles:
System Administrators: An Administrator configures DocuSign server settings to ensure access to your DocuSign server.
Process designers: A Process designer configures the DocuSign connector in a Process to email documents for eSignatures to the intended recipients.
Recipients or document signers: The recipients access the documents through an email sent by DocuSign and sign them. The documents can be signed by both ProcessMaker Platform or external users.
Follow these guidelines to use the DocuSign package:
.
File Manager Package
Upload, preview and download documents during your Processes' Requests.
Overview
Use the File Manager package to preview, download, and share files during your Requests. The File Manager package has the following components after it is installed:
File Manager: Manage files that have been added to your personal file manager:
Manage files any user may access: .
Manage files that have been shared with you: .
Manage starred files: .
File Manager tab in Request summaries: uploaded to a Request in the File Manager tab. The File Manager tab replaces the Files tab in that is in the ProcessMaker open-source edition. From the File Manager tab, view, download, and share files from a Request summary.
Preview files in Tasks: Preview a file uploaded to a previous in that Request via a control.
Documentation Package
Documentation for your Processes that includes an image of the Process map, lists all its elements and connectors, and their functional descriptions.
Overview
Use the Documentation package to enter and view documentation for your Processes. Entered documentation is for informational purposes only and does not affect Request workflow.
The documentation displays as a page within ProcessMaker Platform. Use the Web browser to print or save as a PDF if your browser supports those functions.
Process documentation has the following attributes:
The page generated by the Documentation package provides the following information about the Process:
The name of the Process.
When was theProcess was last updated and by whom.
A description of the Process as entered when creating a new process.
An image of the Process map.
Names of all Process elements and their unique node IDs.
The documented description of each Process element and/or connector. If no description has been entered for an element/connector, No Documentation Found message displays.
Below is a documented Process.
See the following topics regarding how to view Process documentation and edit the description for Process elements and/or connectors:
Google Places Package
Request participants can auto-complete street, location, and/or business addresses entered into a Screen control.
Overview
Use the Google Places package to allow Request participants to do the following in Form-type Screens:
Start entering an address, location, or business name into a Screen control, then allow the Google API to auto-complete that address or location. The Google Place control stores the selected address in the Request data as well as all the returned data from the Google API.
View and/or select from one or more geographical locations in a Google map.
Prior to using the Google Places package, ensure that your organization has a billing account with the Maps JavaScript API and Places API enabled, as well as API keys for each API.
The Google Places package has the following components after it is installed:
Screen Builder control: The Google Places package installs the Google Places control into Form-type Screens. After adding and configuring a Google Places control into your Screen, Request participants start entering an address, then receive auto-complete address options from which to select as the intended address, location, or business name. The Google Place control stores the selected address in the Request data using that control's Variable Name setting value, as well as all the returned data from the Google API. See .
Environment Variable: The Google Places package adds an called GOOGLE_API_TOKEN that contains the Google API token for that ProcessMaker instance. The Environment Variable does not require configuration or revision after it has been added to your ProcessMaker instance.
The Google Places control uses the Google API token to call the Google API when a Google Places control is placed into a Screen, then when address information is entered into the control. Google uses Basic Service Set Identifiers (BSSID) information from the Request participant's Wireless Local Area Network (WLAN) Access Point to get an approximation of where that Request participant is located, even when GPS and WiFi are not available.
Below are a few ways to use the Google Places package:
Allow Request participants to easily enter a shipping or billing address.
Enter a business name into the Google Places control to select a business location.
Enter well-known monuments or international airport names to get their addresses or locations when requesting to travel.
PDF Generator Package
Automatically generate PDFs of Display-type Screens in a Process.
Overview
Use the PDF Generator package to automatically generate PDFs of Display-type Screens during Requests.
After the PDF Generator package is installed, the PDF Generator connector integrates into Process Modeler. Use the PDF Generator connector in your Process models as you would BPMN elements: drag and place the PDF Generator connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
Use the PDF Generator connector in your Process models when you want to provide a printable copy of a Display-type Screen, such as for Request summaries or purchase order receipts.
When the PDF Generator connector successfully generates the PDF during an in-progress Request, the PDF output can be downloaded from the Files tab in its Request summary. The PDF Generator by default names the PDF output the same as the Screen from which the PDF was generated unless the name is configured via text or by referencing a Request variable using mustache syntax. If the PDF Generator successfully generates the PDF, the PDF output remains available from that Request's summary regardless of that Request's status.
See the following topics:
, which contains the same information as that for other Request statuses
PM Blocks Package
Use reusable and pre-built Process Modeler objects created from a set of other objects to serve a specific purpose or function.
Overview
A is a reusable Process Modeler object composed of a set of other objects to serve a specific purpose or function. Process Designers may place into a Process a PM Block as its own Process Modeler object and then configure it as its own functional unit. The Process Modeler need not have the technical skills to have composed the PM Block, but be able to quickly place it into Process models and configure to the business solution.
PM Blocks have the following attributes:
PM Blocks are pre-built, packaged Processes: PM Blocks are ready-to-use, packaged Processes with their own configuration settings designed by the Process Designer who built the PM Block. PM Blocks are no-code to place in Process Modeler.
PM Blocks are reusable: PM Blocks are reusable by any Process Designer with appropriate permissions, and then configured for each business solution. Configuration settings, such as authentication to a third-party service, are separate from the objects within the PM Block. This allows PM Blocks be quickly configured and deployed regardless of technical expertise or the involvement of Administrators.
Built in Process Modeler: PM Blocks are built from Process Modeler, saved as a Process, and then saved as a PM Block. Process Designers can design complex functionality that other Designers may leverage with no technical skills.
Save a Process as a PM Block: Any user with appropriate permissions may save a Process as a PM Block and/or use a PM Block in a Process model.
Built PM Blocks are accessible from Process Modeler for Process design: Within Process Modeler, PM Blocks are available in a separate tab in the left-side panel, adjacent to the ProcessMaker BPMN elements and connectors. With the appropriate permissions, a Process Modeler may place a PM Block as its own object, and then configure it with the configuration settings built for that PM Block.
Java Package
Develop Scripts using Java programming language.
Overview
Use the Java package to develop Scripts in Script Editor using Java programming language.
See the following topics:
Process Optimization Package
Optimize workflow in your Process model by visually evaluating its workflow through its Sequence Flow elements without assigning Task recipients.
Overview
The Process Optimization package integrates into Process Modeler to visually validate the workflow in your Process model. Use visual validation to validate if workflow can potentially complete routing through all elements and/or connectors in your Process model. The Process Optimization package extends basic BPMN 2.0 validation to validate whether all workflows routes are viable, including connectors that do not apply to BPMN 2.0 validation.
The Process Optimization package has the following features:
Click the Check Flow button in the bottom bar of Process Modeler to automatically view how workflow routes in your Process model. Process Modeler evaluates workflow throughout your Process model, and then displays each possible workflow route results in separate sections. Process Modeler evaluates workflow based on the default Sequence Flow elements and/or conditions set to those Sequence Flow elements throughout the Process model.
Tasks need not be assigned to users/groups nor Sequence Flow elements configured with routing conditions.
R Package
Develop Scripts using R programming language.
Overview
Use the R package to develop Scripts in Script Editor using R programming language.
See the following topics:
Saved Searches Package
Save and share search queries associated with Requests and Tasks.
Overview
Use the Saved Searches package to save and share search parameters associated with Requests, Tasks and Collections. In doing so, you manage the search parameters for your Saved Searches. You may share your own Saved Searches with other users and/or groups. Recipients of your shared Saved Searches can only use your Saved Search to view its search results, but cannot modify your Saved Searches' parameter settings you configured. The name for a Saved Search does not need to be unique within your ProcessMaker Platform instance. Therefore, multiple Saved Searches may have the same name when your own Saved Search and one shared with you have the same name.
Similar to advanced Request searches, advanced Task searches, and Collection record searches, filter the data that for a Saved Search using ProcessMaker Query Language (PMQL).
Charts help visualize your Saved Search results. Though you can customize in tabular format the data details for your Saved Searches, nothing distills that data like a customized chart. Create and configure two-dimensional charts to visualize Saved Search results after selecting a Saved Search. You may create customized charts regardless of whether you created the Saved Search or if it was shared with you.
Charts use the data results from the Saved Search to visualize those results in a variety of chart types and styles. Chart data may be filtered by using an optional PMQL query that further filters the data from that Saved Search to visualize minute data.
Screen designers may also embed Saved Search charts into Form- and Display-type Screens using the Saved Search Chart control.
Signature Package
Allows the user to include a personalized signature on a Screen.
Overview
Use the Signature package to include a digital signature within a created form in Screens.
This digital signature package is available providing the user has access to screen sensitivity. After the signature is produced, it is possible to save it in order to be used in further instances.
Please note that it is possible to Redo the signature entered using the Redo button.
When the changes are satisfactory select the Save button.
Send Email Package
Send emails automatically during your Processes' Requests.
Overview
Use the Send Email package to automatically send emails during your Process Requests. The Send Email package has the following components after it is installed:
Process model connector: The integrates into Process Modeler. Use the Send Email connector in your Process models as you would BPMN elements: drag and place the Send Email connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
New Screen type: The Send Email package adds a new Screen type called Email. Use an email-type Screen to compose the email body for email messages to sent with the Send Email package. In doing so, use Variable Name setting values from Screens referenced in a Process model to customize the sent email. The content of referenced Email-type Screens become the email body content. When creating a new Screen, select the Email type.
Send email notifications from Task and Manual Task elements: Send email notifications when a Task or Manual Task element triggers, completes, or under a specified condition. Include either plain text or the contents of an Email-type Screen as the email body content.
The Send Email package provides mailer drivers for the following services:
Slack Notification Package
Send automatic notifications to Slack channels during Requests.
Overview
Use the Slack Notification package to automatically send Slack notifications to a selected Slack channel during your Process Requests.
After the Slack Notification package is installed, the Slack Notification connector integrates into Process Modeler. Use the connector in your Process models as you would BPMN elements: drag and place the Slack Notification connector into your Process model, configure its settings, and then add its incoming and outgoing Sequence Flow elements.
Before using the Slack Notification connector in your Process models, your ProcessMaker Platform instance must be granted access to your Slack workspace by building a Slack App. Ask your Slack administrator to help you with the following:
Learn how to develop a custom package for ProcessMaker Platform to extend its functionality.
Overview
Extend ProcessMaker's functionality with custom functions and/or integrations with third-party services by developing your own .
Requirements
The following are required or assumed to successfully create a package for ProcessMaker Platform:
You are a developer that is comfortable performing command-line operations. This is an advanced development topic.
You are comfortable and knowledgeable about . See .
ProcessMaker Platform is installed on your local computer.
PHP version 7 or later.
Web Entry Package
Allow anonymous or authenticated users to start or participate in Requests via a published URL.
Overview
Allow anonymous or authenticated users to start or participate in Requests via a published URL.
The Web Entry package has the following components after it is installed:
Persons can start a Request: Web Entry integrates with the to allow either an anonymous or authenticated user to start a Request via a Web Entry. In doing so, specify which the Request starter views when accessing the Web Entry's URL, and whether to display a different Screen or be redirected to another URL when the Request starter starts the Request. Each Start Event element in a Process model can be configured with different settings.
Persons can participate in an in-progress Request: Web Entry integrates with the to allow either an anonymous or authenticated user to participate in an in-progress Request via Web Entry. In doing so, specify which Screen the Task assignee views when accessing the Web Entry's URL, and whether to display a different Screen or be redirected to another URL when the Task assignee submits the Task. Each Form Task element in a Process model can be configured with different settings.
Vocabularies Package
Maintain uniform JSON schemas for all ProcessMaker Platform assets in your organization.
Overview
Need to Learn How to Develop JSON Schemas?
Start with .
Use the Vocabularies package to maintain uniform JSON schemas across all assets in your organization. These assets include Processes, Screens, and Scripts.
Use Vocabularies to enforce compliance with a specific data structure in Request data for your Processes. Apply one or more Vocabularies to your Processes and/or specific BPMN elements in your Process models to ensure the JSON data model in Request data complies with a data structure you need to meet regulatory specifications or ensure Request data contains required information as each Request routes through workflow.
A Vocabulary is a JSON schema designed to annotate and validate ProcessMaker Platform assets to which that Vocabulary is applied. The JSON schema describes your existing data format(s) in both a machine and human readable structure. Any ProcessMaker asset to which that Vocabulary applies must conform to that JSON schema.
Use Vocabularies for the following reasons:
Ensure that data associated with the ProcessMaker Platform asset to which the Vocabulary applies complies with a required data format. For example, use a Vocabulary on a Task element. By extension, the Vocabulary applies to the Screen referenced by that Task element. The Vocabulary ensures that the Screen designer complies with the JSON schema as structured in the Vocabulary. This maintains consistency, validation, and compliance across any Task to which that Vocabulary applies.
Ensure the quality and compliance of submitted data. For example, ensure that information entered into a Screen for a Task complies with a regulatory specification.
The Vocabularies package has the following components after it is installed:
Manage your Vocabularies: Manage your organization's Vocabularies. See .
Set Vocabulary permissions: Determine which users and/or groups have permission to view, create, edit or delete Vocabularies. See .
Start Event element configuration: to a Start Event element.
Intermediate Message Catch Event element configuration:
to an Intermediate Message Catch Event element.
Form Task element configuration: to a Form Task element.
Manual Task element configuration: to a Manual Task element.
Script Task element configuration: to a Script Task element.
Sub Process element configuration: to a Sub process element.
Versioning Package
Manage and maintain multiple versions of your Processes, Screens and Scripts.
Overview
Use the Versioning package to manage and maintain multiple versions of your Processes, Scripts and Screens. A version is a set of changes made to a ProcessMaker Platform asset at a particular time by a Process Designer. Versioning maintains a record of all named and unnamed changes to that asset. Versioning information is useful both for auditing and historical data maintenance purposes. The saved versions display in a tabular format when viewing version history for an asset from where they can be edited and/or marked as the Current Versionaccording to your business needs.
The latest saved version of a ProcessMaker Platform asset is automatically designated as the current version and is used in new Requests. Version changes are not reflected in Requests which were in-progress or already completed when that asset version changed.
The Versioning package has the following attributes:
When the Versioning package is installed, versioning is available for Processes, Scripts and Screens.
Every new version is saved with the following information:
Date: The date and time when a Process Designer saved that version.
Name: The name of this version as entered by a Process Designer.
Description: A description of the changes in this version as entered by a Process Designer.
Saved by: The name of the Process Designer who saved this version.
Although multiple versions of each ProcessMaker Platform asset can be saved, only one version can be marked as the current version.
Any existing version of a ProcessMaker Platform asset can become the current version when configuring that asset.
See the following topics regarding how to use versioning in Processes:
Save a version: of a Process in the Process Modeler.
View and configure Version History: of a Process in Process Modeler.
See the following topics regarding how to use versioning in Scripts:
See the following topics regarding how to use versioning in Screens:
Getting a Refresh Token
This guide covers the OAuth 2.0 refresh token mechanism.
Overview
This guide walks you through the steps of refreshing an access token for making RESTful API calls to ProcessMaker. Access tokens typically have a limited lifespan, and once they expire, they need to be refreshed using a refresh token. This guide assumes you already have a refresh token. If not, refer to the guide.
Client Application
Choose Your Tutorial
Step 1: Install Necessary Python Dependencies
Before starting, ensure you have the necessary Python libraries installed. You'll need requests for making HTTP requests.
You can install it via pip:
pip install requests
Step 2: Refreshing the Access Token
Use the following Python code to refresh your access token:
import requests
# Define the token endpoint
token_url = "https://<your-instance>.processmaker.net/oauth/token"
# Define the payload
payload = {
"grant_type": "refresh_token",
"refresh_token": "<your-refresh-token>",
"client_id": "<your-client-id>",
"client_secret": "<your-client-secret>"
}
# Make the POST request
response = requests.post(token_url, data=payload)
token_info = response.json()
# Print the new access token
print(f'New Access Token: {token_info["access_token"]}')
Don't forget!
Replace:
<your-instance> with your actual ProcessMaker instance URL.
<your-refresh-token> with the refresh token you received when you first obtained your access token.
<your-client-id> and <your-client-secret> with the client ID and secret of your application.
Step 3: Review the Response
After executing the script, you should receive a new access token and possibly a new refresh token. Store these securely, as you'll need the access token for future API requests and the refresh token for future token refreshes.
Conclusion
Refreshing your access token is an essential step in maintaining uninterrupted access to the ProcessMaker API. By using Python and the requests library, you can easily and efficiently refresh your token. Always ensure you handle your tokens securely, as they are vital for maintaining secure communication with the API.
Step 1: Obtaining the access token
Step 2: Install Necessary Node.js Libraries
Before starting, ensure you have the necessary Node.js libraries installed. You'll need axios for making HTTP requests.
You can install it via npm:
npm install axios
Step 3: Refreshing the Access Token
Use the following Node.js code to refresh your access token:
<your-instance> with your actual ProcessMaker instance URL.
<your-refresh-token> with the refresh token you received when you first obtained your access token.
<your-client-id> and <your-client-secret> with the client ID and secret of your application.
Step 3: Review the Response
After executing the script, you should receive a new access token and possibly a new refresh token. Store these securely, as you'll need the access token for future API requests and the refresh token for future token refreshes.
Conclusion
Refreshing your access token is an essential step in maintaining uninterrupted access to the ProcessMaker API. By using Node.js and the axios library, you can easily and efficiently refresh your token. Always ensure you handle your tokens securely, as they are vital for maintaining secure communication with the API.
Step 1: Obtaining the access token
Step 2: Download and Install Postman
Step 3: Set Up Your Client Application
If you navigated to this guide before creating your client application, you first need to do so. If you already have your client ID and client secret, proceed to step 3.
Step 4: Create a New Postman Request Tab
Open Postman and click on the + button to create a new tab. Then, click on the Authorization tab.
Step 5: Use the Refresh Token Grant Type
For the refresh token grant type, follow these steps:
Refresh Token Grant
Type: Choose OAuth 2.0 from the drop-down.
Add auth data to: Choose Request Headers.
Configure New Token:
Token Name: Any name for your reference.
Grant Type: Refresh Token.
Access Token URL: The token URL of the OAuth server.
Refresh Token: The refresh token you received when you first obtained your access token.
Client ID: The client ID of your OAuth application.
Client Secret: The client secret of your OAuth application.
Scope: The scope of the access request (if any).
Client Authentication: Send as Basic Auth header.
Click "Get New Access Token". The new access token will be automatically filled in the Access Token field.
Step 6: Making API Requests
After obtaining the refreshed access token, Postman will automatically add the Authorization: Bearer <access-token> header to your requests. You can now continue making requests to the API using the refreshed access token.
Remember: Always protect your client secret, refresh tokens, and access tokens. These grant access to the API and should be treated with the same care as passwords.
Conclusion
That's it! You now know how to refresh an access token using OAuth 2.0 in Postman. Regularly refreshing your access token ensures uninterrupted access to the ProcessMaker API.
Step 1: Obtaining the access token
Step 2: Refreshing the Access Token
Execute the following command in your terminal:
curl -X POST "https://<your-instance>.processmaker.net/oauth/token" \
-d "grant_type=refresh_token&refresh_token=<your-refresh-token>&client_id=<your-client-id>&client_secret=<your-client-secret>"
Replace:
<your-instance> with your actual ProcessMaker instance URL.
<your-refresh-token> with the refresh token you received when you first obtained your access token.
<your-client-id> and <your-client-secret> with the client ID and secret of your application.
Step 3: Review the Response
After executing the command, you should receive a response from the server. This will provide a new access token and possibly a new refresh token. Store these securely, as you'll need the access token for future API requests and the refresh token for future token refreshes.
Conclusion
Refreshing your access token is a crucial step in maintaining uninterrupted access to the ProcessMaker API. By using the curl command, you can easily and efficiently refresh your token directly from the command line. Always ensure you handle your tokens securely, as they are vital for maintaining secure communication with the API.
View Documentation for a process: from the Processes tab.
Start Event element configuration: for a Start Event element.
Start Timer Event element configuration: for a Start Timer Event element.
Signal Start Event element configuration: for a Signal Start Event element.
Message Start Event element configuration: for a Message Start Event element.
Conditional Start Event element configuration: for a Conditional Start Event element.
Intermediate Timer Event element configuration: for an Intermediate Timer Event element.
Intermediate Signal Catch Event element configuration: for an Intermediate Signal Catch Event element.
Intermediate Signal Throw Event element configuration: for an Intermediate Message Throw Event element.
Intermediate Message Catch Event element configuration: for an Intermediate Message Catch Event element.
Intermediate Message Throw Event element configuration: for an Intermediate Message Throw Event element.
Intermediate Conditional Catch Event element configuration: for an Intermediate Conditional Catch event element.
End Event element configuration: for an End Event element.
Message End Event element configuration: for a Message End Event element.
Error End Event element configuration: for an Error End Event element.
Signal End Event element configuration: for a Signal End Event element.
Terminate End Event element configuration: for a Terminate End Event element.
Form Task element configuration: for a Form Task element.
Manual Task element configuration: for a Manual Task element.
Script Task element configuration: for a Script Task element.
Sub Process element configuration: for a Sub process element.
Boundary Timer Event element configuration: for a Boundary Timer Event element.
Boundary Error Event element configuration: for a Boundary Error Event element.
Boundary Signal Event element configuration: for a Boundary Signal Event element.
Boundary Conditional Event element configuration: for a Boundary Conditional Event element.
Boundary Message Event element configuration: for a Boundary Message Event element.
Exclusive Gateway element configuration: for an Exclusive Gateway element.
Inclusive Gateway element configuration: for an Inclusive Gateway element.
Parallel Gateway element configuration: for a parallel Gateway element.
Event-Based Gateway element configuration: for an Event-Based Gateway element.
Pool element configuration: for a Pool element.
Lane element configuration: for a Lane element.
Text Annotation element configuration: for a Text Annotation element.
Message Flow element configuration: for a Message Flow element.
Actions by Email connector configuration: for an Actions by Email connector.
Data Connector connector configuration: for a Data Connector connector.
DocuSign connector configuration: for a DocuSign connector.
PDF Generator connector configuration: for a PDF Generator connector.
Send Email connector configuration: for a Send Email connector.
Slack Notification connector configuration: for a Slack Notification connector.
See .
You may schedule a regular interval in which to email reports for either your own Saved Searches or those shared with you. See .
The Charts tab displays charts created for a Saved Search. See .
See .
See .
Save a version: of a Script in the Script Editor.
View and configure Version History: of a Script in Script Editor.
Save a version: of a Screen in the Screen Builder.
View and configure Version History: of a Screen in Screen Builder.
If you haven't already, and install Postman from their official website.
This part lays the foundation for the tutorial. Each subsequent part builds upon this, adding features to create a custom inbox interface powered by ProcessMaker.
After completing this part, the updated app confirms that you and your IDE are ready to begin creating an Angular inbox, powered via the ProcessMaker REST API.
Step 1: Setting Up
In this step, you'll set up a basic hello world Angular app, ensuring your development environment is ready for the upcoming sections.
Application Structure
We are going to build out a very simple app structure, bare bones, and then add to it. This is what the project should look like for this part:
NPM
Let's get started by creating the folder that will house the app we are going to build. You can name it angular4pm which is what we will be using as the default name as we go through the tutorial.
Inside your root directory of your project, create your package.json as seen in the screenshot above and add the following, making sure to fill in the blank fields as you desire:
If you plan to use version control, you will want to add a gitignore file for your environment.ts file since it will contain sensitive information like oauth secrets and such. Here is one you can start with and tweak as you like.
.gitignore
.DS_STORE
.vscode
/dist/
*.log
node_modules
# Include when developing application packages.
pubspec.lock
.c9
.idea/
.devcontainer/*
!.devcontainer/README.md
!.devcontainer/recommended-devcontainer.json
!.devcontainer/recommended-Dockerfile
.settings/
.vscode/launch.json
.vscode/settings.json
.vscode/tasks.json
.angular
*.swo
*.swp
modules/.settings
modules/.vscode
.vimrc
.nvimrc
# Don't check in secret files
*secret.js
# Ignore npm/yarn debug log
npm-debug.log
yarn-error.log
# build-analytics
.build-analytics
# rollup-test output
/modules/rollup-test/dist/
# User specific bazel settings
.bazelrc.user
# User specific ng-dev settings
.ng-dev.user*
.notes.md
baseline.json
# Ignore .history for the xyz.local-history VSCode extension
.history
# Husky
.husky/
environments/environment.ts
These are the main configuration files that are needed for the app to run properly. Feel free to modify as needed if you are comfortable with Angular and Typescript.
Now that you have setup the basic configuration files, you can begin executing some commands in the terminal.
npm install
In order to run the application, you can use this command which is an Angular command and includes hot reloads for ease of development.
ng serve
Step 2: The src Directory
Custom CSS
The application comes with some optional CSS that you may include if you want the look and feel of the app as we have made it.
Depending on where and how you deploy your application, you will probably want to be able to have different settings or configurations for dev vs prod, such as more verbose logging, extra dependencies in your package.json for better debugging, unit testing, etc.
The default environment file is located within the src directory, at src/environments/environment.example.ts
Here is the contents:
environment.example.ts
// This file can be replaced during build by using the `fileReplacements` array.
// `ng build` replaces `environment.ts` with `environment.prod.ts`.
// The list of file replacements can be found in `angular.json`.
//Below is the hard coded Endpoint URL for the PM4 instance we are wanting to connect to.
//Eventually we will create a text box to enter this on the login form
//This is then used in the auth.service.ts - this.httpClient.post(environment.apiUrl
export const environment = {
production: false,
apiDomain: '',
apiPath: '/api/1.0',
apiProtocol: 'https://',
clientId: '',
clientSecret: '',
oauthUrl: '',
redirectUri: '',
oauthAuthorizeUrl: '',
customCss: false,
calcProps: true,
};
/*
* For easier debugging in development mode, you can import the following file
* to ignore zone related error stack frames such as `zone.run`, `zoneDelegate.invokeTask`.
*
* This import should be commented out in production mode because it will have a negative impact
* on performance if an error is thrown.
*/
// import 'zone.js/plugins/zone-error'; // Included with Angular CLI.
Assets Directory
This contains things like images, logos, apache .htaccess files, etc.
App Directory
This contains the majority of the code. At this stage of the application, it is very bare bones. But, as we continue to add new features and functionality to the application, it will grow.
AppModule
app.component.ts is the source file that describes the app-root component. This is the top-level Angular component in the app. A component is the basic building block of an Angular application. The component description includes the component's code, HTML template, and styles, which can be described in this file, or in separate files.
This is the current contents of the app.module.ts. However, as we continue, we will add more to this file.
app.module.ts
import { NgModule } from '@angular/core';
import '@angular/compiler';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { NgxPaginationModule } from 'ngx-pagination';
import { CommonModule } from '@angular/common';
import { AppComponent } from './components/app.component';
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
HttpClientModule,
NgxPaginationModule,
FormsModule,
ReactiveFormsModule,
CommonModule,
],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
Components Directory
As this is the hello world first part, we only have 1 component that is very simple. All it does is print out a greeting. You can see below how we are using interpolation to dynamically insert the name, in this case, John.
app.component.ts
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template: `<h1>Hello, {{ name }}</h1>`,
})
export class AppComponent {
name = 'John';
}
Step 3: Test your hello world app
In a Web browser, open http://localhost:4200. Confirm that the default Web site appears in the browser. You should see a page just like below.
You can leave ng serve running as you complete the next steps, since it is configured with live/hot reload.
If the page in your browser stops working, make sure to check that you still have your terminal open with the ng serve command running and not displaying any errors.
If ng serve is working and there are no errors at compilation time, you should see something like this in your terminal.
However, if you made a typo or something and your app broke, it would look something like this. I deleted the line where we set the property name just to show what it would look like in your terminal.
And on your Web page you would see something like this.
Review
In this section, you set up a basic Angular app displaying Hello John. You also became familiar with the ng serve command, allowing local testing with ease.
Integrate intelligent document processing (IDP) into your Processes.
Overview
The IDP package includes client-side features to ProcessMaker IDP. ProcessMaker IDP is ProcessMaker's intelligent document processing (IDP) solution.
ProcessMaker IDP is technology that uses Artificial Intelligence (AI) and Machine Learning (ML) algorithms to extract information and insights from unstructured data sources such as documents, images, and videos. ProcessMaker IDP can automatically classify, extract, validate, and transform data from different types of documents such as invoices, contracts, purchase orders, driver's licenses, and many others.
ProcessMaker IDP can benefit organizations in numerous ways. Use ProcessMaker IDP to reduce processing times, minimize errors, improve compliance, and enhance operational efficiency. Specifically, the benefits of including ProcessMaker IDP into workflow solutions may include the following:
Streamline business processes: ProcessMaker IDP can automate repetitive tasks related to document processing, freeing up staff to focus on higher value tasks. This can lead to streamlined business processes, and faster turnaround times.
Cost savings: ProcessMaker IDP can reduce costs associated with manual data entry and processing via automation. Furthermore, save costs by preventing costsly data re-entry related to human errors.
Improved compliance: ProcessMaker IDP can ensure that documents are processed in accordance with company policies and regulatory compliance.
Data insights: ProcessMaker IDP can help organizations to gain insights from documents, such as identifying opportunities for revenue growth and cost savings.
For example, ProcessMaker IDP can automate invoice processing: extract key data from invoices such as the vendor name, invoice date, invoice number, and the total amount, and then automatically validate and transform this data into a format that can be uploaded to the organization's accounting system.
The IDP package has the following components after it is installed:
IDP connector: Use to integrate ProcessMaker IDP into your business Processes.
IDP settings: Prior to using IDP connectors, .
Python Package
Develop Scripts using Python programming language.
Overview
Use the Python package to develop Scripts in Script Editor using Python programming language.
See the following topics:
The Package Skeleton
The Skeleton Package is a template to get started with ProcessMaker Platform Packages
Overview
The skeleton package provides the necessary base to start developing a package for ProcessMaker Platform. Because ProcessMaker is built with Laravel, this is essentially a skeleton package for Laravel, with some modifications to ease development within the ProcessMaker Platform.
Change the package name (default is package skeleton) throughout the package to whatever name you would like:
cd package-skeleton
php rename-project.php string_to_replace
Step 2: Install Composer
Composer
Make sure composer and any dependencies are installed correctly:
composer update && composer install
Node Modules
npm install && npm run dev
Installation
In order to install your package in ProcessMaker, here are the step-by-step instructions.
Don't forget to replace the name you changes above when executing the commands below. They use the default name of package-skeleton but should be replaced with what you changed the name to.
Require the Package
Require the package with Composer and thereby adding it to the composer.json file as a dependency of the application:
The installation code is located within Laravels artisan console commands. You can find additional details about it here: Artisan Docs
Step 3: Navigation and testing
Navigate to the admin menu in your ProcessMaker Platform instance.
You should see your new menu item "Package Skeleton" or whatever you named your package, in the left sidebar.
Uninstall
Note: it is up to the developer to add any necessary code or proceedures to the install and uninstall commands. These can include adding and removing tables in the database, setting or removing api keys etc
Use php artisan package-skeleton:uninstall to uninstall the package.
Use composer remove processmaker/package-skeleton to remove the package completely.
​
ProcessMaker Integration using web hooks into a third-party application
Initiate a request using a ProcessMaker web hook
ProcessMaker Integration using web hooks into a third-party application
Screen(s) that are used to create, edit, and view records in each Collection
File Upload control
Collection permissions
record permissions
Import a CSV file
PMQL
search for record information in a Collection
relationships between records in one Collection with those in a second
Decision Table Management
What is a Decision Table?
Decision Table Editor
Decision Task connector
Manage your Data Connectors
Data Connector connector
BPMN controls
Select List
Record List
Screens
Conversational
Scripts
Script Editor
Create a New Script
Script Editor
Actions by Email Connector
Actions By Email Settings
Configure which commenting functions
Write, preview, and send comments to Request summaries
Write, preview, and send comments to Task summaries
Configure user settings
Configure group settings
Assign a Task to the Process Manager or to the Task assignee's manager
Assign a Task to the Process Manager or to the Task assignee's manager
Configure Signals for user events such as when a user account is created, deleted, read, or updated
Configure user extended properties that become settings in all user accounts
Configure the homepage dashboard, redirect URL, and/or menu for a user account
Configure the homepage dashboard, redirect URL, menu, and/or visibility settings for a group
Configure your DocuSign server in Admin settings
Configure the DocuSign connector in Process Modeler.
Manage files that any user may access
Manage files that other users have shared with you
Manage files that you have deemed important by having starred them
Manage files
Request summaries
Task
File Upload
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Configure how to edit the description
Google Places Control Settings
Environment Variable
PDF Generator Connector
Files tab for in-progress Requests
PM Block
Create a New Script
Script Editor
Optimize Your Process
Create a New Script
Script Editor
Schedule an Interval to Email Reports
Overview of Saved Search Charts
Saved Searches
Signature Control Settings
Send Email connector
Amazon SES mail driver settings
Google Gmail driver settings
Mailgun mail driver settings
Postmark mail driver settings
Sendmail mail driver settings
SMTP mailer driver settings
Slack Notification
Start Event element configuration settings
Screen
Form Task element configuration settings
Vocabularies Management
Vocabulary permissions
Configure how to assign Vocabularies
Configure how to assign Vocabularies
Configure how to assign Vocabularies
Configure how to assign Vocabularies
Configure how to assign Vocabularies
Configure how to assign Vocabularies
Save a version
View and configure version history
Save a version
Save a version
View and configure version history
Configure the language setting when editing a user account as an Administrator that has permission settings to edit user accounts
Access and configure the language setting for your own user profile
User interface language management
Customize the colors in the ProcessMaker Platform user interface
IDP connectors
authenticate ProcessMaker Platform with your ProcessMaker IDP instance and configure which folders in ProcessMaker IDP from which to store documents for processing
Create a New Script
Script Editor
View documentation for a process
View and configure version history
Creating Your First ProcessMaker Package
Learn how to develop a custom package for ProcessMaker Platform to extend its functionality.
Overview
Extend ProcessMaker's functionality with custom functions and/or integrations with third-party services by developing your own .
Requirements
The following are required or assumed to successfully create a package for ProcessMaker Platform:
Requirement
Function
Step 1: Creating the Package
First, let's start by creating a sibling directory to your ProcessMaker Platform installation folder. This example names the new directory processmaker-plugins. For example, if your ProcessMaker installation is located at /opt/processmaker, you can create the processmaker-plugins directory at /opt/processmaker-plugins.
Clone and follow the instructions for setting up the template from our GitHub repository into your processmaker-plugins directory.
Then edit your packages composer.json file, similar to the below:
{
"name": "processmaker/my-first-package",
"friendlY_name": "My First Package",
"description": "Package Skeleton to develop a package for ProcessMaker Platform"
}
Next, locate the the composer.json file for your ProcessMaker application (not to be confused with your packages composer.json file).
You can find the applications main composer.json file at the root of the ProcessMaker application, assuming you are following along, it would be located at /opt/processmaker/composer.json
Now we need to add a reference to your package in the repositories block of the composer.json in order for the application to know of it's existence.
There are still a few things that will need to be fixed by hand:
You will need to rename your core controller from PackageSkeletonController.php to your package's name (e.g. MyFirstPackageController.phpLocated here, assuming you are following along: /opt/processmaker-plugins/my-first-package/src/Http/Controllers )
Now, let's confirm that the controller name is right in addition to the filename.
Open your renamed controller and change the controller name, assuming you are following our conventions, to MyFirstPackageController .
Step 2: Creating PHP Artisan Commands
A good practice is to make sure your install and uninstall commands work well.
Assuming the package is located within /opt/processmaker-plugins/my-first-package you will want to edit the file /opt/processmaker-plugins/my-first-package/routes/console.php located inside your package to set up the artisan commands.
Depending on your preference, the install and uninstall can also be object oriented and done via classes, which would be located at src/Console/Commands/Install.php and src/Console/Commands/Uninstall.php , respectfully.
The Install Command
Perhaps you want to install a database table with your package for specific configuration needs.
We are assuming that you might have a seeder class named MyFirstPackageSeeder that would be responsible for seeding the database with your table and data.
An example of an uninstall command might be to delete your packages assets when uninstalling.
Artisan::command('my-first-package:uninstall', function () {
// Remove the vendor assets
Illuminate\Support\Facades\File::deleteDirectory(
public_path('vendor/processmaker/my-first-package')
);
$this->info('The package has been uninstalled');
})->describe('Uninstalls package');
Running the Artisan Commands
All artisan commands MUST be run within the ProcessMaker application root directory. E.g. /opt/processmaker
To execute the install command, you would then run this from your terminal:
cd /opt/processmaker
php artisan my-first-package:install
To execute the uninstall command, you would then run this from your terminal:
php artisan my-first-package:uninstall
You may want to additionally execute the following lines to completely eliminate the package from the environment:
If you are doing any kind of UI related work or sometimes even other backend work that you need to include npm modules, here is how you can go about it.
Make sure to add all your configuration and dependencies within your packages package.json , located in the root directory of your package (/opt/processmaker-plugins/my-first-package if you have been following along).
Then run your npm commands:
npm install && npm run dev
Step 4: The Service Provider
Finally, the service provider class is what contains the instructions that laravel will execute when your package is loaded.
Here is an example of what can be contained inside a service provider class, specifically within the boot method:
public function boot(){
//Load any blade views
$this->loadViewsFrom(__DIR__ . '/../resources/views/', 'my-first-package');
//Publish package specific assets
$this->publishes([
__DIR__.'/../public' => public_path('vendor/processmaker/my-first-package'),
], 'my-first-package');
if ($this->app->runningInConsole()) {
require(__DIR__ . '/../routes/console.php');
} else {
// Assigning to the web middleware will ensure all other middleware assigned to 'web'
// will execute. If you wish to extend the user interface, you'll use the web middleware
Route::middleware('web')
->namespace($this->namespace)
->group(__DIR__ . '/../routes/web.php');
Route::middleware('api')
->namespace($this->namespace)
->prefix('api/1.0')
->group(__DIR__ . '/../routes/api.php');
//Push the menu class, if you have one
Route::pushMiddlewareToGroup('web', AddMyFirstPackageMenus::class);
}
//Load any migrations you may have for the database
$this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
// Register a seeder that will be executed in php artisan db:seed
$this->registerSeeder(MyFirstPackageSeeder::class);
// Complete the connector boot
$this->completePluginBoot();
}
This can also be used in the install and uninstall commands above.
Working programming knowledge
To code the package. Familiarity with Laravel & PHP is a big plus.
This is an advanced development topic.
Access to ProcessMaker Platform
CLI access to a ProcessMaker instance with super user privileges. Typically, this is done in a local development environment.
