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 you can fin our SiteGenesis documentation included in the installation package.

Install the Package

To receive the installation package from our support team please open a case including the customer name, and whether you use SFRA or SiteGenesis.
NOTE: To be able to install the plugin you need to be a Commerce Cloud developer.

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.

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/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/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/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/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 differently 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

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, which can be found by going to Administration > Operation > Services, 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 creating return shipment labels
http.zenkraft.track zenkraft-track-creds Endpoint used to get order related tracking information

Please note if you need to use our EU datacentres then please update the credentials section (Administration > Operation > Services > Credentials) of each of these services so that the root domain points to api.eu.zenkraft.com instead of api.zenkraft.com

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 introduced with the Zenkraft cartridge

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


Frontend CSS files

List of the 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 and Tracking page
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 check marks in My Account
returns.scss Styles for the returns flow on the website

Master API Key

You will need to enter your Zenkraft Master API key into the Merchant tools > Site preferences > Custom preferences > Zenkraft General > Zenkraft Master API Key field.

If you don't have your Master API key then please contact your Zenkraft account manager and they will be able to help you out.

Release notes

Please find our release notes here