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 live documentation is in SFRA but please contact us for 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 prefered 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.

zenkraft-sys-object-import.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

zenkraft-dropoff-sys-object-import.xml - This contains all of the system object definitions and custom site preference definitions that are related to the Drop Off Shipments Feature ONLY. Import it at Administration -> Site Development -> Import & Export -> Meta Data Import

zenkraft-services-import.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

zenkraft-jobs-import.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 because there are several methods and models that are extending via the Zenkraft cartridge.

Please keep in mind that the cartridge uses overwritten SFRA files (templates).

Site setup - Multi-site vs Locale-based site

Multi-site

All Site preferences and custom objects that are defined within the Zenkraft link cartridge are site-specific, so using the cartridge in multi-site environment is supported out of the box.
In order to setup the cartridge in 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 in 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.

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 consist of only copying the content of the new cartrdige over the existing files, if nothing else stated in the release notes.

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

Jobs

Job Configuration

SendShippingNotifications

UpdateReturnCases

CreateZenkraftShipments

Name Details
SendShippingNotifications In order to schedule tracking updates that then allow you to send shipping notifications from you need to schedule the job that was imported with the previously mentioned meta data import.
After running the import, you’ll need to go to Administration → Operations → Job Schedules, select the SendShippingNotifications job, select the Step Configurator tab, and change the Scope for whatever 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 whatever interval you like, we recommend every 4 hours as a maximum frequency.
UpdateReturnCases In order to update the return tracking statuses from your SFCC returns, you need to schedule the job that was imported with the previously mentioned meta data import.
After running the import, you’ll need to go to Administration → Operations → Job Schedules, select the UpdateReturnCases job, select the Step Configurator tab, and change the Scope for whatever 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 whatever interval you like, but for returns, we recommend running it only once a day, or a maximum of twice a day.
CreateZenkraftShipments In order to Create Zenkraft Shipments from your SFCC orders, you need to schedule the job that was imported with the previously mentioned meta data import.
After running the import, you’ll need to go to Administration → Operations → Job Schedules, select the CreateZenkraftShipments job, select the Step Configurator tab, and change the Scope for whatever site(s) you have.
To schedule the job, go to Administration → Operations → Job Schedules and select the CreateZenkraftShipments job. From there, just schedule it to run at SFCC - SFRA Implementation Guide 17 whatever interval you like.

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