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 processInstanceId

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

As we saw previously, if a card is sent to a group, then you only need to be a member of the group to receive it.

If a card is sent to an entity, then you must be a member of this entity and have the process / state of the card within the user’s perimeter. As the perimeters are attached to groups, the user must therefore be a member of a group attached to this perimeter.

Let’s send this card :

Use the provided script :

The result should be a 201 Http status, and a json object such as:

See the result in the UI, you should not see the card.

Now let’s create this perimeter :

You can use this command line :

or use the provided script :

The result should be a 201 Http status, and a json object such as:

Now let’s attach this perimeter to the Dispatcher group. You can use this command line :

or use the provided script :

The result should be a 200 Http status.

Now, if you refresh the UI or send again the card, you should see the card.

If a card is sent to a group and an entity, then there are 2 possibilities to receive this card :

Let’s send this card (for ENTITY1 and Dispatcher group) :

Use the provided script :

The result should be a 201 Http status, and a json object such as:

See the result in the UI, you should see the card.

Let’s send this card (for ENTITY1 and Planner group) :

Use the provided script :

The result should be a 201 Http status, and a json object such as:

See the result in the UI, you should see the card.

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 Businessconfig bundle requirements.

The previous server response is return for a request like: http://localhost:2002/businessconfig/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 businessconfig micro service source code you should list the content of $THIRDS_PROJECT/build/docker-volume/businessconfig-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.

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.

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

A bundle contains all the configuration regarding a given business process, describing for example the various steps of the process but also how the associated cards and card details should be displayed.

Bundle are technically tar.gz archives containing at least a descriptor file named config.json. To display the card date, some css files, i18n files and handlebars templates must be added.

For didactic purposes, in this section, the businessconfig bundle name is BUNDLE_TEST (to match the parameters used by the script). The l10n (localization) configurations are english, referred as en and french, referred as fr.

As detailed in the Businessconfig core service README the bundle contains at least a metadata file called config.json, a css folder, an i18n folder and a template folder.

Except for the config.json file, all elements are optional.

The file organization within a bundle:

It’s a description file in json format. It lists the content of the bundle.

example

The mandatory field are id,'name' and version.

See the Businessconfig API documentation for details.

There are two ways of internationalization (i18n) for businessconfig service. First one by using l10n files 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.

The integration of the businessconfig service into OperatorFabric need this localisation, i.e. the label displayed for the process, the state, the label displayed for the details of the card…​

OperatorFabric offers the possibility of defining process groups. These groups have an impact only on the UI, for example on the notification configuration screen, by offering a more organized view of all the processes.

To define processes groups, you have to upload a file via a POST http request as described in the

Businessconfig Service API documentation .

Example

Where:

Example of content for uploaded file :

These command line should return a 201 http status.

OperatorFabric defines a css class that you should use so your templates don’t clash with the rest of the OperatorFabric look and feel:

These styles are especially useful for templates used in user card or card with responses.

Your can find example using these classes in the OperatorFabric core repository (src/test/resources/bundles).

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

If a timespan is present without a recurrence object, a reminder will arise at startDate - secondsBeforeTimeSpanForReminder.

It is possible to set a recurrent reminder via the structure recurrence which define a regular event in the timespan structure. It is defined with the following fields :

The reminder will arise for each recurrent date of event - secondsBeforeTimeSpanForReminder starting from startDate.

If the user is not connected at the time of the remind, when he connects if current time is superior to 15 minutes from the event date, no remind will arise.

When the user receives a card with a reminder to set, the log (console) of the browser contains a line with the date when the remind will arise . For example :

2020-11-22T21:00:36.011Z Reminder Will remind card userCardExamples.0cf5537b-f0df-4314-f17f-2797ccd8e4e9 at Sun Nov 22 2020 22:55:00 GMT+0100 (heure normale d’Europe centrale)

The response card is to be received by a third party application for business processing. The third-party application will receive the card as an HTTP POST request. The card is in json format (the same format as when we send a card). The field data in the json contains the user response.

The url of the third party receiving the response card is to be set in the .yml of the publication service. Here is an example with two third parties configured.

The name to use for the third-party is the publisherId of the parent card.

A card can have a response only if it’s in a process/state that is configured for. To do that you need to define the appropriate configuration in the config.json of the concerned process. Here is an example of configuration:

We define here a state name "questionState" with a response field. Now, if we send a card with process "defaultProcess" and state "questionState", the user will have the possibility to respond if he has the required privileges.

For the user to response you need to define the response form in the template with standard HTML syntax

To enable operator fabric to send the response, you need to implement a javascript function in your template called templateGateway.getUserResponse which returns an object containing four fields :

This method will be called by OperatorFabric when the user clicks on the button to send the response.

In the example below, the getUserResponse creates a responseCardData object by retrieving the user’s inputs from the HTML. In addition, if the user chose several options, it overrides the response state defined in the config.json with another state.

To respond to a card a user must have the right privileges, it is done using "perimeters". The user must be in a group that is attached to a perimeter with a right "Write" for the concerned process/state, the state being the response state defined in the config.json.

Here is an example of definition of a perimeter :

To configure it in OperatorFabric , you need to make a POST of this json file to the end point /users/perimeters.

To add it to a group name for example "mygroup", you need to make a PATCH request to endpoint 'users/groups/mygroup/perimeters' with payload ["perimeterQuestion"]

If you want to show the name of an entity that send the response, you need to get the id of the entity via the publisher field of the child card and then you can get the name of the entity by calling templateGateway.getEntityName(entityId)

You can find an example in the file src/test/resources/bundles/defaultProcess_V1/template/en/question.handlebars.

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 entity is loose and can be used to model organizations structures(examples : control center, company , department…​ ). 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’s data (entities field of the user object). In Entity objects, the parents property (array) expresses the fact that this entity is a part of one or several other entities. This feature allows cards to be sent to a group of entities without having to repeat the detailed list of entities for each card. The boolean property entityAllowedToSendCard (default value true) can be used to mark an Entity as not eligible as card publisher. This can be useful for a group of entities where only child entities should be used as card publishers while the parent is just a logical group usable as card recipient.

Examples using entities can be found here .

The notion of group is loose and can be used to simulate role in OperatorFabric (examples : supervisor, dispatcher …​ ). 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. A group contains a list of perimeters which define the rights of reception/writing for a couple process/state. The rules used to send cards are described in the recipients section . .

Perimeters are used to define rights for reading/writing cards. A perimeter is composed of an identifier (unique), a process name and a list of state/rights couple. Possible rights for receiving/writing cards are :

The standard way to handle groups and entities in OperatorFabric instance is dealt on the user information. There is an alternative way to manage groups and entities through the authentication token, the groups and entities are defined by the administrator of the authentication service. See here for more details to use this feature.

A single menu or a menu with sub-menus has at least attributes named id and entries. The entries attribute is an array of menu entry. It is possible to restrict the visibility of one menu entry the one or more user groups by setting the showOnlyForGroups parameter. Note that menus with sub-menus need a label declaring an i18n key.

Each menu entry declares the attributes listed below:

In following example, the configuration file declares two additional business menus. The first has only one entry, the second has two entries. The sample contain also the i18n translations in english and in french.

For iframes opened from menu, the associated request uses an extra parameter containing the current theme information. Named opfab_theme, this parameter has a value corresponding to the current theme:
DAY or NIGHT

Example:

Switching theme will trigger reload of open iframes.

When starting docker in the full docker environment an external environment file could be provided like:

In the provided environment file the Spring active profiles can be set.

This way the configuration file 'cards-publication-local.yml' can be provided in the same configuration directory and can be read by SpringBoot

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. In this file you will find, among others, the parameters below :

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:

Alternatively there is also another flow available:

The NONE flow assumes that the application is behind a secured proxy wich handles login and token generation. Calls to backend services will get a valid token added to the headers and the token will not be visible for the (web)client.

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

Entities have a 'parents' attribute instead of a 'perimeters' one. This attribute is a string array. Each element of the array is the id of another Entity. When adding or patching an Entity into the system, operatorFabric performs a cycle detection. On a positive cycle detection cancels the addition or the patch.