1. Home
  2. Docs
  3. B2Ccommerce
  4. Cartridge Installation
Log a Case

B2C Commerce Cartridge Installation

Instructions for installing cartridge on B2C instance


Install the Zenkraft Cartridge

Zenkraft supports both SiteGenesis and SFRA. Our documentation is for SFRA but please contact us for the SiteGenesis documentation.

Still using SiteGenesis? Please  contact us  for the documentation

Download/clone repository

Go to the official cartridge and download/clone the master branch.

Upload code to SFCC Instance

Using your preferred IDE, upload the code to the active code version of your instance

Import Metadata

In order to function correctly, there are several imports that need to be done. All of these imports can be found in the metadata folder of the integration.

metadata/zenkraft-meta-import/meta/system-objecttype-extensions.xml - This contains all of the system object definitions and custom site preference definitions, as well as a custom object definition for Shipment Notifications. Import it at Administration -> Site Development -> Import & Export -> Meta Data Import

metadata/zenkraft-meta-import/meta/custom-objecttype-definitions.xml - This contains all of the custom object definitions. Import it at Administration -> Site Development -> Import & Export -> Meta Data Import

metadata/zenkraft-meta-import/services.xml - This import contains the Salesforce Commerce Cloud Service Framework definitions for connecting to the Zenkraft API. Import it at Administration -> Operations -> Import & Export -> Services

metadata/zenkraft-meta-import/jobs.xml - This import contains the job that sends shipment notifications. Import it at Administration -> Operations -> Import & Export -> Job Schedules

Assign Cartridge Path

In order to use the int_zenkraft_sfra cartridge, it needs to be assigned to your site through Administration -> Sites -> Manage Sites -> Your Site -> Settings tab. Add the cartridge to the left of your base cartridge as there are several methods and models that are extended via the Zenkraft cartridge.

Please keep in mind that the cartridge uses overwritten SFRA files which you can find in the templates section.

Site setup - Multi-site vs Locale-based site

Multi-site

All site preferences and custom objects defined within the Zenkraft link cartridge are site-specific, so using the cartridge in a multi-site environment is supported out of the box.

In order to setup the cartridge in a multi-site environment, you need to configure the site preferences for each of the site that will use the cartridge, and make sure that the int_zenkraft_sfra cartridge is added to the cartridge path for each of the sites.

Locale-based sites

Locale-based sites are currently not supported out of the box, and will require additional changes on the meta data definitions and code.

Site Preferences Reference

You can find the list of all the Site Preferences available for configuration within the B2C Business Manager by following this link.

Compile files

Static files are compiled using out-of-the-box webpack script that is provided with SFRA cartridge. However this script does not include the files from all cartridges within a project.

If you need to compile all the static files with a single command, you will need to amend the webpack.config.js file.

Please refer to the sample script below:

    
'use strict';

var path = require('path');
var webpack = require('sgmf-scripts').webpack;
var ExtractTextPlugin = require('sgmf-scripts')['extract-text-webpack-plugin'];
var jsFiles = require('sgmf-scripts').createJsPath();
var scssFiles = require('sgmf-scripts').createScssPath();

// Add those imports to your webpack
var glob = require('glob');
var fs = require('fs');
process.noDeprecation = true;
var cwd = process.cwd();

var bootstrapPackages = {
    Alert: 'exports-loader?Alert!bootstrap/js/src/alert',
    // Button: 'exports-loader?Button!bootstrap/js/src/button',
    Carousel: 'exports-loader?Carousel!bootstrap/js/src/carousel',
    Collapse: 'exports-loader?Collapse!bootstrap/js/src/collapse',
    // Dropdown: 'exports-loader?Dropdown!bootstrap/js/src/dropdown',
    Modal: 'exports-loader?Modal!bootstrap/js/src/modal',
    // Popover: 'exports-loader?Popover!bootstrap/js/src/popover',
    Scrollspy: 'exports-loader?Scrollspy!bootstrap/js/src/scrollspy',
    Tab: 'exports-loader?Tab!bootstrap/js/src/tab',
    // Tooltip: 'exports-loader?Tooltip!bootstrap/js/src/tooltip',
    Util: 'exports-loader?Util!bootstrap/js/src/util'
};

// ZENKRAFT: Add this function
function createScssPath() {
    var cartridgesPath = path.resolve(cwd, "cartridges");
    var clientPath = path.resolve(cartridgesPath, '*', "cartridge/client");
    var result = {};

    glob.sync(path.resolve(clientPath, "*", "scss", "**", "*.scss"))
        .filter(f => !path.basename(f).startsWith("_"))
        .forEach(filePath => {
            var name = path.basename(filePath, '.scss');
            if (name.indexOf('_') !== 0) {
                let location = path.relative(cwd, filePath);
                location = location.substr(0, location.length - 5).replace('scss', 'css');
                result[location.replace('client', 'static')] = filePath;
            }
        });

    return result;
};

// ZENKRAFT: Add this function
function createJsFiles() {
    var cartridgesPath = path.resolve(cwd, "cartridges");
    var clientPath = path.resolve(cartridgesPath, '*', "cartridge/client");
    var result = {};

    glob.sync(path.resolve(clientPath, "*", "js", "*.js")).forEach(f => {
        var key = path.join(path.dirname(path.relative(cwd, f)), path.basename(f, ".js"));
        result[key.replace('client', 'static')] = f;
    });

    return result;
};


module.exports = [{
    mode: 'development',
    name: 'js',
    entry: createJsFiles(), // ZENKRAFT: Change the entry from  sgmfScripts.createJsPath(), to createJsFiles(),
    output: {
        path: path.resolve(__dirname) + '/',
        filename: "[name].js"
    },
    module: {
        rules: [
            {
                test: /bootstrap(.)*\.js$/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: ['@babel/env'],
                        plugins: ['@babel/plugin-proposal-object-rest-spread'],
                        cacheDirectory: true
                    }
                }
            }
        ]
    },
    plugins: [new webpack.ProvidePlugin(bootstrapPackages)]
}, {
    mode: 'none',
    name: 'scss',
    entry: createScssPath(),
    output: {
        path: path.resolve(__dirname) + '/',
        filename: '[name].css'
    },
    module: {
        rules: [{
            test: /\.scss$/,
            use: ExtractTextPlugin.extract({
                use: [{
                    loader: 'css-loader',
                    options: {
                        url: false,
                        minimize: true
                    }
                }, {
                    loader: 'postcss-loader',
                    options: {
                        plugins: [
                            require('autoprefixer')()
                        ]
                    }
                }, {
                    loader: 'sass-loader',
                    options: {
                        includePaths: [
                            path.resolve('node_modules'),
                            path.resolve('node_modules/flag-icon-css/sass')
                        ]
                    }
                }]
            })
        }]
    },
    plugins: [
        new ExtractTextPlugin({ filename: '[name].css' })
    ]
}];

Upgrade cartridge

The upgrade process usually consists of copying the content of the new version of the cartridge over the existing files, unless you are specified to do so in the release notes.

Make sure you have checked the  Release notes  for any additional data changes or migration required.
Make sure you are haven't overwritten any of the core cartridge files before you upgrade

Jobs

Job Configuration

Name Details
SendShippingNotifications In order to schedule tracking updates that allow you to send shipping notifications, you need to schedule the job that was imported with the previously mentioned meta data import.
After running the import, go to Administration → Operations → Job Schedules, select the SendShippingNotifications job, select the Step Configurator tab, and change the Scope for the site(s) you have.
To schedule the job, go to Administration → Operations → Job Schedules and select the SendShippingNotifications job. From there, just schedule it to run at the interval you like, we recommend every 4 hours as a maximum frequency.
UpdateReturnCases In order to update the return tracking statuses of your SFCC returns, you need to schedule the job that was imported with the previously mentioned meta data import.
After running the import, go to Administration → Operations → Job Schedules, select the UpdateReturnCases job, select the Step Configurator tab, and change the Scope for the site(s) you have. To schedule the job, go to Administration → Operations → Job Schedules and select the UpdateReturnCases job.
From there, just schedule it to run at the interval you like, but for returns, we recommend running it only once a day, or a maximum of twice a day.

Service definitions

There are currently five services to be setup, all of them share the same service profile - service-zenkraft:
Name Credentials Description
http.zenkraft.dopu zenkraft-dopu-creds Endpoint used for drop off locations
http.zenkraft.label zenkraft-label-creds Endpoint used for generating combined labels
http.zenkraft.rate zenkraft-rate-creds Endpoint used to get carrier shipping rates
http.zenkraft.ship zenkraft-ship-creds Endpoint used for drop off locations
http.zenkraft.track zenkraft-track-creds Endpoint used to get order related tracking information

Style/UI

The front-end files are compiled using the standard SFRA npm commands.
If you need to extend you webpack configuration to support multiple cartridges, please refer to the compile files section above.

Building scss files
Compiles all requires css files for the project
npm run compile:scss


Building js files
Compiles all requires front-end javascript files for the project
npm run compile:js

Frontend Javascript files

List of all front-end javascript files that are introduced with the Zenkraft cartridge

Name Info
dropOffModal.js Contains code and functionalities related to the drop-off / pick-up modals on the website
returns.js Contains code and functionalities related to the return page in My Account of the website
tracking.js Contains code and functionalities related to the tracking page in My Account section of the webiste
zen-product.js Contains code and functionalities related to the PDP widgets for the estimated delivery date and charges for the shipping method
zenkraft.js Contains code and functionalities related to the Checkout flow on the website - loading shipping methods, overwritting shipping charges from Zenkraft and etc.


Frontend CSS files

List of all front-end CSS files that are introduced with the Zenkraft cartridge

Name Info
account/dashboard.scss Styles for the sections in My Account - Returns page, Tracking page and etc.
components/dropOffModal.scss Styles for the drop-off/pick-up location modal
tracking.scss Styles for the tracking page
checkmarks.scss Styles for the Tracking page checkmarks in My Account
returns.scss Styles for the checkout flow on the website