Advanced setup

Configuration file editing guidelines

The processmining.conf is a configuration file that contains properties required for IBM Process Mining to work properly. The file is distributed to work without any modifications if the default values are used. However, when you edit the file, make sure to follow these guidelines:

You must change the values you need (for example, LDAP hostname). You don’t need to delete the values you aren’t using.
You must specify all the values, even if they’re blank. Otherwise, IBM Process Mining doesn’t start.
If you accidentally make a change, this might break the YAML format style and cause it not to work properly.

Running as a service

To run the application as a service, enter the following commands as the root user:

cp <PM_HOME>/bin/pm*.service  /etc/systemd/system/
chmod 664 /etc/systemd/system/pmweb.service
chmod 664 /etc/systemd/system/pmengine.service
chmod 664 /etc/systemd/system/pmanalytics.service
chmod 664 /etc/systemd/system/pmaccelerators.service
chmod 664 /etc/systemd/system/pmmonitoring.service
chmod 664 /etc/systemd/system/pmmonet.service
chmod 664 /etc/systemd/system/pmbrm.service

systemctl daemon-reload
systemctl enable pmengine.service
systemctl enable pmweb.service
systemctl enable pmanalytics.service 
systemctl enable pmaccelerators.service 
systemctl enable pmmonitoring.service
systemctl enable pmmonet.service
systemctl enable pmbrm.service

You must modify the *.service files to set the following configurations:

The correct RUNAS user
The correct PM_HOME path

Service start and stop

Use the following commands to test the service:

systemctl start pmmonet.service
systemctl start pmengine
systemctl start pmweb
systemctl start pmanalytics
systemctl start pmaccelerators
systemctl start pmmonitoring
systemctl start pmbrm
systemctl stop pmmonet.service
systemctl stop pmengine
systemctl stop pmweb
systemctl stop pmanalytics
systemctl stop pmaccelerators
systemctl stop pmmonitoring
systemctl stop pmbrm

Important: If you have SELinux active, you must perform additional tasks that are identified with SELinux.

Email

The email service is used to send a password reset email to the user.

To enable the email service, edit the email section of <PM_HOME>/etc/processmining.conf as follows:

email: {
  from: "sender@mycompany.com" #optional, if empty user field will be used
  user:"theaccount@mycompany.com",
  password:"2bTPnxKK6rsf3z6VNpcEqA==",
  smtp: {
          starttls: {
                  enable: true,
                  required: true
          },
    auth: true,
          host: "smtp.mycompany.com",
    port: "465",
    socketFactory: {
      port: "465" ,
      fallback: false
                }       
        },
  sendgrid : {
                apikey: ""
                #host: "" #optional, if empty default value is https://api.sendgrid.com/v3/mail/send
        }       
},

Using SendGrid

If instead of SMTP is preferred to adopt SendGrid as mailer following configurations are required:

Specify the email.from field (required).
Specify the sendgrid.sendgrid.apikey with your product api key (required).
Define your SengGrid host (optional).
Replace the smtp profile with sendgrid into profile section as in the example.

profiles: [
  ...
  ...
  "sendgrid",                         # smtp | sendgrid
  ...
  ...
]

Note: You must store the password in an encrypted format before saving the password in the file. See the "Password Encryption" section for more details.

Data encryption at rest

Note: This section is valid only for IBM Process Mining Legacy projects.

File system

You can encrypt the data files (CSV) that were uploaded into IBM Process Mining with AWS Key Management Service (KMS).

To encrypt the data files, you must edit the encryption section in: <PM_HOME>/etc/processmining.conf as follows:

encryption: {
  aws: {
    enabled: true,
    # test
    region: "eu-west-1",
    accessKeyId: "<YOUR AWS ACCESS KEY>",
    secretKey: "<YOUR AWS SECRET KEY>",
    # arn of the key
    cmkId: "arn:aws:kms:eu-west-1:992429998518:key/30be1e99-e584-4de5-a2bd-8c9927990f73"  
  }
},

Thereafter, edit the engine.defaults.project.encryptSourceData section and set the value to true.

Warning: The AWS KMS and Server must be in the same AWS region.

Note: The previous configuration must be provided during the first setup. If you enable the CSV encryption and some projects are already created, you must redo the upload of those CSV files.

JVM memory settings

You must set the Java Heap memory settings according to the RAM that is available on the server.

Edit the following properties in <PM_HOME>/bin/environment.conf to set these configurations:

"JVM_MAX_HEAP_ENGINE"

The suggested value is 16 g on a server with 32 Gb RAM available.

The suggested value is 24 g on a server with more than 64 Gb RAM available.

"JVM_MAX_DIRECT_MEMORY_ENGINE"

The default value of 2g is usually adequate to optimize the performance.

"JVM_MAX_HEAP"

The default value of 2g is usually adequate to optimize the performance.

"JVM_MAX_DIRECT_MEMORY"

The default value of 1g is usually adequate to optimize the performance.

After changing the JVM settings, you must restart the server to make the change effective.

Operating system settings

When you create many projects that you plan to use regularly, apply the following settings to as many files as possible:

/etc/sysctl.conf
fs.file-max = 2097152
sudo sysctl -p

sudo vi /etc/security/limits.conf
* soft nofile 500000
ulimit -Sn

Enabling advanced security on Nginx

For a production environment, it is suggested to enable Nginx advanced security configurations.

Mitigate slow-post attack

This configuration is useful to mitigate DDOS slow-post attacks.

For this edit the file /etc/nginx/conf.d/processmining.conf and uncomment sections related to DDOS slow-post mitigate attack.

client_body_timeout 5s;
client_header_timeout 5s;

location /signin 
{
        limit_req zone=one;
        limit_conn addr 10;
        proxy_pass              http://localhost:8080;
  proxy_set_header        X-Real-IP $remote_addr;
  proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header        Host $http_host;
}

And

limit_req_zone $binary_remote_addr zone=one:10m rate=30r/m;
limit_conn_zone $binary_remote_addr zone=addr:10m;

Prevent Host Header Injection

For this edit the file /etc/nginx/conf.d/processmining.conf and

Replace server_name _; with server_name <CURRENT PUBLIC HOSTNAME>;
- That is, server_name pm.mycompany.com;
Uncomment the section Prevent Host Header Injection. This allows logging in to a dedicated file request with an invalid hostname as target.
- Update section that is related to certificates

Secure Cookies

For security reasons, it is recommended to use secure cookies. If the option is enabled, the web application works only with HTTPS and not on the 8080 port.

Edit the profile section in <PM_HOME>/etc/processmining.conf.
Remove the development profile.

Secure integration with Task Mining web application

In a production environment, it is recommended to set the Task Mining web application hostname correctly.

Edit the sso.redirect section in <PM_HOME>/etc/processmining.conf as follows:

sso: {
  redirect: {
        # This must be filled, for security reason, in production environment with the taskmining hostname. I.e. tm.mycompany.com
    allow: ""
  },

Generating a key pair for the process app configuration

A key pair contains a public key and a private key that enable the Process App services to communicate with IBM Process Mining. You can generate the key pair for Process App using the generateKeyPair.sh script. For more information about using the generateKeyPair.sh script to generate key pair, see Creating private key and public key for Process App. However, if you require to remove the existing key pairs and replace them with a new key pair manually, do the following steps:

Go to the /opt/processmining/etc
```
cd /opt/processmining/etc
```
Delete the existing key pair files, acf-ext-publicKey.der, acf-core-privateKey.der and keypair-callsToAcf.pem
```
rm -i acf-ext-publicKey.der
rm -i acf-core-privateKey.der
rm -i keypair-callsToAcf.pem
```

Generate an RSA key pair in the .pem format

openssl genrsa -out keypair-callsToAcf.pem 2048

Run the following command to export the public key in the .der format to the <PM_HOME>/etc directory after generating the key pairs:
```
openssl rsa -in keypair-callsToAcf.pem -outform DER -pubout -out acf-ext-publicKey.der
```
Run the following command to export the private key in the .der format to the {PM_HOME}/etc directory after generating the key pairs:
```
 openssl pkcs8 -topk8 -nocrypt -in keypair-callsToAcf.pem -outform DER -out acf-core-privateKey.der
```

Tip: If the application is not installed in the /opt/processmining directory, then you must set the publicKeyPath property in the <PM_HOME> /etc/processmining.conf file to the following value:

filesystem.home:
"&lt;PM_HOME&gt;/etc/acf-ext-publicKey.der"

Generating the JWT signkeys for process app

You can generate JWT signkeys to establish and secure communication between the Process App services and applications. By default, a signkey for IBM Process Mining is available in the basic settings. If you want to generate new JWT signkeys, use the following key generator portal: https://asecuritysite.com/encryption/keygen.

To generate a JWT signkey in the key generator tool, do the following steps:

In the Passphrase field, type a passphrase of your choice.
Select the encryption algorithm as illustrated below to generate and encrypt the signkey for IBM Process Mining:

Asecuritysite.com

Copy the generated JWT signkeys to the following locations:
- First generated key for IBM Process Mining:
1. Copy to the issuer.jwt.key.ProcessMiningService field in the <PM_HOME>/etc/accelerator-core.properties file
2. Copy to the issuer.jwt.key.ProcessMiningService field in the accelerator section in the <PM_HOME>/etc/processmining.conf file

Configuring the settings for RPA bot generation

You can use IBM Process Mining to generate RPA bots. To do so, it is mandatory that the Task Mining environment is linked to the Process Mining environment and that the active vendors are defined in the configuration file.

To link the Task Mining application to the Process Mining application, you must update the etc/processmining.conf file with the following configuration:

taskmining : {
url : "https://pm-qa-candidate-task-miner.fyre.ibm.com"
}

Note: You must update the value for URL with the URL to Task Mining application in your device.

You must mention the allowed set of active vendors in the etc/processmining.conf file. To define the active vendors for an installation, update the etc/processmining.conf file with the following configuration:

rpa : {
activeVendors : "IBM_RPA,UI_PATH"
}