Installing Workflow Process Service

Workflow Process Service can be run in the Workflow Process Service Authoring environment or the Workflow Process Service Server environment. The authoring environment comes with IBM® Business Automation Studio and allows you to create, maintain, and edit Business Automation Workflow. Both environments run Business Automation Workflow and have IBM Workplace as the front-end user interface. Each of these environments has the same prerequisites but they have unique Docker images.

For details, see IBM Workflow Process Service.

1. Installing prerequisites

Workflow Process Service uses Docker Compose for installation and requires a PostgreSQL 12.x database. It is recommended that access to the database is securely exposed using TLS encryption.
  1. Check the detailed system requirements.
  2. Install Docker Engine 19.03 or later through Install Docker Engine. Information about supported Linux operation system versions is available through the link.
  3. Install Docker Compose 1.27.3 or later through Install Docker Engine
  4. Prepare PostgreSQL database. To make sure the PostgreSQL database is configured correctly for the customer workload, update the following parameters in the postgresql.conf file of the database server:
    Parameter Setting Description
    shared_buffers Minimum 1024 MB PostgreSQL performance tuning recommends using 25% of the memory for the shared buffer. Updates to the Linux kernel configuration might also be required. For more information, see the PostgreSQL tuning guides.
    work_mem Minimum 20 MB This parameter applies to each session and many user sessions can cause large memory usage. This memory is critical because it is used for sort operations. The running time can increase significantly if the value is set too low. For example, the running time may be over an hour for toolkit deployments.
    max_prepared_transactions For example, 200 This value should be at least as large as the max_connections setting.
    max_wal_size For example, 6 GB For larger workloads, the default value must be increased. To check if an increase is required, see the PostgreSQL server log files.
    log_min_duration_statement For example, 5000 This optional parameter allows you to log statements that exceed the specified running time to identify bottlenecks and potential tuning areas. This value is measured in milliseconds. For example, a value of 5000 corresponds to 5 seconds.
  5. You can enable full text search and dashboard support by activating Process Federation Server (PFS) runtime in Process Federation Server. To activate Process Federation Server, you must get Elasticsearch 7.8 or later. Before you start installation, set up an Elasticsearch node or cluster. For more information, see Enabling full text search and dashboard support in Workplace.

2. Configuring the docker-compose YAML file

Create a folder on your local computer, such as sample/folder, where you will run Docker Compose. In the new folder, create a new file named docker-compose.yml. Get the docker-compose.yml file from icp4a/workflow-process-service-samples and copy the contents into your new file. You can choose to install the Workflow Process Service Authoring environment or the Workflow Process Service Server environment by uncommenting the appropriate line at the beginning of the file.

Before you run docker-compose up, you must make the following changes to the YAML file:

  1. Choose the Workflow Process Service Authoring environment or the Workflow Process Service Server environment.

  2. To successfully connect to your PostgreSQL database, set the following environment variables:
    Environment Variable Description
    DB_SERVER_NAME Hostname to connect to the PostgreSQL database.
    DB_SERVER_PORT Port to connect to the PostgreSQL database.
    DB_DATABASE_NAME Name of the database.
    DB_USERNAME User to authenticate the connection to the PostgreSQL database. The database must contain a schema with the same name as DB_USERNAME.
    DB_PASSWORD Password to authenticate the connection to the PostgreSQL database.
  3. If PostgreSQL database is using shared_buffers, mount the root certificate that was used to sign the PostgreSQL server certificate, so the client can verify that the server's leaf certificate was signed by its trusted root certificate. This root certificate must be mounted in /shared/custom/cert-truststoreed/db_root.crt. This file must have the appropriate ownership and access rights to allow dba-user (userId=50001) to read it. To set required ownership and access rights, run the following commands:
    chown 50001:0 db_root.crt
    chmod 400 db_root.crt
  4. Create the database for Workflow Process Service.
    1. Create a file named create-wps-database.sql and copy it to your PostgreSQL server.
    2. Configure your database by using the following commands:
      -- create user wpsdmin
      -- wpsdb
      GRANT ALL PRIVILEGES ON DATABASE wpsdb to wpsadmin;
      \c wpsdb;
      In this example:
      • wpsdmin is the username that Workflow Process Service uses to connect to the database.
      • wpsadmin_password is the password that Workflow Process Service uses to connect to the database.
      • wpsdb is the database name for the Workflow Process Service database. This name is case-sensitive.
    3. Run the following commands on the PostgreSQL server:
      su - postgres
      psql -f create-wps-database.sql
  5. Configure your passwords. By default, passwords are randomly generated. You can set your own passwords by mounting a file at /shared/custom/env/server.env. For example, the file might look like:
    # OIDC client secret, this secret must not be modified after the very first start of the environment
    # Admin user password
    # FUNCTIONAL_USERNAME and FUNCTIONAL_PASSWORD are designed for API invoke. It is used to call automation service by default.
    # The password used to access the keystore file when SSL is enabled.
    Make sure the user dba-user (id=50001) has access to these files:
    chown 50001:0 *.env
    chmod 400 *.env
    To mount your own server.env file on an environment that relies on generated passwords, you must start from a copy of the file located at /shared/custom/env/server.env. The CLIENT_SECRET password is unchanging and you must reuse the same CLIENT_SECRET value as the one that was generated in /shared/custom/env/server.env. If you rely on the generated keystore and truststore, reuse the same SSL_KEYSTORE_PASSWORD value as the one which was generated in /shared/custom/env/server.env.
  6. Configure your keystore and truststore. If you want to provide your own keystore and truststore, you can mount them in PKCS12 format to the /shared/custom/tls/key.p12 and /shared/custom/tls/trusts.p12 locations. For example:
          - ./config/tls/key.p12:/shared/custom/tls/key.p12:Z
          - ./config/tls/trusts.p12:/shared/custom/tls/trusts.p12:Z 
    To mount these files, dba-user (id=50001) must have access to these files:
    chown 50001:0 *.p12
    chmod 400 *.p12
    You must also either provide the keystore and truststore password as documented in the previous step, or provide the password through the SSL_KEYSTORE_PASSWORD environment variable. If you do not provide your own keystore and truststore, they are automatically generated when IBM Workflow Process Service is started. Upon start, when the truststore is generated, all PEM certificates that are found in /shared/custom/cert-trusted folder are added to the truststore.
    Note: The truststore file must have either the .pem or .crt file format.
  7. Configure your hostname. You must configure the EXTERNAL_HOSTNAME environment variable to match the hostname that you use to remotely access the Workflow Process Service Rest API, IBM Workplace, and, when you are running the Workflow Process Service Authoring environment, the IBM Business Automation Studio.

3. Running your environment

  1. If your operating system is Linux and uses Docker as the container engine, make sure the container has read and write permissions in the folder where you want to run docker-compose. Because the container user ID is 50001 and belongs to the root group, you can use the following command to change the folder's permissions:
    sudo chown 50001:0 current_sample_folder
  2. To get the Docker image, follow one of these sets of steps.
    • Connect to the Docker repository where the Docker image is.
      1. Log in to MyIBM Container Software Library with the IBMid and password that is associated with the entitled software.
      2. In the Container software library tile, verify your entitlement on the View library page, and then go to Get entitlement key to retrieve the key.
      3. Use the command docker login and log in to the entitled registry with your entitlement key.
    • Download the Workflow Process Service package (.tgz file) from IBM Passport Advantage.
      1. In Passport Advantage, search for "IBM Cloud Pak for Business Automation 21.0.2 Workflow Process Service Multiplatform English (G01HFEN)" and download "CP4BA_21.0.2-wps.tgz". See IBM Cloud Pak for Business Automation 21.0.2 Download Document.
      2. Extract the archive.
      3. Load the images by changing directory (cd) to the extracted images folder and running the docker load command.
        docker load -i workflow-ps-authoring_21.0.2.tar.gz
        docker load -i workflow-ps-server_21.0.2.tar.gz
      4. (Optional) Push the images to your docker registry. Log in to your docker registry, and push the docker images into your docker registry using the following commands:
        docker login <server>
        docker tag workflow-ps-server:21.0.2 <server>/workflow-ps-server:21.0.2
        docker tag workflow-ps-authoring:21.0.2 <server>/workflow-ps-authoring:21.0.2
        docker push <server>/workflow-ps-server:21.0.2
        docker push <server>/workflow-ps-authoring:21.0.2
        where <server> is the host of the docker image registry that you want to use to pull the images. For example, myregistry.local:5000 or localhost:8080 for a self-hosted registry.

        Update the image tags in the docker-compose.yml file.

  3. Start your Workflow Process Service environment by running the command docker-compose up in the folder where the docker-compose.yml file is located.
  4. Monitor the output of the docker-compose up command. The server is up when you see a message similar to the following:
    The system maintenance monitor is determining if maintenance is required. The system is in an OK state.

Process Portal is not deployed in Workflow Process Service.

The following are commands that you can use for your environment:
  • To start your environment, run docker-compose start.
  • To stop your environment, run docker-compose stop.
  • To restart your environment, run docker-compose restart.
  • To delete your environment, run docker-compose down. This command stops and deletes all running containers as well as the Docker network created by docker-compose. The Docker volumes remain so that your data is recovered next time you start the environment. You must call docker-compose down between two consecutive calls of docker-compose up. Otherwise, PostgreSQL will fail to start.

4. Verifying your installation

  1. Go to https://external_hostname:external_https_port/Workplace to launch the hiring sample process.
  2. Go to https://external_hostname:external_https_port/oidc/endpoint/ums/registration to verify that OIDC clients are registered successfully.
  3. To get the access URLs, admin username, and admin password, run the following command:
    docker exec <container_name> /scripts/
    Follow the links in the output of the command to access Workplace and Business Automation Studio.
  4. To get information about your environment variables, run the following command:
    docker exec <container_name> /scripts/
Data is persisted into the following Docker volumes that are automatically created by Docker Compose:
  • workflow_runtime_data - This volume contains the data that is persisted across restarts
  • workflow_runtime_logs - This volume contains logs, first failure data capture (FFDC) data, and heap dumps generated by the container
To list your volumes, run docker volume ls. To retrieve the location of the volume in your Docker host filesystem, run docker volume inspect volume_name. To delete a volume, run docker volume rm volume_name.


During Docker Compose startup, you might see some login failures in the Docker logs. These login failures are harmless and you can ignore them. They happen because the event manager keeps checking the login status and waits for the client registration before it starts.

Permission denied when running docker-compose up

When you run docker-compose up, you might get the following error:
mkdir: cannot create directory '/shared/custom/env': Permission denied
pc exited with code 1

Follow these steps:

  1. Run docker volume ls to check the created volumes, then find the volume whose name contains production_workflow_runtime_data. Check the details of the volume.
  2. The device that is output by docker volume inspect production_workflow_runtime_data is resolved to an absolute path if docker-compose is run successfully. If the output device is not an absolute path, you must upgrade docker-compose to the latest version because it can't resolve relative paths.
    • The following is an example of docker-compose correctly resolving the absolute path of the device:
      docker volume inspect < volume name >
              "Options": {
                  "device": "/home/tester/ci.docker.baw-designer-mini/test/tryandbuy-compose/persistence/basic",
    • The following is an example of docker-compose failing to resolve the absolute path of the device:
      docker volume inspect < volume name >
              "Options": {
                  "device": "./",

Cannot access Workplace or Business Automation Studio in Chrome

If you can't access Workplace or Business Automation Studio from the Chrome browser on Mac, try another browser. Alternatively, follow these steps:
  1. Click the lock icon to the left of the URL.
  2. In the box that pops up, click Certificate is not valid.
  3. Another box pops up showing information about the certificate. Drag the large certificate icon to a Finder window. A cer file is created in the location you drag it to.
  4. Open the Keychain Access app on your Mac.
  5. Go to the Certificates tab and drag your cer file onto the Keychain Access app.
  6. Double-click your Workflow Process Service certificate and expand the Trust section. Under the When using this certificate section, set the value to Always Trust.
  7. Close the dialog box and use your Mac password to save your settings.

You can customize Workflow Process Service in many ways, including by setting environment variables or Liberty variables. See Customizing Workflow Process Service.

Parent topic: Installing