OperatorFabric README

OperatorFabric is a modular, extensible, industrial-strength and field-tested platform for use in electricity, water, and other utility operations.

System visualization and console integration
Precise alerting
Workflow scheduling
Historian
Scripting (ex: Python, JavaScript)

It is an open source project initiated by RTE with LF Energy.

Table of Contents

1. What does OperatorFabric do in practice?
2. Requirements
3. Getting Started
4. Project Contents
5. Environment variables
6. Gradle Tasks
7. Custom tasks
8. Docker demo
9. Recipes
10. Troubleshooting
11. Contributing

1. What does OperatorFabric do in practice?

To perform their duties, an operator has to interact with multiple applications (perform actions, watch for alerts, etc.), which can prove difficult if there are too many of them.

The idea is to aggregate all the notifications from all these applications into a single screen, and to allow the operator to act on them if needed.

These notifications are materialized by cards sorted in a feed according to their period of relevance and their severity. When a card is selected in the feed, the right-hand pane displays the details of the card: information about the state of the parent process instance in the third-party application that published it, available actions, etc.

In addition, the cards will also translate as events displayed on a timeline (its design is still under discussion) at the top of the screen. This view will be complimentary to the card feed in that it will allow the operator to see at a glance the status of processes for a given period, when the feed is more like a "To Do" list.

Part of the value of OperatorFabric is that it makes the integration very simple on the part of the third-party applications. To start publishing cards to users in an OperatorFabric instance, all they have to do is:

Register as a publisher through the "Thirds" service and provide a "bundle" containing handlebars templates defining how cards should be rendered, i18n info etc.
Publish cards as json containing card data through the card publication API

OperatorFabric will then:

Dispatch the cards to the appropriate users (by computing the actual users who should receive the card from the recipients rules defined in the card)
Take care of the rendering of the cards, displaying details, actions, inputs etc.
Display relevant information from the cards in the timeline

Another aim of OperatorFabric is to make cooperation easier by letting operators forward or send cards to other operators, for example:

If they need an input from another operator
If they can’t handle a given card for lack of time or because the necessary action is out of their scope

This will replace phone calls or emails, making cooperation more efficient and traceable.

For instance, operators might be interested in knowing why a given decision was made in the past: the cards detailing the decision process steps will be accessible through the Archives screen, showing how the operators reached this agreement.

2. Requirements

Important

This section describes the projects requirements regardless of installation options. Please see Getting Started below for details on:

setting up a development environment with these prerequisites
building and running OperatorFabric

2.1. Tools and libraries

Gradle 6
Java 8.0
Maven 3.5.3
Docker
Docker Compose with 2.1+ file format support
Chrome (needed for UI tests in build)

Note	the current Jdk used for the project is Java 8.0.242-zulu.

Important

It is highly recommended to use sdkman and nvm to manage tools versions.

Once you have installed sdkman and nvm, you can source the following script to set up your development environment (appropriate versions of Gradle, Java, Maven and project variables set):

Set up development environment (using sdkman and nvm)

source bin/load_environment_light.sh

2.2. Software

RabbitMQ 3.7.6 +: AMQP messaging layer allows inter service communication
MongoDB 4.0 +: Card persistent storage

RabbitMQ is required for :

Card AMQP push
Multiple service sync

MongoDB is required for :

Current Card storage
Archived Card storage
User Storage

Important

Installing MongoDB and RabbitMQ is not necessary as preconfigured MongoDB and RabbitMQ are available in the form of docker-compose configuration files at src/main/docker

2.3. Browser support

We currently use Firefox (63.0.3). Automatic tests for the UI rely on Chrome (73.0.3683.86).

3. Getting Started

Warning

The steps below assume that you have installed and are using sdkman and nvm to manage tool versions ( for java, gradle, node and npm).

There are several ways to get started with OperatorFabric. Please look into the section that best fits your needs.

Tip	If you encounter any issue, see Troubleshooting below. In particular, a command that hangs then fails is often a proxy issue.

3.1. Build and run using script

The following steps describe how to launch MongoDB, RabbitMQ and SonarQube using Docker, build OperatorFabric using gradle and run it using the run_all.sh script.

3.1.1. Clone repository

git clone https://github.com/opfab/operatorfabric-core.git
cd operatorfabric-core

3.1.2. Set up your environment (environment variables & appropriate versions of gradle, maven, etc…)

source bin/load_environment_light.sh

Tip	From now on, you can use environment variable $OF_HOME to go back to the home repository of OperatorFabric.

3.1.3. Deploy dockerized MongoDB, RabbitMQ and SonarQube

MongoDB, RabbitMQ and SonarQube are needed for the tests to be run so the build can be done.

A docker-compose file with properly configured containers is available there.

The docker-compose can be run in detached mode:

cd src/main/docker/test-quality-environment/
docker-compose up -d

3.1.4. Build OperatorFabric with Gradle

Using the wrapper in order to ensure building the project the same way from one machine to another.

To only compile and package the jars:

cd $OF_HOME
./gradlew assemble

To launch the Unit Test, compile and package the jars:

cd $OF_HOME
./gradlew build

3.1.5. Run OperatorFabric Services using the `run_all.sh` script

bin/run_all.sh start

Tip	See `bin/run_all.sh -h` for details.

3.1.6. Check services status

bin/run_all.sh status

3.1.7. Log into the UI

URL: localhost:2002/ui/

login: admin

password: test

Warning

It might take a little while for the UI to load even after all services are running.

Warning

Don’t forget the final slash in the URL or you will get an error.

3.1.8. Push cards to the feed

You can check that you see cards into the feed by running the push_card_loop.sh script.

services/core/cards-publication/src/main/bin/push_card_loop.sh

3.2. Demonstration mode

If you only want a quick demonstration of what OperatorFabric looks like and what it can do, use our standalone docker demo. See Docker demo for details.

3.3. Going Further

When you feel ready to experiment with the project, or if the steps above don’t quite cover what you’re planning to do, please look into the Recipes section.

Tip	In addition, a Getting Started guide on our website exists. Check it out !

4. Project Contents

4.1. Project Structure

4.1.1. Tree View

project
├──bin
│   └─ travis
├──client
│   ├──cards (cards-client-data)
│   ├──src
│   └──users (users-client-data)
├──services
│   ├──core
│   │   ├──cards-consultation (cards-consultation-business-service)
│   │   ├──cards-publication (cards-publication-business-service)
│   │   ├──src
│   │   ├──thirds (third-party-business-service)
│   │   └──users (users-business-service)
│   ├──infra
│   │   ├──client-gateway (client-gateway-cloud-service)
│   │   ├──config (configuration-cloud-service)
│   │   └──registry (registry-cloud-service)
│   └──web
│       └──web-ui
├──src
|   ├──docs
|   │   ├──asciidoc
|   │   └──modelio
|   └──main
|       ├──docker
|       └──headers
├──tools
│   ├──generic
│   │   ├──test-utilities
│   │   └──utilities
│   ├── spring
│   │   ├──spring-mongo-utilities
│   │   ├──spring-oauth2-utilities
│   │   ├──spring-test-utilities
│   │   └──spring-utilities
│   └──swagger-spring-generators
└─ui

4.1.2. Content Details

bin: contains useful scripts
- travis: travis script for documentation generation and upload to opfab.github.io repository
client: contains REST APIs simple beans definition, may be used by external projects
- cards (cards-client-data): simple beans regarding cards
- src: contains swagger templates for client code generation
- users (users-client-data): simple beans regarding users
services: contains the microservices that make up OperatorFabric
- core: contains core business microservices
  - cards-consultation (cards-consultation-business-service): Card consultation service
  - cards-publication (cards-publication-business-service): Card publication service
  - src: contains swagger templates for core business microservices
  - thirds (third-party-business-service): Third-party information management service
  - users (users-business-service): Users management service
- infra: contains infrastructure microservices
  - client-gateway (client-gateway-cloud-service): spring-gateway client side only gateway microservice, used to serve public apis and web ui
  - config (configuration-cloud-service): spring-configuration centralized configuration microservice
  - registry (registry-cloud-service): eureka microservice registry
- web: contains web pages and application services
  - web-ui: Main OperatorFabric SPA
src
- docs
  - asciidoc: General documentation (Architecture, Getting Started Guide, etc.)
  - modelio: Archive containing documentation diagrams
- main
  - docker: contains docker-compose files to help with tests and demonstrations
  - headers: contains license header files
tools
- generic: Generic (as opposed to Spring-related) utility code
  - test-utilities: Test-specific utility code
  - utilities: Utility code
- spring: Spring-related utility code
  - spring-mongo-utilities : Utility code with Spring-specific dependencies, used to share common features across MongoDB-dependent services
  - spring-oauth2-utilities : Utility code with Spring-specific dependencies, used to share common features across OAuth2-dependent services
  - spring-test-utilities : Utility code with Spring-specific dependencies for testing purposes
  - spring-utilities : Utility code with Spring-specific dependencies
- swagger-spring-generators : Spring Boot generator for swagger, tailored for OperatorFabric needs
ui: Angular sources for the UI

4.2. Conventions regarding project structure and configuration

Sub-projects must conform to a few rules in order for the configured Gradle tasks to work:

4.2.1. Java

[sub-project]/src/main/java	contains java source code
[sub-project]/src/test/java	contains java tests source code
[sub-project]/src/main/resources	contains resource files
[sub-project]/src/test/resources	contains test resource files

4.2.2. Modeling

Core services projects declaring REST APIS that use Swagger for their definition must declare two files:

[sub-project]/src/main/modeling/swagger.yaml	Swagger API definition
[sub-project]/src/main/modeling/config.json	Swagger generator configuration

4.2.3. Docker

Services project all have docker image generated in their build cycle (See Gradle Tasks).

Per project configuration :

docker file : [sub-project]/src/main/docker/Dockerfile
docker-compose file : [sub-project]/src/main/docker/docker-compose.yml
runtime data : [sub-project]/src/main/docker/volume is copied to [sub-project]/build/docker-volume/ by task copyWorkingDir. The latest can then be mounted as volume in docker containers.

4.3. Scripts (bin and CICD)

bin/build_all.sh	builds all artifacts as gradle is not able to manage inter project dependencies
bin/clean_all.sh	remove IDE data (project configuration, build output directory) - idea, vsc
bin/load_environment_light.sh	sets up environment when sourced (java version, gradle version, maven version, node version)
bin/load_environment_ramdisk.sh	sets up environment and links build subdirectories to a ramdisk when sourced at ~/tmp
CICD/prepare_release_version.sh	performs the changes necessary to tag a RELEASE version
CICD/prepare_snapshot_version.sh	performs the changes necessary to tag a SNAPSHOT version
bin/run_all.sh	runs all all services (see below)
bin/setup_dockerized_environment.sh	generate docker images for all services

4.3.1. load_environment_ramdisk.sh

There are prerequisites before sourcing load_environment_ramdisk.sh:

Logged user needs sudo rights for mount
System needs to have enough free ram

Caution

Never ever run a gradle clean or ./gradlew clean to avoid deleting those links.

4.3.2. run_all.sh

Please see run_all.sh -h usage before running.

Prerequisites

mongo running on port 27017 with user "root" and password "password" (See src/main/docker/mongodb/docker-compose.yml for a pre configured instance).
rabbitmq running on port 5672 with user "guest" and password "guest" (See src/main/docker/rabbitmq/docker-compose.yml for a pre configured instance).

Ports configuration

Port
2000	config	Configuration service http (REST)
2001	registry	Registry service http (REST)
2002	gateway	Gateway service http (REST+html)
2100	thirds	Third party management service http (REST)
2102	cards-publication	card publication service http (REST)
2103	users	Users management service http (REST)
2104	cards-consultation	card consultation service http (REST)
4000	config	java debug port
4001	registry	java debug port
4002	gateway	java debug port
4100	thirds	java debug port
4102	cards-publication	java debug port
4103	users	java debug port
4103	cards-consultation	java debug port

4.3.3. setup_dockerized_environment.sh

Please see setup_dockerized_environment.sh -h usage before running.

Builds all sub-projects, generate docker images and volumes for docker-compose.

5. Environment variables

These variables are loaded by bin/load_environment_light.sh bin/load_environment_ramdisk.sh

OF_HOME: OperatorFabric root dir
OF_CORE: OperatorFabric business services subroot dir
OF_INFRA: OperatorFabric infrastructure services subroot dir
OF_CLIENT: OperatorFabric client data definition subroot dir
OF_TOOLS: OperatorFabric tooling libraries subroot dir

Additionally, you may want to configure the following variables

Docker build proxy configuration (used to configure alpine apk proxy settings)
- APK_PROXY_URI
- APK_PROXY_HTTPS_URI
- APK_PROXY_USER
- APK_PROXY_PASSWORD

6. Gradle Tasks

7. Custom tasks

In this section only custom tasks are described. For more information on tasks, refer to the output of the "tasks" gradle task and to gradle and plugins official documentation.

7.1. Services

Common tasks for all sub-projects

Test tasks
- unitTest: runs unit tests
Other:
- copyWorkingDir: copies [sub-project]/src/main/docker/volume to [sub-project]/build/
- copyDependencies: copy dependencies to build/libs

Core

Swagger Generator tasks
- debugSwaggerOperations: generate swagger code from /src/main/modeling/config.json to build/swagger-analyse
- swaggerHelp: display help regarding swagger configuration options for java

Third Party Service

Test tasks
- prepareTestDataDir: prepare directory (build/test-data) for test data
- compressBundle1Data, compressBundle2Data: generate tar.gz third party configuration data for tests in build/test-data
- prepareDevDataDir: prepare directory (build/dev-data) for bootRun task
- createDevData: prepare data in build/test-data for running bootRun task during development
Other tasks
- copyCompileClasspathDependencies: copy compile classpath dependencies, catching lombok that must be sent for sonarqube

infra/config

Test tasks
- createDevData: prepare data in build/test-data for running bootRun task during development

tools/generic

Test tasks
- prepareTestData: copy test data from src/test/data/simple to build/test-data/
- compressTestArchive: compress the contents of /src/test/data/archive to /build/test-data/archive.tar.gz

7.2. Gradle Plugins

In addition to these custom tasks and standard Gradle tasks, OperatorFabric uses several Gradle plugins, among which:

Spring Boot Gradle Plugin
Palantir Docker Gradle Plugin
Docker Compose Plugin
Gradle Swagger Generator Plugin
Gradle Asciidoctor Plugin

8. Docker demo

A global docker compose files for demonstration purposes is available at src/main/docker/deploy : sets up all services, ready for card reception

This setup expose the application UI at localhost:2002/ui/

Warning

Don’t forget the final slash in the URL or you will get an error.

Card publication entry points are exposed at localhost:2102/cards

For debugging purpose the following ports are also exposed:

Complete port table

Port	Forwards to
89	KeyCloak	89	KeyCloak api port
2000	config	8080	Configuration service http (REST)
2001	registry	8080	Registry service http (REST)
2002	gateway	8080	Gateway service http (REST+html)
2100	thirds	8080	Third party management service http (REST)
2102	cards-publication	8080	card publication service http (REST)
2103	users	8080	Users management service http (REST)
2104	cards-consultation	8080	card consultation service http (REST)
2105	actions	8080	actions (REST)
2200	web-ui	8080	card consultation service http (REST)
4000	config	5005	java debug port
4001	registry	5005	java debug port
4002	gateway	5005	java debug port
4100	thirds	5005	java debug port
4102	cards-publication	5005	java debug port
4103	users	5005	java debug port
4104	cards-consultation	5005	java debug port
4105	actions	5005	java debug port
4200	web-ui	5005	java debug port
27017	mongo	27017	mongo api port
5672	rabbitmq	5672	amqp api port
15672	rabbitmq	15672	rabbitmq api port

9. Recipes

9.1. Generating docker images

To Generate all docker images run bin/setup_dockerized_environment.sh.

INFORMATION: If you work behind a proxy you need to specify the following properties to configure alpine apk package manager:

apk.proxy.uri: proxy http uri ex: "http://somewhere:3128" (defaults to blank)
apk.proxy.httpsuri: proxy http uri ex: "http://somewhere:3128" (defaults to apk.proxy.uri value)
apk.proxy.user: proxy user
apk.proxy.password: proxy unescaped password

Alternatively, you may configure the following environment variables :

APK_PROXY_URI
APK_PROXY_HTTPS_URI
APK_PROXY_USER
APK_PROXY_PASSWORD

9.2. Managing a service with docker-compose

Prerequisites : images must be registered

To deploy a service run gradle :[subprojectPath]:composeUp example for the third-party-service service : ` gradle :services:core:third-party-service:composeUp `
To tear down a service run gradle :[subprojectPath]:composeDown
To start an already containerized service run gradle :[subprojectPath]:composeStart
To stop an already containerized service run gradle :[subprojectPath]:composeStop
To follow logs of a running service run gradle :[subprojectPath]:composeLog

9.3. Running sub-project from jar file

gradle :[sub-projectPath]:bootJar
or java -jar [sub-projectPath]/build/libs/[sub-project].jar

9.4. Overriding properties when running from jar file

java -jar [sub-projectPath]/build/libs/[sub-project].jar –spring.config.additional-location=file:[filepath] NB : properties may be set using ".properties" file or ".yml" file. See Spring Boot configuration for more info.
Generic property list extract :
- server.port (defaults to 8080) : embedded server port
:services:core:third-party-service properties list extract :
- operatorfabric.thirds.storage.path (defaults to "") : where to save/load OperatorFabric Third Party data

9.5. Service port table

By default all service built artifacts are configured with server.port set to 8080

If you run the services using bootRun Gradle task or the provided docker-compose files (see [prj]/src/main/docker) the ports used are

Service	bootRun port	docker-compose mapping	docker-compose debug mapping
registry	2001	2001	2001
gateway	2002	2002	2002
thirds	2100	2100	2100
cards-publication	2102	2102	2102
users	2103	2103	2103
cards-consultation	2104	2104	2104
config	4000	4000	4000
registry	4001	4001	4001
gateway	4002	4002	4002
thirds	4100	4100	4100
cards-publication	4102	4102	4102
users	4103	4103	4103
cards-consultation	4103	4103	4103

10. Troubleshooting

Proxy error when running third-party docker-compose

Error message

Pulling rabbitmq (rabbitmq:3-management)...
ERROR: Get https://registry-1.docker.io/v2/: Proxy Authentication Required

Possible causes & resolution

When running docker-compose files using third-party images(such as rabbitmq, mongodb etc.) the first time, docker will need to pull these images from their repositories. If the docker proxy isn’t set properly, you will see the above message.

To set the proxy, follow these steps from the docker documentation.

If your proxy needs authentication, add your user and password as follows:

HTTP_PROXY=http://user:password@proxy.example.com:80/

Important

The password should be URL-encoded.

Gradle Metaspace error

Gradle task (for example gradle build) fails with the following error:

Error message

* What went wrong:
Metaspace

Possible causes & resolution

Issue with the Gradle daemon. Stopping the daemon using gradle --stop and re-launching the build should solve this issue.

Java version not available when setting up environment

When sourcing the load_environment_light script to set up your environment, you might get the following error message:

Error message

Stop! java 8.0.192-zulu is not available. Possible causes:
 * 8.0.192-zulu is an invalid version
 * java binaries are incompatible with Linux64
 * java has not been released yet

Select the next available version and update load_environment_light accordingly before sourcing it again.

Possible causes & resolution

The java version currently listed in the script might have been deprecated (for security reasons) or might not be available for your operating system (for example, 8.0.192-zulu wasn’t available for Ubuntu).

Run sdk list java to find out which versions are available. You will get this kind of output:

================================================================================
Available Java Versions
================================================================================
     13.ea.16-open       9.0.4-open          1.0.0-rc-11-grl
     12.0.0-zulu         8.0.202-zulu        1.0.0-rc-10-grl
     12.0.0-open         8.0.202-amzn        1.0.0-rc-9-grl
     12.0.0-librca       8.0.202.j9-adpt     1.0.0-rc-8-grl
     11.0.2-zulu         8.0.202.hs-adpt
     11.0.2-open         8.0.202-zulufx
     11.0.2-amzn         8.0.202-librca
     11.0.2.j9-adpt      8.0.201-oracle
     11.0.2.hs-adpt  > + 8.0.192-zulu
     11.0.2-zulufx       7.0.211-zulu
     11.0.2-librca       6.0.119-zulu
     11.0.2-sapmchn      1.0.0-rc-15-grl
     10.0.2-zulu         1.0.0-rc-14-grl
     10.0.2-open         1.0.0-rc-13-grl
     9.0.7-zulu          1.0.0-rc-12-grl

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

BUILD FAILED with message Execution failed for task ':ui:main-user-interface:npmInstall'.

Error message

FAILURE: Build failed with an exception.

    What went wrong:
    Execution failed for task ':ui:main-user-interface:npmInstall'.

Possible causes & resolution

A sudo has been used before the ./gradlew assemble.

Important

Don’t use sudo to build OperatorFabric otherwise unexpected problems could arise.

== Licensing

This project and all its sub-projects are licensed under Mozilla Public License V2.0. See LICENSE.txt

11. Contributing

Read our CONTRIBUTING file for more information on how to contribute to the project.

Files

index.adoc

Latest commit

History

index.adoc

File metadata and controls

OperatorFabric README

1. What does OperatorFabric do in practice?

2. Requirements

2.1. Tools and libraries

2.2. Software

2.3. Browser support

3. Getting Started

3.1. Build and run using script

3.1.1. Clone repository

3.1.2. Set up your environment (environment variables & appropriate versions of gradle, maven, etc…)

3.1.3. Deploy dockerized MongoDB, RabbitMQ and SonarQube

3.1.4. Build OperatorFabric with Gradle

3.1.5. Run OperatorFabric Services using the run_all.sh script

3.1.6. Check services status

3.1.7. Log into the UI

3.1.8. Push cards to the feed

3.2. Demonstration mode

3.3. Going Further

4. Project Contents

4.1. Project Structure

4.1.1. Tree View

4.1.2. Content Details

4.2. Conventions regarding project structure and configuration

4.2.1. Java

4.2.2. Modeling

4.2.3. Docker

4.3. Scripts (bin and CICD)

4.3.1. load_environment_ramdisk.sh

4.3.2. run_all.sh

4.3.3. setup_dockerized_environment.sh

5. Environment variables

6. Gradle Tasks

7. Custom tasks

7.1. Services

Common tasks for all sub-projects

Core

Third Party Service

infra/config

tools/generic

7.2. Gradle Plugins

8. Docker demo

9. Recipes

9.1. Generating docker images

9.2. Managing a service with docker-compose

9.3. Running sub-project from jar file

9.4. Overriding properties when running from jar file

9.5. Service port table

10. Troubleshooting

11. Contributing

3.1.5. Run OperatorFabric Services using the `run_all.sh` script