Skip to content

Latest commit

 

History

History
264 lines (213 loc) · 17.3 KB

README.md

File metadata and controls

264 lines (213 loc) · 17.3 KB
Raw

mod-camunda

Copyright (C) 2018-2022 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Table of Contents

  1. Docker deployment
    1. Publish docker image
  2. Camunda Module Dependencies
  3. Workflow Project Structure
  4. App Deployment
  5. Camunda APIs
  6. Kafka Message Broker
  7. FOLIO Integration
  8. Additional Information
  9. Issue Tracker

Docker deployment

cd ..
git clone https://github.com/TAMULib/mod-workflow.git
cd mod-workflow
mvn clean install

cd mod-camunda
docker build -t folio/mod-camunda .
docker run -d -p 9000:8081 folio/mod-camunda

Publish docker image

docker login [docker repo]
docker build -t [docker repo]/folio/mod-camunda:[version] .
docker push [docker repo]/folio/mod-camunda:[version]

Camunda Module Dependencies

This module extends spring-module-core and brings in Camunda BPM to enable workflow capabilities. Camunda is an open-source BPM platform that is embedded in this module via the following dependencies.

# --- VERSIONS ---
<camunda.version>7.9.0</camunda.version>
<camunda.spring.boot.version>3.0.0</camunda.spring.boot.version>

# --- DEPENDENCY MANAGEMENT ---
<dependency>
  <!-- Import dependency management from Camunda -->
  <groupId>org.camunda.bpm</groupId>
  <artifactId>camunda-bom</artifactId>
  <version>${camunda.version}</version>
  <scope>import</scope>
  <type>pom</type>
</dependency>

# --- DEPENDENCIES ---
<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter</artifactId>
  <version>${camunda.spring.boot.version}</version>
</dependency>

<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-webapp</artifactId>
  <version>${camunda.spring.boot.version}</version>
</dependency>

<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-rest</artifactId>
  <version>${camunda.spring.boot.version}</version>
</dependency>

Workflow Project Structure

Business Process Models and Decision Models are built using the Camunda Modeler which impelements BPMN 2.0 and DMN 1.1 specifications.

  • .bpmn files are stored in /src/main/java/resources/workflows
  • .dmn files are stored in /src/main/java/resources/decisions

Any Java code that is executed in the context of a process is usually written in a Java Delegate. These classes are stored in /src/main/java/org/folio/rest/delegate/

Deploy and run the application

  1. Run the application mvn clean spring-boot:run
  2. Deploy all the processes by running scripts/deploy.sh file
  3. Navigate to Camunda Portal localhost:9000/app/welcome/default/#/welcome
  4. Log in as admin user: admin, password: admin

Camunda APIs

Kafka Message Broker

We are using Kafka as the message broker.

FOLIO Integration

For detailed information to bring up a FOLIO instance refer to https://github.com/folio-org/folio-ansible.

The following requires Vagrant 1.9.6 or above.

vagrant up
# wait

When finished Okapi will be running with mod-workflow and mod-camunda deployed under the diku tenant. mod-camunda will have its port forwarded for access to the Camunda webapps. FOLIO UI will be accessible at http://localhost:3000; username: diku_admin, password: admin.

Okapi is being built and redeployed from within this vagrant. Eventually this will not need to happen. If a specific branch of either mod-camunda or mod-workflow is desired to be deployed, modify the Vagrantfile git checkout main to the desired branch and restart vagrant. vagrant destroy, vagrant up

Development

In order to facilitate development on mod-camunda in the context of Okapi, there is a sync directory from the host machine to the guest machine. The host directory is at .vagrant/sync and it will contain okapi, mod-camunda, and mod-workflow. The development and git branch management can be done on the host machine. The guest directory is at /sync. The redeployment of a module must be done from the guest machine.

vagrant ssh
sudo su
cd /sync
# kill mod-camunda running on port 9000
kill $(lsof -t -i :9000)
cd mod-camunda
mvn clean install
nohup java -jar target/mod-camunda-1.1.0.jar &

Login

curl -v -H "Content-Type: application/json" -H "X-Okapi-Tenant: diku" http://localhost:9130/authn/login -d '{"username": "diku_admin", "password": "admin"}'

The response headers of interest are X-Okapi-Token and refreshToken.

Refresh Token

curl -v -H "X-Okapi-Tenant: diku" -H "Content-Type: application/json" http://localhost:9130/refresh -d '{"refreshToken": "`[refresh token goes here]`"}'

The body of this response will contain the new X-Okapi-Token.

Workflow Module Triggers

The Trigger entity from mod-workflow is used to select which request-response events from Okapi are to be published to the ${ENV:folio}.workflow.events topic that mod-camunda can subscribe to. In order to create the Triggers we have to provide the correct permissions to the diku_admin. The vagrant will create an example trigger for when a user is created.

Permissions

In order to call mod-camunda and mod-workflow through the Okapi gateway a user will need the appropriate permissions. In order to accommodate this the Vagrantfile runs a shell script in which updates permissions for diku_admin. Providing him with all permissions to all interfaces of mod-camunda and mod-workflow.

Cleanup

When finished it will be desired to cleanup as the FOLIO vagrant uses a lot of resources.

vagrant destroy
rm -rf .vagrant/sync

Removing the synced directory, .vagrant/sync, on the host will remove any changes during development that have not been pushed.

Environment variables:

The environment variables most notable to deployment are described in the Module Descriptor.

The following is a summary of many of them.

Name Default value Description
CAMUNDA_BPM_ADMINUSER_EMAIL admin@localhost The e-mail address of the Camunda administration user.
CAMUNDA_BPM_ADMINUSER_ID admin The account name of the Camunda administration user.
CAMUNDA_BPM_ADMINUSER_PASSWORD admin The password of the Camunda administration user.
CAMUNDA_BPM_DATABASE_SCHEMAUPDATE true If Camunda should auto-update the BPM database schema.
CAMUNDA_BPM_METRICS false Enable or disable Camunda metrics by default.
DB_CHARSET UTF-8 Database charset.
DB_DATABASE okapi_modules Postgres database name.
DB_HOST postgres Postgres host name.
DB_MAXPOOLSIZE 5 Database max pool size.
DB_PASSWORD - Postgres user password.
DB_PORT 5432 Postgres port.
DB_QUERYTIMEOUT 60000 Database query timeout.
DB_USERNAME folio_admin Postgres user name.
JAVA_OPTIONS -XX:MaxRAMPercentage=75.0 Java options.
KAFKA_HOST kafka Kafka broker host name.
KAFKA_PORT 9092 Kafka broker port.
KAFKA_SECURITY_PROTOCOL PLAINTEXT Kafka security protocol used to communicate with brokers (SSL or PLAINTEXT).
KAFKA_SSL_KEYSTORE_LOCATION - The location of the Kafka key store file. This is optional for client and can be used for two-way authentication for client.
KAFKA_SSL_KEYSTORE_PASSWORD - The store password for the Kafka key store file. This is optional for client and only needed if ssl.keystore.location is configured.
KAFKA_SSL_TRUSTSTORE_LOCATION - The location of the Kafka trust store file.
KAFKA_SSL_TRUSTSTORE_PASSWORD - The password for the Kafka trust store file. If a password is not set, trust store file configured will still be used, but integrity checking is disabled.
OKAPI_URL http://okapi:9130 OKAPI URL used to login system user, required
SERVER_PORT 8081 The port to listen on that must match the PortBindings.
SERVER_SERVLET_CONTEXTPATH / The context path, or base path, to host at.
SPRING_FLYWAY_ENABLED false Database migration support via Spring Flyway.
SPRING_JPA_HIBERNATE_DDLAUTO update Auto-configure database on startup.
TENANT_DEFAULTTENANT diku The name of the default tenant to use.
TENANT_FORCETENANT false Forcibly add or overwrite the tenant name using the default tenant.
TENANT_INITIALIZEDEFAULTTENANT true Perform initial auto-creation of tenant in the database (schema, tables, etc..).
TENANT_RECREATEDEFAULTTENANT false When TENANT_INITIALIZEDEFAULTTENANT is true and the database already exists, then drop and re-create.

Permissions

The permissions provided by this module are described in the Module Descriptor under permissionSets.

The permissions defined are here are specific to the module and are usually not directly added to any user. Instead, permissions available for assignment to users or accounts are found in the ui-workflow Module Permission Sets. These ui-workflow permissions are automatically exposed via the appropriate stripe-ui administration interface.

Additional information

Issue tracker

See project FOLIO at the FOLIO issue tracker.