1. Appendix B: Publication of the client library jars to Maven Central

This is a summary of the steps that were necessary to initially set up the publication of jars to Maven Central. The process to actually publish the jars for each release is detailed in the release process documentation.

Publication process overview
  1. Building and signing the jars

  2. Publishing them to a staging repository where there are validations (e.g. check that the POM contains the required information, validating the signature against the public key)

  3. If the validations pass, release the jar to Maven Central

1.1. Claiming the org.opfab namespace on Maven Central

This is done by logging an issue on the Sonatype JIRA (create an account first). The namespace needs to match a domain that you own (and this will be verified), which is why we had to rename our packages to org.opfab.XXX.

You can then request other users to be granted rights on the namespace as well.

1.2. Creating a GPG key pair

The key pair is generated with GPG2, keeping the default options and using the opfabtech technical account email as contact. The key is further secured with a passphrase.

gpg2 --full-generate-key

gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
  (14) Existing key from card
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 3072
Requested keysize is 3072 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 18m
Key expires at Tue 11 Oct 2022 12:38:13 CEST
Is this correct? (y/N) y

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: opfabtech
E-mail address: opfabtech@gmail.com
Comment: technical account for the OperatorFabric project
You selected this USER-ID:
    "opfabtech (technical account for the OperatorFabric project) <opfabtech@gmail.com>"

Change (N)ame, (C)omment, (E)-mail or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilise the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 469E7252B8D25328 marked as ultimately trusted
gpg: directory '/home/guironnetale/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/guironnetale/.gnupg/openpgp-revocs.d/FE0D7AFF9C129CFBBDC18A0B469E7252B8D25328.rev'
public and secret key created and signed.

pub   rsa3072 2021-04-19 [SC] [expires: 2022-10-11]
      FE0D7AFF9C129CFBBDC18A0B469E7252B8D25328
uid                      opfabtech (technical account for the OperatorFabric project) <opfabtech@gmail.com>
sub   rsa3072 2021-04-19 [E] [expires: 2022-10-11]
A standard practice is to have the key expire in 18 months, so I set up a calendar reminder for us to renew it.

1.3. Sharing the signing key

For other developers to be able to sign jars, you need to share both the key pair and the passphrase.

  • Export the key pair to a file

gpg2 --export-secret-keys OPFAB_KEY_ID > key_pair.key

1.4. Publishing the public key

The public key needs to be published to (preferably several) key directories so people wanting to use the signed jars can check the signature against the public key. It is also checked as part of the validations performed on the staging repository.

Our public key was initially published to pool.sks-keyservers.net, which became deprecated (causing the publication to fail), so it was then published to the two servers that the sonatype validations seem to rely on.

For OpenPGP you need to export the public key (and not the key pair) to a file and upload it to their web interface.

gpg2 --export OPFAB_KEY_ID > my_key.pub

For Ubuntu you need to export the public key as ascii-armored ascii and paste the result to their web interface

gpg2 --export --armor OPFAB_KEY_ID
The key can be retrieved from both these servers by searching either for opfabtech@gmail.com or for the key ID.

1.5. Setting up the signing and publication in Gradle

You can’t publish a jar with version "SNAPSHOT" to the Maven staging repositories (you would get a 403 BAD REQUEST), that’s why the Gradle publication task is configured so that if the version ends with "SNAPSHOT", the jars should be published to a local directory (repos/snapshots) rather than to the Maven Central staging repository.

2. Migration Guide from release 1.4.0 to release 1.5.0

2.1. Refactoring of configuration management

2.1.1. Motivation for the change

The initial situation was to have a Third concept that was meant to represent third-party applications that publish content (cards) to OperatorFabric. As such, a Businessconfig was both the sender of the message and the unit of configuration for resources for card rendering.

Because of that mix of concerns, naming was not consistent across the different services in the backend and frontend as this object could be referred to using the following terms: * Third * ThirdParty * Bundle * Publisher

But now that we’re aiming for cards to be sent by entities, users (see Free Message feature) or external services, it doesn’t make sense to tie the rendering of the card ("Which configuration bundle should I take the templates and details from?") to its publisher ("Who/What emitted this card and who/where should I reply?").

2.1.2. Changes to the model

To do this, we decided that the publisher of a card would now have the sole meaning of emitter, and that the link to the configuration bundle to use to render a card would now be based on its process field.

2.1.2.1. On the Businessconfig model

We used to have a Businessconfig object which had an array of Process objects as one of its properties. Now, the Process object replaces the Businessconfig object and this new object combines the properties of the old Businessconfig and Process objects (menuEntries, states, etc.).

In particular, this means that while in the past one bundle could "contain" several processes, now there can be only one process by bundle.

The Businessconfig object used to have a name property that was actually its unique identifier (used to retrieve it through the API for example). It also had a i18nLabelKey property that was meant to be the i18n key to determine the display name of the corresponding businessconfig, but so far it was only used to determine the display name of the associated menu in the navbar in case there where several menu entries associated with this businessconfig.

Below is a summary of the changes to the config.json file that all this entails:

Field before Field after Usage

name

id

Unique identifier of the bundle. Used to match the publisher field in associated cards, should now match process

name

I18n key for process display name.

states.mystate.name

I18n key for state display name.

i18nLabelKey

menuLabel

I18n key for menu display name in case there are several menu entries attached to the process

processes array is a root property, states array being a property of a given process

states array is a root property

Here is an example of a simple config.json file:

Before
{
  "name": "TEST",
  "version": "1",
  "defaultLocale": "fr",
  "menuEntries": [
    {"id": "uid test 0","url": "https://opfab.github.io/","label": "menu.first"},
    {"id": "uid test 1","url": "https://www.la-rache.com","label": "menu.second"}
  ],
  "i18nLabelKey": "businessconfig.label",
  "processes": {
    "process": {
      "states": {
        "firstState": {
          "details": [
            {
              "title": {
                "key": "template.title"
              },
              "templateName": "operation"
            }
          ]
        }
      }
    }
  }
}
After
{
  "id": "TEST",
  "version": "1",
  "name": "process.label",
  "defaultLocale": "fr",
  "menuLabel": "menu.label",
  "menuEntries": [
    {"id": "uid test 0","url": "https://opfab.github.io/","label": "menu.first"},
    {"id": "uid test 1","url": "https://www.la-rache.com","label": "menu.second"}
  ],
  "states": {
    "firstState": {
      "name" :"mystate.label",
      "details": [
        {
          "title": {
            "key": "template.title"
          },
          "templateName": "operation"
        }
      ]
    }
  }
}
You should also make sure that the new i18n label keys that you introduce match what is defined in the i18n folder of the bundle.
2.1.2.2. On the Cards model
Field before Field after Usage

publisherVersion

processVersion

Identifies the version of the bundle. It was renamed for consistency now that bundles are linked to processes not publishers

process

process

This field is now required and should match the id field of the process (bundle) to use to render the card.

processId

processInstanceId

This field is just renamed , it represent an id of an instance of the process

These changes impact both current cards from the feed and archived cards.

The id of the card is now build as process.processInstanceId an not anymore publisherID_process.

2.2. Change on the web-ui.json

The parameter navbar.thirdmenus.type has been removed from this file. Starting from this release the related functionality has been moved on bundle basis and it’s not more global. See "Changes on bundle config.json" for more information.

2.3. Changes on bundle config.json

Under menuEntries a new subproperty has been added: linkType. This property replace the old property navbar.thirdmenus.type in web-ui.json, making possible a more fine control of the related behaviour.

2.4. Component name

We also change the component name of third which is now named businessconfig.

2.5. Changes to the endpoints

The /third endpoint becomes /businessconfig/processes.

2.6. Migration steps

This section outlines the necessary steps to migrate existing data.

You need to perform these steps before starting up the OperatorFabric instance because starting up services with the new version while there are still "old" bundles in the businessconfig storage will cause the businessconfig service to crash.
  1. Backup your existing bundles and existing Mongo data.

  2. Edit your bundles as detailed above. In particular, if you had bundles containing several processes, you will need to split them into several bundles. The id of the bundles should match the process field in the corresponding cards.

  3. If you use navbar.thirdmenus.type in web-ui.json, rename it to navbar.businessmenus.type

  4. Run the following scripts in the mongo shell to copy the value of publisherVersion to a new processVersion field and to copy the value of processId to a new processInstanceId field for all cards (current and archived):

    Current cards
    db.cards.updateMany(
    {},
    { $rename: { "publisherVersion": "processVersion", "processId": "processInstanceId" } }
    )
    Archived cards
    db.archivedCards.updateMany(
    {},
    { $rename: { "publisherVersion": "processVersion", "processId": "processInstanceId" } }
    )
  5. Make sure you have no cards without process using the following mongo shell commands:

    db.cards.find({ process: null})
    db.archivedCards.find({ process: null})
  6. If it turns out to be the case, you will need to set a process value for all these cards to finish the migration. You can do it either manually through Compass or using a mongo shell command. For example, to set the process to "SOME_PROCESS" for all cards with an empty process, use:

    db.cards.updateMany(
    { process: null },
    {
    $set: { "process": "SOME_PROCESS"}
    }
    )
    db.archivedCards.updateMany(
    { process: null },
    {
    $set: { "process": "SOME_PROCESS"}
    }
    )
  7. If you have any code or scripts that push bundles, you should update it to point to the new endpoint.

3. Migration Guide from release 1.7.0 to release 1.8.0

3.1. Card detail definition in business configuration

There is no more the need for multiple definitions of card’s detail rendering because of the removal of multi-tab rendering. The rendering of the detail of a card is configured specifying the detail title, template name and the list of styles.

In the Businessconfig model definition the field details has been removed.

The new fields detailTitle, templateName and styles have been added.

Here is an example of a simple config.json file:

Before
{
  "id": "TEST",
  "version": "1",
  "name": "process.label",
  "states": {
    "firstState": {
      "name" :"mystate.label",
      "details": [
        {
          "title": {
            "key": "template.title"
          },
          "templateName": "operation",
          "styles": ["style1","style2"]
        }
      ]
    }
  }
}
After
{
  "id": "TEST",
  "version": "1",
  "name": "process.label",
  "states": {
    "firstState": {
      "name" :"mystate.label",
      "detailTitle": {
        "key": "template.title"
        },
      "templateName": "operation",
      "styles": ["style1","style2"]
    }
  }
}

3.2. Business menu definition

The business menu are not configured anymore in the business definition but in a specific single configuration file called ui-menu.json. You must move your configuration from the config.json to this new file, see documentation .

4. Migration Guide from release 1.8.0 to release 2.0.0

4.1. AcknowledgmentAllowed field in business configuration

In the process state definition the acknowledgementAllowed has been renamed to acknowledgmentAllowed. The acknowledgmentAllowed field in no more a boolean type and can now assume one of the following values:

  • "Never": acknowledgment not allowed (default value)

  • "Always": acknowledgment allowed

  • "OnlyWhenResponseDisabledForUser": acknowledgment allowed only when the response is disabled for the user

Here is an example of a simple config.json file:

{
  "id": "TEST",
  "version": "1",
  "name": "process.label",
  "states": {
    "firstState": {
      "name" :"mystate.label",
      "details": [
        {
          "title": {
            "key": "template.title"
          },
          "templateName": "operation",
          "styles": ["style1","style2"]
        }
      ],
      "acknowledgmentAllowed": "Never"
    }
  }
}

4.2. Response card : templateGateway.applyChild()

For card with responses, it is not necessary to call templateGateway.applyChildCards() in your template on loading anymore, OperatorFabric will do it.

5. Migration Guide from release 2.2.0 to release 2.3.0

5.1. Communication between template and opfab

5.1.1. Getting response data from template

Some renaming has been done in version 2.3.0 :

  • the method to have the response information from template is rename in getUserResponse instead of validyForm.

  • the return object of this method shall now contains the response data in field responseCardData instead of formData

So if you have the following code in your template :

    templateGateway.validyForm = function () {
        const response = document.getElementById('response').value;
        const formData = { response: response };
        return {
            valid: true,
            formData: formData
        };
    }

It must be modify this way :

    templateGateway.getUserResponse = function () {
        const response = document.getElementById('response').value;
        const responseCardData = { response: response };
        return {
            valid: true,
            responseCardData: responseCardData
        };

    }

5.1.2. Getting the information if the user can respond

To know from a template that the user can respond to a card you must now call templateGateway.isUserAllowedToRespond() instead of implementing the method templateGateway.setUserCanRespond()

So if you have the following code in your template :

    templateGateway.setUserCanRespond = function(responseEnabled) {
        if (responseEnabled) {
            // do something
        } else {
            // do something
        }
    }

It must be modify this way :

    if (templateGateway.isUserAllowedToRespond()) {
         // do something
    } else {
        // do something
    }

6. Migration Guide from release 2.3.0 to release 2.4.0

6.1. Send card

The API does not provide an endpoint to send an array of cards anymore.

  • The endpoint cards now accepts only one card

  • The endpoint async/cards no longer exists

So if you used to send several cards as array, you need to modify your code to send hem one by one via endpoint cards.

6.2. Package name change

The name of the packages in the OperatorFabric code has been changed from org.lfenergy.operatorfabric. to org.opfab. in preparation for an upload of the client library to Maven Central. You need to update any code using the client library to reflect this name change.

7. Migration Guide from release 2.4.0 to release 2.5.0

7.1. Send card

The API endpoint to send a card doesn’t return CardCreationReport object anymore. The endPoint cards now returns :

  • status code 201 (Created) in case of success.

  • status code 400 (Bad request) in case of a request with wrong data.

So if you use CardCreationReport object when you send card, you need to modify your code to not use it anymore and to test the status code returned.

7.2. Card recipients

The deprecated card field recipient is now deleted. So you have to use the fields userRecipients, groupRecipients and entityRecipients to send a card.

8. Migration Guide from release 2.5.0 to release 2.6.0

8.1. Inter-service communication - Ribbon

Ribbon was used by our Feign client that lets business services get information on the current user from the Users service.

Ribbon is no longer maintained, so we chose to remove it from our dependencies (mostly because it was blocking any update of the other Spring dependencies).

Instead, the Feign client now relies on an external property to know where the Users service can be reached, and there is no load-balancing for now.

This requires a change to service configuration: the users.ribbon.listOfServers property should be removed and replaced with operatorfabric.servicesUrls.users.

It should be set in the configuration of all business services (except users), or in the common configuration.

Example
operatorfabric:
  servicesUrls:
    users: "http://localhost:2103"

According to the Feign documentation, the property should contain "an absolute URL or resolvable hostname (the protocol is optional)".

This property is mandatory, if it is absent the application won’t start.
While the ribbon property could handle an array of several urls, this new property expects a single url as there is no load-balancing mechanism for now.

9. Migration Guide from release 2.6.0 to release 2.7.0

9.1. Send card

The API endPoint cards will now require authentication by default. It is possible to configure the endpoint to not require authentication by setting the configuration parameter checkAuthenticationForCardSending to false in cards-publication service configuration file.

10. Migration Guide from release 2.7.0 to release 2.8.0

10.1. UI Configuration Management

The web-ui container has two configuration files: web-ui.json and ui-menu.json.

To avoid maintaining separate copies of these files for each run environment (docker, dev, Cypress), the reference configuration will be the one for the docker mode, with the others being created by script, changing only the properties that should be different between environments (e.g. environmentName). Only the docker configuration will be version-controlled. The scripts creating the configuration are launched by the docker-compose.sh and docker-compose-cypress.sh.

As a consequence, the web-ui.json and ui-menu.json files have been moved from config/xxx/ to config/xxx/ui-config. The volumes in the docker-compose.yml files have been updated accordingly.

This new organization will also allow us to run Cypress tests against different versions of the configuration, for example to test the behaviour of a property meant to hide a component. See the Cypress tests README (src/test/cypress/README.adoc) for more information.

All modes (dev, docker, config) now use the PASSWORD authentication flow by default. If you want to test with another authentication flow, you should use the setSecurityAuthFlow.sh script AFTER the containers have been started.
Example to use the CODE flow in dev mode
cd src/test/resources
.setSecurityAuthFlow.sh dev CODE

10.2. Management of visible menus

The visibility of some core OperatorFabric menus (monitoring, logging, feed configuration screen,…​) was so far configurable for a given OperatorFabric instance through various properties in web-ui.json.

As of this version, it has been unified with that of custom menus:

  • It will now be managed in ui-menu.json along with custom menus

  • It is now possible to make these menus visible only for certain groups

The following properties in web-ui.json are no longer supported and should be removed
  • navbar.hidden (array of menus to hide)

  • admin.hidden (boolean)

  • feedConfiguration.hidden (boolean)

  • realTimeUsers.hidden (boolean)

  • settings.nightDayMode (boolean)

New property in ui-menu.json
{
  "coreMenusConfiguration":
  [
    {
      "id": "coreMenuId1",
      "visible": true
    },
    {
      "id": "coreMenuId2",
      "visible": false
    },
    {
      "id": "coreMenuId3",
      "visible": true,
      "showOnlyForGroups": ["ADMIN","SOME_OTHER_GROUP"]
    }
  ]
}

All core menus should be listed under this new coreMenusConfiguration property in ui-menu.json, each with their own visible and (optionally) showOnlyForGroups property.

Necessary actions for the migration:

  • Remove the deprecated properties listed above from your web-ui.json

  • Add a coreMenusConfiguration block to your ui-menu.json (see the documentation for details and a full example)

10.3. Simplification MongoDB Configuration

We are getting rid of our specific MongoDB configuration to let SpringBoot autoconfigure it. As a result, we are removing support for the spring.data.mongodb.uris property in favour of the standard spring.data.mongodb.uri property. Please change the application configuration files for the services accordingly.

This property can only hold a single URI.

11. Migration Guide from release 2.10.0 to release 2.11.0

11.1. Logging screen : Filter with tags list

As for archives screen, now you have to specify the list of tags you want to see in the filter of logging screen. You have to set this list in the web-ui.json file, with the parameter logging.filters.tags.list. For example :

"logging": {
  "filters": {
    "tags": {
      "list": [
        {
          "label": "Label for tag 1",
          "value": "tag1"
        }
      ]
    }
  }
}

12. Migration Guide from release 2.11.0 to release 3.0.0

12.1. Changes in configuration due to business translation mechanism removal

In order to remove unnecessary complexity for third-party, we have decided to remove translation for some of business data, this implies the following migration tasks :

12.1.1. Template directory

The template directory does not contain language repository anymore. There is one template per process/state and the templates are located directly in this directory. So you have to move your template for your language directly to the template directory

12.1.2. Changes in config.json

In config.json, the fields process.name, state.name and state.description must not contain i18n data anymore, they must only contain string data. These data will be simply displayed on the screen.

12.1.3. New file i18n.json

The bundle shall contain a new i18n.json file in the root directory. The i18n.json file contains internationalization information for title and summary fields. We keep an i18n mechanism for these two fields in order to have the possibility to adapt the title or summary of the card without having to modify the code of the third party tool sending the card (using only one "language" for translation)

Here is an example file :

{
	"message":{
		"title":"Message",
		"summary":"Message received"
	},
	"chartDetail" : { "title":"A Chart"},
	"chartLine" : { "title":"Electricity consumption forecast"},
	"question" : {"title": "⚡ Planned Outage"},
	"contingencies": {"title" : "⚠️ Network Contingencies ⚠️","summary":"Contingencies report for French network"},
	"processState": {
		"title":"Process state ({{status}})"
	}
}

12.1.4. i18n folder

The folder i18n and contained files has to be removed from bundle structure.

12.1.5. Processes groups

There is no possibility anymore to have translation for the process group name. You can just define the name of the group in the uploaded file. Here is an example of this file :

{
  "groups": [
    {
      "id": "processgroup1",
      "name": "Process Group 1",
      "processes": [
        "process1",
        "process2"
      ]
    },
    {
      "id": "processgroup2",
      "name": "Process Group 2",
      "processes": [
        "process3",
        "process4"
      ]
    }
  ]
}

12.1.6. Script to migrate an existing database

Opfab 3.0 needs two new fields in database : titleTranslated and summaryTranslated. In order to add these two new fields to an existing database, you have to pull the image migration-opfab3, go to the directory OF_HOME/src/tooling/migration-opfab3 and execute the script docker-compose.sh, this way :

./docker-compose.sh <containerNameMongoDB> <portMongoDB> <loginMongoDB> <passwordMongoDB> <pathToBundlesDirectory>

The bundles directory is the directory where you store all the "untar" bundles in the new format with the i18n.json file. It is not the directory where the opfab instance stores the bundles.

12.2. Configuration file web-ui.json

Some attributes have been renamed to be more consistent with their meaning. Here are these attributes :

  • settings.infos.description renamed settings.infos.hide.description

  • settings.infos.language renamed settings.infos.hide.language

  • settings.infos.timezone renamed settings.infos.hide.timezone

  • settings.infos.tags renamed settings.infos.hide.tags

  • settings.infos.sounds renamed settings.infos.hide.sounds

So if you use these fields in web-ui.json file, you have to rename them.

12.3. Configuration file common-docker.yml

A new parameter named operatorfabric.servicesUrls.businessconfig has to be added to your configuration file common-docker.yml (or equivalent)

For example the following configuration:

operatorfabric:
  businessLogActivated: true
  servicesUrls:
    users: "users:8080"

becomes:

operatorfabric:
  businessLogActivated: true
  servicesUrls:
    users: "users:8080"
    businessconfig: "businessconfig:8080"

12.4. Nginx.conf.template file

In order to have a better organized file, we have modified nginx.conf.template file, more precisely the information for location /cardspub/cards. Please report this modification to your local config.

13. Migration Guide from release 3.0.0 to release 3.1.0

13.1. Kafka date format

The signature for sending card dates via Kafka have been changed to better reflect the REST API. Instead of sending the date in seconds since epoch, you can now use the Java Instant object. The following methods are affected:

  • startDate

  • endDate

  • lttd

  • publishDate

  • TimeSpan.setStart

  • TimeSpan.setEnd

For example the following code:

Card card = Card.newBuilder().setStartDate(12345L).build();

becomes:

Card card = Card.newBuilder().setStartDate(Instant.now()).build();

14. Migration Guide from release 3.1.0 to release 3.2.0

14.1. Cache configuration for i18n files

Add the following lines in your nginx.conf to avoid keeping in cache old translation files when migrating opfab

  location /ui/assets/i18n/ {
    add_header Cache-Control "no-cache";
    alias /usr/share/nginx/html/assets/i18n/;
  }

14.2. Tag feed filter removal

The feature to filter tags in the feed has been removed. In consequence, you can remove the following parameters in your web-ui.json configuration file:

  • settings.tags.hide

  • settings.infos.hide.tags

15. Migration Guide from release 3.4.0 to release 3.5.0

15.1. Timezone management removal

The feature to manage timeline inside opfab has been removed. In consequence, you can remove the following parameters in your web-ui.json configuration file:

  • i10n.supported.time-zones

  • settings.infos.hide.timezone

15.2. Kafka card format changes

The Kafka message schema has been changed. The single card used to send messages to and receive from Operator Fabric has been split into two cards; one for sending to OpFab and one for receiving messages from OpFab. The CardCommand structure now contains a card (to OpFab) and a responseCard (from OpFab). You will need to change the Kafka listener to get the response card.

For example change

 @KafkaListener
    public void receivedResponseCard(@Payload ConsumerRecord<String, CardCommand> consumerRecord) {
        CardCommand cardCommand = consumerRecord.value();
        Card = cardCommand.getCard();

to

 @KafkaListener
    public void receivedResponseCard(@Payload ConsumerRecord<String, CardCommand> consumerRecord) {
        CardCommand cardCommand = consumerRecord.value();
        ResponseCard = cardCommand.getResponseCard();

15.2.1. Redirect to business application from a card

The templateGateway.redirectToBusinessMenu function to redirect to business application from a card has changed. The third argument of the function is now a url extension that can contain sub paths and/or parameters instead of only parameters.

You will need to change the call adding a '?' character at the beginning of the third argument.

For example change:

templateGateway.redirectToBusinessMenu('myMenu','myEntry','param1=aParam&param2=anotherParam')

to

templateGateway.redirectToBusinessMenu('myMenu','myEntry','?param1=aParam&param2=anotherParam')

16. Migration Guide from release 3.5.0 to release 3.6.0

16.1. Template rendering

Bootstrap library has been migrate to v5.

If you use bootstrap css classes in your templates, it’s strongly recommended to check your template rendering after migration.

Charts library has been upgraded from version 3.2.1 to 3.7.1

If you use charts in your templates, it’s strongly recommended to check your template rendering after migration.

16.2. Mongo data migration steps

This section outlines the necessary steps to migrate existing data.

If you use response card feature, you need to perform these steps before starting up the OperatorFabric instance to avoid displaying wrong data in archives page.
  1. Backup your existing Mongo data.

  2. Run the following scripts in the mongo shell to update the value of the new field deletionDate for archived cards:

    db.archivedCards.updateMany(
    {"deletionDate": {"$exists": false}},
    {"$set": {"deletionDate": new ISODate("1970-01-01T00:00:00Z")}}
    )

16.3. About screen

You do not need anymore to precise opfab version in web-ui.json to see it on about screen. So you need to remove the corresponding line. For example :

      "operatorfabric": {
        "name": "OperatorFabric",
        "rank": 0,
        "version": "2.5.0.RELEASE"
      }

16.4. Deprecated feature

16.4.1. Method templateGateway.getSpecificCardInformation()

Implementation of method templateGateway.getSpecificCardInformation() in usercard templates is now deprecated, replace it by usercardTemplateGateway.getSpecificCardInformation(). It is just a naming change, the behavior is the same.

16.4.2. Restrict recipient dropdown list for user

Using "recipientList" in state definition (in config.json) is now deprecated

If you use "recipientList" to restrict the list of recipients shown to user, replace it with code in template as in the following example :

    usercardTemplateGateway.setDropdownEntityRecipientList([
            {"id": "ENTITY_FR", "levels": [0,1]},
            {"id": "IT_SUPERVISOR_ENTITY"}
        ]);

16.4.3. Set the list of recipients

Using "recipientList" in state definition (in config.json) is now deprecated

If you use "recipientList" to set the list of recipients, provide now the list of recipients when returning the card object in usercardTemplateGateway.getSpecificCardInformation() in the field entityRecipients.

Example:

    usercardTemplateGateway.getSpecificCardInformation = function () {
        const message = document.getElementById('message').value;
        const card = {
          summary : {key : "message.summary"},
          title : {key : "message.title"},
          entityRecipients: ["ENTITY_FR","IT_SUPERVISOR_ENTITY"],
          data : {message: message}
        };
        if (message.length<1) return { valid:false , errorMsg:'You must provide a message'}
        return {
            valid: true,
            card: card
        };

17. Migration Guide from release 3.6.0 to release 3.7.0

17.1. Docker images names changed

From version 3.7.0 the docker names of the former "business services" are changed. Here are there old names and the new ones.

Old docker name New docker name

lfeoperatorfabric/of-cards-consultation-business-service:3.6.0.RELEASE

lfeoperatorfabric/of-cards-consultation-service:3.7.0.RELEASE

lfeoperatorfabric/of-cards-publication-business-service:3.6.0.RELEASE

lfeoperatorfabric/of-cards-publication-service:3.7.0.RELEASE

lfeoperatorfabric/of-users-business-service:3.6.0.RELEASE

lfeoperatorfabric/of-users-service:3.7.0.RELEASE

lfeoperatorfabric/of-businessconfig-business-service:3.6.0.RELEASE

lfeoperatorfabric/of-businessconfig-service:3.7.0.RELEASE

You must change your docker-compose files accordingly.

17.2. Third parties configuration

The configuration of the third parties applications as external recipents has changed. It is now possible to configure wether the user token shall be propagated to the third party or not by setting the "propagateUserToken" boolean property.

If you have third parties configured in your 'cards-publication.yml' you should change the configuration as follows:

From:

externalRecipients-url: "{\
           third-party1: \"http://thirdparty1/test1\", \
           third-party2: \"http://thirdparty2:8090/test2\", \
           }"

To

external-recipients:
  recipients:
    - id: "third-party1"
      url: "http://thirdparty1/test1"
      propagateUserToken: true
    - id: "third-party2"
      url: "http://thirdparty2:8090/test2"
      propagateUserToken: true

17.3. Rename attribute externalDeviceId

It is now possible to have several external device systems, therefore the attribute externalDeviceId is now renamed into externalDeviceIds and is now a list.

17.3.1. In the configuration file

In the configuration file, replace

userConfigurations:
        - userLogin: operator1_fr
          externalDeviceId: CDS_1
        - userLogin: operator2_fr
          externalDeviceId: CDS_2
        - userLogin: operator3_fr
          externalDeviceId: CDS_3
        - userLogin: operator4_fr
          externalDeviceId: CDS_1

by

userConfigurations:
        - userLogin: operator1_fr
          externalDeviceIds: ["CDS_1"]
        - userLogin: operator2_fr
          externalDeviceIds: ["CDS_2"]
        - userLogin: operator3_fr
          externalDeviceIds: ["CDS_3"]
        - userLogin: operator4_fr
          externalDeviceIds: ["CDS_1"]

17.3.2. Changes in the Mongo data base

17.3.2.1. Before the migration

Before the migration to 3.7.0, one should save its current data base, then add the attribute "externalDeviceIds" based on the value of the existing attribute "externalDeviceId". To add this attribute, simply launch the commands :

var collection = db.getCollection("userConfigurations")
collection.find().forEach(function(user) {collection.updateOne({_id: user._id}, {$set: {externalDeviceIds: [user.externalDeviceId]}})})
17.3.2.2. Once the migration is done

Once the migration to 3.7.0 is done, the attribute "externalDeviceId" is not used anymore. You can remove it by launching :

var collection = db.getCollection("userConfigurations")
collection.find().forEach(function(user) {collection.updateOne({_id: user._id}, {$unset: {"externalDeviceId": 1}})})

17.4. Deprecated feature

17.4.1. Field recurrence

Using "recurrence" field returned by getSpecificCardInformation() method definition is now deprecated.

If you are using the "viewCardInAgenda" and "recurrence" field, use the "timeSpans" field instead when returning the card object in usercardTemplateGateway.getSpecificCardInformation() to configure the visibility of the card in timeline and agenda.

Example:

    usercardTemplateGateway.getSpecificCardInformation = function () {
        const message = document.getElementById('message').value;
        const card = {
          summary : {key : "message.summary"},
          title : {key : "message.title"},
          entityRecipients: ["ENTITY_FR","IT_SUPERVISOR_ENTITY"],
          data : {message: message}
        };

        const recurrence = {
            daysOfWeek : [1,2,3],
            hoursAndMinutes : {hours:10,minutes:44},
            durationInMinutes: 15
        }

        const mystartDate = new Date();
        const timeSpans = [{
            startDate: mystartDate.getTime(),
            endDate: mystartDate.getTime() + 7 * 24 * 3600000,
            recurrence: recurrence
        }]

        return {
            valid: true,
            card: card,
            timeSpans: timeSpans
        };

18. Migration Guide from release 3.7.0 to release 3.8.0

18.1. Kafka card format changes

The Kafka message schema has been changed. Two new, optional fields are added:

  • wktGeometry

  • wktProjection

Make sure your Kafka consumers and producers are updated and use the latest card and responseCard definitions.

19. Migration Guide from release 3.8.x to release 3.9.0

19.1. web-ui.json config file

To declare settings parameters, you now need to group all fields under settings: { } and you must not use a statement like this one : settings.replayInterval: 10

For example:

Replace the following invalid settings config

  "settings.replayInterval": 10,
  "settings.replayEnabled": true,
  "settings": {
    "about": {
      "keycloack": {
        "name": "Keycloak",
        "rank": 2,
        "version": "6.0.1"
      },
    }
    "locale": "en",
    "dateTimeFormat": "HH:mm DD/MM/YYYY",
    "dateFormat": "DD/MM/YYYY",
    "styleWhenNightDayModeDesactivated": "NIGHT"
  },

By this valid one :

  "settings": {
    "replayInterval": 10,
    "replayEnabled": true,
    "about": {
      "keycloack": {
        "name": "Keycloak",
        "rank": 2,
        "version": "6.0.1"
      },
    }
    "locale": "en",
    "dateTimeFormat": "HH:mm DD/MM/YYYY",
    "dateFormat": "DD/MM/YYYY",
    "styleWhenNightDayModeDesactivated": "NIGHT"
  },