OperatorFabric Reference Documentation

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 file 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 is English.

As detailed in the Businessconfig core service README the bundle contains at least a metadata file called config.json, a file i18n.json, a css 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.

This file contains internationalization information, in particular the translation for title and summary fields If there is no i18n file or key is missing, OperatorFabric displays i18n key, such as BUNDLE_TEST.1.missing-i18n-key. In the case where the bundle declares no i18n key corresponds to missing-i18n-key.

The choice of i18n keys is up to the maintainer of the Businessconfig process.

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 several css classes 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 following css styles are available.

OperatorFabric provides a css tooltip component. To use it, you must use the opfab-tooltip class style. You can define where the tooltip will be displayed using left, top or bottom (by default, it is displayed on the right). For example :

or for a tooltip displyed on the left :

OperatorFabric provides a multiselect component based on Virtual Select. To use it, one must use the OperatorFabric style and provide javascript to initialize the component:

You can set selected values via method setSelectedValues();

If you want to set the options list after init, use setOptions method :

You can enable (or disable) the multiselect component using enable (or disable) method :

It is possible to use the component also as single value select. The advantage over a standard select is the possibility to benefit of the searching feature. To use the component as single select, initialize it with the multiple property set to false:

OperatorFabric provides a rich text editor component based on github.com/quilljs/quill. The component provides the following text formatting tools :

To use the rich text editor component just add a <opfab-richtext-editor> tag in the template using the OperatorFabric style. From javascript it is then possible to get formatted text content.

The editor use a custom JSON format called Delta to store the formatted content. To get the JSON content as a string you can call the getContents() method. To get the HTML formatted text you can call the getHtml() method.

To set the initial content of the editor you can either call the setContents(delta) method from javascript providing the content as Delta JSON string or directly in the template by putting the Delta JSON string as content of the <opfab-richtext-editor> tag.

To show the rich message an HTML element you can call the opfab.richTextEditor.showRichMessage(element) method. For example:

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

The version of chartjs integrated in OperatorFabric is v3.7.1.

The user can set a card as "acknowledged," so he will not see it any more by default in the feed. It is as well possible to cancel it and set a card to "unacknowledged" (a filter permit to see acknowledged cards).

To offer the possibility for the user to acknowledge card, it has to be configured in process definition. The configuration is done on a state by setting the acknowledgmentAllowed field. Allowed values are:

It is possible to cancel a card acknowledgment unless process state configuration has the cancelAcknowledgmentAllowed field set to false.

When the user acknowledges a card, the card detail is closed unless process state configuration has the closeCardWhenUserAcknowledges field set to false.

You can see examples in src/test/resources/bundles/defaultProcess_V1/config.json

A card can also be set as acknowledged if a member (or several) of the entity of the user has acknowledged it. A user can be member of several entities, so you can configure if acknowledgment done by only one entity (of the user) suffices for the card to appear as acknowledged or if all entities must acknowledge the card.

To configure how a card is considered as acknowledged for the user, it has to be configured in process definition. The configuration is done on a state by setting the consideredAcknowledgedForUserWhen field. Allowed values are :

The entities acknowledgments can be displayed in the footer of the card. You can choose to display it (or not) via the option showAcknowledgmentFooter in a state definition. Allowed values are :

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

It is possible to set a recurrent reminder for a card. There are two ways to do it :

When a card with a reminder set is sent, the log of the "cards-reminder" service will contain a line with the date when the reminder will arise . For example :

2020-11-22T21:00:36.011Z Reminder Will remind card conferenceAndITIncidentExample.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. It is also possible to configure whether the user token shall be propagated to the third party or not by setting the "propagateUserToken" boolean property. 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 OperatorFabric to send the response, you need to implement a javascript function in your template which returns an object containing the following fields :

This method is to be registered via opfab.currentCard.registerFunctionToGetUserResponse, the 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 "ReceiveAndWrite" 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 opfab.users.entities.getEntityName(entityId)

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

If you want to show only a simple message, you can use the message build-in template, to do that just put in your handlebar file :

The build-in template supposes the message is stored in the card in field data.message.

You can change the text header by providing the message-header attribute:

If you want to create a user card for a simple message, just add in your handlebar file :

The message will be stored in the field data.message of the card

By using attributes you can set some parameters regarding recipients, see common attributes for user cards

If you want to show a question and see user responses, you can use the question build-in template, to do that just put in your handlebar file:

The build-in template supposes the question is stored in the card in the field data.question.

If you want to create a user card for a simple question, just add in your handlebar file :

The question will be stored in the field data.question of the card

By using attributes you can set some parameters regarding recipients, see common attributes for user cards

If you want to show a message or a question and the answers, you can use the message or question list build-in template, to do that just put in your handlebar file:

The build-in template supposes the message or question is stored in the card in the field data.message.

If you want to create a user card where you can select a list of messages or questions linked to a json file, just add in your handlebar file :

The message will be stored in the field data.message of the card You need to set the json file name with the businessData attribute If you want to use the template as is, the json file must follow this structure :

`{ "possibleRecipients": [ {"id": "ENTITY1_FR"}, {"id": "ENTITY2_FR"} ],

}`

The severity field is optional. If not specified, the card will take a default severity value depending on 'question' field value : "ACTION" if question is true, "INFORMATION" if question is false.

The publishers field is optional. It is used to restrict the possible publishers of the message. If specified, the message option is available only for the specified entities. If not specified or empty, there are no restrictions.

The summary field is optional. If specified, considering 'xxx' is the value of the field, so the summary you will see in the feed will be 'Message received : xxx'. If not specified, the summary will only be 'Message received'.

Entity object contains the following fields :

It’s possible to redirect the user from a card to a business application declared in ui-menu.json.

This can be done by calling the following function from the template :

It is also possible to append a url extension (sub paths and/or parameters) to the url that will be called:

This can be useful to pass context from the card to the business application.

It is possible from the template to redirect the user to another "card detail" in feed page

Once the card is loaded, there may be some processing that is time consuming. In this case, it is possible to show a spinner using the method displayLoadingSpinner and hideLoadingSpinner in the card template .

Hide loading spinner previously open with displayLoadingSpinner()

You can access the current selected card as a js object using the getCard() method.

To adapt the template content to the display context it is possible to get from OperatorFabric the page context where the template will be rendered by calling the javascript function getDisplayContext(). The function returns a string with one of the following values :

If inside your template, you want to get the ids of the entities allowed to send a response, you can call the method getEntitiesAllowedToRespond. This method returns an array containing the ids.

If inside your template, you want to get the id of the entity used by the user to send a response, you can call the method getEntityUsedForUserResponse. This method is deprecated and you should favor the use of the method getEntitiesUsableForUserResponse.

If inside your template, you want to get the ids of the entities the user can answer on behalf of, you can call the method getEntitiesUsableForUserResponse. This method will return an array containing the entities' ids

To know if template is locked (i.e user can not respond unless he unlocks the card)

The template can know if the current user has the permission to send a response to the current card by calling the isUserAllowedToRespond() function. An example of usage can be found in the file src/test/resources/bundles/conferenceAndITIncidentExample/template/incidentInProgress.handlebars.

The template can know if the current user is member of an Entity required to respond by calling the isUserMemberOfAnEntityRequiredToRespond function. An example of usage can be found in the file src/test/resources/bundles/defaultProcess_V1/template/question.handlebars.

Register a function to be informed when template is locked (i.e user has responded to the current card)

Register a function to be informed when template is unlocked (i.e user has clicked the modify button to prepare a new response)

Register a function to receive the child cards on card loading and when the childCards list changes

If the card has a last time to decide (lttd) configured, when the time is expired this information can be received by the template by registering a listener.

Card template can be informed when switching day/night mode by registering a listener as follow :

It can be used by a template to refresh styles and reload embedded charts.

To adapt the template content on screen size it is possible to receive from OperatorFabric information on the size of the window where the template will be rendered. To receive screen size information you need to implement a listener function which will receive as input a string parameter with one of the following values :

It is possible to be informed when opfab has finished all tasks regarding rendering template by registering a listener function .The function will be called after the call of the other listener (applyChildCard, lockAnswer ,lttdExpired and screenSize)

It can be used by a template to launch some processing when loading is complete

Register the template function to call to get user response. This function will be called by opfab when user clicks on the "send reponse" button. More explanation can be found in the response card chapter.

For example :

The template can know if the user is creating a new card or editing an existing card by calling the opfab.currentUserCard.getEditionMode() function. The function will return one of the following values:

The template can know the current endDate of the card in creation or edition by calling the opfab.currentUserCard.getEndDate() function. The function will return a number corresponding to the endDate as epoch date value.

The template can know the current expirationDate of the card in creation or edition by calling the opfab.currentUserCard.getExpirationDate() function. The function will return a number corresponding to the expirationDate as epoch date value.

The template can know the current lttd of the card in creation or edition by calling the opfab.currentUserCard.getLttd() function. The function will return a number corresponding to the lttd as epoch date value.

The template can know the process id of the card by calling the opfab.currentUserCard.getProcessId() function. The function will return a string corresponding to the process id.

The template can know the list of entities selected by the user as recipients of the card by calling the opfab.currentUserCard.getSelectedEntityRecipients() function. The function will return an array of entity ids.

The template can know the list of entities selected by the users as recipients of the card by calling the opfab.currentUserCard.getSelectedEntityForInformationRecipients() function. The function will return an array of entity ids.

The template can know the current startDate of the card in creation or edition by calling the opfab.currentUserCard.getStartDate() function.The function will return a number corresponding to the startDate as epoch date value.

The template can know the state of the card by calling the opfab.currentUserCard.getState() function. The function will return a string corresponding to the state.

When editing a user card, the template can get the response sent by the entity of the current user by calling the opfab.currentUserCard.getUserEntityChildCard() function. The function will return the response child card sent by current user entity or null if there is no response.

The template can receive the emitter entity of the card by registering a listener function. The function will be called by OperatorFabric after loading the template and every time the card emitter changes (if the user can choose from multiple entities).

Register the template function to call to get user card specific information. This function will be called by opfab when user clicks on the "preview" button. More explanation can be found in the user card chapter.

For example:

When sending a user card, by default it is possible to choose the recipients from all the available entities. To limit the list of available recipients it is possible to configure the list of possible recipients via javascript in the user template.

For example :

In this example the list of available recipients will contain: "ENTITY_FR" (level 0), all the first level children of "ENTITY_FR" (level 1) and "IT_SUPERVISOR_ENTITY".

When sending a user card, by default it is possible to choose the recipients for information from all the available entities. To limit the list of available recipients it is possible to configure the list of possible recipients via javascript in the user template.

For example :

In this example the list of available recipients for information will contain: "ENTITY_FR" (level 0), all the first level children of "ENTITY_FR" (level 1) and "IT_SUPERVISOR_ENTITY".

From the template it is possible to set the initial value for endDate by calling opfab.currentUserCard.setInitialEndDate(endDate) . The endDate is a number representing an epoch date value.

From the template it is possible to set the initial value for expirationDate by calling opfab.currentUserCard.setInitialExpirationDate(expirationDate) . The expirationDate is a number representing an epoch date value.

From the template it is possible to set the initial value for lttd by calling opfab.currentUserCard.setInitialLttd(lttd) . The lttd is a number representing an epoch date value.

It is possible to configure the list of initially selected recipients via javascript in the user template by calling the setInitialSelectedRecipients method. The method takes as input the list of Entity ids to be preselected. The method will work only at template loading time, cannot be used to modify the selected recipients after the template is loaded or in card edition mode.

For example :

In this example the dropdown list of available recipients will have "ENTITY_FR" and "IT_SUPERVISOR_ENTITY" preselected. The user can anyway change the selected recipients.

It is possible to configure the list of initially selected recipients for information via javascript in the user template by calling the setInitialSelectedRecipientsForInformation method. The method takes as input the list of Entity ids to be preselected. The method will work only at template loading time, cannot be used to modify the selected recipients after the template is loaded or in card edition mode.

For example :

In this example the dropdown list of available recipients will have "ENTITY_FR" and "IT_SUPERVISOR_ENTITY" preselected. The user can anyway change the selected recipients for information.

It is possible to configure the list of selected recipients via javascript in the user template by calling the setInitialSelectedRecipients method. The method takes as input the list of Entity ids to be preselected. This method can be called at any time and also in edition mode.

For example :

In this example the dropdown list of available recipients will have "ENTITY_FR" and "IT_SUPERVISOR_ENTITY" preselected. The user can anyway change the selected recipients.

It is possible to configure the list of selected recipients for information via javascript in the user template by calling the setSelectedRecipientsForInformation method. The method takes as input the list of Entity ids to be selected. This method can be called at any time and also in edition mode.

For example :

In this example the dropdown list of available recipients will have "ENTITY_FR" and "IT_SUPERVISOR_ENTITY" preselected. The user can anyway change the selected recipients for information.

From the template it is possible to set the initial value for card severity choice by calling the function setInitialSeverity(severity)

Allowed severity values are:

From the template it is possible to set the initial values for startDate by calling opfab.currentUserCard.setInitialStartDate(startDate) . The startDate is a number representing an epoch date value.

To avoid script injection, OperatorFabric provides a utility function 'opfab.utils.escapeHtml()' to sanitize input content by escaping HTML specific characters. For example:

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 roles attribute allows to set the utility of an entity. It determines if an entity can send or receive cards and if it’s part of an activity area. 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 a card recipient. The labels property (array) allows to associate string labels to an Entity object.

Examples using entities can be found here .

Permissions in OperatorFabric are used to configure user’s permission on the UI and control the access to the APIs. The information about permissions is stored in the data of the user’s groups (Permissions field of the group object). The available permissions are:

The notion of group is loose and can be used to simulate business role in OperatorFabric (examples : supervisor, dispatcher …​ ) by setting group type to 'ROLE' or to define permissions on processes/states by setting the group type to 'PERMISSION'. 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.

Core menus are objects containing the following fields :

See /config/docker/ui-menu.json for an example containing all core menus.

A menu can target directly a link or give access to several sub-menus when clicked. Those sub-menus can target a link or an opfab core menu. A targeted link can be open in an iframe or in a new tab.

Menus support i18n following the i18n OperatorFabric rules. The ui-menu.json file contains directly the i18n dictionary for the menus.

In case of a single menu, the navigation bar displays the l10n of the label of the entry menu. In this case, the label declared at the root level of the menu is useless and can be omitted (see example below).

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 to one or more user groups by setting the showOnlyForGroups parameter. Note that menus with sub-menus need a label declaring an i18n key.

A menu entry can target a core menu id or a link. If it targets a link, it must declare the attributes listed below:

In the following example, the configuration file declares two additional business menus. The first has only one entry, which targets a link. The second business menu has three entries, one which targets the core menu Dashboard and two others which target links. The sample also contains the 2 top right icons (usercard and calendar), the composition of the top right menu and the i18n translations in English and French.

Given the use case described above, a new service was necessary to act as a link between the OperatorFabric UI and the external devices. This service is in charge of:

This translates as three APIs.

Here is what happens when user operator1_fr receives a card with severity ALARM:

The following elements need to be configurable:

This means that a single physical device allowing 2 different sets of sounds to be played (for example one set for desk A and another set for desk B) would be represented as two different device configurations, with different ids.

Please see the API documentation for details.

The Modbus driver is based on the jlibmodbus library to create a ModbusMaster for each device and then send requests through it using the WriteSingleRegisterRequest object.

We are currently using the "BROADCAST" mode, which (at least in the jlibmodbus implementation) means that the Modbus master doesn’t expect any response to its requests (which makes sense because if there really are several clients responding to the broadcast, ) This is mitigated by the fact that if watchdog signals are enabled, the external devices will be able to detect that they are not receiving signals correctly. In the future, it could be interesting to switch to the TCP default so OperatorFabric can be informed of any exception in the processing of the request, allowing for example to give a more meaningful connection status (see #2294)

New drivers should implement the ExternalDeviceDriver interface, and a corresponding factory implementing the ExternalDeviceDriverFactory interface should be created with it.

The idea is that in the future, using dependency injection, Spring should be able to pick up any factory on the classpath implementing the correct interface.