-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add migration guide for v5.0.0
- Loading branch information
Showing
1 changed file
with
273 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,273 @@ | ||
| # Webapp - v5.0.0 migration guide | ||
|
|
||
| ## Release notes | ||
|
|
||
| For a summary of the bug fixes, new features and breaking changes of v5.0.0, please check the | ||
| [release notes](https://github.com/Cosmo-Tech/azure-sample-webapp/releases/tag/v5.0.0-vanilla). | ||
|
|
||
| ## Breaking changes | ||
|
|
||
| > **Note** | ||
| > A migration script to help you migrate your config folder from v4 to v5 is available. Please refer to section | ||
| > _Migration script_ | ||
| ### Front-end configuration files | ||
|
|
||
| #### Configuration simplification | ||
|
|
||
| In order to simplify the webapp configuration, some settings have been totally removed and replaced by an automatic detection and behavior decision. This means that you no longer need to specify the settings below. | ||
|
|
||
| ##### `dataCy` metadata of scenario parameters | ||
|
|
||
| The field `dataCy` is no longer used in scenario parameters configuration. This tag in the DOM is usually only used for automated tests (e.g. with cypress and jest). Starting with v5.0, the `data-cy` metadata for input components will be automatically generated based on the **input component type** and the **parameter id**. Here are the patterns to use for each input component provided with the webapp: | ||
|
|
||
| - `GenericDateInput`: `date-input-[scenario parameter id]` | ||
| - `GenericEnumInput`: `enum-input-[scenario parameter id]` | ||
| - `GenericNumberInput`: `number-input-[scenario parameter id]` | ||
| - `GenericRadioInput`: `radio-input-[scenario parameter id]` | ||
| - `BasicSliderInput`: `slider-input-[scenario parameter id]` | ||
| - `GenericTable`: `table-[scenario parameter id]` | ||
| - `GenericTextInput`: `text-input-[scenario parameter id]` | ||
| - `GenericToggleInput`: `toggle-input-[scenario parameter id]` | ||
| - `GenericUploadFile`: `file-upload-[scenario parameter id]` | ||
|
|
||
| Example of changes in your configuration file: | ||
|
|
||
| ```js | ||
| const PARAMETERS = { | ||
| nb_waiters: { | ||
| dataCy: 'waiters-input', | ||
| defaultValue: 5, | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| should become: | ||
|
|
||
| ```js | ||
| const PARAMETERS = { | ||
| nb_waiters: { | ||
| defaultValue: 5, | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| Automated tests using the data-cy metadata also have to be changed to look for `number-input-nb_waiters` (provided this parameter was used in a `GenericNumberInput` component) instead of `waiters-input` | ||
|
|
||
| ##### Extra scenario metadata | ||
|
|
||
| The following options are no longer used in the file `src/config/ScenarioParameters.js`: | ||
|
|
||
| - `ADD_SCENARIO_NAME_PARAMETER` | ||
| - `ADD_SCENARIO_ID_PARAMETER` | ||
| - `ADD_SCENARIO_LAST_RUN_ID_PARAMETER` | ||
| - `ADD_SCENARIO_PARENT_ID_PARAMETER` | ||
| - `ADD_SCENARIO_PARENT_LAST_RUN_ID_PARAMETER` | ||
| - `ADD_SCENARIO_MASTER_ID_PARAMETER` | ||
| - `ADD_SCENARIO_MASTER_LAST_RUN_ID_PARAMETER` | ||
| - `ADD_SCENARIO_RUN_TEMPLATE_NAME_PARAMETER` | ||
|
|
||
| Instead, the webapp will automatically generate the values and send these parameters **if the parameters ids below are found in the parameters of the currently selected run template**: | ||
|
|
||
| - `ScenarioName` | ||
| - `ScenarioId` | ||
| - `ScenarioLastRunId` | ||
| - `ParentId` | ||
| - `ParentLastRunId` | ||
| - `MasterId` | ||
| - `MasterLastRunId` | ||
| - `RunTemplateName` | ||
|
|
||
| #### New settings in Solution and Workspace data | ||
|
|
||
| Because of the new **workspace selector** feature, we must **provide all the information** required by the webapp in | ||
| Solution and Workspace objects stored by the Cosmo Tech API, and be able to **override** them for local webapp | ||
| development. **The following files have thus been removed**: | ||
|
|
||
| - _src/config/InstanceVisualization.js_ → Workspace data | ||
| - _src/config/PowerBI.js_ → Workspace data | ||
| - _src/config/ScenarioParameters.js_ → Solution data | ||
|
|
||
| Optionally, **you can now override the data of multiple solutions and workspaces** by using the files | ||
| _src/config/overrides/Solutions.js_ and _src/config/overrides/Workspaces.js_. Complete examples of format for these | ||
| files can be found in the GitHub repository: | ||
|
|
||
| - [Solutions.js](https://github.com/Cosmo-Tech/azure-sample-webapp/blob/c60534b381efaec4904157b5fa87f615d3b1de68/src/config/overrides/Solutions.js) | ||
| - [Workspaces.js](https://github.com/Cosmo-Tech/azure-sample-webapp/blob/c60534b381efaec4904157b5fa87f615d3b1de68/src/config/overrides/Workspaces.js) | ||
|
|
||
| ##### Solution | ||
|
|
||
| **Scenario parameters** (a.k.a. run template parameters) can now be fully configured in the solution description (e.g. in a _Solution.yaml_ file), by using the fields below: | ||
|
|
||
| - `[solution].parameters.[parameter].options.enumValues` | ||
| - `[solution].parameters.[parameter].options.defaultFileTypeFilter` | ||
| - `[solution].parameters.[parameter].options.connectorId` | ||
| - `[solution].parameters.[parameter].options.description` | ||
| - `[solution].parameters.[parameter].options.subType` | ||
| - `[solution].parameters.[parameter].options.columns` | ||
| - `[solution].parameters.[parameter].options.hasHeader` | ||
| - `[solution].parameters.[parameter].options.dateFormat` | ||
|
|
||
| **Parameters groups** also have new settings fields in the solution description: | ||
|
|
||
| - `[solution].parameterGroups.[group].options.authorizedRoles` | ||
| - `[solution].parameterGroups.[group].options.hideParameterGroupIfNoPermission` | ||
|
|
||
| ##### Workspace | ||
|
|
||
| > **Warning** | ||
| > Mind the capital 'A' in `webApp`, in the workspace structure schema. | ||
| **PowerBI dashboards** can now be configured in the workspace description, by using the following fields: | ||
|
|
||
| - `[workspace].webApp.options.charts.dashboardsView` (previously `DASHBOARDS_LIST_CONFIG` in _src/config/PowerBI.js_) | ||
| - `[workspace].webApp.options.charts.scenarioView` (previously `SCENARIO_DASHBOARD_CONFIG` in _src/config/PowerBI.js_) | ||
| - `[workspace].webApp.options.charts.workspaceId` (previously `POWER_BI_WORKSPACE_ID` in _src/config/PowerBI.js_) | ||
| - `[workspace].webApp.options.charts.logInWithUserCredentials` (previously `USE_POWER_BI_WITH_USER_CREDENTIALS` in _src/config/PowerBI.js_) | ||
| - `[workspace].webApp.options.charts.scenarioViewIframeDisplayRatio` (previously `SCENARIO_VIEW_IFRAME_DISPLAY_RATIO` in _src/config/PowerBI.js_) | ||
| - `[workspace].webApp.options.charts.dashboardsViewIframeDisplayRatio` (previously `DASHBOARDS_VIEW_IFRAME_DISPLAY_RATIO` in _src/config/PowerBI.js_) | ||
|
|
||
| The optional instance view, to display a digital twin instance graph, can also be configured in the workspace description: | ||
|
|
||
| - `[workspace].webApp.options.instanceView.dataSource` (previously `DATA_SOURCE` in _src/config/InstanceVisualization.js_) | ||
| - `[workspace].webApp.options.instanceView.dataContent` (previously `DATA_CONTENT` in _src/config/InstanceVisualization.js_) | ||
|
|
||
| The help menu configuration can be overridden for each workspace, by defining the following fields in the workspace description: | ||
|
|
||
| - `[workspace].webApp.options.menu.documentationUrl` (can be used to override the value of `DOCUMENTATION_URL` in _src/config/HelpMenuConfiguration.js_) | ||
| - `[workspace].webApp.options.menu.supportUrl` (can be used to override the value of `SUPPORT_URL` in _src/config/HelpMenuConfiguration.js_) | ||
| - `[workspace].webApp.options.menu.organizationUrl` (can be used to override the value of `COSMOTECH_URL` in _src/config/HelpMenuConfiguration.js_) | ||
|
|
||
| #### New structure of front-end configuration files | ||
|
|
||
| In order to simplify data generation and automation scripts, the remaining configuration files in the src/config folder have been changed to JSON: | ||
|
|
||
| - _GlobalConfiguration.js → GlobalConfiguration.json_ | ||
| - _ApplicationInsights.js → ApplicationInsights.json_ | ||
| - _HelpMenuConfiguration.js → HelpMenuConfiguration.json_ | ||
| - _Languages.js → Languages.json_ | ||
|
|
||
| #### Changes in _GlobalConfiguration.js_ (now _GlobalConfiguration.json_) | ||
|
|
||
| The workspace selector feature removes the necessity of providing a workspace id in the webapp configuration. | ||
|
|
||
| Changes in file _src/config/GlobalConfiguration.js_: | ||
|
|
||
| ```js | ||
| export const WORKSPACE_ID = 'W-rXeBwRa0PM'; // This line must be deleted | ||
| ``` | ||
|
|
||
| After login, the webapp will now display a first page where users can select the workspace to open. If the connected user has access to only one workspace, then this workspace will be automatically opened. If you want to restrict the workspaces a webapp can open, a new setting `WORKSPACES_IDS_FILTER` is available in the file _GlobalConfiguration.json_. Its value can be left to `null` to disable workspace filtering, or you can provide a list of workspace ids to enable the filter. | ||
|
|
||
| Example of configuration for the new file src/config/GlobalConfiguration.json: | ||
|
|
||
| ```json | ||
| { | ||
| "APP_REGISTRATION_CLIENT_ID": "00000000-0000-0000-0000-000000000000", | ||
| "AZURE_TENANT_ID": "00000000-0000-0000-0000-000000000000", | ||
| "COSMOTECH_API_SCOPE": "http://dev.api.cosmotech.com/platform", | ||
| "DEFAULT_BASE_PATH": "https://dev.api.cosmotech.com/v2", | ||
| "ORGANIZATION_ID": "O-0123456789", | ||
| "WORKSPACES_IDS_FILTER": null | ||
| } | ||
| ``` | ||
|
|
||
| Or to restrict the workspace available from the webapp: | ||
|
|
||
| ```json | ||
| { | ||
| [...] | ||
| "WORKSPACES_IDS_FILTER": ["w-0000000000001","w-0000000000002","w-0000000000003"] | ||
| } | ||
| ``` | ||
|
|
||
| ### Webapp security - Impact on CSP | ||
|
|
||
| > **Note** | ||
| > This section is only relevant to you if your webapp uses the Instance Visualization view (a.k.a. flowchart) | ||
| Before release of v5.0, an entry was automatically added to CSP to authorize queries between the webapp and the URL of the _Function App_ responsible to send the instance data. | ||
|
|
||
| Starting with 5.0, because the instance view configuration is fetched from the `Worskpace` objects in Cosmo Tech API, the webapp can not guess automatically the list of URLs to allow for these Function Apps; you must add manually these URLs in the file **_config-overrides.js_**, in the root folder of the webapp repository. | ||
|
|
||
| Example for the brewery webapp: | ||
|
|
||
| ```js | ||
| const cspConfigPolicy = { | ||
| // [...] | ||
| 'connect-src': [ | ||
| // [...] | ||
| 'https://scenario-download-brewery-dev.azurewebsites.net', // the URL of your Function App must be added in the "connect-src" array, inside the "cspConfigPolicy" object | ||
| ], | ||
| }; | ||
| ``` | ||
|
|
||
| ### Environment variables | ||
|
|
||
| The `yarn start` command, declared in the file [package.json](https://github.com/Cosmo-Tech/azure-sample-webapp/blob/v5.0.0-vanilla/package.json), was previously adding an environment variable named `REACT_APP_VERSION`. In order to be consistent with the `APP_VERSION` parameter in the _HelpMenu_ configuration file and the `REACT_APP` prefix convention, **the environment variable `REACT_APP_VERSION` has been renamed to `REACT_APP_APP_VERSION`**. If your solution webapp uses custom code that reads this environment variable, you must rename it in your custom code. | ||
|
|
||
| ## Migration script | ||
|
|
||
| ### Install & use | ||
|
|
||
| The structure of the front-end configuration files has changed in v5.0.0. To make the migration easier, a [migration script](https://github.com/Cosmo-Tech/azure-sample-webapp/tree/main/scripts/migration) has been created to help you migrate your JS configuration files. You can run this script from the root folder of your webapp (still in v4.x) with: | ||
|
|
||
| ```sh | ||
| # Install & use node 16 if necessary | ||
|
|
||
| nvm install 16 | ||
| nvm use 16 | ||
|
|
||
| # Call the migration script from your webapp root folder | ||
|
|
||
| npx @cosmotech/migrate-azure-sample-webapp@latest v5 [-s path/to/solution.yaml] [-w path/to/worskpace.yaml] | ||
| ``` | ||
|
|
||
| The script should create a folder **_config_v5_** with either JSON or YAML files based on the options you provided. After merging (or rebasing on) the tag _v5.0.0-vanilla_, you will be able to use these files to update or override your solutions and workspaces. | ||
|
|
||
| > **Warning** > **Known issue**: JS code that needs to be evaluated in the file _src/config/ScenarioParameters.js_ won't be migrated | ||
| > properly; expressions will either be evaluated and their results will be hard-coded in the new config | ||
| > (e.g. a `new Date()` will be replaced by the date at the time the migration script has been launched), or the line | ||
| > might be dropped when writing the YAML file. | ||
| > | ||
| > If you really need to keep dynamic JS code in your Solution or Workspace configuration, you can keep some parts in the webapp configuration folder _src/config/overrides_ (c.f. section "New settings in Solution and Workspace data" above). | ||
| ### Strategies | ||
|
|
||
| Please note that you have two ways to use this migration script: **manual merge** with Solution and Workspace YAML files, or **assisted merge**. | ||
|
|
||
| #### Manual merge with Solution and Workspace YAML files | ||
|
|
||
| The first option is to use the migration script to generate JSON and YAML based on your current _src/config_ folder, and manually merge them with existing files. Using this method will generate these files: | ||
|
|
||
| - `solution.json` and `solution.yaml` | ||
| - `workspace.json` and `workspace.yaml` | ||
|
|
||
| After **checking that these files are correct**, you can either: | ||
|
|
||
| - manually merge them with existing files to update your solution and/or workspace objects _via_ the Cosmo Tech API | ||
| - or you can keep these values in the webapp configuration files to override existing solution and workspace files, via the files _src/config/overrides/Solutions.js_ and _src/config/overrides/Workspaces.js_ | ||
|
|
||
| > **Warning** > **Do not use API v1** to update workspaces with RBAC security defined (API v2), as it may lead to the **loss of the security data** | ||
| Example of migration command to prepare a manual merge of the webapp configuration: | ||
| `npx @cosmotech/migrate-azure-sample-webapp@latest v5` | ||
|
|
||
| #### Assisted merge with Solution and Workspace YAML files | ||
|
|
||
| The second option is to automatically merge your webapp configuration with **existing solution and workspace**. To use this option, you have to provide the migration script with the options `-s` and `-w` to point to your existing solution and workspace files. Using this method will generate these files, containing the data from all input sources: | ||
|
|
||
| - _mergedSolution.yaml_ | ||
| - _mergedWorkspace.yaml_ | ||
|
|
||
| After **checking that these files are correct**, you can use them to update your solution and/or workspace _via_ the Cosmo Tech API. | ||
|
|
||
| > **Warning** > **Do not use API v1** to update workspaces with RBAC security defined (API v2), as it may lead to the **loss of the security data** | ||
| Example of migration commands to merge webapp configuration with existing files _Solution.yaml_ and _Workspace.yaml_: | ||
|
|
||
| ```sh | ||
| npx @cosmotech/migrate-azure-sample-webapp@latest v5 -s $HOME/dev/brewery_sample_solution/Solution.yaml -w $HOME/dev/brewery_sample_solution/Workspace.yaml | ||
| restish dev update-workspace $CSM_ORG $CSM_WS_SAMPLE_DEV < config_v5/mergedWorkspace.yaml | ||
| restish dev update-solution $CSM_ORG $CSM_SOL_SAMPLE_DEV < config_v5/mergedSolution.yaml | ||
| ``` |