1. Overview
Functional Overview
The cartridge lets you get the Zakeke tool connected with your web store. These plugins enable your customers to customize a product before buying it.
The integration encompasses three cartridges:
- a business cartridge (int_zakeke_shared)
- a storefront cartridge (int_zakeke)
- a cartridge for Business Manager (bm_zakeke).
Limitations, Constraints
The products that can be customized are:
- standard product
- variants of a master product
It’s not possible to customize bundle, set and options product.
Compatibility
The cartridge is designed and developed for:
- Salesforce platform version 19.10
- Sitegenesis version 104.0.0
- Compatibility mode 19.10
2. Implementation Guide
Setup
Deploying cartridge to the sandbox
First of all, upload int_zakeke, int_zakeke_shared, and bm_zakeke to your production or development sandbox. Apply standard procedures to upload cartridges to your environment (use Eclipse UX Studio or sgmf-scripts).
Sandbox setup
-
Go to Business Manager -> Site -> Manage Sites. Select your “Sitegenesis” site, then select Settings tab. In cartridge path at the end write the following: int_zakeke:int_zakeke_shared
-
Go to Business Manager -> Site -> Manage Sites. Click on “Business manager” site, then select Settings tab. In cartridge path at the end write the following: bm_zakeke:int_zakeke_shared
-
Find xml files in the folder ”metadata” of Zakeke LINK cartridge.
-
Go to Administration > Site Development > Import & Export. Click Upload button and select the xml files zakObjects.xml
-
Click Import button and select the file.
-
Go to Administrators->Operations -> Import & Export. Click Upload button and select zakJobs.xml and afterwards zakServices.xml.
-
Click “Job import” and click button import selecting the file zakJobs.xml.
-
Click “Service import” and click button import selecting the file zakServices.xml.
-
Verify that a new Site Preferences group was created with the “Zakeke Configs” ID and “Zakeke Configs” name.
Configuration
This section describes the steps that you should complete to configure the extension both in the Business Manager and in the Zakeke platform front-end.
Commerce Cloud: register your application using Account manager
- Go to account manager at https://account.demandware.com and log in with your administrator credential. Click the link API client.
- Click “Add API Client” button.
- Insert ZakekeApiClientId as Display name, select client_secret_basic as Token Endpoint Auth Method.
- Save.
- A new API client ID will be created. The API secret key correspond to the password of the logged account. It’s advisable to change the password and choose a different password for every client ID.
- Take a copy of the preceding values.
Zakeke platform: configuring the account
Go to https://portal.zakeke.com/Admin/Login and log in using your merchant credential (ask Zakeke for a merchant account with credentials).
- Go to “Api keys” page.
- Copy "Client ID" and "Secret Key" fields. They are the "Zakeke Client Id" and the “Zakeke Client Secret”.
- Go to "E-Commerce Connection" page. Choose Salesforce tab.
- Fill the form as below and save:
- CCloud client id: insert the "Api client ID" previously generated into account manager.
- CCloud secret key: insert the “Api secret key” previously generated into account manager.
- CCloud site id: insert the “SiteID” of the web site linked to Zakeke platform (es. RefArch)
- CCloud site URL: insert the base URL of Commerce Cloud store (es. https://domain01-dw.demandware.net/)
- Currency: choose the base currency of your store
Commerce Cloud: configuring the site preferences
- Choose your site. Go to Business Manager-> Merchant tools -> Custom preferences.
- Click to “ZAKEKE Configs”.
- Fill the form as below:
- Zakeke enabled: choose “Yes” to enable the Zakeke extension.
- Zakeke url: insert the base url of Zakeke platform (https://www.zakeke.com).
- Zakeke credential name: insert the string ZakekeAPICredentials_<SiteName> putting the store siteID in place of <SiteName> (es. ZakekeApiCredentials_Sitegenesis).
- Notification email from: insert the email address to receive the notification from.
- Notification email to: insert the emails to send the notifications to.
- Save the configuration.
Commerce Cloud: configuring the credential
- Go to Administrator -> Operations -> Services.
- Go to Credentials and click to ZakekeAPICredentials_<SiteName>
- Fill the form as below:
- Name: update the string ZakekeAPICredentials_<SiteName> putting the store siteID in place of <SiteName>. This value has to be equal to “Zakeke credential name” inserted above in the custom site preferences.
- URL: insert the base url of Zakeke platform api (https://api.zakeke.com).
- User: insert the “Api client ID” previously generated in Zakeke configuration phase (Zakeke Client Id)
- Password: insert the “Api client secret” previously generated in Zakeke configuration phase (Zakeke Client Secret).
Commerce Cloud: configuring the services
- Go to Administrator -> Operations -> Services.
- Go to Services and for each services in the list repeat step 3
- Select in the list credentials the credential defined in the previous step. See the image below.
Commerce Cloud: configuring the OCAPI setting
- Go to Administrator -> Site development -> Open Commerce API Settings.
- Select “Data” as Type and “Global (organization-wide)” as context.
- In the text field add a new JSON object in the array named “clients”. The object is specified below.
- Remember to insert into the “client id” field the Commerce Cloud “Api client Id” generated into account manager.
{
"allowed_origins":["https://www.zakeke.com"],
"client_id":"<Api client Id generated into account manager>",
"resources":
[
{
"resource_id":"/catalogs",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/catalogs/*",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/catalogs/*/categories",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/sites",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/sites/*",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/products/*",
"methods":["get", "patch"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/products/*/variations",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/products/*/variation_attributes",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/products/*/variation_attributes/*",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/products/*/variant_search",
"methods":["post"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/product_search",
"methods":["post"],
"read_attributes":"(**)",
"write_attributes":"(**)"
},
{
"resource_id":"/locale_info/locales",
"methods":["get"],
"read_attributes":"(**)",
"write_attributes":"(**)"
}
]
}
Commerce Cloud: configuring the custom job ZakekeNotification
- Go to Administrator -> Operations -> Jobs
- Click on job ZakekeNotification
- In the “Schedule and History” page, enable the job clicking the “Enabled” check box
- Go to Job steps page
- Assign the siteID of your store as context of job step. See the image below
Commerce Cloud: configuring log settings
- Go to Administrator -> Operations -> Custom Log settings.
- Add a new Log Category for Zakeke called ZAKEKE
See the image below.
Custom Code
Zakeke application needs some updates on Sitegenesis storefront files. The files to be modified are the following:
storefront_controllers:
- storefront_controllers/cartridge/controllers/COSummary.js
- storefront_controllers/cartridge/templates/default/checkout/cart/cart.isml
- storefront_controllers/cartridge/templates/default/checkout/components/minilineitems.isml
- storefront_controllers/cartridge/templates/default/checkout/summary/summary.isml
- storefront_controllers/cartridge/templates/default/product/components/displayliproduct.isml
- storefront_controllers/cartridge/templates/default/product/productcontent.isml
storefront_core:
- storefront_core/cartridge/scripts/cart/calculate.js
You can find the changed version of this files in the documentation directory of the project. Let’s see each of them in detail.
storefront_controllers/cartridge/controllers/COSummary.js
Substitute the function submit() with the code below:
function submit() {
// Calls the COPlaceOrder controller that does the place order action and any payment authorization.
// COPlaceOrder returns a JSON object with an order_created key and a boolean value if the order was ..
// If the order creation failed, it returns a JSON object with an error key and a boolean value.
var placeOrderResult = app.getController('COPlaceOrder').Start();
if (placeOrderResult.error) {
start({
PlaceOrderError: placeOrderResult.PlaceOrderError
});
} else if (placeOrderResult.order_created) {
showConfirmation(placeOrderResult.Order);
//???????????????????????????????????????????
//Zakeke customize begin---------------------
dw.system.HookMgr.callHook('zak.orderClosed', 'orderClosed', placeOrderResult.Order);
//Zakeke customize end-----------------------
//???????????????????????????????????????????
}
}
storefront_core/cartridge/templates/default/checkout/cart/cart.isml
After the selected code:
Insert the following code:
<!--Zakeke customize begin---------------------- -->
<isscript>
var IsZakekeProduct=!empty(lineItem.getCustom().ZAKEKE_CompositionID);
</isscript>
<!--Zakeke customize end---------------------- -->
Substitute the selected code:
With:
<!--Zakeke customize begin---------------------- -->
<isif condition="${IsZakekeProduct}">
<td class="item-image">
<img src="${lineItem.getCustom().ZAKEKE_CompositionPreview}" alt="${lineItem.productName}" title="${lineItem.productName}" width="65px" height="65px"/>
</td>
<iselse/>
<td class="item-image">
<isif condition="${lineItem.product != null && lineItem.product.getImage('small',0) != null}">
<img src="${lineItem.product.getImage('small',0).getURL()}" alt="${lineItem.product.getImage('small',0).alt}" title="${lineItem.product.getImage('small',0).title}" />
<iselse/>
<img src="${URLUtils.staticURL('/images/noimagesmall.png')}" alt="${lineItem.productName}" title="${lineItem.productName}" />
</isif>
</td>
</isif>
<!--Zakeke customize end---------------------- -->
Substitute the selected code:
With:
<td class="item-details">
<iscomment>Call module to render product</iscomment>
<!--Zakeke customize begin---------------------- -->
<isif condition="${IsZakekeProduct}">
<isdisplayliproduct p_productli="${lineItem}" p_formli="${FormLi}" p_editable="${false}" p_hideprice="${true}" p_hidepromo="${false}" />
<iselse/>
<isdisplayliproduct p_productli="${lineItem}" p_formli="${FormLi}" p_editable="${true}" p_hideprice="${true}" p_hidepromo="${false}" />
</isif>
<!--Zakeke customize end---------------------- -->
</td>
Substitute the selected code:
With:
<div class="item-user-actions">
<isif condition="${!lineItem.bonusProductLineItem || lineItem.getBonusDiscountLineItem() != null}">
<button class="button-text" type="submit" value="${Resource.msg('global.remove','locale',null)}" name="${FormLi.deleteProduct.htmlName}"><span>${Resource.msg('global.remove','locale',null)}</span></button>
</isif>
<!--Zakeke customize begin---------------------- -->
<isif condition="${!IsZakekeProduct}">
<isif condition="${empty(pdict.ProductAddedToWishlist) || pdict.ProductAddedToWishlist != lineItem.productID}">
<isif condition="${!isInWishList && !empty(lineItem.product)}">
<a class="add-to-wishlist" href="${URLUtils.https('Cart-AddToWishlist', 'pid', lineItem.productID)}" name="${FormLi.addToWishList.htmlName}" title="${Resource.msg('global.addthisitemtowishlist.title','locale',null)}">
${Resource.msg('global.addtowishlist','locale',null)}
</a>
</isif>
<iselse/>
<div class="in-wishlist">
${Resource.msg('global.iteminwishlist','locale',null)}
</div>
</isif>
</isif>
<!--Zakeke customize begin---------------------- -->
</div>
Substitute the selected code:
With:
<iscomment>Display the promotion name for each price adjustment.</iscomment>
<isloop items="${lineItem.priceAdjustments}" var="pa" status="prAdloopstatus">
<div class="promo-adjustment">
<isif condition="${lineItem.quantityValue > 1 && lineItem.quantityValue != pa.quantity}">
<!--Zakeke customize begin---------------------- -->
<!-- isprint value="${pa.quantity}" /> x -->
<!--Zakeke customize begin---------------------- -->
</isif>
<isprint value="${pa.promotion.calloutMsg}" encoding="off"/>
</div>
</isloop>
storefront_ core /cartridge/templates/default/checkout/components/minilineitems.isml
After the selected code:
Insert the code:
<!--Zakeke customize begin---------------------- -->
<isset name="IsZakekeProduct" value="${!empty(productLineItem.getCustom().ZAKEKE_CompositionID)}" scope="page" />
<!--Zakeke customize end---------------------- -->
Substitute the selected code:
With the code:
<div class="mini-cart-image">
<!--Zakeke customize begin---------------------- -->
<isif condition="${IsZakekeProduct}">
<img src="${productLineItem.getCustom().ZAKEKE_CompositionPreview}" alt="${productLineItem.productName}" title="${productLineItem.productName}" width="65px" height="65px"/>
<iselse/>
<isif condition="${productLineItem.product != null && productLineItem.product.getImage('small',0) != null}">
<img src="${productLineItem.product.getImage('small',0).getURL()}" alt="${productLineItem.product.getImage('small',0).alt}" title="${productLineItem.product.getImage('small',0).title}"/>
<iselse/>
<img src="${URLUtils.staticURL('/images/noimagesmall.png')}" alt="${productLineItem.productName}" title="${productLineItem.productName}"/>
</isif>
</isif>
<!--Zakeke customize end---------------------- -->
</div>
storefront_ core/cartridge/templates/default/checkout/summary/summary.isml
After the selected code:
Insert:
<!--Zakeke customize begin---------------------- -->
<isscript>
var IsZakekeProduct=!empty(productLineItem.getCustom().ZAKEKE_CompositionID);
</isscript>
<!--Zakeke customize end---------------------- -->
Substitute the selected code:
With the code:
<!--Zakeke customize begin---------------------- -->
<isif condition="${IsZakekeProduct}">
<td class="item-image">
<img src="${productLineItem.getCustom().ZAKEKE_CompositionPreview}" alt="${productLineItem.productName}" title="${productLineItem.productName}" width="65px" height="65px"/>
</td>
<iselse/>
<td class="item-image">
<isif condition="${productLineItem.product != null && productLineItem.product.getImage('small',0) != null}">
<img src="${productLineItem.product.getImage('small',0).getURL()}" alt="${productLineItem.product.getImage('small',0).alt}" title="${productLineItem.product.getImage('small',0).title}"/>
<iselse/>
<img src="${URLUtils.staticURL('/images/noimagesmall.png')}" alt="${productLineItem.productName}" title="${productLineItem.productName}"/>
</isif>
<isif condition="${productLineItem.bonusProductLineItem}">
<div class="bonus-item">
<isset name="bonusProductPrice" value="${productLineItem.getAdjustedPrice()}" scope="page"/>
<isinclude template="checkout/components/displaybonusproductprice" />
<isprint value="${bonusProductPriceValue}" />
</div>
</isif>
</td>
</isif>
<!--Zakeke customize end---------------------- -->
storefront_ core /cartridge/templates/default/product/components/displayliproduct.isml
Substitute the selected code:
With:
<isif condition="${empty(pdict.p_hidepromo) || !pdict.p_hidepromo}">
<iscomment>promotional messaging</iscomment>
<!--Zakeke customize begin---------------------- -->
<isloop items="${productLineItem.priceAdjustments}" var="pli" status="loopstate">
<isif condition="${pli.promotionID!=productLineItem.getCustom().ZAKEKE_CompositionID}">
<div class="promo <isif condition="${loopstate.first}"> first <iselseif condition="${loopstate.last}"> last</isif>">- <isprint value="${pli.lineItemText}"/></div>
</isif>
</isloop>
<!--Zakeke customize end---------------------- -->
</isif>
Insert after the selected code (before the </div>):
The code:
<!--Zakeke customize begin---------------------- -->
<isif condition="${!empty(productLineItem.getCustom().ZAKEKE_Composition)}">
<br>
${Resource.msg('displayliproduct.productPriceAdjustment','zakeke',null)}: <b>${productLineItem.getCustom().ZAKEKE_CompositionID.slice(0,20)} ..</b><br>
${Resource.msg('displayliproduct.customAttributes','zakeke',null)}:
<b>
<isloop items="${JSON.parse(productLineItem.getCustom().ZAKEKE_Composition)}" var = "zakOption">
[${zakOption.optionID}: ${zakOption.valueID}]
</isloop>
</b>
</isif>
<!--Zakeke customize end---------------------- -->
storefront_ core/cartridge/templates/default/product/productcontent.isml
After the selected code:
Insert the code (before <div class=”product-add-to-cart”>):
<!--Zakeke customize begin---------------------- -->
<isset
name="enabled"
value="${(pdict.isProductAvailable && !pdict.Product.bundle && !pdict.Product.optionProduct && !pdict.Product.master && (pdict.Product.product || pdict.Product.variant))}"
scope="page"
/>
<isif condition="${enabled}" >
<isinclude url="${URLUtils.url('ZakButtonCustomize-Show', 'pid', productNumber, 'enabled', enabled )}" />
</isif>
<!--Zakeke customize end------------------------ -->
storefront_core/cartridge/scripts/cart/calculate.js
The module calculate.js contains the function calculate. Add the following codes in the calculate function between PromotionMgr. applyDiscounts(basket) and calculateProductPrices(basket) in this way:
PromotionMgr.applyDiscounts(basket);
//----------------------------------------------
//Zakeke customize begin---------------------
calculateProductPricesAdjustmentZakeke(basket);
//Zakeke customize end-----------------------
//----------------------------------------------
calculateProductPrices(basket);
See image below for greater clarity:
After the “calculate” function, insert these two new functions “calculateProductPricesAdjustmentZakeke” and “isToCallCustomizationModel” whose code is reported below:
/**
* @function calculateProductPricesAdjustmentZakeke
*
* Add product price adjustment only for customized product
* in the product line items. This function returns nothing
*
* @param {object} basket The basket containing the elements to be computed
*/
function calculateProductPricesAdjustmentZakeke(basket){
var Resource = require('dw/web/Resource');
var zakGlobalSite = require('*/cartridge/scripts/zakGlobalSite');
var ZakCustomizationModel=require('*/cartridge/scripts/models/ZakCustomizationModel');
var productLineItems = basket.getAllProductLineItems().iterator();
while (productLineItems.hasNext()) {
var productLineItem = productLineItems.next();
var fixedAmount=null;
if (!empty(productLineItem.getCustom().ZAKEKE_CompositionID)) {
var compositionId=productLineItem.getCustom().ZAKEKE_CompositionID;
var quantity=productLineItem.quantity.value;
var productID=productLineItem.productID;
var customizationType=productLineItem.getCustom().ZAKEKE_CustomizationType;
var platformType=zakGlobalSite.PLATFORM_USED;//SITEGENESIS
var priceCustomiz=productLineItem.getCustom().ZAKEKE_CompositionPrice;
var priceCustomizNoTaxes=productLineItem.getCustom().ZAKEKE_CompositionPriceNoTaxes;
//ZAKEKE_Control: this variable is used to choose if customizationAPI call has to be done or not
//It saves the preceding "<compositionId>____<quantity>" for which the call has already been done
var controlCustomizationCall=productLineItem.getCustom().ZAKEKE_Control;
var controlObjectReturn= {control: ''};
var toCall=isToCallCustomizationModel(controlCustomizationCall, compositionId, quantity, controlObjectReturn);
if(toCall){
var modelCustomization=ZakCustomizationModel.get(productID, compositionId, quantity, customizationType, platformType);
var obj=modelCustomization.customization(); //obj={compositionPreview: xxxx, compositionUnitPrice: xxxx, compositionUnitPriceNoTaxes: xxxxx}
priceCustomiz=obj.compositionUnitPrice;
priceCustomizNoTaxes=obj.compositionUnitPriceNoTaxes;
productLineItem.getCustom().ZAKEKE_CompositionPreview = obj.compositionPreview;
productLineItem.getCustom().ZAKEKE_CompositionPrice = priceCustomiz;//Unit composition price in session currency (WITH TAXES)
productLineItem.getCustom().ZAKEKE_CompositionPriceNoTaxes = priceCustomizNoTaxes;//Unit composition price in session currency (NO TAXES)
productLineItem.getCustom().ZAKEKE_Control = controlObjectReturn.control;
}
if (priceCustomiz>0){
var adj=productLineItem.getPriceAdjustmentByPromotionID(compositionId);
if (empty(adj)){
fixedAmount = productLineItem.createPriceAdjustment(compositionId);
}
else {
fixedAmount=adj;
}
fixedAmount.setManual(false);
fixedAmount.setPriceValue(priceCustomiz*quantity);
fixedAmount.setLineItemText(Resource.msg('displayliproduct.productPriceAdjustment','zakeke',null)+': '+compositionId);
}
}
}
}
function isToCallCustomizationModel(control, compositionId, quantity, controlReturn){
var toCall=false;
var chrSpli='____';//4chr
var controlArray=null;
if(empty(control)){
toCall=true;
controlReturn.control = compositionId+chrSpli+quantity;
}
else{
controlArray=control.split(chrSpli);
var compId=controlArray[0];
var quant=controlArray[1];
if(compId!=compositionId || quant!=quantity){
toCall=true;
controlReturn.control = compositionId+chrSpli+quantity;
}
}
return toCall;
}
3. Testing
After installation and configuration of the CommerceCloud environment and Zakeke platform, the client can test the extension this way:
- Import a new product using Zakeke platform. You can find instructions at the following url: https://zakeke.zendesk.com/hc/en-us?customizer
- Go to business manager. Go to Merchant tools->Product and search for the just configured product.
- If the installation is correct the product should have the field “Zakeke customizable = TRUE” and the field “Customization plugin=<chosen plugin>”as you can see in the image below.
- If you go to the web store and search the selected product, in the PDP (product detail page), a new button “Customize” should appear after the selection of variation options.
4. User Guide
Storefront Functionality
- Go to the web store.
- Search for a customizable product (standard or master product) and go to its detail page.
- Choose the options to define the variation of the item
- A new button “Customize” should appear after the options variation choices. See the image below.
- Clicking the “Customize button”, if you used the “Customizer” as type of customization for the selected product, you are redirected to a custom Zakeke page in which you can use Zakeke <iframe> to customize the product in a 3d environment. See the image below.
- Clicking the “Customize button”, if you used the “Configurator“ as type of customization for the selected product, the configurator plugin page appears. See the image below.
- At the end, you can either close the page or accept the customization clicking the “Add to cart” button.
- The “Add to cart” action adds the selected item to the cart redirecting the customer to the cart page.
The workflow and the steps of the purchase process remain unchanged for both the checkout and payment phases. At the end of the order if you go to Business manager -> Merchant tools-> Orders, you can see the new order record.
There are some additional fields that are added by Zakeke extension: customizationID, price adjustment (if present) and customization detail in the “Notes” section of the order.
See the images below.
The last phase of the customization process is the notification of the order to the Zakeke platform. A custom Zakeke job called ZakekeNotification is present in the Administrator-> Operations -> jobs application.
See the image below.
The job is configured to run every 30 min in a recurring manner. The results of the job is saved in the custom object zakOrderNotification.
To access the custom table go to business manager -> Merchant Tools -> Custom Objects -> Custom Object Editor. On the page “Manage custom object” choose zakOrderNotification as Object type and click the Find button. To see the detail of the row you can click the orderID link. See the images below.
The record can have different statuses. Status can have three different values:
- ADDED = the row has just been added by the web process but not worked yet by the job.
- OK = the row has been successfully worked by the job.
- ERROR = the row has been worked by the job but with error. The message field contains the detail of the error.