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 for accessing the services from outside. It is a nginx server package with docker, this component contains the angular UI component.

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 get a token you can source the provided script:

This will run the following command:

This should return a JSON a response like this:

Your token is the access_token value in the JSON, which the script will export to a $token environment variable.

The sendBundle.sh script below will use of this variable.

Executing the sendBundle.sh script will send the bundle.

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.

The library charts.js is integrate in operator fabric, it means it’s possible to show charts in cards, you can find a bundle example in the operator fabric git (src/test/utils/karate/thirds/resources/bundle_test_api).

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.

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. Examples using entities can be found here .

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

The configuration shared by all business services is in a yaml file, you can find an example with the file /config/docker/common-docker.yml.

Each business service has a specific yaml configuration file. It should a least contain the name of the service:

It can contain references to other services as well, for example :

Examples of configuration of each business service can be found either under config/docker or config/dev depending on the type of deployment you’re looking for.

An external nginx.conf file configures the OperatorFabric Nginx instance named web-ui service. Those files are mounted as docker volumes. There are two of them in OperatorFabric, one in config/dev and one in config/docker.

The one in config/dev is set with permissive CORS rules to enable web development using ng serve within the ui/main project.It’s possible to use ng serve with the one in config/docker version also. To do so use the conf file named nginx-cors-permissive.conf by configuring the /docker-compose.yml with the following line:

instead of:

The properties lie in the web-ui.json.The following table describes their meaning and how to use them. An example file can be found in the config/docker directory.

User Settings default values

There are 3 OAuth2 Authentication flows available into OperatorFabric UI:

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

By default, OperatorFabric manages 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]

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.

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:

instead of

If you want to check that the certificates were correctly added, you can do so with the following steps:

You can also look at the default list of authorities and certificates trusted by the JVM with this command:

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:

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

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.

OperatorFabric uses 4 external services to run properly :

Wait a moment before trying to connect to the`SPA`, leaving time for the OperatorFabricServices 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:

For more realistic card sending use, once Karate env correctly configured, the Karate script called ${OF_HOME}/src/test/api/karate/launchAllCards.sh.

Once logged in, after one of those scripts have been running, 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

The aim of this section is to illustrate how our workflow works on a concrete example, complete with the required git commands.

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.