Migrating custom features

General Page

This document guides you through the steps to migrate the existing Sterling Store Engagement (Next-generation) custom features or flows to the corresponding features or flows in the new micro-frontend architecture-based customization framework.

Prerequisties

Ensure that you have set up UI middleware. Currently, download the middleware that is needed for the development of Sterling Store Engagement.

Complete the following steps for all the custom features or flows that are present within the <OLD_STORE_WORKSPACE>/store-extensions-src/app/features location.

Procedure

Navigate to <NEW_STORE_WORKSPACE>/store-frontend-src directory. Run command yarn new-extension-feature --moduleName=<module-name> --port=<port>. The following tasks are completed:

Create a new angular application named <module-name> under <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features folder.
Installs single-spa-angular in the new micro-frontend application.
Generates a main.single-spa.ts in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src project folder.
Generates a lazy loaded module with <module-name> in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app project folder.
Updates the routing module <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/app-routing.module.ts file with the following route definitions:
- Lazy loaded module with the appropriate route path definition.
- EmptyRouteComponent for unmatched routes.
Updates the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/package.json with the application start and build scripts. These scripts are used for starting and building the application.
Registers the new application in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/root-config/custom/import-map.json. The import-map.json file registers the JavaScript module to load a specific application.
To support localization and internationalization, the i18n folders are generated in the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/assets project folder to maintain the language specific bundles. An empty en.json bundle JSON file is generated within the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/assets/<module-name>/i18n project folder. The code is also updated to set up the TranslateModule to load the suitable translation bundle JSON files.

The following diagram illustrates the project structure:

2. Go to the <OLD_STORE_WORKSPACE>/store-extensions-src/app/features/<feature-name> folder. Except for the <feature-name>.module.ts and <feature-name>-routing.module.ts files, copy the remaining files and folders and paste them in the<NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name> project folder.

3. In the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name>/<module-name>.module.ts file, add the required modules, components, services to imports, declarations, and providers array, respectively.

4. Copy the route definitions from the <OLD_STORE_WORKSPACE>/store-extensions-src/app/features/<feature-name>/<feature-name>-routing.module.ts file to the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name>/<module-name>-routing.module.ts file.

5. Add all the feature route paths in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/root-config/custom/routes.json. This file contains application-provided routes, <NEW_STORE_WORKSPACE>/store-frontend-src/packages/apps/store-root-app/src/assets/root-config/config/feature-routes.json.

6. Update the lazy loaded route definition in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/app-routing.module.ts as provided in the code snippet. If a resource permission is associated with loading the feature route, add the Resource Permission guard as shown in the code snippet:

const routes: Routes = [
  {
    path: routePath('<feature-route>', 'shell'),
    loadChildren: () => import('./features/<module-name>/<module-name>.module').then(m =>
    m.<ModuleName>Module),
    data: { 'resoucePermission': 'ISF000001' },
    canLoad: [ResourcePermissionGuard],
  },
  {
    path: '**',
    component: EmptyRouteComponent
  }];

7. We have updated the class names of frequently used services and utilities from existing @sim-core module. Refer the below table and update the import statements and class names across all the component and data service typescript files within <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name> project folder.

For example,

import { UIUtilsService } from '@sim-core/services/ui-utils.service';

should be changed to

import { UIUtil } from '@store/core';

Old service name	New service/utility name	New service/utility imports from
src/app/core/services AppContextService	AppCtxStore	@store/core
src/app/core/services AppInfoService	AppInfoUtil	@store/core
	AppInitUtil	@store/core
src/app/core/services MessageService	MessageUtil	@store/core
src/app/features/utilities OrderService	OrderUtil	@store/core
src/app/features/utilities PaymentService	PaymentUtil	@store/core
src/app/core/services PrintService	PrintUtil	@store/core
src/app/core/services ResourcePermissionService	ResourcePermissionUtil	@store/core
src/app/core/services RulesService	RulesUtil	@store/core
src/app/features/utilities ShipmentService	ShipmentUtil	@store/core
src/app/core/services UIUtilsService	UIUtil	@store/core
src/app/core/services AuthenticationService	NA	@store/core
src/app/core/services BackNavigationService	NA	@store/core
src/app/core ExitWizardConfirmationService	ExitWizardConfirmationService	@store/core
src/app/core/services ISFNagModalService	AlertModalService	@store/core
src/app/core/services LoadingSpinnerService	NA	@store/core
src/app/core/services LocalizationService	NA	@store/core
src/app/core/services MashupService	NA	@store/core
src/app/core/services ModalService	NA	@store/core
src/app/core MultiTranslateHttpLoader	NA	@store/core
src/app/core/services RelatedTasksService	NA	@store/core
src/app/core/services RestService	NA	@store/core
src/app/core/services RoutingStateService	NA	@store/core
	StoreRouterService	@store/core
src/app/core/services WizardService	NA	@store/core
src/app/core/services BackClickHandlerGuardService	BackClickHandlerGuard	@store/core
src/app/core/services ResourcePermissionGuardService	ResourcePermissionGuard	@store/core
src/app/shared/services AbstractBatchDataLoaderService	NA	@store/common-components
src/app/shared/services AddressDisplayService	NA	@store/common-components
src/app/shared/services BarcodeScannerService	NA	@store/common-components
src/app/shared/services CustomDatepickerI18nService	NA	@store/common-components
src/app/shared/services DatatypeValidatorsService	NA	@store/common-components
src/app/shared/services ManagePersonaService	NA	@store/common-components
src/app/shared/services NumberInputService	NA	@store/common-components

8. The import statements and classnames of components from @sim-shared or @sim-app-common module has been changed in the new store architecture.

The components that are previously part of @store/shared module are now part of @store/common-components library.
The components that are previously part of @store/app-common module are now part of @store/functional-components library.
If you are using components from @store/common-components or @store/functional-components library in your feature module, ensure that you import CommonComponentsModule or FunctionalComponentsModule, accordingly.

Old component name	New component name	New component imports from
src/app IsfpopupComponent	AlertModalComponent	@store/core
src/app/shared/components	packages/libs/common-components/src/lib/components	@store/common-components
src/app/app-shell/unauthorised-page	packages/libs/common-components/src/lib/components/unauthorised-page	@store/common-components
src/app/shared/directives	packages/libs/common-components/src/lib/directives	@store/common-components
src/app/shared/pipes	packages/libs/common-components/src/lib/pipes	@store/common-components
src/app/app-common/address	packages/libs/functional-components/src/lib/address	@store/functional-components
src/app/app-common/components	packages/libs/functional-components/src/lib/modals	@store/functional-components
src/app/app-common/mini-cart	packages/libs/functional-components/src/lib/components/mini-cart	@store/functional-components
src/app/app-common/product-detail	packages/libs/functional-components/src/lib/components/product-detail	@store/functional-components
src/app/app-common/components/payment-method	packages/libs/functional-components/src/lib/components/payment-method	@store/functional-components
src/app/app-common/components/product-view-images	packages/libs/functional-components/src/lib/components/product-view-images	@store/functional-components
src/app/features/alert	packages/libs/functional-components/src/lib/alert	@store/functional-components
src/app/shared/directives/show-product-details.directive.ts	packages/libs/functional-components/src/lib/directives/show-product-details.directive.ts	@store/functional-components
src/app/features/global-search	packages/libs/functional-components/src/lib/global-search	@store/functional-components

9. For all the .scss files that are present in the <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name> project folder, update the import statements. Replace the existing imports with the following imports in all the .scss files.

@import '@store/styles/src/styles/variables'; (Previously, @import "variables_main";)
@import '@store/styles/src/styles/mixins'; (Previously, @import "mixins" )
@import 'bootstrap/scss/mixins';

10. If the custom component uses a loading bee gif file, update the background-image style property in component SCSS file as below:

background-image: url(^assets/styles/images/loading_bee.gif);

11.Replace all this.router.navigate(['<relative-path>'], {options}) or this.router.navigateByUrl(['<path>']) method calls with new custom StoreRouterService (@store/core library) which takes care of navigating between screens/pages.

The following table explains the method signature of navigateToURL:

Argument name	Type	Description
absolutePath	String	Full path to the destination screen. This path will be a combination of feature/flow path defined in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/app-routing.module.ts file and the screen path defined in <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/app/<module-name>/<module-name>.module.ts file. Sample paths: customer-pickup/order-search-results shipment/summary/<shipmentKey>
this.router	Router	Angular Router instance
options	JSON object	JSON object to pass query parameters to destination screen and other angular route options to pass to Angular router. When passing query parameters please use param name as queryParams strictly. Please refer to examples below.

The following table explains a sample usage of the navigateToURL method:

Use case	Method sample usage
Without queryParams	this._storeRouterService.navigateToURL('customer-pickup/order-search-results', this.router);
With queryParams only	this._storeRouterService.navigateToURL('customer-pickup/order-search-results', this.router, { queryParams: searchInput});
With angular routing options only	this._storeRouterService.navigateToURL('customer-pickup/order-search-results', this.router, { replaceUrl: true});
With queryParams and angular routing options	this._storeRouterService.navigateToURL('customer-pickup/order-search-results', this.router, { queryParams: searchInput, replaceUrl: true});

12. Copy the custom feature specific bundle JSON files from <old_store_workspace>/store-extensions-src/assets/store-frontend/i18n/<feature-name> to <NEW_STORE_WORKSPACE>/store-frontend-src/extensions/features/<module-name>/src/assets/<module-name>/i18n folder.

13. Review the bootstrap v5 migration support page and update the classes accordingly in the portlet component, HTML and SCSS files.

[{"Line of Business":{"code":"LOB59","label":"Sustainability Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSGTZV","label":"IBM Sterling Store Engagement"},"ARM Category":[{"code":"a8m0z000000cy2QAAQ","label":"Call Center Store and SIM"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions","Type":"MASTER"}]

Tips

Migrating custom features

General Page

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?