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:

• Docker
• docker-compose

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

1. 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.

2. For OS X users: make path to folder with config shared in Docker -> Preferences... -> File Sharing.

3. 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.

4. Change Minio credentials in .env file. Generate MINIO_ACCESS_KEY and MINIO_SECRET_KEY values with any credentials generator, e.g. pwgen 32 2.

5. Run docker-compose:

   docker-compose up -d

6. Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.

7. Login to HydraOMS with [email protected]/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

1. Follow the instructions below:

   • With Oracle Instant Client.

   • Without Oracle Instant Client (default way).

2. Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.

3. Export all variables from .env file

   export $(cat .env | xargs)
   

4. Change in bpm.yml value of development.base_url from http://camunda:8080/engine-rest/ to http://localhost:8766/engine-rest/

5. In database.yml change value of development.host from <%= ENV['HOMS_DB_HOST'] %> to localhost

6. Install Yarn and run:

   yarn install
   

7. Compile assets:

   yarn dev

8. Start HOMS application in another console tab:

   rails s

9. Create and populate the database (adds an admin user, initial order types, and orders):

   rails db:migrate
   export SEED_DB=true
   rails db:seed

10. Log in at HydraOMS with [email protected]/changeme.

Work with SSO

Requirements:

• Keycloak

For using SSO with HOMS:

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

3. 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:

1. Fork this repo and clone it to your workstation.
2. Create a feature branch for your change.
3. Write code and tests.
4. 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

Links

1. Repo with helper classes for BPMN development.

2. Example of creating a demo business process.

License

Copyright (c) 2019 Latera LLC under the Apache License.