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 .

It provides a filtered view of the APIS and static served pages for external access through browsers or other http compliant accesses. It provide the rooting and load balancing for accessing the micro-services from outside. It is implemented by Spring Cloud Gateway.

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.

The broker is used to share information asynchronously across the whole services. It is implemented via RabbitMQ

The architecture provide a default authentication service via KeyCloak but it can delegates it to an external provider. Authentication is done through the use of Oauth2, three flows are supported: implicit, authorization code and password.

The cards are stored in a MongoDb database. The bundles are stored in a file system.

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.

We can send a new version of the card (updateCard.json) :

You can send the updated card with :

The card should be updated on the UI.

You can delete the card using DELETE HTTP code with reference to publisher and processId

or use provided script:

Your bundle need to be package in a tar.gz file, a script is available

A file name bundle.tar.gz will be created.

To send the bundle you need to be authentified . To do that you need to get a token with the following commande :

or use the provided script

You should received JSON a reponse like this :

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.

Replace the value "THE TOKEN" with the token in the sendBundle.sh script :

You can now execute the script, it will send the bundle.

You should received the following JSON in response , describing your bundle.

You can send the following card to test your new bundle :

To use the new bundle , we set publisherVersion to "2"

To send the card :

You should see in the UI the detail card with the new template.

If you switch langage to french in the UI (Settings menu on the top rigth 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".

Extract content if possible and compress it to a correct compressed archive format.

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.

The internal file structure of your bundle is incorrect. config.json file and folders need to be at the first level.

Add or organize the files and folders of the bundle to fit the Third bundle requirements.

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

Either request another l10n or add the requested one to the bundle and re-upload it.

Add or verify the name of the templates declared in the config.json file of the bundle.

Those examples are played in an environment where an OperatorFabric instance (all micro-services) is running along a MongoDB Database and a RabbitMQ instances.

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, a media folder (not created in this example), 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:

To summarize, there are 5 directories and 8 files.

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 is stored in the user information.

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 name them specifically. The information about membership to a group is stored in the user information. The rules used to send cards are describe in the Card Publication Service.

Those attributes are used by OperatorFabric to manage how cards are stored, to whom and when they’re sent.

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.

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.

The previous cards were nearly empty regarding information carrying. In fact, cards are intended to contains more information than a title and a summary. The optional attribute data is here for that. This attribute is destined to contains any json object. The creator of the card is free to put any information needed as long as it’s in a json format.

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.

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.

This Archives screen relies on dedicated endpoints in the card-consultation API, as described here.

Download and install RabbitMQ following the official procedure for the target environment

If RabbitMQ may not bind to the following ports, it won’t start :

See the guide for production configuration guidelines

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:

Setting automated user creation==. Creation user requires an user id. Given name and family name are optional.

By default, Operator-Fabric manage groups through the user’s group. Another mode can be defined, the JWT mode. The groups come from the authentication token. The administrator of the authentication service has to set what claims define a group. In the Operator-Fabric configuration, the opfab administrator has to set properties to retrieve thoses groups.

application.yml

JWT example

As the result, the group will be [ATTR1, ATTR2, roleA, roleB, roleC, USER, roleBBB, roleAAA]

OperatorFabric Actions Business service is a Spring Webflux application bootstrapped using SpringBoot.

In our spring micro service architecture this service depends on Eureka Registry.

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.

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.

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.

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.

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.

OperatorFabric Thirds Business service is a Spring MVC application bootstrapped using SpringBoot.

In our spring micro service architecture this service depends on Eureka Registry.

OperatorFabric Users Business service is a Spring MVC application bootstrapped using SpringBoot.

In our spring micro service architecture this service depends on Eureka Registry.

OperatorFabric Web UI service is a Spring MVC application bootstrapped using SpringBoot. Its sole purpose is to serve the Angular SPA to browsers.

In our spring micro service architecture this service depends on Eureka Registry.

First of all, list the users (who are the recipients in OperatorFabric) of the system with the following commands:

Httpie

cURL

response

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:

Or here cURL:

response

It’s always a good thing to verify if all the information has been correctly recorded in the system:

with httpie:

or with cURL:

response

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:

or with cURL:

response

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 lists the groups existing in the server.

Httpie

cURL

response

Firstly, the group called OPERATORS has to be added to the system using the following command:

using httpie:

using cURL:

response

The result return 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:

using cURL:

response

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:

with cURL:

response

As both new group and new user are correct it’s time to make the user member of the group. To achieve this, use the following command:

with httpie:

with cURL:

response

Let’s verify that the changes are correctly recorded by fetching the :

with cURL

response

It’s now possible to send cards either specifically to john-doe-operator or more generally to the OPERATORS group.

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:

with cURL:

response

A last command to verify that OPERATORS is no longer linked to john-doe-operator:

with httpie:

with cURL:

response

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:

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. Currently you need to use a connection pair define in $OPERATOR_FABRIC_HOME/services/infra/auth/src/main/java/org/lfenergy/operatorfabric/auth/config/WebSecurityConfiguration.java. It could be admin with test, for example.

To test the reception of cards, you can use the following script to create dummy cards:

Once logged in, with that script running in the background, you should be able to see some cards displayed in localhost:2002/ui/feed.

Run in the $OF_HOME/ui/main directory the command ng test --watch=false to execute the unit tests based on Jasmine using Karma to drive the browser.

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

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

Per project configuration :

There are prerequisites before sourcing load_environment_ramdisk.sh:

Please see run_all.sh -h usage before running.

Prerequisites

Please see setup_dockerized_environment.sh -h usage before running.

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

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

Used to map the user name to a field that suits services

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

Work in Progress

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.

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.

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.

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.

Our website contains all the documentation and resources we’re currently working on. Here is what we aim to provide:

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.

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.

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:

And if you’re interested in LF Energy in general: LF Energy General Discussion

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:

A CRON Travis job runs daily (the time of the day may vary) and generates the documentation and docker snapshot images. After you have finished switching to the Y.Y.Y.SNAPSHOT version, you should wait for such a job to run and check that the snapshot images are correctly generated and pushed on DockerHub.