3. Integration Specifications Document
4.1.
Availability ......................................................................................................23
4.2.
Support ..........................................................................................................23
5. User guide.............................................................................................................23
5.1.
Roles, Responsibilities .....................................................................................23
5.2.
Business Manager ...........................................................................................23
5.3.
Storefront Functionality ...................................................................................23
6. Known Issues ........................................................................................................28
7. Release History ......................................................................................................28
1.
Summary
Kiala Cartridge for Demandware allows merchants to use Kiala shipping methods as
an added alternative to their shipping options.
Kiala responds to shipping needs of both registered and guest consumers by offering
a fast and flexible delivery service for parcels to a convenient collection point.
Kiala Cartridge for Demandware is a self-contained cartridge that can be easily integrated
into any project.
2.
Component Overview
2.1.
Functional Overview
Kiala Cartridge for Demandware features the following:
1. The cartridge implements Kiala shipping services for Demandware platform;
2. The Kiala services are integrated with the Demandware eCommerce platform and the
merchant can configure the options and parameters from Business Manager panel of
Demandware;
3. The parcel is delivered to a selected Kiala point;
4. The last selected Kiala point is automatically displayed whenever a new order is
placed;
4. Integration Specifications Document
5. The closest Kiala point is automatically calculated based on the closest proximity to
the ZIP code;
6. The customer can track the parcel by using the URL received after submitting order.
This URL can also be accessed from Order Details from Order History interface;
7. The user can select the language in which he wants to receive notification – Kiala
notifies the customer when the parcel is available for collection in the Kiala point;
8. The merchant has the possibility to set up the price ranges for certain packages
depending on weight or to set up a default parcel weight for all packages. The fields
that can be set by merchant are:
- Enable Weight Pricing – if this option is checked the parcel weight will be
calculated based on products weight (the products weight field should be populated
to be able to use this option);
- Default Parcel Weight – this value is used only when the Enable Weight Pricing
option is not checked and the merchant sets up a default weight for parcels;
- Mid Weight / Max Weight represents the thresholds for parcels; if a parcel has a
weight over the max weight value the shipment will not be handled;
- Price Below Mid Weight – is the parcel price when the weight is below the mid
weight;
- Price Between Mid and Max Weight – is the parcel price when the weight is
between the mid and max weight.
2.2.
Integration components
Refer to the list of components below:
Cartridge name
int_kiala
Pipelines
Kiala.xml
KialaJob.xml
Scripts
checkout/KialaShipmentPointAction.ds
kiala/piplets/ExportOrders.ds
kiala/piplets/FormValidation.ds
kiala/piplets/GetKialaPointInfo.ds
kiala/piplets/GetMapParamiters.ds
kiala/piplets/GetMapPoint.ds
kiala/piplets/GetPointDelivery.ds
kiala/piplets/GetPoints.ds
kiala/piplets/KialaCalculate.ds
kiala/piplets/KialaPointOrderPage.ds
kiala/piplets/KialaPointPlaceOrderPage.ds
kiala/piplets/UploadOrders.ds
Templates
5. Integration Specifications Document
default/checkout/shipping/kiala/kiala_shipping.isml
default/checkout/shipping/kiala/pointDelivery.isml
default/components/footer/kiala/footer_UI.isml
default/components/map/getPoint.isml
default/components/map/map_result.isml
default/components/map/mapPoint.isml
default/kiala/getmap.isml
Resources
resources/forms.properties
resources/kiala.properties
Static
files
static/default/css/shipping.kiala.css
static/default/images/infoKiala.png
static/default/images/kialaLogo.jpg
static/default/js/app.kiala.js
Metadata
Metadata/kiala_jobs.xml
Metadata/kiala_metadata.xml
Metadata/kiala_shippingMethod.xml
2.3.
Use cases
The Kiala shipping flow is very simple for customer to follow.
The order confirmation page was modified by Kiala shipping cartridge so there is a special
shipping address / shipping methods section where the customer can see the details of his
order.
The below use cases describe the Kiala Shipping flow:
1. Registered customers place first time order with Kiala shipping
a. A registered customer selects products and proceeds to checkout page;
b. When shipping details are displayed, user can select an already existing address
from saved addresses or can provide a new address;
c. The user selects the Ship with Kiala option;
d. The user selects the language for delivery notification;
e. The closest Kiala point is automatically calculated (based on ZIP provided in
delivery address) and displayed and also the map with other suggested Kiala
points appears (Note: the Kiala points available are also listed if the user presses
the Voir la liste avec les Relais Kiala);
f. The user selects the desired Kiala point directly from map or from the list (Note:
if the closest suggested Kiala point is the one that fits customer expectations
than the user can directly click Select button). The customer ha the possibility to
change the selected point by pressing Change button to select another point and
6. Integration Specifications Document
also has the possibility to see the opening hours program and location on the
map by pressing to the name of the selected point;
g. The user clicks Continue and will be redirected to billing page from where s/he
can select an appropriate payment method;
h. The customer submits the order and the shipping information and the URL for
tracking the parcel are displayed;
i. The customer receives the confirmation email that includes details of the Kiala
shipping.
2. Registered customers place subsequent order with Kiala shipping :
a. A registered customer selects products and proceeds to checkout page;
b. When shipping details are displayed, user can select an already existing address from
saved addresses or can provide a new address;
c. The user selects the Ship with Kiala option;
d. The user selects the language for delivery notification;
e. The previously selected Kiala Point is displayed, also the closest Kiala point is
displayed (calculated based on ZIP provided in delivery address) and the map with
other suggested Kiala points appears (Note: the Kiala points available are also listed
if the user press the Voir la liste avec les Relais);
f. The user selects the desired Kiala point directly from map or from the list (Note: if
the closest suggested Kiala point or the previously selected Kiala Point is the one that
fits customer expectations than the user can directly click Select button to choose
that point to receive their order). The customer has the possibility to change the
selected point by pressing Change button to select another point and also has the
possibility to see the opening hours program and location on the map by pressing to
the name of the selected point;
g. The user clicks Continue and will be redirected to billing page from where s/he can
select an appropriate payment method;
h. The customer submits the order and the shipping information and the URL for
tracking the parcel are displayed;
i. The customer receives the confirmation emails that include details of the Kiala
shipping.
3. Guest customers place order with Kiala shipping:
a. A guest customer selects products and proceeds to checkout page;
b. When shipping details are displayed, user enters the shipping address;
c. The user selects the Ship with Kiala option;
d. The user selects the language for delivery notification;
e. The closest Kiala point is automatically calculated (based on ZIP provided in
delivery address) and displayed and also the map with other suggested Kiala
points appears (Note: the Kiala points available are also listed if the user presses
the Voir la liste avec les Relais Kiala);
f. The user selects the desired Kiala point directly from map or from the list (Note:
if the closest suggested Kiala point is the one that fits customer expectations
than the user can directly click Select button to choose that point to receive their
7. Integration Specifications Document
order). The customer ha the possibility to change the selected point by pressing
Change button to select another point and also has the possibility to see the
opening hours program and location on the map by pressing to the name of the
selected point;
g. The user clicks Continue and will be redirected to billing page from where s/he
can select an appropriate payment method;
h. The customer submits the order and the shipping information and the URL for
tracking the parcel are displayed;
i. The customer receives the confirmation emails that include details of the Kiala
shipping.
2.4.
Compatibility
Based and tested on Demandware version 13.1.
2.5.
Limitations, Constraints
The cartridge provides data structure to use Demandware with an ERP. However, the
cartridge provides features to handle orders in a standalone mode (manual “readyto-ship” status, manual barcode…) including a FTP connection management. In this
mode, FTP usage is limited to one DSPID only;
The ERP connection modification to handle Kiala specific data is not provided;
The merchant should manually insert the list of Kiala supported countries.
3.
Implementation Guide
3.1.
Setup
3.1.1. Overview
There will be two files provided to the merchant:
A configuration file in XML format – will be imported and installed in Business
Manager interface;
The documentation (integration details) in pdf / word format – will describe all
installation and integration required steps for both cartridge and configuration file.
3.1.2. Import metadata for int_kiala
Job schedules
1. Login to Business Manager
2. Go to Administration > Operations > Import & Export > Upload
8. Integration Specifications Document
3. Upload Metadata/kiala_jobs.xml
4. Click on the << Back button
5. Go to Import
6. Select “kiala_jobs.xml”
7. Click Next >>
9. Integration Specifications Document
Shipping Methods
1. Login to Business Manager
2. Go to [YOUR SITE] > Ordering > Import & Export > Upload
3. Upload Metadata/kiala_shippingMethod.xml
4. Click on the << Back button
5. Go to Shipping Methods > Import
10. Integration Specifications Document
6. Select “kiala_shippingMethod.xml”
7. Click Next >>
System Object Definitions
1. Login to Business Manager
2. Go to Administration > Site Development > Import & Export > Upload
3.
4.
5.
6.
7.
Upload Metadata/kiala_metadata.xml
Click on the << Back button
Go to Meta Data > Import
Select “kiala_metadata.xml”
Click Next >>
3.1.3. Install cartridge
1.
2.
3.
4.
Open Demandware Studio
Click File > Import > General > Existing Files Into Workspace
Browse to the “int_kiala” directory
Click Finish
11. Integration Specifications Document
5. Login to Business Manager
6. Go to Administration > Sites > Manage Sites
7. Select [YOUR SITE]
8. Click on the “Settings” tab
9. Append “:int_kiala” to the “Cartridges:” field
10. Click Apply
3.2.
Configuration
1. Login to Business Manager
2. Go to [YOUR SITE] > Site Preferences > Custom Preferences > Kiala
3. Here you can find various configuration items for your Kiala installation. Each of
these items has a description about what it is used for.
12. Integration Specifications Document
3.3.
Custom Code
3.3.1. Custom code added to storefront_core
1. cartridge/forms/default/billingaddress.xml
1. Edit “country” form field and add the list of supported countries by Kiala (eg.
FR/France). The value of this field is used to get the correct DSPID from the list of
supported DSP Ids form Business Manager.
2. cartridge/forms/default/shippingaddress.xml
7) Edit “country” form field and add the list of supported countries by Kiala (eg.
FR/France). The value of this field is used to get the correct DSPID from the list of
supported DSP Ids form Business Manager.
3. cartridge/templates/resources/components.properties
1) Add the following lines to “orderdetails” section
orderdetails.shippingaddress=Shipping Address
orderdetails.shippingmethods=Shipping Methods
4. cartridge/templates/resources/forms.properties
17. Integration Specifications Document
.
<span class="state"><isprint
value="${ShippingAddress.stateCode}"/> </span>
.
<span class="zip"><isprint value="${ShippingAddress.postalCode}"/></span>
. </div><!-- END:location -->
. <div class="country"><isprint value="${ShippingAddress.countryCode}"/></div>
. </isif>
</div><!-- END:name -->
10. cartridge/pipelines/Cart.xml
-
-
Go to Cart-Calculate node
Below the “cart/CalculateCart.ds” script piplet add a new decision node with the
following decision key “Basket.defaultShipment.shippingMethodID == 'kiala'” as in
the screen shoot below.
On the Yes branch of the decision node make a call to Kiala-Calculate node
11. cartridge/pipelines/COPlaceOrder.xml
18. Integration Specifications Document
-
Go to COPlaceOrder-Start node
Between COPlaceOrder-CreateOrder and COPlaceOrder-HandlePayments call nodes
add a call node to Kiala-SavePointIdToPlaceOrder as in the screen shoot below.
12. cartridge/pipelines/COShipping.xml
-
Go to “COShipping-Start” node
Between “COShipping-InitForms” and “COShipping-PrepareShipments” add a call
node to “Kiala-InitForm”
19. Integration Specifications Document
-
Go to the “Save” transition branch
Right above the call to the “COBilling-Start” call node add a call node to the “KialaSavePointIdToOrder”
The “next” transition branch from the call to “Kiala-SavePointIdToOrder” should
continue to “COBilling-Start” while the “KialaValidationError” transition branch should
make a call to “COShipping-Start” as in the screen shoot below
20. Integration Specifications Document
3.3.2. Custom code added to storefront_richUI
1. Cartridge/templates/default/components/footer/footer_UI.isml
1. Add the following lines at the end of the file:
<iscomment>Include Kiala Shipping Footer</iscomment>
<isinclude template="components/footer/kiala/footer_UI"/>
21. Integration Specifications Document
2. cartridge/static/default/js/app.js
1.
2.
3.
4.
Go to “app.checkout” module
Go to “addressLoad” function
Go to “$cache.addressList.on("change"” handler
Look for the following pice of code
// re-validate the form
$cache.checkoutForm.validate().form();
5. Insert the following code right above:
if (app.Kiala) {
if (app.Kiala.currentShippingMethId == 'kiala') {
app.Kiala.ShowShippingOptions($('.kialaMap').attr('data-map-type'));
}
}
6. Go to “initializeEvents” function
7. Add the following code inside “if (isShipping) {” bellow “shippingLoad();”
if (app.Kiala) {
app.Kiala.init();
}
22. Integration Specifications Document
3.4.
Testing
For a complete scenario to use the Kiala Shipping method you can go through the following
steps:
1. Go to Demandware Storefront;
2. As registered or guest customer you need to add products to your shopping cart
then proceed to checkout;
3. On shipping section you can pick an existing address from saved addresses (in case
of registered customers) or you can add a new address as registered or guest
customer;
4. From “Select Shipping Method” section select Ship with Kiala option;
5. Select the language for delivery notification;
6. Select the desired Kiala point for parcel delivery – you can select the closest Kiala
point suggested or other Kiala point from the map (unlike guest user, as registered
user you have the possibility to select a previously selected Kiala point);
7. The selected point and associated info are displayed and you have the possibility to
change it by pressing the Change button and to select another point; you can see
the opening hours program and location on the map by clicking on the name of the
selected point;
8. Click Continue button and select the billing address (if it wasn’t checked to be used
the same address as shipping address) and the payment method and go further to
submit the order;
9. After submitting the order the Shipment information is displayed – the shipping
address is the selected Kiala point address and there is also displayed the track &
trace URL – to check the order status.
4.
Operations, Maintenance
23. Integration Specifications Document
4.1.
Availability
If, for any reason, the service becomes inactive then the option to use Kiala as shipping
method will not be displayed on the webstore.
4.2.
Support
Supporting documentation and data will be provided:
Archived cartridge;
Configuration / installation files;
Integration guide
5.
User guide
5.1.
Roles, Responsibilities
The merchant will have administrative role.
5.2.
Business Manager
In Business Manager, the merchant can easily find all the shipping information saved by
customer for each order. The info can be verified in:
- Business Manager > Ordering>Orders>Shipment>Attributes – all the shipping
information is displayed.
5.3.
Storefront Functionality
The additional feature on storefront will be the availability of Kiala shipping method. Once a
customer completes the shipping address based on provided ZIP code the system will
display a map with available Kiala points. If the customer wants to receive the parcel to
other location s/he is able to change the ZIP code directly from the map by clicking the
Address button and after adding the new address by clicking the Search button - the new
calculated Kiala points are displayed to the map.
24. Integration Specifications Document
1. In Shipping page the customer selects an existing address or provides a new address
(as register or as guest customer);
1. The customer selects Ship with Kiala option
Note: the Ship with Kiala option can be checked as default shipping method and
based on settings of calculating parcel price, set up by merchant, the customer can
see the shipping price in right side.
25. Integration Specifications Document
2.
The customer selects the desired Kiala point from:
Suggested points : Closest Kiala Point or Previously Selected Kiala
Point OR
Any point available on the map.
Notes:
Closest Kiala Point will be displayed for all customers
Previously Selected Kiala Point will be displayed only for registered
customers who used Kiala shipping services in the past;
The points from the map marked in grey are those points that are not
available for the moment;
The customer has the possibility to change the selected point by pressing
Change button to select another point and also has the possibility to see the
opening hours program and location on the map by clicking on the name of
the selected point;
27. Integration Specifications Document
4. The customer clicks Continue button and goes to Billing page;
5. The customer follows standard checkout process required to submit the order (the
information of Kiala point selected for delivery is displayed on the right and can be
edited)
6. After submitting the order the Shipping information and track and trace URL are
displayed;
