Skip to content

Latest commit

 

History

History
204 lines (160 loc) · 10.7 KB

v3.0.0.md

File metadata and controls

204 lines (160 loc) · 10.7 KB

Webapp - v3.0.0 migration guide

Allow new redirection URL after login

The post-login redirection URL has been changed from /scenario to /sign-in. This URL has been modified to prevent a change of page during the interaction with the Microsoft Authentication Library (MSAL) pop-up, that could cause the login to fail in some browsers.

You must change the accepted redirect URLs in the Azure portal of your App Registration, in the Authentication blade, and replace /scenario by /sign-in in the redirect URL of your web-app.

Update configuration files

Migration script

The structure of the front-end configuration files has changed in v3.0.0. To make the migration easier, a migration script has been created to automatically convert JS config files to the new format. You can run this script from the root folder of your webapp (still in v2.x) with:

# 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 v3

The script should create a folder src/config_v3 with the expected files structure for v3.0.0 of the webapp. After merging (or rebasing on) the tag v3.0.0-vanilla, you will be able to replace the content of the folder src/config by the files generated in src/config_v3.

Detailed changes in the configuration folder

In case the migration does not work for your solution, or if you are just curious, this section provides a list of modifications to apply in your configuration folder to migrate from v2.x to v3.0.0.

Optional files

Renamed files

  • Dashboards.js has been renamed to PowerBI.js; this file now also defines & exports these constants:
    • POWER_BI_WORKSPACE_ID (previously in AppInstance.js)
    • USE_POWER_BI_WITH_USER_CREDENTIALS (previously in AppConfiguration.js)
    • SCENARIO_VIEW_IFRAME_DISPLAY_RATIO (previously in AppConfiguration.js)
    • DASHBOARDS_VIEW_IFRAME_DISPLAY_RATIO (previously in AppConfiguration.js)
  • AppInstance.js has been renamed to GlobalConfiguration.js; this file now only contains the 6 parameters below (other parameters have been moved to new files):
    • AZURE_TENANT_ID
    • APP_REGISTRATION_CLIENT_ID
    • COSMOTECH_API_SCOPE
    • DEFAULT_BASE_PATH
    • ORGANIZATION_ID
    • WORKSPACE_ID

New files

  • ApplicationInsights.js defines & exports the constants ENABLE_APPLICATION_INSIGHTS (previously in AppConfiguration.js) and APPLICATION_INSIGHTS_INSTRUMENTATION_KEY (previously in AppInstance.js)
  • HelpMenuConfiguration.js defines & exports the following constants (previously in AppConfiguration.js):
    • SUPPORT_URL
    • COSMOTECH_URL
    • DOCUMENTATION_URL
    • APP_VERSION
  • Languages.js defines & exports the constants LANGUAGES and FALLBACK_LANGUAGE (previously in AppConfiguration.js)

Modified files

  • ScenarioParameters.js now also defines & exports these constants (previously in AppConfiguration.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

Other changes

The following parameters are highly technical and have been moved outside of the front-end configuration folder:

  • SESSION_INACTIVITY_TIMEOUT
  • SCENARIO_STATUS_POLLING_DELAY
  • SCENARIO_RUN_LOG_TYPE
  • POWER_BI_INFO_POLLING_DELAY

Transform your factories into React components

All generic factories that create tabs and inputs in Scenario Parameters have been transformed into React functional components and moved to the src/components/ScenarioParameters folder. Even if the factory mechanism is still supported in this version, it is considered deprecated and will be definitively removed in a future major version of the web app so we recommend to refactor all your custom factories into React functional components. It consists mainly in transforming the arguments of the create function in component's props:

// GenericTextInput replaces BasicTextInputFactory in v3:

import React from 'react';
import { BasicTextInput } from '@cosmotech/ui';
import { useTranslation } from 'react-i18next'; // using component's syntax lets you import the translation function directly in the input component
import PropTypes from 'prop-types'; // React PropTypes lets you check the type of passing values

export const GenericTextInput = ({ parameterData, parametersState, setParametersState, context }) => {
const { t } = useTranslation();

  // ...

  return (
    <BasicTextInput
     //...
    />
  );
};
GenericTextInput.propTypes = {
  parameterData: PropTypes.object.isRequired,
  parametersState: PropTypes.object.isRequired,
  setParametersState: PropTypes.func.isRequired,
  context: PropTypes.object.isRequired,
};

Note that unlike factories React components give access to the Redux store so, for example, there is no need to pass datasets as argument to your function since you can access it directly from component using useSelector() hook, like in GenericTable component:

// GenericTable component replaces TableFactory
// ...
const datasets = useSelector((state) => state.dataset?.list?.data);
// ...

Finally, editMode boolean is put in the context prop that can also serve as wrapper for every additional information, like isDarkTheme in the GenericTable component:

//...
return (
  <Table
    ...
    agTheme={context.isDarkTheme ? gridDark.agTheme : gridLight.agTheme}
    ...
  />
);

You can find more information about creating your custom components in the web app documentation.

New theme structure

In order to respect Material UI’s theme structure, the following changes have been made:

  • theme is dynamic and has to be imported from Redux from now on; a button in the app bar allows to switch between dark and light theme;
  • only palette.js, grid.js and pictures.js remain in dark and light theme directories:
    • palette.js overrides Material UI classic variables, and defines custom ones
      • primary, secondary, warning, success, info and error are overridden in palette.js only when needed;
      • main, dark, light and/or contrastText properties of the above categories are specified only when needed;
      • custom variables define the Sign In with Microsoft button, as well as colors for the Sign In page, and the app bar fixed colors; integrators can define their own ones, but I strongly recommend to only specify main, dark, light, and/or contrastText properties;
    • grid.js contains the specification for tables style in Scenario Parameters;
    • pictures.js contains two versions of Cosmo's logo (one with black text, one with white text) as well as light or dark background images used on the Sign In page;
  • typography.js has been removed, Material UI default file is enough for now; NB: this doesn’t mean integrators cannot override typographies if they need to: the webapp simply doesn’t need it right now;
  • override directory’s files have been removed, for Material UI is already powerful enough in most cases; NB: same goes for this directory: integrators can still override components if they so desire;

Migration to react-router v6

This section concerns projects that have developed custom views or routes only; if your web app uses build-in views, the following breaking changes shouldn’t impact it.

Web app v3.0.0 uses new version of React Router (v6) which implies some breaking changes:

  • the router doesn’t support custom routes anymore; <PrivateRoute> and <PublicRoute> components were deleted from @cosmotech/ui package so all custom routes in your web app must be replaced by regular <Route> (main routes have already been replaced in v3).
  • useHistory() hook must be replaced with useNavigate() hook or <Navigate /> component
  • if you use custom views, the corresponding component must be called differently in the AppLayout.js file:
const TABS = [
  {
    key: view key,
    label: view label,
    to: view path,
    // v2 :
    render: () => <View /> // eslint-disable-line
    // v3:
    render: <View /> // eslint-disable-line
  },
]
  • <Redirect> and <Switch> components have been deprecated in the new version of React Router 6 and must be replaced by <Routes>. To avoid any confusion and stick to the React Router new syntax, the new AppRoutes component (src/AppRoutes.js) now replaces Routes component and regroups all application’s routes from Routes and TabLayout (src/layouts/TabLayout/TabLayout.js). If you have customized routes in TabLayout, move all your modifications in AppRoutes:
const AppRoutes = (props) => {
  return (
    <Routes>
      <Route index element={...} replace />
      <Route path="/sign-in" element={...} />
      <Route path="/accessDenied" element={...} />
      <Route path="/" element={<TabLaout />}>
        {tabs.map((tab) => (
          <Route
            key={tab.key}
            path={tab.to}
            element={...}
          >
            {tab.to === '/scenario' && (
              <Route
                path="/scenario/:id"
                element={...}
              />
            )}
          </Route>
        ))}
      </Route>
    </Routes>
  );
};

For more information, see the React Router migration guide.