How to migrate a tenant to XPLib

This guide describes how to enable XP as a Library in a tenant.

The new Marfeel architecture uses providers as its main extension point and requires that MediaGroups are decoupled from the core infrastructure. Achieve this decoupling, and unlock the usage of any provider with XP as a library.

TIP

Even if some of the following files are at the root of the MediaGroup, you can activate XPLib one tenant at a time in features.json.

Step 1: Assess the complexity

First, scan the MediaGroup looking for incompatibilities and anything that will require migration.

Find your tenant's audit result in Kibana (opens new window) for a quick overview of the complexity. Depending on the audit results, check the following points:

1. Check the main.js file/s. They should contain only the initialization functions or as little customizations as possible.

• Remove old widgets if possible
• Ask TEN if there is any customization you don't know how to migrate
• Fix the imports if necessary

Imports

Take the opportunity to clean JavaScript imports, if you can.

Use the caretaker command on each JS file:

cd MediaGroup/tenant.com
npx @marfeel/caretaker to-marfeel-packages index/src/js/main.js

Make sure the tenant still works after any import change. You can also search the public-modules file (opens new window) to find the available functions.

2. Ad configuration: Check which AdServers the tenant uses and note which ones will need migration to providers. If the tenant doesn't use inventory.json, you must create it.

• Validate if required Adserver providers exist
• Check if the old Adservers are still in use: if not, remove them.

3. Metrics: XPLib tenants use analytics.json, which is only compatible with analytics providers. Assess which metrics the tenant is using and check if they exist as providers. The ones that aren't, need to be migrated.

4. Widgets: Check if the tenant is using widgets. If there are any in main.js, they ideally need to be migrated to a widget provider. Also, check for widgets using metadata: if there are any, replace them with a middleware

5. Custom JSP: Some custom JSP can be removed or replaced by new Marfeel components.

6. Check if the tenant uses PhantomJS and how complex would be the migration to Puppeteer.

7. Check if the tenant uses LayoutDescriptor and otherwise, it needs to be configured.

8. renovate.json must be in the root folder of the repository. Add it if it isn't already there:

{
   "extends": ["github>Marfeel/renovate-config"]
}

After all these checks, you will have a clear idea of how complex the migration is. Now it's time to discuss with CS / Tech Lead about how to distribute tasks and give a rough estimation to the tenant if necessary.

Step 2: Migrate the tenant

1. Create the package.json file from the template (opens new window).

• Make sure all dependencies use the latest versions, especially @marfeel/core.

• Replace REPOSITORY_NAME with your MediaGroup information.

• Remove "**/src/whiteCollar/*.js" from eslintIgnore if the tenant uses Puppeteer.

  Fast packages update

  To update all the dependencies to their latest version, follow these steps:

  • Run npx npm-check-updates -u in the MediaGroup: it updates all the versions in your package.json.
  • Remove the package-lock.json file.
  • Run npm install: the new versions are installed, and the new package-lock.json is generated!

2. Update the .gitignore file so it has the same content as the template (opens new window).

3. Add .npmrc file as it is in the template (opens new window).

4. Replace the providers that already exist in core for metrics, widgets, and ads.

• Add the provider in the right JSON
• Remove the old implementation
• npm install each package

TIP

• Using Ad Server Providers
• Using Widget Providers
• Using Analytics Providers

5. Remove all main.l.js files, or rename them to main.xl.js if xl doesn't exist.

6. Add useMarfeelXPAsALibrary flag to features.json.

7. Remove the useMetricsJson flag from the definition.

8. Change the links from bc. to live.mrf.io in definition.json and check if there are other resources that require this change.

9. Implement the necessary providers spotted in Step 1: Assess the complexity.

10. Once all providers are implemented, add them to the right JSON files and install their packages.

• Verify all widgets, metrics, and ads are working as expected

11. Run npm i to generate the final package-lock.json, which you must also commit.

Optional considerations:

• Add the invokeMiddleware flag in features.json if there is any middleware
• Add the enableReact flag in definition.json if there are any widget providers