Utilities for IBM Cloud Pak® for Business Automation
Last update: 2024-02-01 use '1.1.2'
> branch 1.1.2
Minimal adjustments
> branch 1.1.1-stable
All generated files are now created in 'prjfolder/output' folder.
> branch 1.1.0-stable
bug fixed:
- wrong tag for federated CR
new functionalities:
- CR in yaml format generated into 'output' folder
- new run option '-g' for generate CR only without deployment
This repository contains a series of examples and tools for creating and configuring Workflow Process Service (WFPS) in IBM Cloud Pak for Business Automation deployment.
Two scenarios are described, one with non-federated servers and one with federated servers.
For both scenarios we will use a 'starter' type installation.
The second scenario is preparatory to a more complex configuration which requires the presence of a federated BAW runtime instance as well.
The BAW in its '/ProcessPortal' dashboard will offer the applications/tasks running on the other federated WFPSs.
WARNING:
++++++++++++++++++++++++++++++++++++++++++++++++
This software and the configurations contained in the repository MUST be considered as examples for educational purposes.
Do not use in a production environment without making your own necessary modifications.
++++++++++++++++++++++++++++++++++++++++++++++++
Please use '-stable' versions, the main branch may contain untested functionality.
See 'Prerequisites' section before deploying WFPS servers.
If you want run a WFPS instance in federated environment using 'Process Federation Server' in container (same namespace) you must configure a PFS deployment; use guidance and tools from repository https://github.com/marcoantonioni/cp4ba-process-federation-server ...will be public soon.
You may deploy non-federated WFPS into same namespace of federated WFPS server.
All examples make use of dynamic storage, the presence of a storage class for dynamic volume allocation is required.
The tools 'oc' and 'jq' are required.
The 'openssl' tool is required only for the integration scenario with external services protected by TLS transports.
All examples and scripts are only available for Linux boxes with bash shell.
WARNING: before run any command please update configuration files with your values.
WFPS configuration file variables
WFPS_NAME=<name-of-cr> # any name k8s compatible
WFPS_NAMESPACE=<target-namespace> # any name k8s compatible
WFPS_STORAGE_CLASS=<name-of-file-type-storage-class> # select one available from your OCP cluster
WFPS_APP_VER=<cp4ba-version-number> (eg: 23.0.2)
WFPS_APP_TAG="${WFPS_APP_VER}" # do not modify
WFPS_FEDERATE=<true|false> # if true the deployment scripts generate the required tags
# self explaining
WFPS_LIMITS_CPU=750m
WFPS_LIMITS_MEMORY=2048Mi
WFPS_REQS_CPU=500m
WFPS_REQS_MEMORY=1024Mi
# federation values
WFPS_STORAGE_CLASS_BLOCK=<name-of-block-type-storage-class> # select one available from your OCP cluster
WFPS_FEDERATE_TEXTSEARCH=<true|false> # if true the deployment scripts generate the required tags
WFPS_FEDERATE_TEXTSEARCH_SIZE="10Gi" # size of storage used by PVC
WFPS_FEDERATE_TEXTSEARCHSIZE_SNAP="2Gi" # size of storage used by PVC
Trusted certificates configuration file variables. The script will create a tls type secret containing the public key obtained from endpoint url.
TCERT_ENDPOINT_URL_1=<hostname-and-port-of-target-service> # eg: cpd-cp4ba.apps.1234567890.cloud.techzone.ibm.com:443
TCERT_SECRET_NAME_1=<secret-name> # any name k8s compatible
# add as you like with sequential number as suffix
TCERT_ENDPOINT_URL_2=
TCERT_SECRET_NAME_2=
The demo applications in this repository have been developer using CP4BA BAStudio v23.0.2
For each application both source code (.twx) and deployable package (.zip) are in 'apps' folder
The app SimpleDemoWfPS implements a process named 'SimpleProcess'. This process can be started either via '/Workplace' browser or via REST service (see example interaction with cUrl). The process implements two tasks associated respectively with the Requester role and the Validator role (see TeamBindings for associated users).
The app SimpleDemoStraightThroughProcessingWfPS implements a process named 'SimpleSTPProcess'. This process can be started either via '/Workplace' browser or via REST service (see example interaction with cUrl). The 'Straight Through Processing' type process does not implement tasks, it starts and ends independently.
Both processes write to the server log file (to consult the logs see example in the 'Spare commands' section
To continue with the deployment examples, the following prerequisites must be met:
- The destination namespace must contain at least a running Foundation deployment.
Examples for WFPS server deployments.
# WFPS deploy (non federated configuration)
# REMEMBER: adapt the properties file to your environment
# 1. deploy WFPS
time ./wfps-deploy.sh -c ../configs/wfps1.properties
# WFPS deploy using trusted certificates (non federated configuration)
# REMEMBER: adapt the properties file to your environment
# 1. create secret with remote server certificate
time ./wfps-add-secrets-trusted-certs.sh -c ../configs/wfps2.properties -t ../configs/trusted-certs.properties
# 2. deploy WFPS and add trusted certificates list
time ./wfps-deploy.sh -c ../configs/wfps2.properties -t ../configs/trusted-certs.properties
./wfps-export-env-vars-to-file.sh -c ../configs/wfps1.properties
./wfps-export-env-vars-to-file.sh -c ../configs/wfps1.properties
# source using generated vars file (adapt the file name to your wfps name)
source ../output/exp-wfps-1.vars
oc rsh -n ${WFPS_NAMESPACE} ${WFPS_NAME}-wfps-runtime-server-0 tail -n 1000 -f /logs/application/${WFPS_NAME}-wfps-runtime-server-0/liberty-message.log
Example for installing applications.
# install first application using WFPS runtime described in 'wfps1.properties'
time ./wfps-install-application.sh -c ../configs/wfps1.properties -a ../apps/SimpleDemoWfPS.zip
# install second application using WFPS runtime described in 'wfps2.properties'
time ./wfps-install-application.sh -c ../configs/wfps2.properties -a ../apps/SimpleDemo2WfPS.zip
# install third application using WFPS runtime described in 'wfps2.properties'
time ./wfps-install-application.sh -c ../configs/wfps2.properties -a ../apps/SimpleDemoStraightThroughProcessingWfPS.zip
Applications are configured with TemBindings ready for 'cpadmin' and 'cp4admin' users.
In the case of a 'starter' type CP4BA deployment the local LDAP is configured for user1, user2, etc...
The example configurations assume the presence of these user names, in case you can modify the list of users in the properties file.
For team bindings configuration see file './configs/team-bindings-app-1.properties'
# parameters:
# -c path to wfps configuration file
# -t path to team bindings configuration file
# -r [optional] remove actual team binding configuration
time ./wfps-update-team-bindings.sh -c ../configs/wfps1.properties -t ../configs/team-bindings-app-1.properties -r
To activate|deactivate or make as 'default' a snapshot
# deactivate preinstalled demo app, force process instances suspension
time ./wfps-update-application.sh -c ../configs/wfps1.properties -a HSS -b RHSV180 -s deactivate -f
# activate preinstalled demo app
time ./wfps-update-application.sh -c ../configs/wfps1.properties -a HSS -b RHSV180 -s activate
# deactivate app, dont force (may result in error if unique snapshot)
time ./wfps-update-application.sh -c ../configs/wfps1.properties -a SDWPS -b 0.5 -s deactivate
# deactivate demo app, force process instances suspension
time ./wfps-update-application.sh -c ../configs/wfps1.properties -a SDWPS -b 0.5 -s deactivate -f
# activate app
time ./wfps-update-application.sh -c ../configs/wfps1.properties -a SDWPS -b 0.5 -s activate
Prerequisite: The snapshot must be deactivated
# remove app, no force (may result in error if unique snapshot)
time ./wfps-remove-application.sh -c ../configs/wfps1.properties -a SDWPS -b 0.5
# remove app, force
time ./wfps-remove-application.sh -c ../configs/wfps1.properties -a SDWPS -b 0.5 -f
# remove preinstalled demo app, force
time ./wfps-remove-application.sh -c ../configs/wfps1.properties -a HSS -b RHSV180 -f
Below are some examples for invoking REST services exposed by the demo applications deployed in WFPS.
The script 'wfps-export-env-vars-to-file.sh' exports the environment variables necessary to interact via 'cUrl' with REST services into a support file.
Login in browser to '/Workplace' as a user defined in TeamBindings role to interact with tasks. To administer the WfPS runtime login in browser to '/ProcessAdmin' as admin user defined in configuration variable 'WFPS_ADMINUSER'.
# generate and source env vars
./wfps-export-env-vars-to-file.sh -c ../configs/wfps1.properties
source ../output/exp-wfps-1.vars
# call a service
curl -sk -u ${WFPS_ADMINUSER}:${WFPS_ADMINPASSWORD} -H 'accept: application/json' -H 'content-type: application/json' -H 'BPMCSRFToken: '${WFPS_CSRF_TOKEN} -X POST ${WFPS_EXTERNAL_BASE_URL}/automationservices/rest/SDWPS/SimpleDemoREST/startService -d '{"request": {"name":"Marco", "counter": 10, "flag": true}}' | jq .
# call a service that start a new process instance
curl -sk -u ${WFPS_ADMINUSER}:${WFPS_ADMINPASSWORD} -H 'accept: application/json' -H 'content-type: application/json' -H 'BPMCSRFToken: '${WFPS_CSRF_TOKEN} -X POST ${WFPS_EXTERNAL_BASE_URL}/automationservices/rest/SDWPS/SimpleDemoREST/startProcess -d '{"request": {"name":"Marco in process", "counter": 20, "flag": true}}' | jq .
# generate and source env vars
./wfps-export-env-vars-to-file.sh -c ../configs/wfps2.properties
source ../output/exp-wfps-2.vars
# test STP demo
curl -sk -u ${WFPS_ADMINUSER}:${WFPS_ADMINPASSWORD} -H 'accept: application/json' -H 'content-type: application/json' -H 'BPMCSRFToken: '${WFPS_CSRF_TOKEN} -X POST ${WFPS_EXTERNAL_BASE_URL}/automationservices/rest/SDSTPWP/ServiceSTP/startProcess -d '{"request": {"contextId":"ctx1", "counter": 3, "delayMillisecs": 100}}' | jq .
You can federate a WFPS instance only after installing a PFS within the same namespace.
To federate or unfederate an existing wfps instance set WFPS_FEDERATE var to true for federate or false to unfederate
# REMEMBER: adapt the properties file to your environment
# WFPS must exists
time ./wfps-federate.sh -c ../configs/wfps1.properties
# get storage classes
oc get sc
# get Zen admin user name and password
oc get secrets ${WFPS_NAMESPACE} platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 -d && echo
oc get secrets ${WFPS_NAMESPACE} platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d && echo
# delete all wfps
oc get wfps --no-headers | awk '{print $1}' | xargs oc delete wfps
Installing a CP4BA Workflow Process Service production deployment https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/23.0.2?topic=deployments-installing-cp4ba-workflow-process-service-production-deployment
Federating IBM Business Automation Workflow on containers https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/23.0.2?topic=deployment-federating-business-automation-workflow-containers
TOOLS
Openshift CLI https://docs.openshift.com/container-platform/4.14/cli_reference/openshift_cli/getting-started-cli.html
JQ https://jqlang.github.io/jq
For other free tools related to IBM Cloud Pak for Business Automation you can search for projects with the prefix 'cp4ba-' in my public git https://github.com/marcoantonioni