1. Component Overview
Functional Overview
The Zakeke cartridge let you get both a cloud-based product configurator or a product customizer that you can use into your web store. These plugins enable your customers to compose/customize chosen product according to their needs and tastes.
The integration encompasses three cartridges: a business cartridge (int_zakeke_shared), a storefront cartridge (int_zakeke_sfra) and 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
- SFRA version 4.3.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 “SFRA” site, then select Settings tab. In cartridge path at the beginning write the following: int_zakeke_sfra: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 should be completed to configure the extension both in the Business Manager or in the Zakeke platform front-end.
Commerce Cloud: register your application using Account manager
1. Go to account manager to https://account.demandware.com and log in with your administrator credential. Click the link API client.
2. Click “Add API Client” button.
3. Insert ZakekeApiClientId as Display name, select client_secret_basic as Token Endpoint Auth Method.
4. Save.
5. 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.
6. Take a copy of the preceding values.
Zakeke platform: configuring the account
1. Go to https://portal.zakeke.com/Admin/Login and log in using your merchant credential (ask Zakeke for a merchant account with credentials).
2. The “customizer” dashboard page opens. If you would like to use the configurator instead, switch to “3d product configurator” from the top bar.
Customizer configuration
1. Go to “Api keys” page. If “Api ClientId” is not present click the “Generate new key” button. A new “Api clientID” and “Api secret” key will be generated by the system.
2. Copy "Client ID" and "Secret Key" fields. They are the "Zakeke Client Id" and the “Zakeke Client Secret”.
3. Go to Your Account -> E-commerce Connection. Choose Salesforce tab.
4. 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
Configurator configuration
1. Navigate to “Integration” link and select “Commerce cloud”.
2. Fill the form as below:
· 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. sitegenesis)
· 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
3. Copy "Client ID" and "Secret Key" fields at the top of the form. They are the "Zakeke Client Id" and the “Zakeke Client Secret”.
4. Click on “Save integration”.
Commerce Cloud: configuring the site preferences
1. Choose your site. Go to Business Manager-> Merchant tools -> Custom preferences.
2. Click to “ZAKEKE Configs”.
3. 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_RefArch).
· Notification email from: insert the email address to receive the notification from.
· Notification email to: insert the emails to send the notifications to.
4. Save the configurations.
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 the 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 “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
1. Go to Administrator -> Operations -> Custom Log settings.
2. Add a new Log Category for Zakeke called ZAKEKE
See the image below.
Custom Code
Storefront Reference Architecture (SFRA) does not imply modification of core cartridge to enable any of LINK integration cartridges. int_zakeke_sfra, int_zakeke_shared, bm_zakeke follows best practices recommended by Salesforce, thus no any code changes are required for the default installation.
3. Testing
After installation and configuration of CommerceCloud environment and Zakeke platform, the client can test the extension this way.
1. Import a new product using Zakeke platform. You can find instructions at the following url: https://zakeke.zendesk.com/hc/en-us?customizer
2. Go to business manager. Go to Merchant tools->Product and search for the just configured product.
3. 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.
4. 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
1. Go to the web store.
2. Search a customizable product (standard or master product) and go to its detail page.
3. Choose the options to define the variation of the item
4. A new button “Customize” should appear after the options variation choices. See the image below.
5. 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.
6. 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.
7. At the end, you can either close the page or accept the customization clicking the “Add to cart” button.
8. 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 checkout and payment phase. 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 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. In the page “Manage custom object” choose zakOrderNotification as Object type and click Find button. To see the detail of the row you can click the orderID link. See the images below.
The record can have different status. 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.