Hydra Order Management System (HOMS)

HOMS is an open source web application for order and business process management.

Application consists of three parts:

User interface - managing orders and tasks for registered users (Single Page Application).
Administrator interface - managing users and order types.
REST API - operations with orders and users.

Requirements:

Compatibility:

Camunda 7.9.0 compatible with PostgreSQL 9.1 / 9.3 / 9.4 / 9.6
MinioRELEASE.2021-06-17T00-10-46Z

Resources:

Documentation: http://hydra-oms.com/docs
Demo: http://demo.hydra-oms.com
Community: http://community.hydra-oms.com
Tickets/Issues: https://github.com/latera/homs/issues

Installation

The prefered way to install HOMS is to use Docker.

In production

Download docker-compose.yml and default .env config file:

wget https://raw.githubusercontent.com/latera/homs/master/docker-compose.yml
wget https://raw.githubusercontent.com/latera/homs/master/.env.sample -O .env

📌 All variables are set in .env file. There you can change them, if you want to.

For OS X users: make path to folder with config shared in Docker -> Preferences... -> File Sharing.
Set SECRET_KEY_BASE variable in your .env with uniq id as value. You can generate key with openssl rand -hex 64 command. For example:
```
SECRET_KEY_BASE=0750fd0eac13032778f0a42e2ab450003eaece477ea881501be0cc438f870a2f498dbbc00ffb7c8379c30c960568a402d315496bb7bc2b3ee324401ba788a
```
⚠️ Make sure this key is secret and don't share it with anyone.
Change Minio credentials in .env file. Generate MINIO_ACCESS_KEY and MINIO_SECRET_KEY values with any credentials generator, e.g. pwgen 32 2.
Run docker-compose:
```
docker-compose up -d
```
Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.
Login to HydraOMS with user@example.com/changeme. Now you are able to start Pizza Order demo process.

You can login to Camunda Admin interface with credentials equal to BPM_USER:BPM_PASSWORD values from .env file (user/changeme if these variables aren't set).

In development

Follow the instructions below:
- With Oracle Instant Client.
- Without Oracle Instant Client (default way).
Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.
Export all variables from .env file
```
export $(cat .env | xargs)
```
Change in bpm.yml value of development.base_url from http://camunda:8080/engine-rest/ to http://localhost:8766/engine-rest/
In database.yml change value of development.host from <%= ENV['HOMS_DB_HOST'] %> to localhost
Install Yarn and run:
```
yarn install
```
Compile assets:
```
yarn dev
```
Start HOMS application in another console tab:
```
rails s
```
Create and populate the database (adds an admin user, initial order types, and orders):
```
rails db:migrate
export SEED_DB=true
rails db:seed
```
Log in at HydraOMS with user@example.com/changeme.

Work with SSO

Requirements:

Keycloak

For using SSO with HOMS:

Add user roles. HOMS use "admin" and "user" client level roles. Only one role could be assigned to user.
Add user attributes in Keycloak: company, department.
Add mappers in Keycloak without prefix:

Name	Mapper type	User attribute	Token clain name	Claim JSON type	Add to ID token	Add to access token	Add to userinfo	Multivalued	Aggregate attributes values
`company`	`User Attribute`	`company`	`company`	string	On	On	On	Off	Off
`department`	`User Attribute`	`department`	`department`	string	On	On	On	Off	Off

Add to HOMS config file homs_configuration.yml:

sso:
  enabled: true
  use_regular_login: true
  keycloak:
    auth_server_url: "http://keycloak_host:keycloak_port/auth/"
    realm: hydra
    client_id: homs
    redirect_uri: "http://homs_host:homs_port/authenticate_by_keycloak"
    secret: "af9504fc-b030-405e-97b6-813220c07a7e"
    logout_redirect: "http://homs_host:homs_port"
    scope:
      - homs

Filter business processes by user

Set cadidate_starters.enabled in hbw.yml to true to send user email to camunda when fetching business processes definition. That way you can allow users to run only certain business processes.

Contributing/Development

The general development process is:

Fork this repo and clone it to your workstation.
Create a feature branch for your change.
Write code and tests.
Push your feature branch to github and open a pull request against master.

Reporting Issues

Issues can be reported by using GitHub Issues.

Testing

HOMS uses RSpec for unit/spec tests. You need to set up different testing database. Otherwise your development DB would be erased.

# Run all tests
bundle exec rspec spec

# Run a single test file
bundle exec rspec spec/PATH/TO/FILE_spec.rb

# Run a subset of tests
bundle exec rspec spec/PATH/TO/DIR

HBW Widget uses jest and snapshots for tests.

# Run frontend tests
jest
# Update snapshots after intentionally changing implementation elements
jest --updateSnapshot

FranckPachot/homs