OperatorFabric Architecture
1. Introduction
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)
Workflow Scheduling could be addressed either as an internal module or through simplified and standardized (BPMN) integration with external workflow engines, we’re still weighing the pros and cons of the two options._ |
OperatorFabric is part of the LF Energy coalition, a project of The Linux Foundation that supports open source innovation projects within the energy and electricity sectors.
OpFab is an open source platform licensed under Mozilla Public License V2. The source code is hosted on GitHub in this repository : operatorfabric-core.
The aim of this document is to describe the architecture of the solution, first by defining the business concepts it deals with and then showing how this translates into the technical architecture.
2. Business Architecture
OperatorFabric is based on the concept of cards, which contain data regarding events that are relevant for the operator. A third party tool publishes cards and the cards are received on the screen of the operators. Depending on the type of the cards, the operator can send back information to the third party via an "action".
2.1. Business components

To do the job, the following business components are defined :
-
Card Publication : this component receives the cards from third party tools
-
Card Consultation : this component delivers the cards to the operators and provide access to all cards exchanged (archives)
-
Actions : this component receives the action from the operator and send it to the third party tool
-
Card rendering and process definition : this component stores the information for the card rendering (templates, internationalization, …) and a light description of the process associate (states, actions, …). This configuration data can be provided either by an administrator or by a third party tool.
-
User Management : this component is used to manage users, groups and entities.
2.2. Business objects
The business objects can be represented as follows :

-
Card : the core business object which contains the data to show to the user(or operator)
-
Publisher : the third party which publishes cards
-
User : the operator receiving cards and responding via actions
-
Group : a group (containing a list of users)
-
Entity : an entity (containing a list of users)
-
Process : the process the card is dealing with
-
State : the step in the process
-
Card Rendering : data for card rendering
-
Action : a list of possible actions for a specific state in a process
3. Technical Architecture
The architecture is based on micro-services. All business services are accessible via REST API.

3.1. Business components
We find here the business component seen before:
-
We have a "UI" component which stores the static pages and the UI code that is downloaded by the browser. The UI is based an Angular and Handlebars for the card templating.
-
The business component named "Card rendering and process definition" is at the technical level known as "Third service". This service receive card rendering and process definition as a bundle. The bundle is a tar.gz file containing
-
json process configuration file (containing states & actions)
-
templates for rendering
-
stylesheets
-
internationalization information
-
All business components are based on SpringBoot and packaged via Docker.
Spring WebFlux is used to provide the card in a fluid way.
3.2. Technical components
3.2.1. Registry
It is the central component where all services are registered. It serves as a reference point for the gateway and other services to find information about the running services instance and allow for local load balancing of accesses. It is implemented by Spring Cloud Netflix .
3.2.2. Gateway
It provides a filtered view of the APIS and static served pages for external access through browsers or other http compliant accesses. It provides the rooting and load balancing for accessing the micro-services from outside. It is implemented by Spring Cloud Gateway.
3.2.3. Configuration
A configuration service is not mandatory in a micro-services architecture but may allow for better sharing of common configuration and to dispatch global configuration changes to all services. It is implemented via Spring Cloud Config.
3.2.4. Broker
The broker is used to share information asynchronously across the whole services. It is implemented via RabbitMQ
3.2.5. Authentication
The architecture provides a default authentication service via KeyCloak but it can delegate it to an external provider. Authentication is done through the use of Oauth2, three flows are supported : implicit, authorization code and password.
3.2.6. Database
The cards are stored in a MongoDb database. The bundles are stored in a file system.
OperatorFabric Getting Started
4. Prerequisites
To use OperatorFabric, you need a linux OS with the following:
-
Docker install with 4Gb of space
-
16Gb of RAM minimal, 32 Gb recommended
5. Install and run server
To start OperatorFabric, you first need to clone the getting started git
git clone https://github.com/opfab/operatorfabric-getting-started.git
Launch the startserver.sh
in the server directory. You need to wait for all the services to start (it usually takes one minute to start), it is done when no more logs are written on the output (It could continue to log but slowly).
Test the connection to the UI: to connect to OperatorFabric, open in a browser the following page: localhost:2002/ui/ and use tso1-operator
as login and test
as password.
If you are not accessing the server from localhost, there is a bug with authentication redirection. Your must use the following URL, replacing SERVER_IP
by the IP address of your server :
http://SERVER_IP:89/auth/realms/dev/protocol/openid-connect/auth?response_type=code&client_id=opfab-client&redirect_uri=http://SERVER_IP:2002/ui/
After connection, you should see the following screen

To stop the server, use:
docker-compose down &
6. Examples
For each example, useful files and scripts are in the directory client/exampleX
.
All examples assume you connect to the server from localhost
(otherwise change the provided scripts)
6.1. Example 1: Send and update a basic card
Go in directory client/example1
and send a card:
curl -X POST http://localhost:2102/cards -H "Content-type:application/json" --data @card.json
or use provided script
./sendCard.sh card.json
The result should be a 200 Http status, and a json object such as:
{"count":1,"message":"All pushedCards were successfully handled"}
See the result in the UI, you should see a card, if you click on it you’ll see the detail

6.1.1. Anatomy of the card :
A card is containing information regarding the publisher, the recipients, the process, the data to show…
More information can be found in the Card Structure section of the reference documentation.
{ "publisher" : "message-publisher", "publisherVersion" : "1", "process" :"defaultProcess", "processId" : "hello-world-1", "state" : "messageState", "recipient" : { "type" : "GROUP", "identity" : "TSO1" }, "severity" : "INFORMATION", "startDate" : 1553186770681, "summary" : {"key" : "defaultProcess.summary"}, "title" : {"key" : "defaultProcess.title"}, "data" : {"message" :"Hello World !!! That's my first message"} }
6.1.2. Update the card
We can send a new version of the card (updateCard.json):
-
change the message, field data.message in the JSON File
-
the severity , field severity in the JSON File
{ "publisher" : "message-publisher", "publisherVersion" : "1", "process" :"defaultProcess", "processId" : "hello-world-1", "state" $: "messageState", "recipient" : { "type" : "GROUP", "identity" : "TSO1" }, "severity" : "ALARM", "startDate" : 1553186770681, "summary" : {"key" : "defaultProcess.summary"}, "title" : {"key" : "defaultProcess.title"}, "data" : {"message" :":That's my second message"} }
You can send the updated card with:
./sendCard.sh cardUpdate.json
The card should be updated on the UI.
6.1.3. Delete the card
You can delete the card using DELETE HTTP code with reference to publisher and processId
curl -s -X DELETE http://localhost:2102/cards/message-publisher_hello-world-1
or use provided script:
./deleteCard.sh
6.2. Example 2: Publish a new bundle
The way the card is display in the UI is defined via a Bundle containing templates and process description.
The bundle structure is the following:
├── css : stylesheets files ├── i18n : internalization files └── template : ├── en : handlebar templates for detail card rendering ├── .... config.json : process description and global configuration
The bundle is provided in the bundle directory of example2. It contains a new version of the bundle used in example1.
We just change the template and the stylesheet instead of displaying:
Message : The message
we display:
You received the following message The message
If you look at the template file (template/en/template.handlebars):
<h2> You received the following message </h2> {{card.data.message}}
In the stylesheet css/style.css we just change the color value to red (#ff0000):
h2{ color:#ff0000; font-weight: bold; }
The global configuration is defined in config.json :
{ "name":"message-publisher", "version":"2", "templates":["template"], "csses":["style"], "processes" : { "defaultProcess" : { "states":{ "messageState" : { "details" : [{ "title" : { "key" : "defaultProcess.title"}, "templateName" : "template", "styles" : [ "style.css" ] }] } } } } }
To keep the old bundle, we create a new version by setting version to 2.
6.2.1. Package you bundle
Your bundle need to be package in a tar.gz file, a script is available
./packageBundle.sh
A file name bundle.tar.gz will be created.
6.2.2. Get a Token
To send the bundle you need to be authenticated. To do that you need to get a token with the following command :
curl -s -X POST -d "username=admin&password=test&grant_type=password&client_id=opfab-client" http://localhost:2002/auth/token
or use the provided script
./getToken.sh
You should received JSON a response like this:
{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSbXFOVTNLN0x4ck5SRmtIVTJxcTZZcTEya1RDaXNtRkw5U2NwbkNPeDBjIn0.eyJqdGkiOiIzZDhlODY3MS1jMDhjLTQ3NDktOTQyOC1hZTdhOTE5OWRmNjIiLCJleHAiOjE1NzU1ODQ0NTYsIm5iZiI6MCwiaWF0IjoxNTc1NTQ4NDU2LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9kZXYiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiYTNhM2IxYTYtMWVlYi00NDI5LWE2OGItNWQ1YWI1YjNhMTI5IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoib3BmYWItY2xpZW50IiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiODc3NzZjOTktYjA1MC00NmQxLTg5YjYtNDljYzIxNTQyMDBhIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIiwic3ViIjoiYWRtaW4iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIn0.XMLjdOJV-A-iZrtq7sobcvU9XtJVmKKv9Tnv921PjtvJ85CnHP-qXp2hYf5D8TXnn32lILVD3g8F9iXs0otMAbpA9j9Re2QPadwRnGNLIzmD5pLzjJ7c18PWZUVscbaqdP5PfVFA67-j-YmQBwxiys8psF8keJFvmg-ExOGh66lCayClceQaUUdxpeuKFDxOSkFVEJcVxdelFtrEbpoq0KNPtYk7vtoG74zO3KjNGrzLkSE_e4wR6MHVFrZVJwG9cEPd_dLGS-GmkYjB6lorXPyJJ9WYvig56CKDaFry3Vn8AjX_SFSgTB28WkWHYZknTwm9EKeRCsBQlU6MLe4Sng","expires_in":36000,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzZjdkZTM0OC05N2Q5LTRiOTUtYjViNi04MjExYTI3YjdlNzYifQ.eyJqdGkiOiJhZDY4ODQ4NS1hZGE0LTQwNWEtYjQ4MS1hNmNkMTM2YWY0YWYiLCJleHAiOjE1NzU1NTAyNTYsIm5iZiI6MCwiaWF0IjoxNTc1NTQ4NDU2LCJpc3MiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9kZXYiLCJhdWQiOiJodHRwOi8va2V5Y2xvYWs6ODA4MC9hdXRoL3JlYWxtcy9kZXYiLCJzdWIiOiJhM2EzYjFhNi0xZWViLTQ0MjktYTY4Yi01ZDVhYjViM2ExMjkiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoib3BmYWItY2xpZW50IiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiODc3NzZjOTktYjA1MC00NmQxLTg5YjYtNDljYzIxNTQyMDBhIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUifQ.sHskPtatqlU9Z8Sfq6yvzUP_L6y-Rv26oPpykyPgzmk","token_type":"bearer","not-before-policy":0,"session_state":"87776c99-b050-46d1-89b6-49cc2154200a","scope":"email profile"}
Your token is the access_token value in the JSON. The token will be valid for 10 hours, after you will need to ask for a new one.
6.2.3. Send the bundle
Replace the value "THE TOKEN" with the token in the sendBundle.sh script:
token=THE TOKEN curl -s -X POST "http://localhost:2100/thirds" -H "accept: application/json" -H "Content-Type: multipart/form-data" -H "Authorization:Bearer $token" -F "file=@bundle.tar.gz;type=application/gzip"
You can now execute the script, it will send the bundle.
./sendBundle.sh
You should received the following JSON in response, describing your bundle.
{"name":"message-publisher","version":"2","templates":["template"],"csses":["style"],"i18nLabelKey":null,"processes":{"defaultProcess":{"statesData":{"messageState":{"detailsData":[{"title":{"key":"defaultProcess.title","parameters":null},"titleStyle":null,"templateName":"template","styles":null}],"actionsData":null,"details":[{"title":{"key":"defaultProcess.title","parameters":null},"titleStyle":null,"templateName":"template","styles":null}],"actions":null}},"states":{"messageState":{"detailsData":[{"title":{"key":"defaultProcess.title","parameters":null},"titleStyle":null,"templateName":"template","styles":null}],"actionsData":null,"details":[{"title":{"key":"defaultProcess.title","parameters":null},"titleStyle":null,"templateName":"template","styles":null}],"actions":null}}}},"menuEntries":null}
6.2.4. Send a card
You can send the following card to test your new bundle:
{ "publisher" : "message-publisher", "publisherVersion" : "2", "process" :"defaultProcess", "processId" : "hello-world-1", "state": "messageState", "recipient" : { "type" : "GROUP", "identity" : "TSO1" }, "severity" : "INFORMATION", "startDate" : 1553186770681, "summary" : {"key" : "defaultProcess.summary"}, "title" : {"key" : "defaultProcess.title"}, "data" : {"message":"Hello world in new version"} }
To use the new bundle, we set publisherVersion to "2"
To send the card:
./sendCard.sh
You should see in the UI the detail card with the new template.
6.2.5. Internationalization
If you switch language to french in the UI (Settings menu on the top right of the screen), you should see the cards in french.
OperatorFabric will use templates define in repository "template/fr" and keys define in "i18n/fr.json".
6.3. Example 3: Process with state
For this example, we will set the following process:
-
Step 1: A critical situation arise on the HightVoltage grid
-
Step 2: The critical situation evolve
-
Step 3: The critical situation ended
To model this process in OperatorFabric, we will use a "Process" with "States", we will model this in the config.json
of the bundle:
{ "name":"alert-publisher", "version":"1", "templates":["criticalSituationTemplate","endCriticalSituationTemplate"], "csses":["style"], "processes" : { "criticalSituation" : { "states":{ "criticalSituation-begin" : { "details" : [{ "title" : { "key" : "criticalSituation-begin.title"}, "templateName" : "criticalSituationTemplate", "styles" : [ "style.css" ] }] }, "criticalSituation-update" : { "details" : [{ "title" : { "key" : "criticalSituation-update.title"}, "templateName" : "criticalSituationTemplate", "styles" : [ "style.css" ] }] }, "criticalSituation-end" : { "details" : [{ "title" : { "key" : "criticalSituation-end.title"}, "templateName" : "endCriticalSituationTemplate", "styles" : [ "style.css" ] }] } } } } }
You can see in the JSON we define a process name "criticalSituation" with 3 states: criticalSituation-begin, criticalSituation-update and criticalSituation-end. For each state we define a title for the card, and the template a stylesheets to use.
The title is a key which refer to an i18n found in the corresponding i18n repository:
{ "criticalSituation-begin":{ "title":"CRITICAL SITUATION", "summary":" CRITICAL SITUATION ON THE GRID, SEE DETAIL FOR INSTRUCTION" }, "criticalSituation-update":{ "title":"CRITICAL SITUATION - UPDATE", "summary":" CRITICAL SITUATION ON THE GRID, SEE DETAIL FOR INSTRUCTION" }, "criticalSituation-end":{ "title":"CRITICAL SITUATION - END", "summary":" CRITICAL SITUATION ENDED" } }
The templates can be found in the template directory.
We can now send cards and simulate the process, first we send a card at the beginning of the critical situation:
{ "publisher" : "alert-publisher", "publisherVersion" : "1", "process" :"criticalSituation", "processId" : "alert1", "state": "criticalSituation-begin", "recipient" : { "type" : "GROUP", "identity" : "TSO1" }, "severity" : "ALARM", "startDate" : 1553186770681, "summary" : {"key" : "criticalSituation-begin.summary"}, "title" : {"key" : "criticalSituation-begin.title"}, "data" : {"instruction":"Critical situation on the grid : stop immediatly all maintenance on the grid"} }
The card refer to the process "criticalSituation" as defined in the config.json, the state attribute is put to "criticalSituation-begin" which is the first step of the process, again as defined in the config.json. The card can be sent via provided script :
./sendCard.sh card.json
Two other card have be provided to continue the process
-
cardUpdate.json: the state is criticalSituation-update
-
cardEnd.json: the state is criticalSituation-end and severity set to "information"
You can send these cards:
./sendCard.sh cardUpdate.json
./sendCard.sh cardEnd.json
6.4. Example 4: Time Line
To view the card in the time line, you need to set times in the card using timeSpans attributes as in the following card:
{ "publisher" : "scheduledMaintenance-publisher", "publisherVersion" : "1", "process" :"maintenanceProcess", "processId" : "maintenance-1", "state": "planned", "recipient" : { "type" : "GROUP", "identity" : "TSO1" }, "severity" : "INFORMATION", "startDate" : 1553186770681, "summary" : {"key" : "maintenanceProcess.summary"}, "title" : {"key" : "maintenanceProcess.title"}, "data" : { "operationDescription":"Maintenance operation on the International France England (IFA) Hight Voltage line ", "operationResponsible":"RTE", "contactPoint":"By Phone : +33 1 23 45 67 89 ", "comment":"Operation has no impact on service" }, "timeSpans" : [ {"start" : 1576080876779}, {"start" : 1576104912066} ] }
For this example, we use a new publisher called "scheduledMaintenance-publisher". You won’t need to post the corresponding bundle to the thirds service as it has been loaded in advance to be available out of the box (only for the getting started). If you want to take a look at its content you can find it under server/thirds-storage/scheduledMaintenance-publisher/1.
Before sending the card provide, you need to set the good time values as epoch (ms) (en.wikipedia.org/wiki/Epoch_(computing)) in the json. For each value you set, you will have a point in the timeline. In our example, the first point represent the beginning of the maintenance operation, and the second the end of the maintenance operation.
To get the dates in Epoch, you can use the following commands:
For the first date:
date -d "+ 600 minutes" +%s%N | cut -b1-13
And for the second
date -d "+ 900 minutes" +%s%N | cut -b1-13
To send the card use the provided script in example4 directory
./sendCard.sh card.json
A second card (card2.json) is provided as example, you need again to set times values in the json file and then send it
./sendCard.sh card2.json
This time the criticality of the card is ALERT, you should see the point in red in the timeline

7. Troubleshooting
7.1. My bundle is not loaded
The server send a {"status":"BAD_REQUEST","message":"unable to open submitted
file","errors":["Error detected parsing the header"]}
, despite correct http
headers.
The uploaded bundle is corrupted. Test your bundle in a terminal (Linux solution).
Example for a bundle archive named MyBundleToTest.tar.gz
giving the
mentioned error when uploaded :
tar -tzf MyBundleToTest.tar.gz >/dev/null tar: This does not look like a tar archive tar: Skipping to next header tar: Exiting with failure status due to previous errors
7.1.1. Solution
Extract content if possible and compress it to a correct compressed archive format.
7.2. I can’t upload my bundle
The server responds with a message like the following:
{"status":"BAD_REQUEST","message":"unable to open submitted
file","errors":["Input is not in the .gz format"]}
The bundle has been compressed using an unmanaged format.
7.2.1. Format verification
Linux solution
Command line example to verify the format of a bundle archive named
MyBundleToTest.tar.gz
(which gives the mentioned error when uploaded):
tar -tzf MyBundleToTest.tar.gz >/dev/null
which should return in such case the following messages:
gzip: stdin: not in gzip format tar: Child returned status 1 tar: Error is not recoverable: exiting now
7.2.2. Solution
Use tar.gz
format for the archive compression. Shell command is tar -czvf
MyBundleToTest.tar.gz config.json template/ css/
for a bundle containing
templates and css files.
7.3. My bundle is rejected due to internal structure
The server sends {"status":"BAD_REQUEST","message":"Incorrect inner file
structure","errors":["$OPERATOR_FABRIC_INSTANCE_PATH/d91ba68c-de6b-4635-a8e8-b58
fff77dfd2/config.json (Aucun fichier ou dossier de ce type)"]}
Where $OPERATOR_FABRIC_INSTANCE_PATH
is the folder where thirds files are
stored server side.
7.3.1. Reason
The internal file structure of your bundle is incorrect. config.json
file and
folders need to be at the first level.
7.3.2. Solution
Add or organize the files and folders of the bundle to fit the Third bundle requirements.
7.4. No template display
The server send 404 for requested template with a response like
{"status":"NOT_FOUND","message":"The specified resource does not
exist","errors":["$OPERATOR_FABRIC_INSTANCE_PATH/thirds-storage/BUNDLE_TEST/1/te
mplate/fr/template1.handlebars (Aucun fichier ou dossier de ce type)"]}
7.4.1. Verification
The previous server response is return for a request like:
http://localhost:2002/thirds/BUNDLE_TEST/templates/template1?locale=fr&version
=1
The bundle is lacking localized folder and doesn’t contain the requested localization.
If you have access to the card-publication
micro service source code you
should list the content of
$CARDS_PUBLICATION_PROJECT/build/docker-volume/third-storage
7.4.2. Solution
Either request another l10n or add the requested one to the bundle and re-upload it.
7.5. My template is not used.
It need to be declared in the config.json of the bundle.
7.5.1. Solution
Add or verify the name of the templates declared in the config.json
file of
the bundle.
7.6. My value is not displayed in the detail template
There are several possibilities:
-
the path of the data used in the template is incorrect;
-
number of pair of
{
and}
has to follow those rules:-
with no helper the good number is only 2 pairs;
-
with OperatorFabric helpers it’s 3 pairs of them.
-
OperatorFabric Reference Documentation
The aim of this document is to:
-
Explain what OperatorFabric is about and define the concepts it relies on
-
Give a basic tour of its features from a user perspective
-
Describe the technical implementation that makes it possible
8. Introduction
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.
9. A quick walk through the user interface
Work in progress
10. Technical overview
11. Thirds service
As stated above, third-party applications (or "thirds" for short) interact with OperatorFabric by sending cards. The Thirds service allows them to tell OperatorFabric
-
how these cards should be rendered
-
what actions should be made available to the operators regarding a given card
-
if several languages are supported, how cards should be translated
In addition, it lets third-party applications define additional menu entries for the navbar (for example linking back to the third-party application) that can be integrated either as iframe or external links.
11.1. Declaring a Third Party Service
This sections explains Third Party Service Configuration
The third party service configuration is declared using a bundle which is described below. Once this bundle fully created, it must be uploaded to the server which will apply this configuration into current for further web UI calls.
The way configuration is done is explained throughout examples before a more technical review of the configuration details. The following instructions describe tests to perform on OperatorFabric to understand how customization is working in it. The card data used here are sent automatically using a script as described here .
11.1.1. Requirements
Those examples are played in an environment where an OperatorFabric instance (all micro-services) is running along a MongoDB Database and a RabbitMQ instances.
11.1.2. Bundle
Third bundles customize the way third card details are displayed. Those tar.gz
archives contain a descriptor file
named config.json
, eventually some css files
, i18n files
and handlebars templates
to do so.
For didactic purposes, in this section, the third name is BUNDLE_TEST
(to match the parameters used by the script).
This bundle is localized for en
and fr
.
As detailed in the Third core service README
the bundle contains at least a metadata file called config.json
,
a css
folder, an i18n
folder and a template
folder.
All elements except the config.json file
are optional.
The files of this example are organized as below:
bundle ├── config.json ├── css │ └── bundleTest.css ├── i18n │ ├── en.json │ └── fr.json └── template ├── en │ ├── template1.handlebars │ └── template2.handlebars └── fr ├── template1.handlebars └── template2.handlebars
To summarize, there are 5 directories and 8 files.
The config.json file
It’s a description file in json
format. It lists the content of the bundle.
example
{ "name": "BUNDLE_TEST", "version": "1", "csses": [ "bundleTest" ], "i18nLabelKey": "third-name-in-menu-bar", "menuEntries": [ { "id": "uid test 0", "url": "https://opfab.github.io/whatisopfab/", "label": "first-menu-entry" }, { "id": "uid test 0", "url": "https://www.lfenergy.org/", "label": "b-menu-entry" }, { "id": "uid test 1", "url": "https://github.com/opfab/opfab.github.io", "label": "the-other-menu-entry" } ], "processes" : { "simpleProcess" : { "start" : { "details" : [ { "title" : { "key" : "start.first.title" }, "titleStyle" : "startTitle text-danger", "templateName" : "template1" } ], "actions" : { "finish" : { "type" : "URL", "url": "http://somewher.org/simpleProcess/finish", "lockAction" : true, "called" : false, "updateStateBeforeAction" : false, "hidden" : true, "buttonStyle" : "buttonClass", "label" : { "key" : "my.card.my.action.label" }, } } }, "end" : { "details" : [ { "title" : { "key" : "end.first.title" }, "titleStyle" : "startTitle text-info", "templateName" : "template2", "styles" : [ "bundleTest.css" ] } ] } } } }
-
name: third name;
-
version: enable the correct display, even the old ones as all versions are stored by the server. Your card has a version field that will be matched to third configuration for correct rendering ;
-
processes : list the available processes and their possible states; actions and templates are associated to states
-
css file template list as
csses
; -
third name in the main bar menu as
i18nLabelKey
: optional, used if the third service add one or several entry in the OperatorFabric main menu bar, see the menu entries section for details; -
extra menu entries as
menuEntries
: optional, see below for the declaration format of objects of this array, see the menu entries section for details;
The mandatory declarations are name
and version
attributes.
See the Thirds API documentation for details.
i18n
There are two ways of i18n for third service. The first one is done using l10n files which are located in the i18n
folder, the second one throughout l10n name folder nested in the template
folder.
The i18n
folder contains one json file per l10n.
These localisation is used for integration of the third service into OperatorFabric, i.e. the label displayed for the third service, the label displayed for each tab of the details of the third card, the label of the actions in cards if any or the additional third entries in OperatorFabric(more on that at the chapter ????).
Template folder
The template
folder must contain localized folder for the i18n of the card details. This is why in our example, as the bundle is localized for en
and fr
language, the template
folder contains a en
and a fr
folder.
If there is no i18n file or key is missing, the i18n key is displayed in OperatorFabric.
The choice of i18n keys is left to the Third service maintainer. The keys are referenced in the following places:
-
config.json
file:-
i18nLabelKey
: key used for the label for the third service displayed in the main menu bar of OperatorFabric; -
label
ofmenu entry declaration
: key used to l10n themenu entries
declared by the Third party in the bundle;
-
-
card data
: values ofcard title
andcard summary
refer toi18n keys
as well askey attribute
in thecard detail
section of the card data.
example
So in this example the third service is named Bundle Test
with BUNDLE_TEST
technical name. The bundle provide an english and a french l10n.
The example bundle defined an new menu entry given access to 3 entries. The title and the summary have to be l10n, so needs to be the 2 tabs titles.
The name of the third service as displayed in the main menu bar of OperatorFabric. It will have the key "third-name-in-menu-bar"
. The english l10n will be Bundle Test
and the french one will be Bundle de test
.
A name for the three entries in the third entry menu. Their keys will be in order "first-menu-entry"
, "b-menu-entry"
and "the-other-menu-entry"
for an english l10n as Entry One
, Entry Two
and Entry Three
and in french as Entrée une
, Entrée deux
and Entrée trois
.
The title for the card and its summary. As the card used here are generated by the script of the cards-publication
project we have to used the key declared there. So they are respectively process.title
and process.summary
with the following l10ns for english: Card Title
and Card short description
, and for french l10ns: Titre de la carte
and Courte description de la carte
.
A title for each (two of them) tab of the detail cards. As for card title and card summary, those keys are already defined by the test script. There are "process.detail.tab.first"
and "process.detail.tab.second"
. For english l10n, the values are First Detail List
and Second Detail List
and for the french l10n, the values are Première liste de détails
and Seconde liste de détails
.
Here is the content of en.json
{ "third-name-in-menu-bar":"Bundle Test", "first-menu-entry":"Entry One", "b-menu-entry":"Entry Two", "the-other-menu-entry":"Entry Three", "process":{ "title":"Card Title", "summary":"Card short description", "detail":{ "tab":{ "first":"First Detail List", "second":"Second Detail List" } } } }
Here the content of fr.json
{ "third-name-in-menu-bar":"Bundle de test", "first-menu-entry":"Entrée une", "b-menu-entry":"Entrée deux", "the-other-menu-entry":"Entrée trois", "process":{ "title":"Titre de la carte", "summary":"Courte description de la carte", "detail":{ "tab":{ "first":"Première liste de détails", "second":"Deuxième liste de détails" } } } }
Once the bundle is correctly uploaded, the way to verify if the i18n have been correctly uploaded is to use the GET method of third api for i18n file.
The endpoint is described here .
The locale
language, the version
of the bundle and the technical name
of the third party are needed to get
json in the response.
To verify if the french l10n data of the version 1 of the BUNDLE_TEST third party we could use the following command line
curl -X GET "http://localhost:2100/thirds/BUNDLE_TEST/i18n?locale=fr&version=1" -H "accept: application/json"
The service response with a 200 status and with the json corresponding to the defined fr.json file show below.
{ "third-name-in-menu-bar":"Bundle de test", "first-menu-entry":"Entrée une", "b-menu-entry":"Entrée deux", "the-other-menu-entry":"Entrée trois", "tests":{ "title":"Titre de la carte", "summary":"Courte description de la carte", "detail":{ "tab":{ "first":"Première liste de détails", "second":"Deuxième liste de détails" } } } }
Menu Entries
Those elements are declared in the config.json
file of the bundle.
If there are several items to declare for a third service, a title for the third menu section need to be declared
within the i18nLabelKey
attribute, otherwise the first and only menu entry
item is used to create an entry in the
menu nav bar of OperatorFabric.
This kind of objects contains the following attributes :
-
id
: identifier of the entry menu in the UI; -
url
: url opening a new page in a tab in the browser; -
label
: it’s an i18n key used to l10n the entry in the UI.
In the following examples, only the part relative to menu entries in the config.json
file is detailed, the other parts are omitted and represented with a '…'.
Single menu entry
{ … "menuEntries":[{ "id": "identifer-single-menu-entry", "url": "https://opfab.github.io", "label": "single-menu-entry-i18n-key" }], }
Several menu entries
Here a sample with 3 menu entries.
{ … "i18nLabelKey":"third-name-in-menu-navbar", "menuEntries": [{ "id": "firstEntryIdentifier", "url": "https://opfab.github.io/whatisopfab/", "label": "first-menu-entry" }, { "id": "secondEntryIdentifier", "url": "https://www.lfenergy.org/", "label": "second-menu-entry" } , { "id": "thirdEntryIdentifier", "url": "https://opfab.github.io", "label": "third-menu-entry" }] }
Processes and States
Processes and their states allows to match a Third Party service process specific state to a list of templates for card details and actions allowing specific card rendering for each state of the business process.
The purpose of this section is to display elements of third card data in a custom format.
Regarding the card detail customization, all the examples in this section will be based on the cards generated by the script existing in the Cards-Publication
project. For the examples given here, this script is run with arguments detailed in the following command line:
$OPERATOR_FABRIC_HOME/services/core/cards-publication/src/main/bin/push_card_loop.sh --publisher BUNDLE_TEST --process tests
where:
-
$OPERATOR_FABRIC_HOME
is the root folder of OperatorFabric where tests are performed; -
BUNDLE_TEST
is the name of the Third party; -
tests
is the name of the process referred by published cards.
The process entry in the configuration file is a dictionary of processes, each key maps to a process definition. A process definition is itself a dictionary of states, each key maps to a state definition. A state is defined by:
-
a list of details: details are a combination of an internationalized title (title), css class styling element (titleStyle) and a template reference
-
a dictionary of actions: actions are described below
{ "type" : "URL", "url": "http://somewher.org/simpleProcess/finish", "lockAction" : true, "called" : false, "updateStateBeforeAction" : false, "hidden" : true, "buttonStyle" : "buttonClass", "label" : { "key" : "my.card.my.action.label" } }
An action aggregates both the mean to trigger action on the third party and data for an action button rendering:
-
type - mandatory: for now only URL type is supported:
-
URL: this action triggers a call to an external REST end point
-
-
url - mandatory: a template url for URL type action. this url may be injected with data before actions call, data are specified using curly brackets. Available parameters:
-
processInstance: the name/id of the process instance
-
process: the name of the process
-
state: the state name of the process
-
jwt: the jwt token of the user
-
data.[path]: a path to object in card data structure
-
-
hidden: if true, action won’t be visible on the card but will be available to templates
-
buttonStyle: css style classes to apply to the action button
-
label: an i18n key and parameters used to display a tooltip over the button
-
lockAction: not yet implemented
-
updateStateBeforeAction: not yet implemented
-
called: not yet implemented
For in depth information on the behavior needed for the third party rest endpoints refer to the Actions service reference.
For demonstration purposes, there will be two simple templates. For more advance feature go to the section detailing the handlebars templates in general and helpers available in OperatorFabric.
As the card used in this example are created
above
, the bundle template folder needs to contain 2 templates: template1.handlebars
and template2.handlebars
.
examples of template (i18n versions)
/template/en/template1.handlers
<h2>Template Number One</h2> <div class="bundle-test">'{{card.data.level1.level1Prop}}'</div>
/template/fr/template1.handlers
<h2>Patron numéro Un</h2> <div class="bundle-test">'{{card.data.level1.level1Prop}}'</div>
Those templates display a l10n title and an line containing the value of the scope property card.level1.level1Prop
which is This is a root property
.
/template/en/template2.handelbars
<h2>Second Template</h2> <ul class="bundle-test-list"> {{#each card.data.level1.level1Array}} <li class="bunle-test-list-item">{{this.level1ArrayProp}}</li> {{/each}} </ul>
/template/fr/template2.handelbars
<h2>Second patron</h2> <ul class="bundle-test-list"> {{#each card.data.level1.level1Array}} <li class="bunle-test-list-item">{{this.level1ArrayProp}}</li> {{/each}} </ul>
Those templates display also a l10n title and a list of numeric values from 1 to 3.
This folder contains regular css files.
The file name must be declared in the config.json
file in order to be used in the templates and applied to them.
As above, all parts of files irrelevant for our example are symbolised by a …
character.
Declaration of css files in config.json
file
{ … "csses":["bundleTest"] … }
CSS Class used in ./template/en/template1.handlebars
… <div class="bundle-test">'{{card.data.level1.level1Prop}}'</div> …
As seen above, the value of {{card.data.level1.level1Prop}}
of a test card is This is a level1 property
Style declaration in ./css/bundleTest.css
.h2{ color:#fd9312; font-weight: bold; }
Expected result

Upload
For this, the bundle is submitted to the OperatorFabric server using a POST http method as described in the Thirds Service API documentation .
Example :
cd $BUNDLE_FOLDER curl -X POST "http://localhost:2100/thirds" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "file=@bundle-test.tar.gz;type=application/gzip"
Where:
-
$BUNDLE_FOLDER
is the folder containing the bundle archive to be uploaded. -
bundle-test.tar.gz
is the name of the uploaded bundle.
These command line should return a 200 http status
response with the details of the content of the bundle in the response body such as :
{ "menuEntriesData": [ { "id": "uid test 0", "url": "https://opfab.github.io/whatisopfab/", "label": "first-menu-entry" }, { "id": "uid test 0", "url": "https://www.lfenergy.org/", "label": "b-menu-entry" }, { "id": "uid test 1", "url": "https://github.com/opfab/opfab.github.io", "label": "the-other-menu-entry" } ], "name": "BUNDLE_TEST", "version": "1", "csses": [ "bundleTest" ], "i18nLabelKey": "third-name-in-menu-bar", "menuEntries": [ { "id": "uid test 0", "url": "https://opfab.github.io/whatisopfab/", "label": "first-menu-entry" }, { "id": "uid test 0", "url": "https://www.lfenergy.org/", "label": "b-menu-entry" }, { "id": "uid test 1", "url": "https://github.com/opfab/opfab.github.io", "label": "the-other-menu-entry" } ], "processes" : { "simpleProcess" : { "start" : { "details" : [ { "title" : { "key" : "start.first.title" }, "titleStyle" : "startTitle text-danger", "templateName" : "template1" } ], "actions" : { "finish" : { "type" : "URL", "url": "http://somewher.org/simpleProcess/finish", "lockAction" : true, "called" : false, "updateStateBeforeAction" : false, "hidden" : true, "buttonStyle" : "buttonClass", "label" : { "key" : "my.card.my.action.label" }, } } }, "end" : { "details" : [ { "title" : { "key" : "end.first.title" }, "titleStyle" : "startTitle text-info", "templateName" : "template2", "styles" : [ "bundleTest.css" ] } ] } } } }
Otherwise please refer to the Troubleshooting section to resolve the problem.
11.2. Bundle Technical overview
See the model section (at the bottom) of the swagger generated documentation for data structure.
11.2.1. Resource serving
CSS
CSS 3 style sheet are supported, they allow custom styling of card template
detail all css selector must be prefixed by the .detail.template
parent
selector
Internationalization
Internationalization (i18n) files are json file (JavaScript Object Notation). One file must be defined by module supported language. See the model section (at the bottom) of the swagger generated documentation for data structure.
Sample json i18n file
{ "emergency": { "message": "Emergency situation happened on {{date}}. Cause : {{cause}}." "module": { "name": "Emergency Module", "description": "The emergency module managed ermergencies" } } }
i18n messages may include parameters, these parameters are framed with double curly braces.
The bundled json files name must conform to the following pattern : [lang].json
ex:
fr.json en.json de.json
Templates
Templates are Handlebars template files. Templates are fuelled with a scope structure composed of
-
a card property (See card data model for more information)
-
a userContext :
-
login: user login
-
token: user jwt token
-
firstName: user first name
-
lastName: user last name
-
In addition to Handlebars basic syntax and helpers, OperatorFabric defines the following helpers :
numberFormat
formats a number parameter using developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Nu mberFormat[Intl.NumberFormat]. The locale used is the current user selected one, and options are passed as hash parameters (see Handlebars doc Literals section).
{{numberFormat card.data.price style="currency" currency="EUR"}}
dateFormat
formats the submitted parameters (millisecond since epoch) using mement.format. The locale used is the current user selected one, the format is "format" hash parameter (see Handlebars doc Literals section).
{{dateFormat card.data.birthday format="MMMM Do YYYY, h:mm:ss a"}}
slice
extracts a sub array from ann array
example:
<!-- {"array": ["foo","bar","baz"]} --> <ul> {{#each (slice array 0 2)}} <li>{{this}}</li> {{/each}} </ul>
outputs:
<ul> <li>foo</li> <li>bar</li> </ul>
and
<!-- {"array": ["foo","bar","baz"]} --> <ul> {{#each (slice array 1)}} <li>{{this}}</li> {{/each}} </ul>
outputs:
<ul> <li>bar</li> <li>baz</li> </ul>
now
outputs the current date in millisecond from epoch. The date is computed from application internal time service and thus may be different from the date that one can compute from javascript api which relies on the browsers' system time.
NB: Due to Handlebars limitation you must provide at least one argument to helpers otherwise, Handlebars will confuse a helper and a variable. In the bellow example, we simply pass an empty string.
example:
<div>{{now ""}}</div> <br> <div>{{dateFormat (now "") format="MMMM Do YYYY, h:mm:ss a"}}</div>
outputs
<div>1551454795179</div> <br> <div>mars 1er 2019, 4:39:55 pm</div>
for a local set to FR_fr
preserveSpace
preserves space in parameter string to avoid html standard space trimming.
{{preserveSpace card.data.businessId}}
bool
returns a boolean result value on an arithmetical operation (including object equality) or boolean operation.
Arguments: - v1: left value operand - op: operator (string value) - v2: right value operand
arithmetical operators:
-
==
-
===
-
!=
-
!==
-
<
-
⇐
-
>
-
>=
boolean operators:
-
&&
-
||
examples:
{{#if (bool v1 '<' v2)}} v1 is strictly lower than v2 {{else}} V2 is lower or equal to v1 {{/if}}
math
returns the result of a mathematical operation.
arguments:
-
v1: left value operand
-
op: operator (string value)
-
v2: right value operand
arithmetical operators:
-
+
-
-
-
*
-
/
-
%
example:
{{math 1 '+' 2}}
split
splits a string into an array based on a split string.
example:
<ul> {{#each (split 'my.example.string' '.')}} <li>{{this}}</li> {{/each}} </ul>
outputs
<ul> <li>my</li> <li>example</li> <li>string</li> </ul>
action
outputs a card action button whose card action id is the concatenation of an arbitrary number of helper arguments
{{{action "PREREQUISITE_" id}}}
svg
outputs a svg tag with lazy loading, and missing image replacement message. The image url is the concatenation of an arbitrary number of helper arguments
{{{svg baseUri scheduledOpId "/" substation "/before/" computationPhaseOrdinal}}}
i18n
outputs a i18n result from a key and some parameters. There are two ways of configuration :
-
Pass an object as sole argument. The object must contain a key field (string) and an optional parameter field (map of parameterKey ⇒ value)
{{i18n card.data.i18nTitle}}
-
Pass a string key as sole argument and use hash parameters (see Handlebars doc Literals section) for i18n string parameters.
<!-- emergency.title=Emergency situation happened on {{date}}. Cause : {{cause}}. --> {{i18n "emergency.title" date="2018-06-14" cause="Broken Cofee Machine"}}
outputs
Emergency situation happened on 2018-06-14. Cause : Broken Cofee Machine
sort
sorts an array or some object’s properties (first argument) using an optional field name (second argument) to sort the collection on this fields natural order.
If there is no field argument provided :
-
for an array, the original order of the array is kept ;
-
for an object, the structure is sorted by the object field name.
<!-- users : {"john": { "firstName": "John", "lastName": "Cleese"}, "graham": { "firstName": "Graham", "lastName": "Chapman"}, "terry": { "firstName": "Terry", "lastName": "Gilliam"}, "eric": { "firstName": "Eric", "lastName": "Idle"}, "terry": { "firstName": "Terry", "lastName": "Jones"}, "michael": { "firstName": "Michael", "lastName": "Palin"}, --> <ul> {{#each (sort users)}} <li>{{this.firstName}} {{this.lastName}}</li> {{/each}} </ul>
outputs :
<ul> <li>Eric Idle</li> <li>Graham Chapman</li> <li>John Cleese</li> <li>Michael Pallin</li> <li>Terry Gilliam</li> <li>Terry Jones</li> </ul>
and
<ul> {{#each (sort users "lastName")}} <li>{{this.firstName}} {{this.lastName</li> {{/each}} </ul>
outputs :
<ul> <li>Graham Chapman</li> <li>John Cleese</li> <li>Terry Gilliam</li> <li>Eric Idle</li> <li>Terry Jones</li> <li>Michael Pallin</li> </ul>
12. OperatorFabric Users Service
The User service manages users, groups and entities.
- Users
-
represent account information for a person destined to receive cards in the OperatorFabric instance.
- Groups
-
-
represent set of users destined to receive collectively some cards.
-
can be used in a way to handle rights on card reception in OperatorFabric.
-
- Entities
-
-
represent set of users destined to receive collectively some cards.
-
can be used in a way to handle rights on card reception in OperatorFabric.
-
The user define here is an internal representation of the individual card recipient in OperatorFabric the authentication is leave to specific OAuth2 external service.
|
In the following commands the $token is an authentication token currently valid for the OAuth2 service used by the current OperatorFabric system.
|
12.1. Users, groups and entities
User service manages users, groups and entities.
12.1.1. Users
Users are the individuals and mainly physical person who can log in OperatorFabric.
The access to this service has to be authorized, in the OAuth2
service used by the current OperatorFabric
instance, at least to access User information and to manage Users. The membership of groups and entities are stored in the user information.
Automated user creation
In case of a user does exist in a provided authentication service but he does not exist in the OperatorFabric
instance, when he is authenticated and connected
for the first time in the OperatorFabric
instance, the user is automatically created in the system without attached group or entity.
The administration of the groups and entities is dealt by the administrator manually. More details about automated user creation
here
.
12.1.2. Groups
opfab_spec_conf
The notion of group is loose and can be used to simulate role in OperatorFabric
.
Groups are used to send cards to several users without a name specifically. The information about membership to a
group is stored in the user information. The rules used to send cards are described in the
recipients section
.
12.1.3. Entities
Entities are used to send cards to several users without a name specifically. The information about membership to an entity is stored in the user information. The rules used to send cards are described in the recipients section .
Alternative way to manage groups
The standard way to handle groups in OperatorFabric
instance is dealt on the user information.
There is an alternative way to manage groups through the authentication token, the groups are defined by the
administrator of the authentication service.
See
here
for more details to use this feature.
13. Cards Publication Service
The Cards Publication Service exposes a REST API through which third-party applications, or "publishers" can post cards to OperatorFabric. It then handles those cards:
-
Time-stamping them with a "publishDate"
-
Sending them to the message broker (RabbitMQ) to be delivered in real time to the appropriate operators
-
Persisting them to the database (MongoDB) for later consultation
13.1. Card Structure
Cards are represented as Json
objects. The technical design of cards is described in
the cards api documentation
. A card correspond to the state of a Process in OperatorFabric.
13.1.1. Technical Information of the card
Those attributes are used by OperatorFabric to manage how cards are stored, to whom and when they’re sent.
Mandatory information
Below, the json
technical key is in the '()' following the title.
Publisher (publisher
)
Quite obviously it’s the Third party which publish the card. This information is used to look up for Presentation resources of the card.
Publisher Version (publisherVersion
)
Refers the version
of publisher third
to use to render this card (i18n, title, summary and details).
As through time, the presentation of a publisher card data changes, this changes are managed through publisherVersion
in OperatorFabric. Each version is keep in the system in order to be able to display correctly old cards.
Process Identifier (processId
)
It’s the way to identify the process to which the card is associated. A card represent a state of a process.
Start Date (startDate
)
This attribute is a part of the card life management system. It’s indicate OperatorFabric the moment since the card can be displayed to the operators or main recipients, see Display rules .
Severity (severity
)
The severity is a core principe of the OperatorFabric Card system. There are 4 severities available. A color is associated in the GUI to each severity. Here the details about severity and their meaning for OperatorFabric:
-
ALARM: represents a critical state of the associated process, need an action from the operator. In the UI, the card is red;
-
ACTION: the associated process need an action form operators in order to evolve correctly. In the UI, the card is orange;
-
COMPLIANT: the process related to the card is in a compliant status. In the UI, the card is green.;
-
INFORMATION: give information to the operator. In the UI, the card is blue.
Title (title
)
This attribute is display as header of a card in the feed of the GUI. It’s the main User destined Information of a card. The value refer to an i18n
value used to localized this information.
Summary (summary
)
This attribute is display as a description of a card in the feed of the GUI, when the card is selected by the operator. It’s completing the information of the card title. The value refer to an i18n
value used to localized this information.
Recipient (recipient
)
Declares to whom the card is send. For more details about way recipient works see
Display rules
. Without recipient declaration a card is useless in OperatorFabric
system.
Card Life Management Configuration
With this attributes OperatorFabric knows when to display or hide cards.
Start Date (startDate
)
See Start Date and Display rules for more examples.
End Date (endDate
)
Fixes the moment until when OperatorFabric
displays the card. After the card is remove from the GUI feed,
Display rules
for some examples.
Optional information
Tags (tag
)
Tags are intended as an additional way to filter cards in the feed of the GUI.
EntityRecipients (entityRecipients
)
Used to send to cards to entity : all users members of the listed entities will receive the card. If it is used in conjunction with groups recipients, users must be members of one of the entities AND one of the groups to receive the cards.
Last Time to Decide (lttd
)
Fixes the moment until when a actions
associated to the card are available. After then, the associated actions won’t be displayed or actionable.
Store information
uid (uid
)
Unique identifier of the card in the OperatorFabric system. This attribute can be sent with card, but by default it’s managed by OperatorFabric.
id (id
)
State id of the associated process, determined by OperatorFabric
can be set arbitrarily by the publisher
.
Other technical attributes
Publish Date (publishDate
)
Indicates when the card has been registered in OperatorFabric
system. This is a technical information exclusively managed by OperatorFabric
.
Deletion Date (`deletionDate°)
Indicates when the card has been removes from OperatorFabric
system. Technical information manage by OperatorFabric
.
13.1.2. User destined Information of the card
There are two kind of User destined information in a card. Some are restricted to the card format, others are defined by the publisher as long as there are encoded in json
format.
Custom part
Data (data
)
Determines where custom information is store. The content in this attribute, is purely publisher
choice.
This content, as long as it’s in json
format can be used to display details. For the way the details are
displayed, see below.
13.1.3. Presentation Information of the card
details (details
)
This attribute is a string of objects containing a title
attribute which is i18n
key and a template
attribute
which refers to a template name contained in the publisher bundle. The bundle in which those resources will be looked
for is the one corresponding of the
version
declared in the card for the current
publisher
.
If no resource is found, either because there is no bundle for the given version or
there is no resource for the given key, then the corresponding key is displayed in the details section of the GUI.
See more documentation about third bundles here .
example:
The TEST
publisher has only a 0.1
version uploaded in the current OperatorFabric
system. The details
value is [{"title":{"key":"first.tab.title"},"template":"template0"}]
.
If the publisherVersion
of the card is 2
then only the title
key declared in the details
array will be displays without any translation, i.e. the tab will contains TEST.2.first.tab.title
and will be empty. If the l10n
for the title is not available, then the tab title will be still TEST.2.first.tab.title
but the template will be compute and the details section will display the template content.
TimeSpans (timeSpans
)
When the simple startDate and endDate are not enough to characterize your process business times, you can add a list of TimeSpan to your card. TimeSpans are rendered in the timeline component as cluster bubbles. This has no effect on the feed content
example :
to display the card two times in the timeline you can add two TimeSpan to your card:
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", ... "timeSpans" : [ {"start" : 1546297200000}, {"start" : 1546297500000} ] }
In this sample, the card will be displayed twice in the time line. The card start date will be ignored.
For timeSpans, you can specify an end date but it is not implemented in OperatorFabric (it was intended for future uses but it will be deprecated).
13.2. Cards Examples
Before detailing the content of cards, let’s show you what cards look like through few examples of json.
13.2.1. Minimal Card
The OperatorFabric Card specification defines 8 mandatory attributes, but some optional attributes are needed for cards to be useful in OperatorFabric. Let’s clarify those point through few examples of minimal cards and what happens when they’re used as if.
Send to One User
The following card contains only the mandatory attributes.
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"card.title.key"}, "summary":{"key":"card.summary.key"}, "recipient":{ "type":"USER", "identity":"tso1-operator" } }
This an information about the process process-000
, send by the TSO1
. The title and the summary refer to i18n
keys defined in the associated i18n
files of the publisher. This card is displayable since the first january 2019 and should only be received by the user using the tso1-operator
login.
Send to several users
Simple case (sending to a group)
The following example is nearly the same as the previous one except for the recipient.
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"card.title.key"}, "summary":{"key":"card.summary.key"}, "recipient":{ "type":"GROUP", "identity":"TSO1" } }
Here, the recipient is a group, the TSO1
. So all users who are members of this group will receive the card.
Simple case (sending to an entity)
The following example is nearly the same as the previous one except for the recipient.
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"card.title.key"}, "summary":{"key":"card.summary.key"}, "recipient":{ "type":"USER", } "entityRecipients" : ["ENTITY1"] }
Here, the recipient is an entity, the ENTITY1
. So all users who are members of this entity will receive the card.
Simple case (sending to a group and an entity)
The following example is nearly the same as the previous one except for the recipient.
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"card.title.key"}, "summary":{"key":"card.summary.key"}, "recipient":{ "type":"GROUP", "identity":"TSO1" } "entityRecipients" : ["ENTITY1"] }
Here, the recipients are a group and an entity, the TSO1
group and ENTITY1
entity. So all users who are both members of this group and this entity will receive the card.
Complex case
If this card need to be view by a user who is not in the TSO1
group, it’s possible to tune more precisely the definition of the recipient. If the tso2-operator
needs to see also this card, the recipient definition could be(the following code details only the recipient part):
"recipient":{ "type":"UNION", "recipients":[ { "type": "GROUP", "identity":"TSO1"}, { "type": "USER", "identity":"tso2-operator"} ] }
So here, all the users of the TSO1
group will receive the INFORMATION
as should the tos2-operator
user.
13.2.2. Regular Card
The previous cards were nearly empty regarding information carrying. In fact, cards are intended to contain more information than a title and a summary. The optional attribute data
is here for that. This attribute is destined to contain any json
object. The creator of the card is free to put any information needed as long as it’s in a json
format.
Full of Hidden data
For this example we will use our previous example for the TSO1
group with a data
attribute containing the definition of a json
object containing two attributes: stringExample
and numberExample
.
{ "publisher":"TSO1", "publisherVersion":"0.1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"card.title.key"}, "summary":{"key":"card.summary.key"}, "recipient":{ "type":"USER", "identity":"tso1-operator" }, "data":{ "stringExample":"This is a not so random string of characters.", "numberExample":123 } }
This card contains some data but when selected in the feed nothing more than the previous example of card happen because there is no rendering configuration.
Fully useful
When a card is selected in the feed (of the GUI), the data is displayed in the detail panel.
The way details are formatted depends on the template uploaded by Third parties as
described here
. To have an effective example without to many actions to performed, the following example will use an already existing
configuration.The one presents in the development version of OperatorFabric, for test purpose(TEST
bundle).
At the card level, the attributes in the card telling OperatorFabric which template to use is the details
attributes.
{ "publisher":"TEST", "publisherVersion":"1", "processId":"process-000", "startDate":1546297200000, "severity":"INFORMATION", "title":{"key":"process.title"}, "summary":{"key":"process.summary"}, "recipient":{ "type":"USER", "identity":"tso1-operator" }, "data":{"rootProp":"Data displayed in the detail panel"}, "details":[{"title":{"key":"process.detail.tab.first"}, "templateName":"template1"}] }
So here a single custom data is defined and it’s rootProp
. This attribute is used by the template called by the details
attribute. This attribute contains an array of json
object containing an i18n
key and a template
reference. Each of those object is a tab in the detail panel of the GUI. The template to used are defined and configured in the Third
bundle upload into the server by the publisher.
13.2.3. Display Rules
Dates
Dates impact both the feed rendering and the timeline rendering.
In the feed cards are visible based on a collection of filters among which a time filter.
In the time line cards are visible based on a similar filter plus the time line renders the "position" in time of said cards. By default, it groups cards at close time in bubbles whom color indicates severity and inner number indicates number of cards.
Start Date (startDate
)
The card is only display after this date is reach by the current time. It’s a mandatory attributes for OperatorFabric cards.
example:
The current day is the 29 january 2019.
A card with the following configuration "startDate":1548758040000
, has a start date equals to the iso date: "2019-01-29T10:34:00Z". So the operator will see it appearing in it’s feed at 10h34 AM universal time. And if there is no endDate
defines for it, it will stay in the feed indefinitely, so this card should be still visible the 30th january 2019. Before "10h34 AM universal time", this card was not visible in the feed.
End Date (endDate
)
This optional attribute, corresponds to the moment after which the card will be remove from the feed of the GUI.
example:
Imagine that the current day is still the 29 january 2019.
The card we are looking after, has the same value for the startDate than in the previous example but has the following configuration for the endDate
: "endDate":1548765240000
. It’s corresponding to "2019-01-29T12:34:00Z" universal time.
So our card is present in the feed between "11h34" and "13h34". Before and after those hours, the card is not available.
Recipients
The attribute recipient
of a card tells to whom it’s sent.
The available types are:
-
GROUP
: Card is sent to every user belonging to a group (identity) -
USER
: Card is sent to a single user (identity) -
UNION
: Card is sent to users according to the union of a recipient list (recipients) -
DEADEND
: Card is sent to no one (mostly for testing purposes)
The simplest way to determine the recipient is to assign the card to a user
or a group
as seen previously in
Minimal Card
.
But it’s possible to combine groups and potentially users using UNION
type to have a better control on whom should receive the card.
UNION
For example, if a card is destined to the operators of TSO1
and TSO2
and needs to be also seen by the admin
, the recipient configuration looks like:
"recipient":{"type":"UNION", "recipients":[ {"type":"GROUP","identity":"TSO1"}, {"type":"GROUP","identity":"TSO2"}, {"type":"USER","identity":"admin"} ] }
14. Cards Consultation Service
The User Interface depends on the Cards Consultation service to be notified of new cards and to consult existing cards, both current and archived.
14.1. Archived Cards
14.1.1. Key concepts
Every time a card is published, in addition to being delivered to the users and persisted as a "current" card in MongoDB, it is also immediately persisted in the archived cards.
Archived cards are similar in structure to current cards, but they are managed differently. Current cards are uniquely identified by their id (made up of the publisher and the process id). That is because if a new card is published with id as an existing card, it will replace it in the card collection. This way, the current card reflects the current state of a process instance. In the archived cards collection however, both cards will be kept, so that the archived cards show all the states that a given process instance went through.
14.1.2. Archives screen in the UI
The Archives screen in the UI allows the users to query these archives with different filters. The layout of this screen is very similar to the Feed screen: the results are displayed in a (paginated) card list, and the user can display the associated card details by clicking a card in the list.
The results of these queries are limited to cards that the user is allowed to see, either because this user is direct recipient of the card or because he belongs to a group (or entity) that is a recipient of the card. If a card is sent to an entity and a group, then this user must be part of both the group and the entity. |
14.1.3. Archive endpoints in the card-consultation API
This Archives screen relies on dedicated endpoints in the card-consultation API, as described here
Deployment and Administration of OperatorFabric
15. Deployment
For now OperatorFabric consist of Docker images available either by compiling the project or by using images releases from Dockerhub
Service images are all based on openjdk:8-jre-alpine.
For simple one instance per service deployment, you can find a sample deployment as a docker-compose file here
16. Adding certification authorities or certificates to the Java keystore
If you’re using certificates (for example for Keycloak) that are not from a certification authority trusted by the JVM, this will cause errors such as this one:

If that is the case, you can pass the additional authorities or certificates that you use to the containers at runtime.
To do so, put the relevant files (*.der files for example) under src/main/docker/certificates.
-
This directory should only contain the files to be added to the keystore.
-
The files can be nested inside directories.
-
Each certificate will be added with its filename as alias. For example, the certificate in file mycertificate.der will be added under alias mycertificate. As a consequence, filenames should be unique or it will cause an error.
-
If you need to add or remove certificates while the container is already running, the container will have to be restarted for the changes to be taken into account.
If you would like certificates to be sourced from a different location, replace the volumes declarations in the deploy docker-compose.yml file with the selected location:
volumes: - "path/to/my/selected/location:/certificates_to_add"
instead of
volumes: - "../../../../src/main/docker/certificates:/certificates_to_add"
The steps described here assume you’re running OperatorFabric in docker mode using the deploy docker-compose, but they can be adapted for single container deployments and development mode. |
If you want to check that the certificates were correctly added, you can do so with the following steps:
-
Open a bash shell in the container you want to check
docker exec -it deploy_thirds_1 bash
-
Run the following command
$JAVA_HOME/bin/keytool -list -v -keystore /tmp/cacerts -storepass changeit
You can also look at the default list of authorities and certificates trusted by the JVM with this command:
$JAVA_HOME/bin/keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit
To run OperatorFabric in development mode, see the development environment documentation .
17. RabbitMQ
17.1. Docker container
In development mode, the simplest way to deploy a RabbitMQ server is to create a RabbitMQ docker container. A docker-compose file is provided to allow quick setup of a convenient RabbitMQ server.
17.2. Server installation
This section is dedicated to production deployment of RabbitMQ. It is not complete and needs to be tailored to any specific production environment.
17.2.1. Download & Installation
Download and install RabbitMQ following the official procedure for the target environment
17.2.2. Used ports
If RabbitMQ may not bind to the following ports, it won’t start :
-
4369: epmd, a peer discovery service used by RabbitMQ nodes and CLI tools
-
5672, 5671: used by AMQP 0-9-1 and 1.0 clients without and with TLS
-
25672: used for inter-node and CLI tools communication (Erlang distribution server port) and is allocated from a dynamic range (limited to a single port by default, computed as AMQP port + 20000). Unless external connections on these ports are really necessary (e.g. the cluster uses federation or CLI tools are used on machines outside the subnet), these ports should not be publicly exposed. See networking guide for details.
-
35672-35682: used by CLI tools (Erlang distribution client ports) for communication with nodes and is allocated from a dynamic range (computed as server distribution port + 10000 through server distribution port + 10010). See networking guide for details.
-
15672: HTTP API clients, management UI and rabbitmqadmin (only if the management plugin is enabled)
-
61613, 61614: STOMP clients without and with TLS (only if the STOMP plugin is enabled)
-
1883, 8883: (MQTT clients without and with TLS, if the MQTT plugin is enabled)
-
15674: STOMP-over-WebSockets clients (only if the Web STOMP plugin is enabled)
-
15675: MQTT-over-WebSockets clients (only if the Web MQTT plugin is enabled)
17.2.3. Production configuration
See the guide for production configuration guidelines
18. Configuration
OperatorFabric has multiple services to configure. These configurations are managed by a Configuration Service, of which they can be several instances to ensure availability.
architecture documentation for more information on the different services.
All services are SpringBoot applications and use jetty as an embedded servlet container. As such, they share some common configuration which is described in the following documentation:
18.1. Global configuration
Aside from the one for the configuration service, all configurations are gathered as resources in the configuration service (under /services/infra/config/src/main/docker/volume).
Note that a few things cannot be set in the configuration served by the configuration service (because its needed right at the application startup for example) and must be set in each service bootstrap configuration file. In this regard, Cloud Configuration Service and Cloud Registry Service services have specific configuration but for other services, they all require the same minimal information:
-
mandatory service name(spring.application.name)
-
mandatory configuration name (spring.cloud.config.name)
-
mandatory configuration fetch from registry enabled (spring.cloud.config.discovery.enabled: true)
-
mandatory configuration service name in registry (spring.cloud.config.discovery.service-id)
-
mandatory eureka registration (eureka.client.register-with-eureka: true and eureka.client.fetch-registry: true)
-
mandatory eureka registry urls (eureka.client.service-url.defaultZone)
-
configuration fail fast (spring.cloud.config.fail-fast)
-
configuration fetch maximum retry (spring.cloud.config.retry.max-attempts)
In most situation, you do not need to change the default bootstrap configuration for those services. Make a copy of the default bootstrap (inside the jar or from the sources) and set eureka up (see above).
The different services also share a common configuration you can setup in the
config service backend. Those common configuration may be set up in the backend
file.application.yml
spring:
rabbitmq:
host: rabbitmq
port: 5672
username: guest
password: guest
data:
mongodb:
uris:
- mongodb://root:password@mongodb:27017/operator-fabric?authSource=admin&authMode=scram-sha1
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: http://authserver/auth/realms/dev/protocol/openid-connect/certs
eureka:
client:
service-url:
defaultZone: http://registry:8080/eureka
region: default
registryFetchIntervalSeconds: 5
operatorfabric:
security:
oauth2:
client-id: opfab-client
client-secret: opfab-oauth-secret
jwt:
login-claim: preferred_username
expire-claim: exp
In the above example you can see that we need to configure:
-
RabbitMQ (See spring-amqp doc)
-
MongoDB
-
Eureka (See spring eureka)
-
OperatorFabric
18.2. OperatorFabric Mongo configuration
We only use URI configuration for mongo through the usage of the
,
it allows us to share the same configuration behavior for simple or cluster
configuration and with both spring classic and reactive mongo configuration.
See mongo connection string for the complete URI syntax.spring.data.mongodb.uris
18.2.1. Define time to live for archived cards
By default, archived cards will remain stored in the database forever. It is possible to have them automatically removed after a specified duration by using the TTL index feature of mongoDB on their publishDate field.
For example, to have cards expire after 10 days (864000s), enter the following commands in the mongo shell:
use operator-fabric
db.archivedCards.createIndex( { "publishDate": 1 }, { expireAfterSeconds: 864000 } )
You cannot use createIndex() to change the value of expireAfterSeconds of an existing index. Instead use the collMod database command in conjunction with the index collection flag. Otherwise, to change the value of the option of an existing index, you must drop the index first and recreate. |
18.3. OperatorFabric Specific configuration
Below are description of OperatorFabric specific configuration properties.
Note that other components may have specific configuration, see the relevant sub-sections.
18.3.1. Security Configuration
Common configuration
This concern is configured within the ${OF_HOME}/services/infra/config
project
into 3 distinct files:
-
application.yml
; -
web-ui.yml
; -
client-gateway.yml
.
They are located into the following folders within the ${OF_HOME}/services/infra/config/java/src/main/docker/volume
folder:
-
dev-configurations
: to be use intodev
mode; -
docker-configurations
: used by docker at run time.
EXAMPLE: the configuration for dev
before compilation is done in the following files:
- ${OF_HOME}/services/infra/config/java/src/main/docker/volume/dev-configurations/application.yml
;
- ${OF_HOME}/services/infra/config/java/src/main/docker/volume/dev-configurations/client-gateway.ym
;
- ${OF_HOME}/services/infra/config/java/src/main/docker/volume/dev-configurations/web-ui.yml
.
For test purposes in dev
mode, it’s possible to edit files located into `${OF_HOME}/services/infra/config/build/docker-volume/dev-configurations
.
Be aware that those changes will be lost after a new compilation or even a simple re-run of the project.
This configuration files follow the springframework
configuration convention. Within a same file it’s possible to
use SpEL ${}
convention. For example, ${AnotheProperty}
allows to re-use the value of AnotherProperty
already declared.
It helps to avoid typos or missing to report some changes. An example could be find below into the delegate-url
property.
application.yml
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.security.oauth2.client-id |
null |
yes |
Oauth2 client id used by OperatorFabric may be specific for each service |
operatorfabric.security.oauth2.client-secret |
null |
yes |
Oauth2 client secret used by OperatorFabric may be specific for each service |
operatorfabric.security.jwt.login-claim |
sub |
no |
Jwt claim is used as user login or id |
operatorfabric.security.jwt.expire-claim |
exp |
no |
Jwt claim is used as token expiration timestamp |
spring.security.oauth2.resourceserver.jwt.provider-url |
null |
yes |
The keycloak instance url |
spring.security.oauth2.resourceserver.jwt.provider-realm |
null |
yes |
The realm name within the keycloak instance |
example of application.yml
operatorfabric:
security:
oauth2:
client-id: opfab-client
client-secret: opfab-keycloak-secret
jwt:
login-claim: preferred_username
expire-claim: exp
where operatorfabric.security.jwt.expire-claim
could have been omitted because having the same value as the default one.
client-gateway.yml
Filters and CORS configuration
In the configuration service client-gateway.yml
file:
-
The application must set up a route to the oauth server
-
/auth/token(?<path>.*)
: must match the oauth2 token entry point; -
/auth/code/(?<params>.*)
: must match the auth entry point with specific query parameters likeresponse_type=code&client_id=[client id]&${params}
; -
/auth/check_token
: must match token introspection entry point
-
-
The application must add request header for each request:
-
AddRequestHeader: Authorization, Basic
: followed, separated with a space, by theOAuth2 client-id
and theOAuth2 client-secret
encoded in base64.
-
-
The application may set up CORS rules if api are to be accessed from browser outside of the deployment domain
Configuration example of the filters, for the docker dev keycloak:
spring.cloud.gateway.routes[0].filters:
- RewritePath=/auth/token(?<path>.*), /auth/realms/dev/protocol/openid-connect/token$\{path}
- RewritePath=/auth/code/(?<params>.*), /auth/realms/dev/protocol/openid-connect/auth?response_type=code&client_id=opfab-client&$\{params}
- RewritePath=/auth/check_token, /auth/realms/dev/protocol/openid-connect/token/introspect
- AddRequestHeader=Authorization, Basic b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
where:
-
spring.cloud.gateway.routes.uri
: is your keycloak instance -
spring.cloud.gateway.routes[0]
is the routes withid
equals toauth
; -
/realms/dev
: is the keycloak realm whereopfab-client
is defined. -
b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
: is the base64 encoded string ofopfab-client:opfab-keycloak-secret
withopfab-client
as client-id andopfab-keycloak-secret
its client secret.
In the configuration service client-gateway.yml
file, the application must set up the URI
of the Action Service
.
To do so, the spring.cloud.gateway.routes.id="action".uri
property is set with the actual value of this service.
In the case of a development set-up, this value is localhost:2105
where 2105
is the default port as set in the application.yml
used by the Action service
as configuration.
client-gateway.yml
of the dev-configuration
as example:
spring:
cloud:
gateway:
routes:
- id: actions
uri: http://localhost:2105
predicates:
- Path=/actions/**
filters:
- RewritePath=/actions/(?<path>.*), /$\{path}
As explained earlier, the key to configure is uri
of the spring.cloud.gateway.routes
with the id
equals to actions
.
web-ui.yml
For OAuth2 security concerns into this file, there are two way to configure it, based on the Oauth2 chosen flow. There are two common properties:
-
operatorfabric.security.oauth2.flow.provider
which corresponds to the OAuth2 provider. -
operatorfabric.security.realm-url
: which is the OAuth2 realm provider under which the OpertaroFabric client is declared. -
operatorfabric.security.provider-url
: which is the The keycloak server instance.
OAuth2 Flows and specific configuration
There are 3 OAuth2 Authentication flows available into OperatorFabric UI:
-
password grant: referred as PASSWORD mode flow;
-
code flow : referred as CODE mode flow;
-
implicit flow: referred as IMPLICIT mode flow.
OAuth2 IMPLICIT Flow
It had its own way of configuration. To enable IMPLICIT Flow authentication the following properties need to be set:
-
operatorfabric.security.oauth2.flow.mode
toIMPLICIT
; -
operatorfabric.security.oauth2.flow.delegate-url
with the URL of the OAuth2 leading to the.well-known/openid-configuration
end-point used for authentication configuration.
operatorfabric:
keycloak:
realm: dev
security:
oauth2:
flow:
mode: IMPLICIT
provider: Opfab Keycloak
delagate-url: http://localhost:89/auth/realms/${operatorfabric.keycloak.realm}
Within the delegate-url
property the ${operatorfabric.keycloak.realm}
refers to the value of the operatorfabric.keycloak.realm
declared earlier, dev
here.
For keycloak instance used for dev purposes, this delegate-url
correspond to the realm under which the client opfab-client
is registred. The
url look up by the implicit ui mechanism is localhost:89/auth/realms/dev/.well-known/openid-configuration
.
OAuth2 PASSWORD or CODE Flows
These two modes share the same way of declaring the delegate URL. The default configuration for dev is set to CODE
and work straight away.
-
operatorfabric.security.oauth2.flow.mode
toPASSWORD
orCODE
; -
operatorfabric.security.oauth2.flow.delegate-url
with the URL of the OAuth2 leading to the protocol used for authentication.
operatorfabric:
keycloak:
realm: dev
security:
oauth2:
flow:
mode: CODE
provider: Opfab Keycloak
delagate-url: http://localhost:89/auth/realms/${operatorfabric.keycloak.realm}/protocol/openid-connect/auth?response_type=code&client_id=opfab-client
Within the delegate-url
property the ${operatorfabric.keycloak.realm}
refers to the value(also dev
here) of the operatorfabric.keycloak.realm
declared earlier.
Here, the client-id
value is opfab-client
which is define as client under the realm
named dev on the dev keycloak instance.
Using token
Get a token
End point: localhost:2002/auth/token
Method: POST
Body arguments:
-
client_id:
string
constant=clientIdPassword
; -
grant_type:
string
constant=password
; -
username:
string
any value, must match an OperatorFabric registered user name; -
password:
string
any value;
The following examples will be for admin
user.
command:
curl -s -X POST -d "username=admin&password=test&grant_type=password&client_id=clientIdPassword" http://localhost:2002/auth/token
example of expected result:
{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cC I6MTU1MjY1OTczOCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOi IwMmQ4MmU4NS0xM2YwLTQ2NzgtOTc0ZC0xOGViMDYyMTVhNjUiLCJjbGllbnRfaWQiOiJjbGllbnRJZF Bhc3N3b3JkIiwic2NvcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.SDg-BEzzonIVXfVBnnfq0oMbs_0 rWVtFGAZzRHj7KPgaOXT3bUhQwPOgggZDO0lv2U1klwB94c8Cb6rErzd3yjJ8wcVcnFLO4KxrjYZZxdK VAz0CkMKqng4kQeQm_1UShsQXGLl48ezbjXyJn6mAl0oS4ExeiVsx_kYGEdqjyb5CiNaAzyx0J-J5jVD SJew1rj5EiSybuy83PZwhluhxq0D2zPK1OSzqiezsd5kX5V8XI4MipDhaAbPYroL94banZTn9RmmAKZC AYVM-mmHbjk8mF89fL9rKf9EUNhxOG6GE0MDqB3LLLcyQ6sYUmpqdP5Z94IkAN-FpC7k93_-RDw","to ken_type":"bearer","refresh_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI iOiJhZG1pbiIsInNjb3BlIjpbInJlYWQiLCJ1c2VyX2luZm8iXSwiYXRpIjoiMDJkODJlODUtMTNmMC0 0Njc4LTk3NGQtMThlYjA2MjE1YTY1IiwiZXhwIjoxNTUyNzAxMTM4LCJhdXRob3JpdGllcyI6WyJST0x FX0FETUlOIiwiUk9MRV9VU0VSIl0sImp0aSI6IjMwOWY2ZDllLWNmOGEtNDg0YS05ZjMxLWViOTAxYzk 4YTFkYSIsImNsaWVudF9pZCI6ImNsaWVudElkUGFzc3dvcmQifQ.jnZDt6TX2BvlmdT5JV-A7eHTJz_s lC5fHrJFVI58ly6N7AUUfxebG_52pmuVHYULSKqTJXaLR866r-EnD4BJlzhk476FtgtVx1nazTpLFRLb 8qDCxeLrzClQBkzcxOt6VPxB3CD9QImx3bcsDwjkPxofUDmdg8AxZfGTu0PNbvO8TKLXEkeCztLFvSJM GlN9zDzWhKxr49I-zPZg0XecgE9j4WITkFoDVwI-AfDJ3sGXDi5AN55Sz1j633QoqVjhtc0lO50WPVk5 YT7gU8HLj27EfX-6vjnGfNb8oeq189-NX100QHZM9Wgm79mIm4sRgwhpv-zzdDAkeb3uwIpb8g","exp ires_in":1799,"scope":"read user_info","jti":"02d82e85-13f0-4678-974d-18eb06215a65"}
http --form POST http://localhost:2002/auth/token username=admin password=test grant_type=password client_id=clientIdPassword
example of expected result:
.HTTP/1.1 200 OK Cache-Control: no-store Content-Type: application/json;charset=utf-8 Date: Fri, 15 Mar 2019 13:57:19 GMT Pragma: no-cache X-Content-Type-Options: nosniff X-Frame-Options: DENY X-XSS-Protection: 1; mode=block transfer-encoding: chunked { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTU1MjY2MDAzOS wiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOiI2MjQzMDliMS03Yz g3LTRjZGMtODQ0My0wMTI0NTE1Zjg3ZjgiLCJjbGllbnRfaWQiOiJjbGllbnRJZFBhc3N3b3JkIiwic2 NvcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.VO4OZL7ycqNez0cHzM5WPuklr0r6SAOkUdUV2qFa5Bd 3PWx3DFHAHUxkfSX0-R4OO6iG2Zu7abzToAZNVLwk107LH_lWXOMQBriGx3d2aSgCf1yx_wI3lHDd8ST 8fxV7uNeolzywYavSpMGfgz9GXLzmnyeuPH4oy7eyPk9BwWVi0d7a_0d-EfhE1T8eaiDfymzzNXJ4Bge 8scPy-93HmWpqORtJaFq1qy4QgU28N2LgHFEEEWCSzfhYXH-LngTCP3-JSNcox1hI51XBWEqoeApKdfD J6o4szR71SIFCBERxCH9TyUxsFywWL3e-YnXMiP2J08eB8O4YwhYQEFqB8Q", "expires_in": 1799, "jti": "624309b1-7c87-4cdc-8443-0124515f87f8", "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsInNjb3BlIjpbInJlYWQiLC J1c2VyX2luZm8iXSwiYXRpIjoiNjI0MzA5YjEtN2M4Ny00Y2RjLTg0NDMtMDEyNDUxNWY4N2Y4IiwiZX hwIjoxNTUyNzAxNDM5LCJhdXRob3JpdGllcyI6WyJST0xFX0FETUlOIiwiUk9MRV9VU0VSIl0sImp0aS I6ImRiYzMxNTJiLTM4YTUtNGFmZC1hY2VmLWVkZTI4MjJkOTE3YyIsImNsaWVudF9pZCI6ImNsaWVudE lkUGFzc3dvcmQifQ.Ezd8kbfNQHOOvUCNNN4UmOOkncHiT9QVEM63FiW1rq0uXDa3xfBGil8geM5MsP0 7Q2He-mynkFb8sGNDrAXTdO-8r5o4a60zWrktrMg2QH4icC1lyeZpiwZxe6675QpLpSeMlXt9PdYj-pb 14lrRookxXP5xMQuIMteZpbtby7LuuNAbNrjveZ1bZ4WMi7zltUzcYUuqHlP1AYPteGRrJVKXiuPpoDv gwMsEk2SkgyyACI7SdZZs8IT9IGgSsIjjgTMQKzj8P6yYxNLUynEW4o5y1s2aAOV0xKrzkln9PchH9zN qO-fkjTVRjy_LBXGq9zkn0ZeQ3BUe1GuthvGjaA", "scope": "read user_info", "token_type": "bearer" }
Extract token
From the previous results, the data need to be considered to be authenticated
by OperatorFabric services is the content of the "access_token"
attribute of
the body response.
Once this value extracted, it need to be passed at the end of the value of the
http HEADER of type Authorization:Bearer
.
example from previous results:
Authorization:Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTU1MjY1OTczOCw iYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOiIwMmQ4MmU4NS0xM2Y wLTQ2NzgtOTc0ZC0xOGViMDYyMTVhNjUiLCJjbGllbnRfaWQiOiJjbGllbnRJZFBhc3N3b3JkIiwic2N vcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.SDg-BEzzonIVXfVBnnfq0oMbs_0rWVtFGAZzRHj7KPga OXT3bUhQwPOgggZDO0lv2U1klwB94c8Cb6rErzd3yjJ8wcVcnFLO4KxrjYZZxdKVAz0CkMKqng4kQeQm _1UShsQXGLl48ezbjXyJn6mAl0oS4ExeiVsx_kYGEdqjyb5CiNaAzyx0J-J5jVDSJew1rj5EiSybuy83 PZwhluhxq0D2zPK1OSzqiezsd5kX5V8XI4MipDhaAbPYroL94banZTn9RmmAKZCAYVM-mmHbjk8mF89f L9rKf9EUNhxOG6GE0MDqB3LLLcyQ6sYUmpqdP5Z94IkAN-FpC7k93_-RDw
Authorization:Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTU1MjY2MDAzOSw iYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOiI2MjQzMDliMS03Yzg 3LTRjZGMtODQ0My0wMTI0NTE1Zjg3ZjgiLCJjbGllbnRfaWQiOiJjbGllbnRJZFBhc3N3b3JkIiwic2N vcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.VO4OZL7ycqNez0cHzM5WPuklr0r6SAOkUdUV2qFa5Bd3 PWx3DFHAHUxkfSX0-R4OO6iG2Zu7abzToAZNVLwk107LH_lWXOMQBriGx3d2aSgCf1yx_wI3lHDd8ST8 fxV7uNeolzywYavSpMGfgz9GXLzmnyeuPH4oy7eyPk9BwWVi0d7a_0d-EfhE1T8eaiDfymzzNXJ4Bge8 scPy-93HmWpqORtJaFq1qy4QgU28N2LgHFEEEWCSzfhYXH-LngTCP3-JSNcox1hI51XBWEqoeApKdfDJ 6o4szR71SIFCBERxCH9TyUxsFywWL3e-YnXMiP2J08eB8O4YwhYQEFqB8Q
Check a token
from previous example
curl -s -X POST -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTU1MjY1 OTczOCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOiIwMmQ4MmU4 NS0xM2YwLTQ2NzgtOTc0ZC0xOGViMDYyMTVhNjUiLCJjbGllbnRfaWQiOiJjbGllbnRJZFBhc3N3b3Jk Iiwic2NvcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.SDg-BEzzonIVXfVBnnfq0oMbs_0rWVtFGAZzR Hj7KPgaOXT3bUhQwPOgggZDO0lv2U1klwB94c8Cb6rErzd3yjJ8wcVcnFLO4KxrjYZZxdKVAz0CkMKqn g4kQeQm_1UShsQXGLl48ezbjXyJn6mAl0oS4ExeiVsx_kYGEdqjyb5CiNaAzyx0J-J5jVDSJew1rj5Ei Sybuy83PZwhluhxq0D2zPK1OSzqiezsd5kX5V8XI4MipDhaAbPYroL94banZTn9RmmAKZCAYVM-mmHbj k8mF89fL9rKf9EUNhxOG6GE0MDqB3LLLcyQ6sYUmpqdP5Z94IkAN-FpC7k93_-RDw" http://localhost:2002/auth/check_token
which gives the following example of result:
{ "sub":"admin", "scope":["read","user_info"], "active":true,"exp":1552659738, "authorities":["ROLE_ADMIN","ROLE_USER"], "jti":"02d82e85-13f0-4678-974d-18eb06215a65", "client_id":"clientIdPassword" }
from previous example:
http --form POST http://localhost:2002/auth/check_token token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTU1MjY2M DAzOSwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJqdGkiOiI2MjQzMDliM S03Yzg3LTRjZGMtODQ0My0wMTI0NTE1Zjg3ZjgiLCJjbGllbnRfaWQiOiJjbGllbnRJZFBhc3N3b3JkI iwic2NvcGUiOlsicmVhZCIsInVzZXJfaW5mbyJdfQ.VO4OZL7ycqNez0cHzM5WPuklr0r6SAOkUdUV2q Fa5Bd3PWx3DFHAHUxkfSX0-R4OO6iG2Zu7abzToAZNVLwk107LH_lWXOMQBriGx3d2aSgCf1yx_wI3lH Dd8ST8fxV7uNeolzywYavSpMGfgz9GXLzmnyeuPH4oy7eyPk9BwWVi0d7a_0d-EfhE1T8eaiDfymzzNX J4Bge8scPy-93HmWpqORtJaFq1qy4QgU28N2LgHFEEEWCSzfhYXH-LngTCP3-JSNcox1hI51XBWEqoeA pKdfDJ6o4szR71SIFCBERxCH9TyUxsFywWL3e-YnXMiP2J08eB8O4YwhYQEFqB8Q
which gives the following example of result:
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, max-age=0, must-revalidate Content-Type: application/json;charset=utf-8 Date: Fri, 15 Mar 2019 14:19:31 GMT Expires: 0 Pragma: no-cache X-Content-Type-Options: nosniff X-Frame-Options: DENY X-XSS-Protection: 1; mode=block transfer-encoding: chunked { "active": true, "authorities": [ "ROLE_ADMIN", "ROLE_USER" ], "client_id": "clientIdPassword", "exp": 1552660039, "jti": "624309b1-7c87-4cdc-8443-0124515f87f8", "scope": [ "read", "user_info" ], "sub": "admin" }
18.3.2. User creation
Setting automated user creation==. Creation user requires a user id. Given name and family name are optional.
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.security.jwt.login-claim |
sub |
no |
Jwt claim is used as a user login or id |
operatorfabric.security.jwt.given-name-claim |
given-name |
no |
Jwt claim is used to set the user’s given name |
operatorfabric.security.jwt.family-name-claim |
family-name |
no |
Jwt claim is used to set the user’s family name |
18.3.3. Alternative way to manage groups (and/or entities)
By default, Operator-Fabric
manage groups (and/or entities) through the user’s collection in the database. Another mode can be defined, the JWT mode. The groups (and/or entities) come from the authentication token. The administrator of the authentication service has to set what claims define a group (and/or entity). In the Operator-Fabric
configuration, the opfab administrator has to set properties to retrieve those groups (and/or entities).
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.security.jwt.groups.mode |
OPERATOR_FABRIC |
no |
Set the group mode, possible values JWT or OPERATOR_FABRIC |
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimStandard.path |
no |
path in the JWT to retrieve the claim that defines a group |
|
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimStandardArray.path |
no |
path in the JWT to retrieve the claim that defines an array of groups |
|
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimStandardList.path |
no |
path in the JWT to retrieve the claim that defines a list of group |
|
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimStandardList.separator |
no |
set the separator value of the list of group |
|
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimCheckExistPath.path |
no |
path in the JWT to check if that path does exist, if it does, use the roleValue as a group |
|
operatorfabric.security.jwt.groups.rolesClaim.rolesClaimCheckExistPath.roleValue |
no |
set the value of the group if the path exists |
|
operatorfabric.security.jwt.entitiesIdClaim |
no |
set the name of the field in the token |
|
operatorfabric.security.jwt.gettingEntitiesFromToken |
no |
boolean indicating if you want the entities of the user to come from the token and not mongoDB (possible values : true/false) |
application.yml
operatorfabric:
security:
jwt:
entitiesIdClaim: entitiesId
gettingEntitiesFromToken: true
groups:
mode: JWT # value possible JWT | OPERATOR_FABRIC
rolesClaim:
rolesClaimStandard:
- path: "ATTR1"
- path: "ATTR2"
rolesClaimStandardArray:
- path: "resource_access/opfab-client/roles"
rolesClaimStandardList:
- path: "roleFieldList"
separator: ";"
rolesClaimCheckExistPath:
- path: "resource_access/AAA"
roleValue: "roleAAA"
- path: "resource_access/BBB"
roleValue: "roleBBB"
JWT example
{
"jti": "5ff87583-10bd-4946-8753-9d58171c8b7f",
"exp": 1572979628,
"nbf": 0,
"iat": 1572961628,
"iss": "http://localhost:89/auth/realms/dev",
"aud": [
"AAA",
"BBB",
"account"
],
"sub": "example_user",
"typ": "Bearer",
"azp": "opfab-client",
"auth_time": 0,
"session_state": "960cbec4-fcb2-47f2-a155-975832e61300",
"acr": "1",
"realm_access": {
"roles": [
"offline_access",
"uma_authorization"
]
},
"resource_access": {
"AAA": {
"roles": [
"role_AAA"
]
},
"BBB": {
"roles": [
"role_BBB"
]
},
"opfab-client": {
"roles": [
"USER"
]
},
"account": {
"roles": [
"manage-account",
"manage-account-links",
"view-profile"
]
}
},
"scope": "openid ATTR2 email ATTR1 profile roleFieldList",
"email_verified": false,
"name": "example_firtstname example_lastname",
"ATTR2": "roleATTR2",
"ATTR1": "roleATTR1",
"preferred_username": "example_user",
"given_name": "example_firtstname",
"entitiesId": "ENTITY1",
"family_name": "example_lastname",
"email": "example_user@mail.com",
"roleFieldList": "roleA;roleB;roleC"
}
As the result, the group will be [ATTR1, ATTR2, roleA, roleB, roleC, USER, roleBBB, roleAAA]
18.4. Service-specific configuration
18.4.1. Actions Business service
OperatorFabric Actions Business service is a Spring Webflux application bootstrapped using SpringBoot.
Mandatory configuration, Profiles and default properties
The service has the following mandatory configuration.
Mandatory properties
The following table recaps all the needed properties for the action service
to run properly. They’re defined in the application.yml
configuration file.
The configuration use during the development should be included into the
application-dev.yml
configuration file.
key | Usage | Example |
---|---|---|
server.port |
Defines the port of the service |
2105 |
spring.security.oauth2.resourceserver.jwt.jwk-set-uri |
URI serving the public key use to control OAuth2 jwt signature. See RFC 7517 - JSON Web Key (JWK) |
|
operatorfabric.services.base-url.cards |
URL of the |
|
operatorfabric.services.base-url.thirds |
URL of the |
|
operatorfabric.services.base-url.users |
URL of the |
Specifying external configuration properties when launching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when launching a docker image
At time of writing, you cannot specify an alternate profile at runtime.
The profiles available to be activated at runtime are docker
and native
.
Available environment variables for docker image
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when launching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
JAVA_OPTIONS: Additional java options
18.4.2. Cards-Consultation Business service
OperatorFabric Cards-Consultation Business service is a Spring Webflux application bootstrapped using SpringBoot.
In our spring micro service architecture this service depends on Eureka Registry.
Mandatory configuration, Profiles and default properties
The service has no mandatory configuration beside global configuration and usual bootstrap configuration.
For other configuration see:
Service specific properties
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: cards-consultation
cloud:
config:
name: cards-consultation
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: cards-consultation
cloud:
config:
name: cards-consultation
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: cards-consultation
cloud:
config:
name: cards-consultation
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
service-url:
defaultZone: 'http://localhost:2001/eureka'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample development configuration
server:
port: 2104
logging.level.root: DEBUG
Sample docker image configuration
Specifying external configuration properties when launching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when launching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writing, you cannot specify an alternate profile at runCards-Consultation. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when launching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.4.3. Cards-Publication Business service
OperatorFabric Cards-Publication Business service is a Spring Webflux application bootstrapped using SpringBoot.
In our spring micro service architecture this service depends on Eureka Registry.
Mandatory configuration, Profiles and default properties
The service has no mandatory configuration beside global configuration and usual bootstrap configuration.
For other configuration see:
Service specific properties
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.card-write.window.size |
1000 |
no |
card input window size to fill before flush |
operatorfabric.card-write.window.timeout |
500 |
no |
card input window millis wait time before flush |
operatorfabric.card-notification.window.size |
100 |
no |
card notification window size to fill before flush |
operatorfabric.card-notification.window.timeout |
1000 |
no |
card notification window millis wait time before flush |
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: cards-publication
cloud:
config:
name: cards-publication
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: cards-publication
cloud:
config:
name: cards-publication
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: cards-publication
cloud:
config:
name: cards-publication
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
service-url:
defaultZone: 'http://localhost:2001/eureka'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample development configuration
server:
port: 2102
Sample docker image configuration
Specifying external configuration properties when launching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when launching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writing, you cannot specify an alternate profile at runCards-Publication. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when launching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.4.4. Cloud Gateway service
OperatorFabric Client Gateway service is a Spring Cloud Gateway application bootstrapped using SpringBoot.
In our spring micro service architecture the gateway service depends on Eureka Registry.
Mandatory configuration, Profiles and default properties
To get a working gateway service, there a few mandatory configuration properties:
Filters and CORS configuration
Authentication Server
In the configuration service client-gateway.yml
file:
-
The application must set up a route to the oauth server
-
/auth/token(?<path>.*)
: must match the oauth2 token entry point; -
/auth/code/(?<params>.*)
: must match the auth entry point with specific query parameters likeresponse_type=code&client_id=[client id]&${params}
; -
/auth/check_token
: must match token introspection entry point
-
-
The application must add request header for each request:
-
AddRequestHeader: Authorization, Basic
: followed, separated with a space, by theOAuth2 client-id
and theOAuth2 client-secret
encoded in base64.
-
-
The application may set up CORS rules if api are to be accessed from browser outside of the deployment domain
Configuration example of the filters, for the docker dev keycloak:
spring.cloud.gateway.routes[0].filters:
- RewritePath=/auth/token(?<path>.*), /auth/realms/dev/protocol/openid-connect/token$\{path}
- RewritePath=/auth/code/(?<params>.*), /auth/realms/dev/protocol/openid-connect/auth?response_type=code&client_id=opfab-client&$\{params}
- RewritePath=/auth/check_token, /auth/realms/dev/protocol/openid-connect/token/introspect
- AddRequestHeader=Authorization, Basic b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
where:
-
spring.cloud.gateway.routes.uri
: is your keycloak instance -
spring.cloud.gateway.routes[0]
is the routes withid
equals toauth
; -
/realms/dev
: is the keycloak realm whereopfab-client
is defined. -
b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
: is the base64 encoded string ofopfab-client:opfab-keycloak-secret
withopfab-client
as client-id andopfab-keycloak-secret
its client secret.
Action Service
In the configuration service client-gateway.yml
file, the application must set up the URI
of the Action Service
.
To do so, the spring.cloud.gateway.routes.id="action".uri
property is set with the actual value of this service.
In the case of a development set-up, this value is localhost:2105
where 2105
is the default port as set in the application.yml
used by the Action service
as configuration.
client-gateway.yml
of the dev-configuration
as example:
spring:
cloud:
gateway:
routes:
- id: actions
uri: http://localhost:2105
predicates:
- Path=/actions/**
filters:
- RewritePath=/actions/(?<path>.*), /$\{path}
As explained earlier, the key to configure is uri
of the spring.cloud.gateway.routes
with the id
equals to actions
.
For other configuration see spring cloud gateway documentation.
Service specific properties
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.gateway.configs |
null |
no |
an array of string for each allowed config entries |
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: client-gateway
cloud:
config:
name: client-gateway
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: client-gateway
cloud:
config:
name: client-gateway
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: client-gateway
cloud:
config:
name: client-gateway
failFast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
register-with-eureka: true
fetch-registry: true
service-url:
defaultZone: 'http://localhost:2001/eureka/'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample developpement configuration
server:
port: 2002
spring:
cloud:
gateway:
routes:
- id: auth
uri: http://localhost:89
predicates:
- Path=/auth/**
filters:
- RewritePath=/auth/token(?<path>.*), /auth/realms/dev/protocol/openid-connect/token$\{path}
- RewritePath=/auth/code/(?<params>.*), /auth/realms/dev/protocol/openid-connect/auth?response_type=code&client_id=opfab-client&$\{params}
- RewritePath=/auth/check_token, /auth/realms/dev/protocol/openid-connect/token/introspect
- AddRequestHeader=Authorization, Basic b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
# WARNING : THIS CORS CONFIGURATION SHOULD NOT BE USED IN PRODUCTION
globalcors:
corsConfigurations:
'[/**]':
allowedOrigins: "*"
allowedMethods: "*"
allowedHeaders: "Authorization, Content-Type"
operatorfabric.gateway.configs:
- web-ui.json
#logging.level.root: debug
Sample docker image configuration
spring:
cloud:
gateway:
routes:
- id: auth
uri: http://keycloak:8080
predicates:
- Path=/auth/**
filters:
- RewritePath=/auth/token(?<path>.*), /auth/realms/dev/protocol/openid-connect/token$\{path}
- RewritePath=/auth/code/(?<params>.*), /auth/realms/dev/protocol/openid-connect/auth?response_type=code&client_id=opfab-client&$\{params}
- RewritePath=/auth/check_token, /auth/realms/dev/protocol/openid-connect/token/introspect
- AddRequestHeader=Authorization, Basic b3BmYWItY2xpZW50Om9wZmFiLWtleWNsb2FrLXNlY3JldA==
# WARNING : THIS CORS CONFIGURATION SHOULD NOT BE USED IN PRODUCTION
globalcors:
corsConfigurations:
'[/**]':
allowedOrigins: "*"
allowedMethods: "*"
allowedHeaders: "Authorization, Content-Type"
operatorfabric.gateway.configs:
- web-ui.json
Specifying external configuration properties when lauching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when lauching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writting, you cannot specify an alternate profile at runtime. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when lauching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.4.5. Cloud Configuration service
OperatorFabric Configuration service is a Spring Cloud Config application bootstrapped using SpringBoot.
In our spring micro service architecture Configuration instances are the first services to bootstrap, thus they are configured in a specific way contrary to other services.
Mandatory configuration, Profiles and default properties
To get a working configuration service, there a few mandatory configuration properties:
-
in a bootstrap file:
-
The application must have a set name (spring.application.name)
-
-
in an application property file
-
The application must have a configured rabbitmq service for configuration change notification (spring.rabbitmq.*)
-
The application must have a configured eureka server (eureka.client.*)
-
For other configuration see spring cloud config documentation.
Note that it is mandatory to define an environment repository for the service. Dev and Docker profile uses a file system backend which is not suitable for production and redundancy. You should prefer the usage of Git or Vault for production.
default properties
It is preferable not to change the following bootstrap.yml file.
bootstrap.yml
spring:
application:
name: config
application.yml
management:
endpoints:
web:
exposure:
include: '*'
The above embedded configurations are the basic settings of the application: * it sets its name as a service (config) * it exposes management endpoints
dev profile
dev is the profile we use internally for developpement we make it available for external developers so that they don’t need extensive configuration to get a jar working in the development environment
server:
port: 2000
spring:
# level.root: debug
profiles:
active: [native,dev]
cloud:
config:
server:
native:
search-locations:
- file:./build/dev-data/dev-configurations
rabbitmq:
host: localhost
port: 5672
username: guest
password: guest
eureka:
client:
region: default
service-url:
defaultZone: http://localhost:2001/eureka
registryFetchIntervalSeconds: 5
-
it exposes the service on port 2000 (defaults to 8080)
-
it activates the dev and native profile (native is mandatory for serving config from file system)
-
it configures rabbitmq for dispatching config change messages to other services
-
it configures registration in eureka discovery service
docker profile
docker is the profile we use in our docker images
spring:
profiles:
active: [native]
cloud:
config:
server:
native:
search-locations:
- file:/service-config
rabbitmq:
host: ${RABBITMQ_HOST}
port: ${RABBITMQ_PORT}
username: ${RABBITMQ_USER}
password: ${RABBITMQ_PASSWORD}
eureka:
client:
region: default
service-url:
defaultZone: http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka
registryFetchIntervalSeconds: 5
-
it activates the native profile (native is mandatory for serving config from file system)
-
it configures rabbitmq for dispatching config change messages to other services
-
it configures registration in eureka discovery service
Specifying external configuration properties when lauching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
Seehttps://docs.spring.io/spring-boot/docs/2.1.2.RELEASE//reference/htmlsingle/#howto-set-active-spring-profiles[Set the Active Spring Profiles] for specifying alternate profile.
Specifying configuration properties when lauching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writting, you cannot specify an alternate profile at runtime. The default profiles activated are docker and native.
Available environment variables for docker image
-
RABBITMQ_HOST: Rabbitmq host name
-
RABBITMQ_PORT: Rabbitmq host port
-
RABBITMQ_USER: Rabbitmq user name used for authentication service
-
RABBITMQ_PASSWORD: Rabbitmq user password used for authentication service
-
REGISTRY_HOST: Registry (eureka) host name
-
REGISTRY_PORT: Registry (eureka) host port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when lauching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
RABBITMQ_HOST: Rabbitmq host name
-
RABBITMQ_PORT: Rabbitmq host port
-
RABBITMQ_USER: Rabbitmq user name used for authentication service
-
RABBITMQ_PASSWORD: Rabbitmq user password used for authentication service
-
REGISTRY_HOST: Registry (eureka) host name
-
REGISTRY_PORT: Registry (eureka) host port
-
JAVA_OPTIONS: Additional java options
18.4.6. Cloud Registry service
OperatorFabric Registry service is a Spring Eureka application bootstrapped using SpringBoot.
In our spring micro service architecture Eureka Registry instances are the second services to bootstrap, its configuration relies on the Cloud Configuration Service .
Mandatory configuration, Profiles and default properties
To get a working registry service, there a few mandatory configuration properties:
-
In a bootstrap file
-
The application must have a set name (spring.application.name)
-
The application must have a set configuration name (spring.cloud.config.name)
-
The application must have a set configuration server (spring.cloud.config.uri)
-
The application may have a retry/failfast configuration for config access (spring.cloud.config.failfast, spring.cloud.config.retry)
-
-
In a configuration service registry.yml file
-
The application may deactivate eureka registration to avoid self registration (deactivated by default in internal application.yml file)
-
The application must set the Eureka instance hostname (eureka.instance.hostname)
-
The application must set the Eureka default zone (eureka.lient.serviceUrl.defaultZone)
-
For other configuration see spring cloud netflix documentation.
default properties
It is preferable not to change the following bootstrap.yml file.
bootstrap.yml
spring:
application:
name: registry
cloud.config:
name: registry
fail-fast: true
bootstrap-docker.yml
spring:
application:
name: registry
cloud.config:
name: registry
uri: http://${CONFIG_HOST}:${CONFIG_PORT}
failFast: true
retry:
maxAttempts: 50
bootstrap-dev.yml
spring:
application:
name: registry
cloud.config:
name: registry
uri: http://localhost:2000
application.yml
eureka:
client:
register-with-eureka: false
fetch-registry: false
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our developpement environment
The above embedded configurations are the basic settings of the application: * it sets its name as a service (config) * it sets the configuration name to use (which configuration file to retrieve) * it must set the configuration service (example in bootstrap-docker.yml)
dev profile
dev is the profile we use internally for developpement we make it available for external developers so that they don’t need extensive configuration to get a jar working in the development environment
server:
port: 2001
eureka:
instance.hostname: localhost
client.serviceUrl.defaultZone: http://localhost:2001/eureka/
Sample development configuration
server:
port: 2001
eureka:
instance.hostname: localhost
client.serviceUrl.defaultZone: http://localhost:2001/eureka/
Sample docker image configuration
eureka:
instance.hostname: registry
client:
serviceUrl.defaultZone: http://registry:8080/eureka/
registerWithEureka: false
fetchRegistry: false
server:
waitTimeInMsWhenSyncEmpty: 0
Specifying external configuration properties when lauching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when lauching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writting, you cannot specify an alternate profile at runtime. The default profiles activated are docker and native.
Available environment variables for docker image
-
CONFIG_HOST: Configuration service host
-
CONFIG_PORT: Configuration service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when lauching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
CONFIG_HOST: Configuration service host
-
CONFIG_PORT: Configuration service port
-
JAVA_OPTIONS: Additional java options
18.4.7. Thirds Business service
OperatorFabric Thirds Business service is a Spring MVC application bootstrapped using SpringBoot.
In our spring micro service architecture this service depends on Eureka Registry.
Mandatory configuration, Profiles and default properties
The service has no mandatory configuration beside global configuration and usual bootstrap configuration.
For other configuration see:
Service specific properties
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.thirds.storage.path |
null |
no |
File path to data storage folder |
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: thirds
cloud:
config:
name: thirds
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: thirds
cloud:
config:
name: thirds
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: thirds
cloud:
config:
name: thirds
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
service-url:
defaultZone: 'http://localhost:2001/eureka'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample development configuration
server:
port: 2100
operatorfabric.thirds:
storage:
path: "./services/core/thirds/build/docker-volume/thirds-storage"
Sample docker image configuration
operatorfabric.thirds:
storage:
path: "/thirds-storage"
Specifying external configuration properties when launching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when launching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writing, you cannot specify an alternate profile at runThirds. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when launching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.4.8. Users Business service
OperatorFabric Users Business service is a Spring MVC application bootstrapped using SpringBoot.
In our spring micro service architecture this service depends on Eureka Registry.
Mandatory configuration, Profiles and default properties
The service has no mandatory configuration beside global configuration and usual bootstrap configuration.
For other configuration see:
Service specific properties
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.users.default.users |
null |
no |
Array of user objects to create upon startup if they don’t exist |
operatorfabric.users.default.user-settings |
null |
no |
Array of user settings objects to create upon startup if they don’t exist |
operatorfabric.users.default.groups |
null |
no |
Array of group objects to create upon startup if they don’t exist |
operatorfabric.users.default.entities |
null |
no |
Array of entity objects to create upon startup if they don’t exist |
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: users
cloud:
config:
name: users
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: users
cloud:
config:
name: users
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: users
cloud:
config:
name: users
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
service-url:
defaultZone: 'http://localhost:2001/eureka'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment.
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample development configuration
server:
port: 2103
operatorfabric.users.default:
users:
- login: admin
groups: ["ADMIN"]
entities: ["ENTITY1","ENTITY2"]
- login: rte-operator
groups: ["RTE","ADMIN","TRANS"]
- login: tso1-operator
groups: ["TSO1","TRANS"]
entities: ["ENTITY1"]
- login: tso2-operator
groups: ["TSO2", "TRANS"]
entities: ["ENTITY2"]
groups:
- name: ADMIN
description: The admin group
- name: RTE
description: RTE TSO Group
- name: TSO1
description: TSO 1 Group
- name: TSO2
description: TSO 2 Group
- name: TRANS
description: Transnationnal Group
entities:
- id: ENTITY1
name: Entity 1 name
description: Entity 1 short description
- id: ENTITY2
name: Entity 2 name
description: Entity 2 short description
user-settings:
- login: rte-operator
description: Da Operator Rulez
#logging.level.root: DEBUG
Sample docker image configuration
operatorfabric.users.default:
users:
- login: admin
groups: ["ADMIN"]
entities: ["ENTITY1","ENTITY2"]
- login: rte-operator
groups: ["RTE","ADMIN","TRANS"]
- login: tso1-operator
groups: ["TSO1","TRANS"]
entities: ["ENTITY1"]
- login: tso2-operator
groups: ["TSO2", "TRANS"]
entities: ["ENTITY2"]
groups:
- name: ADMIN
description: The admin group
- name: RTE
description: RTE TSO Group
- name: TSO1
description: TSO 1 Group
- name: TSO2
description: TSO 2 Group
- name: TRANS
description: Transnationnal Group
entities:
- id: ENTITY1
name: Entity 1 name
description: Entity 1 short description
- id: ENTITY2
name: Entity 2 name
description: Entity 2 short description
Specifying external configuration properties when launching a jar file
See Application Property Files on how to set up an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when launching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writing, you cannot specify an alternate profile at runUsers. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when launching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.4.9. Web UI
OperatorFabric Web UI service is built on top of a NGINX server. Its sole purpose is to serve the Angular SPA to browsers.
NGINX configuration
The NGINX configuration used is the NGINX default one.
Please refer to the NGINX documentation for more details for any required customisations.
Service specific properties
name | default | mandatory? | Description |
---|---|---|---|
operatorfabric.security.realm-url |
yes |
The realm name in keycloak server settings page. This is used for the log out process to know which realm should be affected. |
|
operatorfabric.security.provider-url |
yes |
The keycloak server instance |
|
operatorfabric.security.logout-url |
yes |
The keycloak logout URL. Is a composition of: - Your keycloak instance and the auth keyword (ex: www.keycloakurl.com/auth), but we also support domains without auth (ex: www.keycloakurl.com/customPath) - The realm name (Ex: dev) - The redirect URL (redirect_uri): The redirect URL after success authentification |
|
operatorfabric.security.oauth2.flow.mode |
PASSWORD |
no |
authentication mode, awailable options:
|
operatorfabric.security.oauth2.flow.provider |
null |
no |
provider name to display on log in button |
operatorfabric.security.oauth2.flow.delegate-url |
null |
no |
Url to redirect the browser to for authentication. Mandatory with:
|
operatorfabric.feed.subscription.timeout |
60000 |
no |
Milliseconds between card subscription renewal |
operatorfabric.feed.card.time.display |
BUSINESS |
no |
card time display mode in the feed. Values :
|
operatorfabric.feed.timeline.hide |
false |
no |
If set to true, the time line is not loaded in the feed screen |
operatorfabric.feed.notify |
false |
no |
If set to true, new cards are notified in the OS through web-push notifications |
operatorfabric.playSoundForAlarm |
false |
no |
If set to true, a sound is played when Alarm cards are added or updated in the feed |
operatorfabric.playSoundForAction |
false |
no |
If set to true, a sound is played when Action cards are added or updated in the feed |
operatorfabric.playSoundForCompliant |
false |
no |
If set to true, a sound is played when Compliant cards are added or updated in the feed |
operatorfabric.playSoundForInformation |
false |
no |
If set to true, a sound is played when Information cards are added or updated in the feed |
operatorfabric.i18n.supported.locales |
no |
List of supported locales (Only fr and en so far) |
|
operatorfabric.i10n.supported.time-zones |
no |
List of supported time zones, for instance 'Europe/Paris'. Values should be taken from the TZ database. |
|
operatorfabric.navbar.thirdmenus.type |
BOTH |
no |
Defines how thirdparty menu links are displayed in the navigation bar and how they open. Possible values:
|
operatorfabric.archive.filters.page.size |
no |
The page size of archive filters |
|
operatorfabric.archive.filters.page.first |
no |
The first page start of archiving module |
|
operatorfabric.archive.filters.process.list |
no |
List of processes to choose from in the corresponding filter in archives |
|
operatorfabric.archive.filters.tags.list |
no |
List of tags to choose from in the corresponding filter in archives |
|
operatorfabric.settings.tags.hide |
no |
Control if you want to show or hide the tags filter in settings and feed page |
|
operatorfabric.settings.nightDayMode |
false |
no |
if you want to activate toggle for night or day mode |
operatorfabric.settings.styleWhenNightDayModeDesactivated |
no |
style to apply if not using day night mode, possible value are DAY,NIGHT or LEGACY (black background and white timeline) |
|
operatorfabric.settings.infos.disable |
no |
Control if we want to disable/enable editing user email, description in the settings page |
|
operatorfabric.settings.infos.email |
false |
no |
Control if we want to hide(true) or display(false or not specified) the user email in the settings page |
operatorfabric.settings.infos.description |
false |
no |
Control if we want to hide(true) or display(false or not specified) the user description in the settings page |
operatorfabric.settings.infos.language |
false |
no |
Control if we want to hide(true) or display(false or not specified) the language in the settings page |
operatorfabric.settings.infos.timezone |
false |
no |
Control if we want to hide(true) or display(false or not specified) the timezone in the settings page |
operatorfabric.settings.infos.timeformat |
false |
no |
Control if we want to hide(true) or display(false or not specified) the timeformat in the settings page |
operatorfabric.settings.infos.dateformat |
false |
no |
Control if we want to hide(true) or display(false or not specified) the dateformat in the settings page |
operatorfabric.settings.infos.datetimeformat |
false |
no |
Control if we want to hide(true) or display(false or not specified) the datetimeformat in the settings page |
operatorfabric.settings.infos.tags |
false |
no |
Control if we want to hide(true) or display(false or not specified) the tags in the settings page |
operatorfabric.settings.infos.sounds |
false |
no |
Control if we want to hide(true) or display(false or not specified) the checkboxes for sound notifications in the settings page |
operatorfabric.settings.about |
|
no |
Declares application names and their version into web-ui about section. |
operatorfabric.logo.base64 |
medium OperatorFabric icon |
no |
The encoding result of converting the svg logo to Base64, use this online tool to encode your svg. If it is not set, a medium (32px) OperatorFabric icon is displayed. |
operatorfabric.logo.height |
32 |
no |
The height of the logo (in px) (only taken into account if operatorfabric.logo.base64 is set). |
operatorfabric.logo.width |
150 |
no |
The width of the logo (in px) (only taken into account if operatorfabric.logo.base64 is set). |
operatorfabric.logo.limitSize |
true |
no |
If it is true, the height limit is 32(px) and the width limit is 200(px), it means that if the height is over than 32, it will be set to 32, if the width is over than 200, it is set to 200. If it is false, no limit restriction for the height and the width. |
operatorfabric.title |
OperatorFabric |
no |
Title of the application, displayed on the browser |
User Settings default values
name |
default |
mandatory? |
Description |
operatorfabric.settings.timeZone |
no |
Default user time zone for users (use |
|
operatorfabric.settings.timeFormat |
LT |
no |
Default user time format (moment) |
operatorfabric.settings.dateFormat |
LL |
no |
Default user date format (moment) |
operatorfabric.settings.dateTimeFormat |
LL LT |
no |
Default user date format (moment) |
operatorfabric.settings.locale |
en |
no |
Default user locale (use en if not set) |
operatorfabric.settings.default-tags |
no |
Default user list of filtered in tags |
default properties
Note that you must provide a bootstrap file with a convenient registry configuration
bootstrap.yml
spring:
application:
name: web-ui
cloud:
config:
name: web-ui
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
bootstrap-docker.yml
spring:
application:
name: web-ui
cloud:
config:
name: web-ui
failFast: true
retry:
maxAttempts: 20
discovery:
service-id: config
enabled: true
# level.root: debug
eureka:
client:
registerWithEureka: true
fetchRegistry: true
registryFetchIntervalSeconds: 5
service-url:
defaultZone: 'http://${REGISTRY_HOST}:${REGISTRY_PORT}/eureka/'
bootstrap-dev.yml
spring:
application:
name: web-ui
cloud:
config:
name: web-ui
fail-fast: true
retry:
max-attempts: 20
discovery:
service-id: config
enabled: true
eureka:
client:
service-url:
defaultZone: 'http://localhost:2001/eureka'
The bootstrap-docker.yml file is a replacement bootstrap file we use for our docker images configuration.
The bootstrap-dev.yml file is a replacement bootstrap file we use for our development environment
The above embedded configurations are the basic settings of the application:
-
it sets its service name
-
it sets the configuration name to use (which configuration file to retrieve)
-
it must set the registry service (example in bootstrap-docker.yml)
Sample development configuration
server:
port: 2200
operatorfabric:
security:
provider-url: http://localhost:89
provider-realm: dev
logout-url: ${operatorfabric.security.provider-url}/auth/realms/${operatorfabric.security.provider-realm}/protocol/openid-connect/logout?redirect_uri=http://localhost:2002/ui/
oauth2:
flow:
mode: CODE
provider: Opfab Keycloak
delagate-url: ${operatorfabric.security.provider-url}/auth/realms/${operatorfabric.security.provider-realm}/protocol/openid-connect/auth?response_type=code&client_id=opfab-client
feed:
subscription:
timeout: 600000
card:
time:
display: BUSINESS
timeline:
domains:
- "TR"
- "J"
- "7D"
- "W"
- "M"
- "Y"
notify: false
archive:
filters:
page.size:
- "10"
page.first:
- "0"
publisher.list:
- value: "TEST"
label: "Test Publisher"
- value: "TEST2"
label: "Test Publisher 2"
process.list:
- process
- someOtherProcess
tags.list:
- value: "tag1"
label: "Label for tag 1"
- value: "tag2"
label: "Label for tag 2"
i10n.supported.time-zones:
- value: "Europe/Paris"
label: "Headquarters timezone"
- value: "Australia/Melbourne"
label: "Down Under"
- Europe/London
- Europe/Dublin
- Europe/Brussel
- Europe/Berlin
- Europe/Rome
- Europe/Madrid
- Europe/Lisbon
- Europe/Amsterdam
- Europe/Athens
- Pacific/Samoa
i18n.supported.locales:
- en
- fr
settings:
locale: en
nightDayMode: true
infos:
description: true
about:
firstapplication:
name: First application
version: v12.34.56
rank: 1
keycloack:
name: Keycloak
version: 6.0.1
rank: 2
lastapplication:
name: Wonderful Solution
version: 0.1.2-RELEASE
Sample docker image configuration
server:
port: 2200
operatorfabric:
security:
provider-url: http://localhost:89
provider-realm: dev
logout-url: ${operatorfabric.security.provider-url}/auth/realms/${operatorfabric.security.provider-realm}/protocol/openid-connect/logout?redirect_uri=http://localhost:2002/ui/
oauth2:
flow:
mode: CODE
provider: Opfab Keycloak
delagate-url: ${operatorfabric.security.provider-url}/auth/realms/${operatorfabric.security.provider-realm}/protocol/openid-connect/auth?response_type=code&client_id=opfab-client
feed:
subscription:
timeout: 600000
card:
time:
display: BUSINESS
timeline:
domains:
- "TR"
- "J"
- "7D"
- "W"
- "M"
- "Y"
notify: false
archive:
filters:
page.size:
- "10"
page.first:
- "0"
publisher.list:
- value: "TEST"
label: "Test Publisher"
- value: "TEST2"
label: "Test Publisher 2"
process.list:
- process
- someOtherProcess
tags.list:
- value: "tag1"
label: "Label for tag 1"
- value: "tag2"
label: "Label for tag 2"
i10n.supported.time-zones:
- value: "Europe/Paris"
label: "Headquarters timezone"
- value: "Australia/Melbourne"
label: "Down Under"
- Europe/London
- Europe/Dublin
- Europe/Brussel
- Europe/Berlin
- Europe/Rome
- Europe/Madrid
- Europe/Lisbon
- Europe/Amsterdam
- Europe/Athens
- Pacific/Samoa
i18n.supported.locales:
- en
- fr
settings:
locale: en
nightDayMode: true
infos:
description: true
about:
firstapplication:
name: First application
version: v12.34.56
rank: 1
keycloack:
name: Keycloak
version: 6.0.1
rank: 2
lastapplication:
name: Wonderful Solution
version: 0.1.2-RELEASE
Specifying external configuration properties when lauching a jar file
See Application Property Files on how to setup an external spring properties or yml file.
See Set the Active Spring Profiles for specifying alternate profile.
Specifying configuration properties when lauching a docker image
Our docker image expects optional property file to be stored in the container /service-config folder. You can bind so docker volume to this path to make properties or yml available.
At time of writing, you cannot specify an alternate profile at runCards-Publication. The default profiles activated are docker and native.
Available environment variables for docker image
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
Specifying configuration properties when lauching on Kubernetes
In progress
Available environment variables when launching on Kubernetes
-
REGISTRY_HOST: Registry service host
-
REGISTRY_PORT: Registry service port
-
JAVA_OPTIONS: Additional java options
18.5. Users, Groups and Entities Administration
A new operator call John Doe, who has OAuth granted right to connect ot current OperatorFabric
instance, need to receive cards within current OperatorFabric
instance. As a user of OperatorFabric, he needs to be added to the system with a login
(john-doe-operator), his firstName
(John) and his lastName
(Doe).
operator
As there is no Administration GUI
for the moment, it must be performed through command line, as detailed in the Users API.
18.5.1. List all users
First of all, list the users (who are the recipients in OperatorFabric) of the system with the following commands:
Httpie
http http://localhost:2103/users "Authorization:Bearer $token" "Content-Type:application/type"
cURL
curl -v http://localhost:2103/users -H "Authorization:Bearer $token" -H "Content-Type:application/type"
response
HTTP/1.1 200 OK [ { "firstName": null, "groups": [ "ADMIN" ], "entities": [ "ENTITY1", "ENTITY2" ], "lastName": null, "login": "admin" }, { "firstName": null, "groups": [ "RTE", "ADMIN", "CORESO", "TRANS", "TEST" ], "lastName": null, "login": "rte-operator" }, { "firstName": null, "groups": [ "ELIA" ], "lastName": null, "login": "elia-operator" }, { "firstName": null, "groups": [ "CORESO" ], "lastName": null, "login": "coreso-operator" }, { "firstName": null, "groups": [ "TSO1", "TRANS", "TEST" ], "entities": [ "ENTITY1" ], "lastName": null, "login": "tso1-operator" }, { "firstName": null, "groups": [ "TSO2", "TRANS" ], "entities": [ "ENTITY2" ], "lastName": null, "login": "tso2-operator" }, ]
18.5.2. Create a new User
We are sure that no John-doe-operator exists in our OperatorFabric instance. We can add him in our OperatorFabric instance using the following command use httpie:
echo '{"login":"john-doe-operator","firstName":"Jahne","lastName":"Doe"}' | http POST http://localhost:2103/users "Authorization:Bearer $token" "Content-Type:application/json"
Or here cURL:
curl -X POST http://localhost:2103/users -H "Authorization:Bearer $token" -H "Content-Type:application/json" --data '{"login":"john-doe-operator","firstName":"Jahne","lastName":"Doe"}'
response
HTTP/1.1 200 OK { "firstName": "Jahne", "lastName": "Doe", "login": "john-doe-operator" }
18.5.3. Fetch user details
It’s always a good thing to verify if all the information has been correctly recorded in the system:
with httpie:
http -b http://localhost:2103/users/john-doe-operator "Authorization:Bearer $token" "Content-Type:application/json"
or with cURL:
curl http://localhost:2103/users/john-doe-operator -H "Authorization:Bearer $token" -H "Content-Type:application/json"
response
HTTP/1.1 200 OK { "firstName": "Jahne", "groups": [], "entities": [], "lastName": "Doe", "login": "john-doe-operator" }
18.5.4. Update user details
As shown by this result, the firstName of the new operator has been misspelled.We need
to update the existing user
with john-doe-operator
login. To correct this mistake, the following commands can be used :
with httpie:
echo '{"login":"john-doe-operator","lastName":"Doe","firstName":"John"}' | http PUT http://localhost:2103/users/john-doe-operator "Authorization:Bearer $token" "Content-Type:application/json"
or with cURL:
curl -X PUT http://localhost:2103/users/john-doe-operator -H "Authorization:Bearer $token" -H "Content-Type:application/json" --data '{"login":"john-doe-operator","firstName":"John","lastName":"Doe"}'
response
HTTP/1.1 200 OK { "firstName": "John", "lastName": "Doe", "login": "john-doe-operator" }
18.6. Groups/Entities
All the commands below :
-
List groups
-
Create a new group
-
Fetch details of a given group
-
Update details of a group
-
Add a user to a group
-
Remove a user from a group
are available for both groups and entities. In order not to overload the documentation, we will only detail groups endpoints.
18.6.1. List groups (or entities)
This operator is the first member of a new group operator called the OPERATORS
, which doesn’t exist for the moment in
the system. As shown when we
list the groups
existing in the server.
Httpie
http http://localhost:2103/groups "Authorization:Bearer $token" "Content-Type:application/type"
cURL
curl http://localhost:2103/groups -H "Authorization:Bearer $token" -H "Content-Type:application/json"
response
HTTP/1.1 200 OK [ { "description": "The admin group", "name": "ADMIN group", "id": "ADMIN" }, { "description": "RTE TSO Group", "name": "RTE group", "id": "RTE" }, { "description": "ELIA TSO group", "name": "ELIA group", "id": "ELIA" }, { "description": "CORESO Group", "name": "CORESO group", "id": "CORESO" }, { "description": "TSO 1 Group", "name": "TSO1 group", "id": "TSO1" }, { "description": "TSO 2 Group", "name": "TSO2 group", "id": "TSO2" }, { "description": "Transnationnal Group", "name": "TRANS group", "id": "TRANS" } ]
18.6.2. Create a new group (or entity)
Firstly, the group called OPERATORS
has to be
added to the system
using the following command:
using httpie:
echo '{"id":"OPERATORS","decription":"This is the brand new group of operator"}' | http POST http://localhost:2103/groups "Authorization:Bearer $token" "Content-Type:application/json"
using cURL:
curl -X POST http://localhost:2103/groups -H "Authorization:Bearer $token" -H "Content-Type:application/json" --data '{"id":"OPERATORS","decription":"This is the brand new group of operator"}'
response
HTTP/1.1 200 OK { "description": null, "name": null, "id": "OPERATORS" }
18.6.3. Fetch details of a given group (or entity)
The result returned seems strange, to verify if it’s the correct answer by
displaying the details of the group
called OPERATORS
, use the following command:
using httpie:
http http://localhost:2103/groups/OPERATORS "Authorization:Bearer $token" "Content-Type:application/json"
using cURL:
curl http://localhost:2103/groups/OPERATORS -H "Authorization:Bearer $token" -H "Content-Type:application/json"
response
HTTP/1.1 200 OK { "description": null, "name": null, "id": "OPERATORS" }
18.6.4. Update details of a group (or entity)
The description is really null. After verification, in our first command used to create the group, the attribute for the description is misspelled. Using the following command to update the group with the correct spelling, the new group of operator gets a proper description:
with httpie:
echo '{"id":"OPERATORS","description":"This is the brand-new group of operator"}' | http -b PUT http://localhost:2103/groups/OPERATORS "Authorization:Bearer $token" "Content-Type:application/json"
with cURL:
curl -X PUT http://localhost:2103/groups/OPERATORS -H "Authorization:Bearer $token" -H "Content-Type:application/json" --data '{"id":"OPERATORS","description":"This is the brand-new group of operator"}'
response
{ "description": "This is the brand-new group of operator", "name": null, "id": "OPERATORS" }
18.6.5. Add a user to a group (or entity)
As both new group and new user are correct it’s time to make the user a member of the group . To achieve this, use the following command:
with httpie:
echo '["john-doe-operator"]' | http PATCH http://localhost:2103/groups/OPERATORS/users "Authorization:Bearer $token" "Content-Type:application/json"
with cURL:
curl -X PATCH http://localhost:2103/groups/OPERATORS/users -H "Authorization:Bearer $token" -H "Content-Type:application/json" --data '["john-doe-operator"]'
response
HTTP/1.1 200 OK
Let’s verify that the changes are correctly recorded by fetching the :
http http://localhost:2103/users/john-doe-operator "Authorization:Bearer $token" "Content-Type:application/json"
with cURL
curl http://localhost:2103/users/john-doe-operator -H "Authorization:Bearer $token" -H "Content-Type:application/json"
response
HTTP/1.1 200 OK { "firstName": "John", "groups": ["OPERATORS"], "entities": [], "lastName": "Doe", "login": "john-doe-operator" }
It’s now possible to send cards either specifically to john-doe-operator
or more generally to the OPERATORS
group.
18.6.6. Remove a user from a group (or entity)
When John Doe is no longer in charge of hypervising cards for OPERATORS
group, this group has to be removed from his login by using the following command:
with httpie:
http DELETE http://localhost:2103/groups/OPERATORS/users/john-doe-operator "Authorization:Bearer $token"
with cURL:
curl -X DELETE -H "Authorization:Bearer $token" http://localhost:2103/groups/OPERATORS/users/john-doe-operator
response
HTTP/1.1 200 OK { "login":"john-doe-operator"," firstName":"John", "lastName":"Doe", "groups":[], "entities":[] }
A last command to verify that OPERATORS
is no longer linked to john-doe-operator
:
with httpie:
http http://localhost:2103/users/john-doe-operator "Authorization:Bearer $token" "Content-Type:application/json"
with cURL:
curl http://localhost:2103/users/john-doe-operator -H "Authorization:Bearer $token" -H "Content-Type:application/json"
response
HTTP/1.1 200 OK { "firstName": "John", "groups": [], "entities": [], "lastName": "Doe", "login": "john-doe-operator" }
19. 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, the run_all.sh
script or the deploy docker-compose,
the used ports are:
Port | Service | Forwards to | Description |
---|---|---|---|
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 |
Cards publication service http (REST) |
2103 |
users |
8080 |
Users management service http (REST) |
2104 |
cards-consultation |
8080 |
Cards consultation service http (REST) |
2105 |
actions |
8080 |
Actions service http (REST) |
2200 |
web-ui |
8080 |
Web UI (Nginx server) |
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 |
27017 |
mongo |
27017 |
mongo api port |
5672 |
rabbitmq |
5672 |
amqp api port |
15672 |
rabbitmq |
15672 |
rabbitmq api port |
20. Restricted operations (administration)
Some operations are restricted to users with the ADMIN role, either because they are administration operations with the potential to impact the OperatorFabric instance as a whole, or because they give access to information that should be private to a user.
Below is a quick recap of these restricted operations.
Any action (read, create/update or delete) regarding a single user’s data (their personal info such as their first and last name, as well as their settings) can be performed either by the user in question or by a user with the ADMIN role.
Any action on a list of users or on the groups (or entities) (if authorization is managed in OperatorFabric) can only be performed by a user with the ADMIN role.
Any write (create, update or delete) action on bundles can only be performed by a user with the ADMIN role. As such, administrators are responsible for the quality and security of the provided bundles. In particular, as it is possible to use scripts in templates, they should perform a security check to make sure that there is no XSS risk.
The ADMIN role doesn’t grant any special privileges when it comes to card consultation (be they current or archived), so a user with the ADMIN role will only see cards that have been addressed to them (or to one of their groups (or entities)), just like any other user. |
Development environment
21. Requirements
This section describes the projects requirements regardless of installation options. Please see Setting up your environment ifndef::single-page-doc[Setting up your environment] below for details on:
-
setting up a development environment with these prerequisites
-
building and running OperatorFabric
21.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)
the current Jdk used for the project is Java 8.0.242-zulu. |
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):
source bin/load_environment_light.sh
21.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
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 |
21.3. Browser support
We currently use Firefox (63.0.3). Automatic tests for the UI rely on Chrome (73.0.3683.86).
22. Setting up your development environment
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.
If you encounter any issue, see Troubleshooting below. In particular, a command that hangs then fails is often a proxy issue. |
The following steps describe how to launch MongoDB, RabbitMQ and Keycloak
using Docker, build OperatorFabric using gradle and run it using the
run_all.sh
script.
22.1. Clone repository
git clone https://github.com/opfab/operatorfabric-core.git
cd operatorfabric-core
22.2. Set up your environment (environment variables & appropriate versions of gradle, maven, etc…)
source bin/load_environment_light.sh
From now on, you can use environment variable ${OF_HOME} to go back to
the home repository of OperatorFabric .
|
22.3. Deploy needed docker containers
22.3.1. Minimal configuration for gradle
build
Two docker container must be available during a gradle build of OperatorFabric
:
* RabbitMQ;
* MongoDB.
They can be launch using the ${OF_HOME}/src/main/docker/test-environment/docker-compose.yml
.
Remind that, during a gradle build, before the assemble
task, the test
one is called. The Unit tests depend on those
two software.
22.3.2. Enabling local quality report generation
To get a Sonarqube report, in addition to the two previously listed docker containers, a SonarQube
docker container is
required. Use the ${OF_HOME}/src/main/docker/test-quality-environment/docker-compose.yml
to get them all running.
To generate the quality report use the following command:
---
cd ${OF_HOME}
./gradlew jacocoTestReport
---
To export the different report into the SonarQube
docker instance you need to install and use SonarScanner.
22.3.3. Development environment
During OperatorFabric
development the running docker images of MongoDB
, RabbitMQ
, web-ui
and Keycloak
are needed.
The docker-compose
can be run in detached mode:
cd ${OF_HOME}/src/main/docker/dev-environment/
docker-compose up -d
The configuration of the web-ui
embeds a grayscale favicon which can be usefull to spot the OperatorFabric
dev tab in the browser.
Sometime a CTRL+F5
on the tab is required to refresh the favicon.
22.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}
docker-compose -f ${OF_HOME}/src/main/docker/test-environment/docker-compose.yml up -d
./gradlew build
22.5. Run OperatorFabric Services using the run_all.sh
script
cd ${OF_HOME}
docker-compose -f ${OF_HOME}/src/main/docker/dev-environment/docker-compose.yml up -d
bin/run_all.sh start
the ${OF_HOME}/bin/run_all.sh must be launched from ${OF_HOME} otherwise some runtime exception will occur.
|
See bin/run_all.sh -h for details.
|
22.6. Check services status
cd ${OF_HOME}
bin/run_all.sh status
22.7. Log into the UI
URL: localhost:2002/ui/
login: tso1-operator
password: test
The other users available in development mode are rte-operator
and admin
, both with test
as password.
It might take a little while for the UI to load even after all services are running. |
Don’t forget the final slash in the URL or you will get an error, a 404 page.
|
22.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
23. User Interface
The Angular CLI version 6.0.8 has been used to generate this project.
In the following document the variable declared as OF_HOME is the root folder of the operatorfabric-core project .
|
CLI |
stands for Command Line Interface |
SPA |
stands for Single Page Application |
23.1. Run
23.1.1. Linux
After launching docker containers, use the following command line $OF_HOME/bin/run_all.sh start
to run the application.
Once the whole application is ready, you should have the following output in your terminal:
##########################################################
Starting client-gateway-cloud-service, debug port: 5008
##########################################################
pid file: $OF_HOME/services/infra/client-gateway/build/PIDFILE
Started with pid: 7479
##########################################################
Starting users-business-service, debug port: 5009
##########################################################
pid file: $OF_HOME/services/core/users/build/PIDFILE
Started with pid: 7483
##########################################################
Starting cards-consultation-business-service, debug port: 5011
##########################################################
pid file: $OF_HOME/services/core/cards-consultation/build/PIDFILE
Started with pid: 7493
##########################################################
Starting cards-publication-business-service, debug port: 5012
##########################################################
pid file: $OF_HOME/services/core/cards-publication/build/PIDFILE
Wait a moment before trying to connect to the`SPA`, leaving time for the`client-gateway` to boot up completely.
The SPA
, on a local machine, is available at the following Url: localhost:2002/ui/
.
To log in you need to use a valid user among the following: tso1-operator
, rte-operator
or admin
.
The common password is test
for them all.
To test the reception of cards, you can use the following script to create dummy cards:
${OF_HOME}/services/core/cards-publication/src/main/bin/push_cards_loop.sh
Once logged in, with that script running in the background, you should be able to see some cards displayed in localhost:2002/ui/feed
.
23.2. Build
Run ng build
to build the project. The build artifacts will be stored in :
${OF_HOME}/ui/main/build/distribution
23.3. Test
23.3.1. Standalone tests
23.3.2. Test during UI development
-
if the RabbitMQ, MongoDB and Keycloak docker containers are not running, launch them;
-
set your environment variables with
source ${OF_HOME}/bin/load_environment_light.sh
; -
run the micro services using the same command as earlier:
${OF_HOME}/bin/run_all.sh start
; -
if needed, enable a card-operation test flow using the script
${OF_HOME}/service/core/cards-publication/src/main/bin/push_cards_loop.sh
; -
launch an angular server with the command:
ng serve
; -
test your changes in your browser using this url:
localhost:4200
which leads tolocalhost:4200/#/feed
.
24. 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
-
25. Project Structure
25.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-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
25.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
-
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-ui: project based on Nginx server to serve the OperatorFabric UI
-
-
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
25.3. Conventions regarding project structure and configuration
Sub-projects must conform to a few rules in order for the configured Gradle tasks to work:
25.3.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 |
25.3.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 |
25.3.3. Docker
Services project all have docker image generated in their build cycle. See Gradle Tasks for details.
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.
26. Development tools
26.1. 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 |
bin/run_all.sh |
runs all all services (see below) |
bin/setup_dockerized_environment.sh |
generate docker images for all services |
26.1.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
Never ever run a gradle clean or ./gradlew clean to avoid deleting those links.
|
26.1.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).
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
Ports configuration
Port
26.1.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.
26.2. Gradle 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.
26.2.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
-
Thirds 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
-
26.2.2. Gradle Plugins
In addition to these custom tasks and standard Gradle tasks, OperatorFabric uses several Gradle plugins, among which:
27. Useful recipes
27.1. Running sub-project from jar file
-
gradle :[sub-projectPath]:bootJar
-
or java -jar [sub-projectPath]/build/libs/[sub-project].jar
27.2. 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
-
27.3. 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[somewhere:3128]" (defaults to blank)
-
apk.proxy.httpsuri: proxy http uri ex: "http://somewhere:3128[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
28. Troubleshooting
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:
Proxy error when running third-party docker-compose
Pulling rabbitmq (rabbitmq:3-management)...
ERROR: Get https://registry-1.docker.io/v2/: Proxy Authentication Required
HTTP_PROXY=http://user:password@proxy.example.com:80/
The password should be URL-encoded.
Gradle task (for example gradle build) fails with the following error: Issue with the Gradle daemon. Stopping the daemon using
Gradle Metaspace error
* What went wrong:
Metaspace
gradle --stop
and re-launching the build should solve this issue.
Select the next available version and update
load_environment_light accordingly before
sourcing it again. 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
Java version not available when setting up environment
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
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
================================================================================
A
BUILD FAILED with message
Execution failed for task ':ui:main-user-interface:npmInstall'.
FAILURE: Build failed with an exception.
What went wrong:
Execution failed for task ':ui:main-user-interface:npmInstall'.
sudo
has been used before the ./gradlew assemble
.
Don’t use sudo to build OperatorFabric otherwise unexpected problems could arise.
29. Keycloak Configuration
The configuration needed for development purposes is automatically loaded from the dev-realms.json file. However, the steps below describe how they can be reproduced from scratch on a blank Keycloak instance in case you want to add to it.
The Keycloak Management interface is available here: [host]:89/auth/admin Default credentials are admin/admin.
29.1. Add Realm
-
Click top left down arrow next to Master
-
Add Realm
-
Name it dev (or whatever)
29.2. Setup at least one client (or best one per service)
29.2.1. Create client
-
Click Clients in left menu
-
Click Create Button
-
Set client ID to "opfab-client" (or whatever)
-
Select Openid-Connect Protocol
-
Enable Authorization
-
Access Type to Confidential
-
save
29.2.2. Add a Role to Client
-
In client view, click Roles tab
-
Click Add button
-
create a USER role (or whatever)
-
save == create a Mapper
Used to map the user name to a field that suits services
-
name it sub
-
set mapper type to User Property
-
set Property to username
-
set Token claim name to sub
-
enable add to access token
-
save
29.3. Create Users
-
Click Users in left menu
-
Click Add User button
-
Set username to admin
-
Save
-
Select Role Mappings tab
-
Select "opfab-client" in client roles combo (or whatever id you formerly chose)
-
Select USER as assigned role (or whatever role you formerly created)
-
Select Credentials tab
-
set password and confirmation to "test" *
repeat process for other users: rte-operator, tso1-operator, tso2-operator
29.3.1. Development-specific configuration
To facilitate development, in the configuration file provided in the git (dev-realms.json) ,session are set to have a duration of 10 hours (36000 seconds) and SSL is not required. These parameters should not be used in production.
The following parameters are set : accessTokenLifespan : 36000 ssoSessionMaxLifespan : 36000 accessCodeLifespan" : 36000 accessCodeLifespanUserAction : 36000 sslRequired : none
OperatorFabric Community
The aim of this document is to present the OperatorFabric community, its code of conduct and to welcome contributors!
First of all, thank you for your interest !
We can’t stress enough that feedback, discussions, questions and contributions on OperatorFabric are very much appreciated. However, because the project is still in its early stages, we’re not fully equipped for any of it yet, so please bear with us while the contribution process and tooling are sorted out.
This project and everyone participating in it is governed by the OperatorFabric Code of Conduct . By participating, you are expected to uphold this code. Please report unacceptable behavior to opfab_AT_lists.lfenergy.org.
30. License and Developer Certificate of Origin
OperatorFabric is an open source project licensed under the Mozilla Public License 2.0. By contributing to OperatorFabric, you accept and agree to the terms and conditions for your present and future contributions submitted to OperatorFabric.
The project also uses a mechanism known as a Developer Certificate of Origin (DCO) to ensure that we are legally allowed to distribute all the code and assets for the project. A DCO is a legally binding statement that asserts that you are the author of your contribution, and that you wish to allow OperatorFabric to use your work.
Contributors sign-off that they adhere to these requirements by adding a Signed-off-by
line to commit messages. All
commits to any repository of the OperatorFabric organization have to be signed-off like this:
This is my commit message. Signed-off-by: John Doe <john.doe@email-provider.com>
You can write it manually but Git has a -s command line option to append it automatically to your commit message:
$ git commit -s -m 'This is my commit message'
Note that in the future a check will be performed during the integration, making sure all commits in the Pull Request
contain a valid Signed-off-by
line.
These processes and templates have been adapted from the ones defined by the PowSyBl project.
31. Reporting Bugs and Suggesting Enhancements
Work in Progress
32. Contributing Code or Documentation
32.1. Code Guidelines
-
We don’t mention specific authors by name in each file (in Javadoc or in the documentation for example), so as not to have to maintain these mentions (since this information is tracked by git anyway).
-
If you are working on a JIRA issue:
-
Please name your branch with the corresponding JIRA issue ID: OC-XXX
-
Start all your commit messages with [OC-XXX]
This allows the branch, PR and commits to be directly accessible from the JIRA issue.
-
-
Before submitting your PR, please rebase your branch against the current master to minimize conflicts when merging.
git checkout OC-XXX git fetch git rebase origin/master
-
Before submitting your PR, please squash/fix your commits so as to reduce the number of commits and comment them accordingly. In the end, the division of changes into commits should make the PR easier to understand and review.
-
Feel free to add a copyright header (on top of the existing ones) to files you create or amend. See src/main/headers for examples.
32.2. Documentation Guidelines
The aim of this section is to explain how the documentation is currently organized and to give a few guidelines on how it should be written.
32.2.1. Structure
All the sources for the AsciiDoc documentation published on our website are found under the src/docs/asciidoc folder in the operatorfabric-core repository.
It is organized into several folders (architecture documentation, deployment documentation, etc.). Each of these folders represent a document and contain an index.adoc file, optionally referencing other adoc files (to break it down into sections).
In addition, an images folder contains images for all documents and a resources folder contains various appendices that might be of use to some people but that we felt weren’t part of the main documentation.
The table below gives a short summary of the content of each document as well as advice on which ones you should focus on depending on your profile.
Contributor |
A developer who contributes (or wishes to) to the OperatorFabric project |
Developer |
A developer working on an application using OperatorFabric or a third-party application posting content to an OperatorFabric instance |
Admin |
Someone who is in charge of deploying and maintaining OperatorFabric in production as part of an integrated solution |
Product Owner |
Project managers, anyone interested in using OperatorFabric for their business requirements. |
Folder | Content | Contributor | Developer | Admin | Product Owner |
---|---|---|---|---|---|
architecture |
Architecture documentation Describes the business objects and concepts handled by OperatorFabric as well as the microservices architecture behind it. |
Yes |
Yes |
Yes |
|
CICD |
CICD Pipeline documentation Describes our CICD pipeline and release process |
Yes |
|||
community |
OF Community documentation Everything about the OperatorFabric Community: Code of conduct, governance, contribution guidelines, communication channels. |
Yes |
|||
deployment |
Deployment documentation Explains how to deploy and configure an OperatorFabric instance |
Yes |
Yes |
Yes |
|
dev_env |
Development Environment documentation Explains how to set up a working development environment for OperatorFabric with all the appropriate tooling and how to run OperatorFabric in development mode. |
Yes |
|||
docs |
This folder contains the documentation that should be archived for previous releases (as of today, the release notes and single page documentation - see below). |
Yes |
Yes |
Yes |
Yes |
getting_started |
Getting Started Guide guides you through setting up OperatorFabric and experimenting with its main features |
Yes |
Yes |
Maybe |
|
reference_doc |
Reference Documentation contains the reference documentation for each microservice. It starts off with a high-level functional documentation and then goes into more technical details when needed. |
Yes |
Yes |
Yes |
In addition to this asciidoctor documentation, API documentation is available in the form of SwaggerUI-generated html
pages. It is generated by the generateSwaggerUI
Gradle task, using the swagger.yaml files from each service (for
example for the
Actions API
). It can be found under the build/docs/api folder for each client or service project.
32.2.2. Conventions
-
In addition to the "visible" structure described above, documents are broken down into coherent parts using the "include" feature of AsciiDoc. This is done mostly to avoid long files that are harder to edit, but it also allows us to reuse some content in different places.
-
Given the number of files this creates, we try to keep header attributes in files to a minimum. Instead, they’re set in the configuration of the asciidoctor gradle task:
build.gradleasciidoctor { sources { include '*/index.adoc','docs/*' } resources { from('src/docs/asciidoc') { include 'images/*' } } attributes nofooter : '', revnumber : operatorfabric.version, revdate : operatorfabric.revisionDate, sectnums : '', toc : 'left', toclevels : '3', icons : 'font', "hide-uri-scheme" : '', "source-highlighter": 'coderay' }
In particular, the version and revision date are set automatically from the version defined in the VERSION file at the root of the project and the current date.
-
All files are created starting with level 0 titles so:
-
They can be generated on their own if need be.
-
They can be included at different levels in different documents using leveloffset.
-
-
In addition to being available as separate documents (architecture, reference, etc.) for the current release, the documentation is also generated as a single page document available for all releases from the releases page. This is also a way to make searching the documentation for specific terms easier, and could be used to generate a single page pdf documentation.
-
Unfortunately, this entails a little complexity for cross-references and relative links, because the path to the content is a little different depending on whether the content is generated as different pages or as a single page document.
For example, to link to the "Card Structure" section of the reference document from the architecture document, one needs to use the following external cross-reference:
<<{gradle-rootdir}/documentation/current/reference_doc/index.adoc#card_structure, Card Structure>>
In the case of the single-page documentation however, both the architecture content and the reference content are part of the same document, so the cross-reference becomes a simple internal cross-reference:
<<card_structure, Card Structure>>
This is managed by using the
ifdef
andindef
directives to define which link syntax should be used:ifdef::single-page-doc[<<card_structure, Card Structure>>] ifndef::single-page-doc[<<{gradle-rootdir}/documentation/current/reference_doc/index.adoc#card_structure, Card Structure>>]
The label ("Card Structure" in this example) is defined with each link because it seems that defining it in the target file along with the ID ( [[my_section_id, text to display]]
) doesn’t work with relative links.In the same way, for relative links to external files (mostly the API documentation):
ifdef::single-page-doc[link:../api/cards/index.html#/archives[here]] ifndef::single-page-doc[link:{gradle-rootdir}/documentation/current/api/cards/index.html#/archives[here]]
For this to work, the single_page_doc.adoc file needs to have :single-page-doc:
as a header attribute. -
As you can see in the examples above, we are using custom-defined section ids as anchors rather than taking advantage of generated ones (see documentation). This is cumbersome but:
-
Generation will give a warning if duplicate ids are defined, whereas with generated ids it will silently link to the wrong section.
-
Restructuring the document might change the generated section ID, creating broken links.
-
Its easier to find referenced text (ctrl-f on id)
-
The presence of a custom-defined ID is a sign that the content is referenced somewhere else, which you should take into account if you’re thinking of deleting or moving this content.
-
-
The :imagesdir: attribute is set globally as
../images
, because all images are stored undersrc/docs/asciidoc/images
. -
In addition to links, it is sometimes necessary to display the actual content of files (or part of it) in the documentation (in the case of configuration examples, for instance). Whenever possible, this should be done by using the include directive rather than copying the content into the adoc file. This way the documentation will always be up to date with the file content at the time of generation.
See the build.gradle include above for an example using tags to include only part of a file.
-
Source-highlighting is done using Coderay. See their documentation for supported languages, and the AsciiDoctor documentation on how to apply source-highlighting.
-
Avoid long lines whenever possible (for example, try not to go beyond 120 characters). This makes editing the documentation easier and diffs more readable.
-
Most links to other OperatorFabric documents should be relative (see above) so they automatically point to the document in the same version rather than the latest version. Links starting with opfab.github.io/documentation/current/ should only be used when we want to always refer to the latest (release) version of the documentation.
32.3. Contribution Process
Code Contribution is tracked as GitHub Pull Requests. Crafting a good pull request takes time and energy and we will help as much as we can, but be prepared to follow our iterative process. The iterative process has several goals:
-
Maintain the quality of the project
-
Fix issues that are important to users
-
Allow everyone from the community to take part in the discussions, to reach the best possible solution
-
Make the review by OperatorFabric maintainers as efficient as possible
Please follow these steps to have your contribution considered by the maintainers:
-
Request a GitHub review by one of the core developers
-
Take their review into account or discuss the requested changes. Please don’t take criticism personally, it is normal to iterate on this step several times.
-
Repeat step 3 until the pull request is merged!
Continuous integration is set up to run on all branches automatically and will often report problems, so don’t worry about getting everything perfect on the first try (SonarCloud Analysis is a notorious problem source). Until you add a reviewer, you can trigger as many builds as you want by amending your commits. The status checks enforce the following:
-
All tests in the test suite pass
-
Checkstyle and SonarCloud report no violations (coming soon)
-
The code coverage is high enough (coming soon)
33. Project Governance
33.1. Project Owner
OperatorFabric is part of the LF Energy Foundation, a project of the Linux Foundation that supports open source innovation projects within the energy and electricity sectors.
33.2. Committers
Committers are contributors who have made several valuable contributions to the project and are now relied upon to both write code directly to the repository and screen the contributions of others. In many cases they are programmers but it is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the project, and will bring a level of expertise and understanding that earns them the respect of the community and the project owner.
33.3. Technical Steering Committee
The Technical Steering Committee (TSC) is composed of voting members elected by the active Committers as described in the project’s Technical Charter.
OperatorFabric TSC voting members are:
Boris Dolley will chair the TSC, with Hanae Safi as his deputy.
33.4. Contributors
Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the project.
Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements and no selection process. To become a contributor, a community member simply has to perform one or more actions that are beneficial to the project.
34. Communication channels
In addition to GitHub we have set up:
34.1. Website: opfab.org
Our website contains all the documentation and resources we’re currently working on. Here is what we aim to provide:
-
Architecture documentation
-
REST API documentation
-
Reference documentation for each component
-
Javadoc/Compodoc for each component
-
Tutorials and QuickStart guides and videos
This documentation is our priority right now so future contributors can quickly find their way around the project. Needless to say, it’s a work in progress so feel free to tell us what you feel is missing or what type of documentation you would be interested in as a contributor.
We also use this website to broadcast any news we have about the project so don’t hesitate to subscribe to the RSS feed on the home page to be informed of any update. |
34.2. Spectrum Community : spectrum.chat/opfab
If you would like to join the discussions regarding OperatorFabric, please join our community on Spectrum!
Regarding issue tracking, our Jira platform should be open soon.
34.3. LF Energy Mailing Lists
Several mailing lists have been created by LF Energy for the project, please feel free to subscribe to the ones you could be interested in:
-
OperatorFabric Announcements (such as new releases)
-
OperatorFabric Developers for project development discussions
And if you’re interested in LF Energy in general: LF Energy General Discussion
34.4. JIRA
35. Code of Conduct
The Code of Conduct for the OperatorFabric community is version 2.0 of the Contributor Covenant.
35.1. Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
35.2. Our Standards
Examples of behavior that contributes to a positive environment for our community include:
-
Demonstrating empathy and kindness toward other people
-
Being respectful of differing opinions, viewpoints, and experiences
-
Giving and gracefully accepting constructive feedback
-
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-
Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
-
The use of sexualized language or imagery, and sexual attention or advances of any kind
-
Trolling, insulting or derogatory comments, and personal or political attacks
-
Public or private harassment
-
Publishing others’ private information, such as a physical or email address, without their explicit permission
-
Other conduct which could reasonably be considered inappropriate in a professional setting
35.3. Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
35.4. Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
35.5. Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at opfab-tsc_AT_lists.lfenergy.org. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
Correction
- Community Impact
-
Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
- Consequence
-
A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
Warning
- Community Impact
-
A violation through a single incident or series of actions.
- Consequence
-
A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
Temporary Ban
- Community Impact
-
A serious violation of community standards, including sustained inappropriate behavior.
- Consequence
-
A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
Permanent Ban
- Community Impact
-
Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
- Consequence
-
A permanent ban from any sort of public interaction within the community.
35.6. Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at www.contributor-covenant.org/version/2/0/code_of_conduct.html. Community Impact Guidelines were inspired by Mozilla’s code of conduct enforcement ladder. For answers to common questions about this code of conduct, see the FAQ at www.contributor-covenant.org/faq. Translations are available at www.contributor-covenant.org/translations. www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.txt
OperatorFabric CICD
36. Pipeline Configuration
This section briefly describes the organization of our CICD pipeline. If you are looking for more detailed information, see this document describing the steps that were necessary to create our mock pipeline as well as the issues we ran into.
Most of the access and permissions required by our CICD plateform (Travis) are managed by tokens that are created on each of the required services (SonarCloud, DockerHub, GitHub). A technical user account (opfabtech) has been created for each of these services so that these tokens are not linked to the account of any member of the team.
36.1. CICD Pipeline
36.1.1. Travis CI
We use Travis CI to manage our pipeline. As of today, it is composed of 3 stages:
test-assemble |
Run on every push regardless of the branch, does the build and produces test reports. It also triggers a sonar-scanner analysis and pushes the results to SonarCloud (except for external pull requests). |
doc |
Run only on the master branch, for the daily cron jobs or if a commit is push with a message containing ci_documentation. It generates the documentation (adoc, javadoc, compodoc, reports) and pushes it to the opfab.github.io repository to update the website. |
docker |
Run only on the master branch, for the daily cron jobs or if a commit is push with a message containing ci_docker. It generates the docker images for the current version and pushes them to DockerHub. |
36.1.2. SonarCloud
To be allowed to push results to SonarCloud, Travis needs to be authenticated. This is done by generating a token on SonarCloud with an account (opfabtech) that has admin rights to the organization, and then providing this token to Travis either through the .travis.yml file or as an environment variable through Travis settings.
36.1.3. GitHub (documentation)
To be allowed to push the generated documentation to the opfab.github.io, Travis needs write access to the repository. This is done by setting up a Personal Access Token in GitHub using the technical account. This token is then passed to Travis as an environment variable through Travis settings, and is used in the .travis.yml file. Right now the scope of this token is maximal, it can probably be reduced (see OC-755).
After new content is pushed to the opfab.github.io repository, it can take a few minutes before this content is visible on the website because it needs to be built by GitHub pages, and this can take a short while depending on how busy the service is. |
36.1.4. DockerHub
To be allowed to push images to DockerHub, Travis needs to be authenticated. This is done by setting the dockerhub login and password of the technical account as environment variables through Travis settings and referencing them in the .travis.yml file.
37. Release process
37.1. Version numbers
Version numbers X.Y.Z.label should be understood like this:
-
X: Major version, a major version adds new features and breaks compatibility with previous major and minor versions.
-
Y: Minor version, a minor version adds new features and does not break compatibility with previous minor versions for the same major version.
-
Z: Patch, a patch version only contains bug fixes of current minor version
-
Label: pre-release or build metadata:
-
SNAPSHOT: a version whose development is in progress, nightly builds only deliver SNAPSHOT versions
-
RELEASE: a version whose development is finished
-
37.2. Releasing Version
To release a version we use some Travis dedicated jobs. These jobs are triggered by specific commit keywords and rely on the VERSION file at the root of this repository to know which version is being produced. It is thus crucial to double-check the content of this file before any push (triggering the Travis jobs) is made. |
Before releasing a version, you need to prepare the release.
Considering a version X.X.X.SNAPSHOT.
37.2.1. Check the release notes
-
Click the appropriate version from JIRA the release list to get the release notes (click "Release notes" under the version name at the top) listing new features, fixed bugs etc…
-
Make sure that the release_notes.adoc file lists all the issues, bugs, tags or feature requests that are relevant for OperatorFabric users along with explanations if need be.
37.2.2. In the source repository (operatorfabric-core)
-
Use the ./CICD/prepare_release_version.sh script to automatically perform all the necessary changes:
./CICD/prepare_release_version.sh
This will perform the following changes:
-
Replace X.X.X.SNAPSHOT with X.X.X.RELEASE in swagger.yaml files and the VERSION file at the root operator-fabric folder
-
Change the version from W.W.W.RELEASE (previous release) to X.X.X.RELEASE in the deploy docker-compose file
The VERSION file is particularly important as the CI/CD pipeline tasks (building the documentation and the docker images for example) are based on it.
-
-
Commit with the template message:
[RELEASE] X.X.X.RELEASE (ci_docker,ci_documentation)
The commit comment leverages these three keywords to trigger the delivery of documentation and docker images, so you should check that they are correctly spelt.
-
ci_docker: triggers the build and upload of versioned docker images to DockerHub
-
ci_documentation: triggers the build and upload of the current documentation
-
-
Tag the commit with the version
git tag X.X.X.RELEASE
-
Push the commit
git push
-
Push the tag
git push origin X.X.X.RELEASE
-
Check that the build is correctly triggered
You can check the status of the build job triggered by the commit on Travis CI. The build job should have the following three stages:
Wait for the build to complete (around 30 minutes).
-
Check that the X.X.X.RELEASE images have been generated and pushed to DockerHub.
-
Check that the latest images have been updated on DockerHub.
-
Check that the documentation has been generated and pushed to the GitHub pages website
-
Check the version and revision date at the top of the documents in the current documentation (for example the architecture documentation)
-
Check that you see the X.X.X.RELEASE under the releases page and that the links work.
-
-
Check that the tag was correctly pushed to GitHub and is visible under the releases page for the repository.
37.2.3. Checking deploy docker-compose
The deploy docker-compose file should always rely on the latest RELEASE version available on DockerHub. Once the CI pipeline triggered by the previous steps has completed successfully, and you can see X.X.X.RELEASE images for all services on DockerHub, you should:
-
Remove your locally built X.X.X.RELEASE images if any
-
Run the deploy docker-compose file to make sure it pulls the images from DockerHub and behaves as intended.
37.2.4. In Jira
-
Set all concerned tickets (US, BUG, FR) and set fix version to X.X.X.RELEASE
-
In the "Releases" screen release X.X.X.RELEASE version
37.3. Advertising the new release on the LFE mailing list
-
Take the text from the release note and use it to send an email to the opfab-announce@lists.lfenergy.org mailing list.
37.4. Preparing next version
You should wait for all the tasks associated with creating the X.X.X.RELEASE version to finish and make sure that they’ve had the expected output before starting the preparation of the next version. This is because any committed/pushed changes preparing the new version will make rolling back or correcting any mistake on the release more complicated. |
To prepare a next version you simply need to increment the version after a release (see Version numbers ).
37.4.1. In the source repository (operatorfabric-core)
-
Use the ./CICD/prepare_snapshot_version.sh script to automatically perform all the necessary changes:
./CICD/prepare_snapshot_version.sh --version Y.Y.Y.SNAPSHOT
This will perform the following changes:
-
Replace all occurrences of X.X.X.RELEASE by Y.Y.Y.SNAPSHOT EXCEPT in the deploy docker-compose file (src/main/docker/deploy/docker-compose.yml). The files concerned are swagger.yaml files and the VERSION file at the root operatorfabric-core folder.
The VERSION file is particularly important as the CI/CD pipeline tasks (building the documentation and the docker images for example) are based on it. If no --version parameter is provided to the script, the new version will be the next minor version.
-
-
Modify the release_notes.adoc file to initialize the release notes for version Y.Y.Y.RELEASE.
-
Commit and push changes with the following message:
[PREPARE] next version: Y.Y.Y.SNAPSHOT (ci_docker,ci_documentation)
Wait for the build to complete (around 30 minutes).
-
Check that the snapshot images have been generated and pushed to DockerHub.
-
Check that the documentation has been generated and pushed to the GitHub pages website: you should see the Y.Y.Y.SNAPSHOT under the releases page. Check that the links work.
37.4.2. In Jira
-
In the "Releases" screen create a Y.Y.Y.RELEASE version.
Resources
38. Appendix A: Mock CICD Pipeline
We wanted to be able to test changes to this configuration or to the scripts used by the pipeline without risks to the real master branch, to our docker images or to the documentation. We didn’t find any such "dry-run" options on Travis CI so we decided to create a complete mock pipeline replicating the actual pipeline. This is a short summary of the necessary steps.
38.1. GitHub
-
Create organization opfab-mock
-
Create user account opfabtechmock
-
Invite opfabtechmock to opfab-mock organization as owner (see later if this can/should be restricted)
-
Fork operatorfabric-core and opfab.github.io repos to opfab-mock organization
38.2. Travis CI
-
Go to travis-ci.org (not travis-ci.com)
-
Sign in with GitHub (using opfabtechmock) This redirects to a page offering to grant access to your account to Travis CI for Open Source, click ok.
Note: This page (github.com/settings/applications) lets you review the apps that have keen granted this kind of access and when it was last used.
-
Looking at travis-ci.org/account/repositories, the opfab-mock organization didn’t appear even after syncing the account, so click on "review and add your authorized organizations" (this redirects to github.com/settings/connections/applications/f244293c729d5066cf27).
-
Click "grant" next to the organization.
-
After that, Travis CI for Open Source is visible here: github.com/organizations/opfab-mock/settings/oauth_application_policy.
This allowed the opfab-mock organization to appear in the account: travis-ci.org/account/repositories Click on opfab-mock to get to the list of repositories for this organization and toggle "operatorfabric-core" on.
-
Under the Travis settings for the operatorfabric-core repository, create a Cron Job on branch master, that runs daily and is always run.
38.3. SonarCloud
-
Go to SonarCloud.io
-
Sign in with GitHub
When switching between accounts (your own and the technical account for example), make sure to log out of SonarCloud when you’re done using an account because otherwise it will keep the existing session (even in a new tab) rather than sign you back in with the account you’re currently using on GitHub. -
Authorize SonarCloud by sonarcloud + Create a new organization from the "+" dropdown menu to the left of your profile picture
Click on "Just testing? You can create manually" on the bottom right, and not "Choose an organization on GitHub". This is because the "opfab" SonarCloud organization that we are trying to replicate is not currently linked to its GitHub counterpart (maybe the option didn’t exist at the time), so we’re doing the same here. In the future it might be a good idea to link them (see OC-751)as SonarCloud states that
Binding an organization from SonarCloud with GitHub is an easy way to keep them synchronized. To bind this organization to GitHub, the SonarCloud application will be installed.
And then it warns again that
Manual setup is not recommended, and leads to missing features like appropriate setup of your project or analysis feedback in the Pull Request.
-
Click "Analyze new project" then "Create manually" (for the same reasons as the organization).
Project key and display name : org.lfenergy.operatorfabric:operatorfabric-core-mock Then choose "Public" and click "Set Up".
-
This redirects to the the following message : We initialized your project on SonarCloud, now it’s up to you to launch analyses! Now we need to provide Travis with a token to use to access SonarCloud.
-
To generate a token, go to Account/Security
There are two options to pass this token to Travis:
-
Option A: Define a new SONAR_TOKEN environment variable in the repository’s settings in Travis, then use it in the .travis.yml file as follows:
addons: sonarcloud: organization: "opfab-mock" token: secure: ${SONAR_TOKEN}
-
Option B: Encrypt this token using the travis gem:
travis encrypt XXXXXXXXXXXXXXXXXXXXXXXXXXXX
This has to be run at the root of the repository otherwise you get the following error: Can’t figure out GitHub repo name. Ensure you’re in the repo directory, or specify the repo name via the -r option (e.g. travis <command> -r <owner>/<repo>)
Do not use the --add option (to add the encrypted value directly to the .travis.yml file) as it changes a lot of things in the file (remove comments, change indentation and quotes, etc.). Paste the result (YYYY) in the .travis.yml file:
addons: sonarcloud: organization: "opfab-mock" token: secure: "YYYY"
Option A would be better as it’s not necessary to make a new commit if the token needs to be changed, but it stopped working suddenly, maybe as a result of a travis policy change regarding encryption. OC-752 was created to investigate.
-
There is still a SONAR_TOKEN environment variable defined in the Travis settings (with a dummy value) because there is a test on its presence to decide whether sonar-scanner should be launched or not (in the case of external PRs) (see OC-700 / OC-507). |
-
Finally change the organization in .travis.yml file and the project key in sonar-project.properties (replace the actual values with mock values).
In travis.yml we launch the sonar-scanner command whereas the tutorials mention gradle sonarqube. It looks like we’re following this which says that "The SonarScanner is the scanner to use when there is no specific scanner for your build system." But there is a specific scanner for Gradle: |
The SonarScanner for Gradle provides an easy way to start SonarCloud analysis of a Gradle project. The ability to execute the SonarCloud analysis via a regular Gradle task makes it available anywhere Gradle is available (CI service, etc.), without the need to manually download, setup, and maintain a SonarScanner installation. The Gradle build already has much of the information needed for SonarCloud to successfully analyze a project. By configuring the analysis based on that information, the need for manual configuration is reduced significantly.
→ This could make sonar easier to run locally and reduce the need for configuration (see OC-754).
38.4. GitHub (documentation)
-
Create a personal access token for GitHub (for the documentation). Its name is not important.
See GitHub documentation.
-
Create a GH_DOC_TOKEN env variable in Travis settings for the operatorfabric-core repository , making it available to all branches.
38.5. DockerHub
-
Create account opfabtechmock
-
Create organization lfeoperatorfabricmock
-
Change organization name in docker config in services.gradle
docker { name "lfeoperatorfabricmock/of-${project.name.toLowerCase()}" tags 'latest', dockerVersionTag labels (['project':"${project.group}"]) files jar.archivePath, 'src/main/resources/bootstrap-docker.yml', '../../../src/main/docker/java-config-dependent-docker-entrypoint.sh' buildArgs(['JAR_FILE' : "${jar.archiveName}", 'http_proxy' : apk.proxy.uri, 'https_proxy' : apk.proxy.uri, 'HTTP_PROXY_AUTH': "basic:*:$apk.proxy.user:$apk.proxy.password"]) dockerfile file("src/main/docker/Dockerfile") }
-
Add the opfabtechmock dockerhub account credentials as DOCKER_CLOUD_USER / DOCKER_CLOUD_PWD in Travis env variables in settings (see GH_DOC_TOKEN above).
38.6. Updating the fork
To make the mock repositories catch up with the upstream (the real repositories) from time to time, follow this procedure (the command line version), except you should do a rebase instead of a merge: rick.cogley.info/post/update-your-forked-repository-directly-on-github/