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

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 authenticated. To do that you need to get a token with the following command :

or use the provided script

You should received JSON a response 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 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".

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, 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 and entities are stored in the user information.

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 .

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 .

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

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 a user id. Given name and family name are optional.

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

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.

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 built on top of a NGINX server. Its sole purpose is to serve the Angular SPA to browsers.

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 list 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 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:

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 a 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

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.

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:

To export the different report into the SonarQube docker instance you need to install and use SonarScanner.

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:

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.

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

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 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 for details.

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

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.

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.

We use Travis CI to manage our pipeline. As of today, it is composed of 3 stages:

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.

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

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.

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:

Wait for the build to complete (around 30 minutes).