OSF Integrator for Demandware and Canada Post - Integration Specifications Document
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
OSF Integrator for Demandware and
Canada Post
Integration Specifications Document
© 2015 OSF Global Services. All Rights Reserved. Page 1
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Table of Contents
1. Summary.................................................................................................................................... 3
2. Component Overview............................................................................................................... 3
2.1 Functional Overview ........................................................................................................... 3
2.2 Integration components..................................................................................................... 4
2.3 Use cases.............................................................................................................................. 7
2.4 Compatibility ...................................................................................................................... 10
2.5 Limitations, Constraints.................................................................................................... 10
3. Implementation Guide ........................................................................................................... 11
3.1 Setup................................................................................................................................... 11
3.1.1 Overview ...................................................................................................................... 11
3.1.2 Import meta data for Canada Post cartridge ......................................................... 11
3.1.3 Install cartridge........................................................................................................... 15
3.1.4 Setup “Update Shipping Methods” job .................................................................... 19
3.2 Configuration ..................................................................................................................... 21
3.3 Custom Code...................................................................................................................... 27
3.3.1 SiteGenesis 1 Custom code....................................................................................... 27
3.3.2 SiteGenesis 2 Custom code....................................................................................... 37
3.4 Testing ................................................................................................................................ 46
4. Operations, Maintenance....................................................................................................... 47
4.1 Availability .......................................................................................................................... 47
4.2 Support ............................................................................................................................... 47
5. User guide ............................................................................................................................... 47
5.1 Roles, Responsibilities ...................................................................................................... 48
5.2 Business Manager ............................................................................................................. 48
5.3 Storefront Functionality.................................................................................................... 49
6. Known Issues .......................................................................................................................... 56
7. Release History ....................................................................................................................... 56
© 2015 OSF Global Services. All Rights Reserved. Page 2
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
1. Summary
OSF Integrator for Demandware and Canada Post allows merchants to use the
Canada Post shipping methods as an added alternative to their shipping options.
By choosing Canada Post shipping methods, customers have different delivery options
including picking up their products from local Canada Post office.
Both registered and guest customers can select and use these services.
OSF Integrator for Demandware and Canada Post is a self-contained cartridge that can
be easily integrated into any project.
2. Component Overview
2.1 Functional Overview
OSF Integrator for Demandware and Canada Post features the following:
1. The cartridge implements Canada Post shipping services into the Demandware
webstore
2. “All-in-one” service: all Canada post shipping methods are provided in a
configuration panel and they can be selected or unselected by clicking on a
checkbox;
3. The order shipping price is calculated directly by calling a web-service based on a
set of inputs provided by the customer (address details) and merchant (product
weights, store address). The price will be accurate and will also include the
shipping taxes - there is no need for other additional configuration;
4. “Deliver to Post Office” option is included - the customer can select to pick up
the ordered products from a Canada Post office (this option will be available with
Xpresspost and Expedited Parcel methods). All available postal offices within an
area will be displayed and the customer has the possibility to pick an office from
a map (or from an additional list of postal offices next to the map);
5. The functionality of the cartridge provides precise expected delivery dates in
order to set accurate customer expectations.
6. Setting the prices for the shipping services offered to the customers.
a. Inflated/Deflated rates – the standard Canada Post shipping rates can be
modified as per business requirements
b. Flat Rates – fixed rates for specific services can be offered to customer
© 2015 OSF Global Services. All Rights Reserved. Page 3
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
c. Free Shipping – shipping free of charge can be offered for orders exceeding a
certain value
7. Through the Fulfilment Days option, the merchant can set the number of days
required for the products to transit from the warehouse to Canada Post locations
for shipping. The outcome of this is that the Expected Delivery Date provided to
the customers will be even more accurate.
8. Customer will be able to track their order and see the shipping status directly
from the merchant’s website.
9. Automatically conversion from pounds to kilograms for product/parcel weight, in
order to ensure accurate calculations of the shipping price.
10. The merchant has the possibility of selecting different options offered by Canada
Post with their shipping services. Depending on the products that the merchant
is selling, these options may be applicable.
11. The user can edit the Post Office address on any checkout page and then select
a different post office from the map.
2.2 Integration components
Refer to the list of components below:
Cartridge name
int_canadapost
Forms
canadapostmerchantpanel.xml
canadapostnpoaddresses.xml
Pipelines
CPAdministrativePanel.xml
CPNearestPO.xml
CPOpenReturnLabel.xml
CPOriginPostCode.xml
CPRating.xml
CPShippingMethods.xml
CPTracking.xml
Scripts
bm/install/AssignOptionsToService.ds
bm/install/CreateCPOption.ds
bm/install/CreateCPService.ds
bm/pricing_rules/CPAddPricingRule.ds
bm/pricing_rules/CPDeletePricingRule.ds
bm/pricing_rules/CPEditPricingRule.ds
bm/pricing_rules/CPUpdatePricingRule.ds
bm/pricing_rules/CPUpdateRuleProperty.ds
© 2015 OSF Global Services. All Rights Reserved. Page 4
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
bm/CPGetMerchantRegistrationInfo.ds
bm/CPGetMerchantRegistrationToken.ds
bm/CPMerchantFormObject.ds
bm/CPProcessToCustomObjects.ds
bm/CPUpdateShippingMethods.ds
canadapost/callCPShippingServices.ds
lib/libCPUtils.ds
lib/libCPWSUtils.ds
returnlabels/CPCreateOpenReturnTemplate.ds
returnlabels/CPGetOpenReturnTemplate.ds
returnlabels/CPGetOpenReturnTemplateDetails.ds
returnlabels/CPGetOpenReturnTemplates.ds
returnlabels/CPRetrieveNextOpenReturnArtifact.ds
storefront/CPCreateShippingAddress.ds
storefront/CPDiscoverServices.ds
storefront/CPGetCurrencyConvertionRate.ds
storefront/CPGetExchangeRate.ds
storefront/CPGetNearestPostOffice.ds
storefront/CPGetOption.ds
storefront/CPGetOriginPostalCode.ds
storefront/CPGetPostOfficeDetail.ds
storefront/CPGetPostOfficeFeedback.ds
storefront/CPGetRates.ds
storefront/CPGetSelectedShippingMethod.ds
storefront/CPGetService.ds
storefront/CPGetTrackingDetails.ds
storefront/CPGetTrackingSummary.ds
storefront/CPSaveNearestPOAddress.ds
storefront/CPSaveNearestPOAddress1.ds
Static
css/cp_main.css
css/cp_lang_switch.css
bm/js/cp.app.js
bm/js/jquery.cookie.js
bm/lib/jquery/jquery-1.9.1.min.js
bm/lib/jquery/jquery-ui-1.10.1.custom.js
js/cp.main.js
js/cp.main_sg1.js
js/handlebars-1.0.rc.1.min.js
js/jquery.storelocator.js
js/jquery.storelocator_sg1.js
storelocatortemplates/infowindow-description.isml
storelocatortemplates/location-list-description.isml
bm/images/cplogo.jpg
images/ajax-loader.gif
© 2015 OSF Global Services. All Rights Reserved. Page 5
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
images/close-icon.png
images/cp-info-ok.png
images/cp-marker-blank.png
images/cp-marker.png
images/help_ico.gif
images/overlay-bg.png
Templates
bm/cp_administrative_panel.isml
bm/cp_services.isml
bm/pricing_rules/cp_flatrate.isml
bm/pricing_rules/cp_free.isml
bm/pricing_rules/cp_inflatedeflate.isml
bm/pricing_rules/cp_json_response.isml
checkout/shipping/cp_discoverservices.isml
checkout/shipping/cp_get_basket_status.isml
checkout/shipping/cp_locations_error.isml
checkout/shipping/cp_locations_feedback.isml
checkout/shipping/cp_locations.isml
checkout/shipping/cp_nearestpo.isml
checkout/shipping/cp_office_detail.isml
checkout/shipping/cp_origin_post_code.isml
checkout/shipping/cp_right_column_sg1.isml
checkout/shipping/cp_right_column.isml
checkout/shipping/cp_save_cp_shipping_details.isml
checkout/shipping/cp_save_po_shipping_address.isml
checkout/shipping/cp_selected_shipping_method_json.isml
checkout/shipping/cp_serviceoption.isml
checkout/shipping/cp_serviceoptions.isml
checkout/shipping/cp_servicerates.isml
checkout/shipping/cp_shippingmethods.isml
checkout/tracking/cp_trackingsummary.isml
components/footer/canadapost_footer_sg1.isml
components/footer/canadapost_footer.isml
components/order/cp_orderdetails.isml
components/order/cp_orderdetailsemail.isml
resources/cp_appresources_sg1.isml
resources/cp_appresources.isml
resources/cp_bmresources.isml
util/canadapost_errormessage.isml
util/canadapost_inputfield.isml
util/canadapost_modules.isml
Resources
resources/canadapost_fr_CA.properties
resources/canadapost.properties
Webreferences
© 2015 OSF Global Services. All Rights Reserved. Page 6
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
artifact.xsd
authreturn.wsdl
authreturn.xsd
common.xsd
converter.wsdl
customerinfo.xsd
merchantregistration.wsdl
merchantregistration.xsd
openreturn.xsd
openreturn.wsdl
postoffice.wsdl
postoffice.xsd
rating.xsd
rating.wsdl
tracking.wsdl
tracking.xsd
Custom extensions
bm_extensions.xml
Metadata
geolocations/Geolocations-ca.zip
meta/site-pref_CPConfigs.xml
meta/site-pref_CPOptions.xml
meta/site-pref_CPParcelCharacteristics.xml
meta/site-pref_CPPricingRules.xml
meta/site-pref_CPServices.xml
2.3 Use cases
The Canada Post shipping flow is very simple for customers to follow.
The order notification emails have been modified by the cartridge so they contain a
special Shipping Details section where the customer can see all of the details of their
order.
The below use cases describe the Canada Post Shipping Flow:
1. The customer selects a shipping service based on their personal
address:
a. A registered or guest customer selects products and proceeds to checkout
page;
b. When shipping details are displayed, the user can select an already existing
address from saved addresses or can provide a new address;
c. The user selects the Canada Post shipping option;
d. All of the associated services will appear in a dropdown list;
© 2015 OSF Global Services. All Rights Reserved. Page 7
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
e. User selects one or more services from the available list based on the options
checked by the merchant in the Business Manager for the selected service.
f. The shipping price can be displayed by clicking the Calculate Shipping Price;
otherwise a user can directly click on Continue;
g. The customer will be redirected to the billing page from where they can
select an appropriate payment method;
h. The customer submits the order and all the shipping details (price, delivery
address, selected services).
2. Customer submits order with Free shipping service.
a. Merchant creates a new free shipping rule for one of the Shipping Services;
b. User selects products and proceeds to checkout.
c. When shipping details are displayed, user can select an already existing
address from saved addresses or can provide a new address;
d. The user selects Canada Post from shipping section;
e. In the services list, user will have the Free Shipping service set up by the
merchant through the rule.
f. The shipping price can be displayed by clicking the Calculate Shipping Price,
it will be 0;
g. The customer will be redirected to billing page where they can select an
appropriate payment method;
h. The customer submits the order and all of the shipping details (price, delivery
address, selected services).
3. Customer submits order with Deliver to Post Office option:
a. A 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 Canada Post shipping from shipping section;
d. The user selects one desired service from the dropdown list;
e. All the associated services appear and the user checks the Deliver to Post
Office to pick up the products from a local postal office;
f. The ZIP code field will be populated with the ZIP code of the address and the
user can select to change it or use the existing one. By clicking the Show the
Map button, the nearest postal offices in that area will be displayed both on
the map and as a list.
g. Once selected, the desired postal code will be taken into account as delivery
point;
© 2015 OSF Global Services. All Rights Reserved. Page 8
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
h. The shipping price can be displayed by clicking the Calculate Shipping Price;
otherwise the user can directly click on Continue;
i. The customer will be redirected to billing page where they can select an
appropriate payment method;
j. The customer submits the order and all the shipping details (price, delivery
address, selected services).
4. Customer submits order with Flat rate shipping:
a. A 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 Canada Post shipping from shipping section;
d. The user selects one desired service from the dropdown list;
e. The method selected by the user has a Flat Rate rule set up and activated by
the merchant;
f. The price displayed, after clicking Calculate Shipping Price, will be the one set
up by the merchant in the Business Manager.
g. The customer will be redirected to the billing page where they can select an
appropriate payment method;
h. The customer submits the order and all the shipping details (price, delivery
address, selected services).
5. Customer submits order with Flexible rate shipping:
a. A 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 Canada Post shipping from shipping section;
d. The user selects one desired service from the dropdown list;
e. The method selected by the user has a Flexible Rate rule set up and
activated by the merchant;
f. The price displayed, after clicking Calculate Shipping Price, is inflated or
deflated based on the rule set up by the merchant.
g. The customer will be redirected to the billing page where they can select an
appropriate payment method;
h. The customer submits the order and all the shipping details (price, delivery
address, selected services).
Note: customers will have no visibility on the fact that the rate has been
inflated/deflated.
6. Registered customer tracks an order:
© 2015 OSF Global Services. All Rights Reserved. Page 9
6655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
a. A customer is logged into the merchant’s website.
b. A customer has at least ONE order submitted;
c. Customer clicks Check Order to track one of the submitted orders ;
d. A new page with the Order History is opened, where all of the orders are
displayed;
e. Customer clicks on Order Details;
f. Customer enters the Tracking Number and clicks Track.
g. Details regarding the order delivery are displayed.
7. Guest Customer tracks an order:
a. A customer is logged into the merchant’s website.
b. A customer has at least an order submitted;
c. Customer enters their order number and Billing Zip Code and clicks Check
Status;
d. A new page with the Order Details are displayed where the user can enter a
Tracking Number;
e. Customer enters the Tracking Number and clicks Track.
2.4 Compatibility
Based and tested on Demandware version 13.5. (Site Genesis1 and 2)
2.5 Limitations, Constraints
1. The product inventory list is not linked to the stores; some products might not
be available in the nearest store, thus “Shipping Distribution Center ZIP code”
could be taken into account and be used if most of the products are likely to
be found within that centre (the functionality of linking the inventory list to the
stores may be provided in a further version);
2. The nearest post office list is generated based on the provided postal code
only (full address is not yet included when searching the nearest post offices).
3. Multi-ship method available with SG version 13.3 is not supported by the
current version of the cartridge.
4. Expected delivery date – in the case an order contains multiple types of
product availabilities (i.e. a product in-stock and a back ordered product) only
one delivery date (the latest) will be provided.
5. Expected delivery date – functionality is mainly restricted to shipping within
Canada.
6. Inactive options in the merchant administrative panel – these options are
subject to customization due to reduced incidence in the ecommerce business.
© 2015 OSF Global Services. All Rights Reserved. Page 106655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
7. Signature and identity options (Signature option, Proof of Age Required-18,
Proof of Age Required-19) are options that may have a fee and therefore be
reflected in the rate when a merchant is using an actual-rate shipping policy.
These options should not be used when merchant is applying special pricing
rules (i.e. flat rate, free shipping etc.)
8. Special Pricing – there can be only one rule applied to a service at a time
(either flat rate or free shipping or flexible pricing)
9. Special pricing – there can be only one flat rate or free shipping activated at a
time for multiple services. (i.e. if a flat rate for Priority service has been
activated, a flat rate for XpresssPost cannot be activated too).
10. Flat rates – this pricing option is currently offered for Canadian shipping. For
US and International destinations, this service is subject to customization work.
11. Free shipping – this pricing option is currently offered for Canadian shipping.
For US and International destinations, this service is subject to customization
work.
12. Delivery to Post office is offered only for shipping within Canada.
3. Implementation Guide
3.1 Setup
3.1.1 Overview
There will be three files provided to the merchant:
The cartridge in an archived format – will be installed and
configured from UX Studio (Eclipse);
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 meta data for Canada Post cartridge
1. Go to “Business Manager -> Administration ->Site Development -> Import &
Export” and choose “Upload” from “Import & Export Files” section;
© 2015 OSF Global Services. All Rights Reserved. Page 116655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
2. From “Upload Import Files” choose “site-pref_CPConfigs.xml“ file which comes
together with the cartridge;
3. Upload the file;
4. Repeat process from steps (2.) and (3.) for “site-pref_CPOptions.xml”, “site-
pref_CPPricingRules.xml”, “site-pref_CPServices.xml” and “Geolocations-ca.zip”
that also comes together with the cartridge;
© 2015 OSF Global Services. All Rights Reserved. Page 126655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
5. With this files uploaded and ready to use go back to “Business Manager ->
Administration ->Site Development -> Import & Export” and choose “Import”
from “Meta Data” section;
6. Select “site-pref_CPConfigs.xml” and click Next;
7. The preference file should be validated in order to be imported to your system;
8. After the file was validated, the preferences can be imported to the system.
Click Import;
© 2015 OSF Global Services. All Rights Reserved. Page 136655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
9. Repeat process from steps (5.), (6.), (7.) and (8.) for “site-pref_CPOptions.xml”,
“site-pref_CPPricingRules.xml” and “site-pref_CPServices.xml”
10. The preferences have been successfully installed and you can go back to
“Business Manager -> Administration ->Site Development -> Import & Export”
and choose “Import” from “Geolocation” section;
11. Select “Geolocation-ca.xml” and click Next;
12. Wait until XML schema validation is done;
© 2015 OSF Global Services. All Rights Reserved. Page 146655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
13. Now the file is validated and the “Geolocations” can be imported to the system.
Click Import;
13. The “Geolocations” has been successfully installed.
3.1.3 Install cartridge
Follow below steps in order to import the cartridge:
1. Select the connection to the DW server -> Import;
2. Select “Existing Project into Workspace” option;
© 2015 OSF Global Services. All Rights Reserved. Page 156655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
3. Import Projects -> Select archive file (or “root directory”) if you have
already unzipped the cartridge;
© 2015 OSF Global Services. All Rights Reserved. Page 166655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
4. Select the archive from your local source (or the unzipped cartridge);
5. Click Finish and Yes in order to complete the import;
© 2015 OSF Global Services. All Rights Reserved. Page 176655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
6. After successfully completing these steps the cartridge is added to your
project and you need to check if it was also added to Project References;
© 2015 OSF Global Services. All Rights Reserved. Page 186655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
7. Next, go to Business Manager -> Manage Sites -> Your Site – Settings add
“int_canadapost” cartridge to the cartridges path in front of storefront
cartridge;
8. To check if the cartridge was added to the current active version go to
“Business Manager -> Administration -> Code Deployment;
After all these steps the cartridge is successfully installed and ready to use.
3.1.4 Setup “Update Shipping Methods” job
To correctly create and setup the “Update Shipping Methods” job you need to go
Business Manager -> Administration -> Operations-> Job Schedules -> New (to create a
new job) and you need to complete the steps below:
In the general tab, enter the job name : Update Shipping Methods, then
enable it;
In Execution Scope field choose Sites;
Choose CPShippingMethods pipeline which will run a job;
Choose UpdateShippingMethods for start node;
Run the job;
Go to Business Manager -> -> Custom Objects ->
Custom Object Editor
© 2015 OSF Global Services. All Rights Reserved. Page 196655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Select CPServices for Object Type, then click Find : You should see 20 items.
If you see less than 20 items in the list, (e.g. only 17 items):
1. Click “Show All items” link in the pagination bar;
2. Click “Select All” link in the header, so that all 17 checkboxes will be selected;
3. Click “Delete” button;
4. Click “Yes” when you are asked “Are you sure that you want to delete these
items?”;
5. Re-run the “Update Shipping Methods” job;
Select CPOptions and click Find : You should see 122 items.
If you see less than 122 items in the list, e.g. only 120 items:
1. Click “Show All items” link in the pagination bar;
2. Click “Select All” link in the header, so that all 120 checkboxes will be
selected;
3. Click “Delete” button;
4. Click “Yes” when you are asked “Are you sure that you want to delete these
items?”;
5. Re-run the “Update Shipping Methods” job;
© 2015 OSF Global Services. All Rights Reserved. Page 206655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
In the Sites tab, choose the site for which you want to run the job
3.2 Configuration
For a proper configuration you need to go through these steps:
1. Go to Business Manager->Ordering->Shipping Methods->New->Canada Post
Shipping - Canada Post is added as a new Shipping Method and no additional
settings are required;
© 2015 OSF Global Services. All Rights Reserved. Page 216655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
2. Go to Business Manager->User Profile - choose the preferred language;
The cartridge has language files for both English and French;
The labels and messages of the cartridge will be changed based on merchant
preferred language.
3. Go to Business Manager->Administration->Organization->Roles & Permissions
a) Choose Administrator role
b) Go to Business Manager Modules tab
c) Select Canada Post site in the Select Context drop-down
d) Click Apply
e) Click the checkbox for the Canada Post Shipping->Merchant Administrative
Panel module and click Update
© 2015 OSF Global Services. All Rights Reserved. Page 226655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
4. Go to Business Manager->Canada Post site->Canada Post Shipping->Merchant
Administrative Panel
© 2015 OSF Global Services. All Rights Reserved. Page 236655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
There are seven sections that divide the functionality for better structuring;
a. When the Register button is selected, the Merchant will be registered on behalf
of the platform (OSF) and “Merchant Registration Data” will be automatically
populated;
o “Shipping Method ID” represents the ID configured in “Business Manager-
>Ordering->Shipping Methods” section and may be different from site to
site; it will be manually added by the merchant and used as an identifier by
the logic of the cartridge;
o “GUI Shipping Method List ID” represents the ID of the HTML element from
Checkout page where shipping methods are displayed;
Important note:
- For SiteGenesis 1 this string should be “shippingmethodform”;
© 2015 OSF Global Services. All Rights Reserved. Page 246655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
- For SiteGenesis 2 it should be “shipping-method-list”;
o Fulfilment days: the number of days required for the products to transit
from the warehouse to Canada Post locations for shipping.
b. The “Shipping Services” section includes all of the available services grouped by
destination (Canada, US, International);
o The merchant may choose from the available services based on each site
requirements by selecting / unselecting a checkbox;
o The merchant may choose the shipping options that will be available to
shoppers;
o Only one of the options Proof of Age Required – 18 and Proof of Age
Required – 19 should be selected at a time.
o Some options are offered by Canada Post free of charge, whereas others
may incur additional charges. Currently the free options are: Deliver to
Post Office, Leave At Door – do not card, Do Not Safe Drop, Card for
Pickup). They can be enabled by the merchant to be displayed on the
storefront at all times. Other options that may incur fees should be mainly
activated when standard shipping prices are used. Please contact Canada
Post for more pricing information on the paid services.
o There are certain compatibility rules applicable to the service options (i.e.
if Signature option is selected, Leave at door-do not card option cannot
be selected). These rules are driven by Canada Post policies.
c. “Parcel Characteristics” section includes a series of options related to the parcel:
o Parcel Weight (Default) can be used in the following cases:
The merchant sells a series of products whose weight is not very
important (e.g. supplements, pills) and the parcel weight can be
anticipated or is very unlikely to exceed a certain weight;
The merchant uses this cartridge for testing purpose only and is not
necessary to configure weights for each product;
Emergency cases: the product weights cannot be available a short
period of time due to some unexpected events;
Note: if the product weight is not defined in the Business Manager, the
calculation of the shipping price will be done based on the parcel weight
value.
o Product Weight Attribute:
Demandware does not have a system attribute for product weight;
© 2015 OSF Global Services. All Rights Reserved. Page 256655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Due to the case above this attribute may be different from merchant
to merchant;
Our application needs to identify the attribute used for product weight
by each merchant;
o Parcel Weight Measurement Unit and Product Weight Measurement Unit :
Choose kg or pound (lb)
d. “Shipping Config Data” section has the following parameters:
o “Shipping Method Id”: Represents the Canada Post shipping method ID
configured by the merchant;
o “Shipping Distribution Center”: The default store used for calculating the
shipping price, in case the system fails to provide the merchant’s nearest
store;
o “Fulfilment Days”: The transit time required for the products to reach Canada
Post from the merchant’s store.
o “GUI Shipping Method List ID”: Represents the ID of the HTML element from
the Checkout page where shipment methods are displayed.
e. “Deliver to Post Office” section is related to the similar option and has the
following parameters:
o “Maximum Number of Retrieved Offices” represents the maximum number of
the returned postal offices which are within the area searched by the
customer;
o “Google Map Zoom Level”: This parameter is used to set the default zoom
level of the Google map which shows the nearest post offices ;
f. “Pricing” section is the management system for Flat rates, Flexible rates and
Free Shipping
o “Flat rates”
The merchant has the option to offer one flat rate for each of the
following Canada Post services.
o “Flexible rates”
The merchant has the option to inflate or deflate the rate returned by
Canada Post by either a percentage or a fixed amount.
o “Free shipping”
The merchant has the option to offer free shipping for orders above a
specific amount.
g. “Tracking” section:
o Tracking Summary: enabled order tracking and displays shipping status
directly on the merchant’s website.
© 2015 OSF Global Services. All Rights Reserved. Page 266655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
3.3 Custom Code
3.3.1 SiteGenesis 1 Custom code
3.3.1.1 Custom code added to storefront core
Forms
o Single shipping form: singleshipping.xml. Add the following code:
after
© 2015 OSF Global Services. All Rights Reserved. Page 276655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Order tracking form: ordertrack.xml.
For non-registered users to see order details, they need to enter an order
number and zip code (default Demandware functionality). To make it work for
Canadian postal code you need to change regexp attribute of “postalCode”
formfield of ordertrack.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVWXYZabc
eghjklmnprstvxy](
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
o Shipping address form : billingaddress.xml.
To make it work for Canadian postal code you need to change regexp
attribute of “zip” formfield of shippingaddress.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVW
XYZabceghjklmnprstvxy](
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
o Billing address form : billingaddress.xml.
To make it work for Canadian postal code you need to change regexp
attribute of “zip” formfield of billingaddress.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVW
XYZabceghjklmnprstvxy](
© 2015 OSF Global Services. All Rights Reserved. Page 286655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
Pipelines
o Add pipeline Resources.xml:
Add a Resources.xml file in cartridge/pipelines and add the following content
to the file:
© 2015 OSF Global Services. All Rights Reserved. Page 296655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
© 2015 OSF Global Services. All Rights Reserved. Page 306655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Resource Template
The pipeline should look like this:
o Pipeline OnSession.xml.
Add the following (non-transactional) script node
Script File: int_canadapost:canadapost/callCPShippingServices.ds.
© 2015 OSF Global Services. All Rights Reserved. Page 316655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Pipeline Order-History in Order.xml
For registered users, include call node right before orderdetails.isml
template
o Pipeline Order-Find in Order.xml.
For non-registered users, include call node right before “ok” end node
© 2015 OSF Global Services. All Rights Reserved. Page 326655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Scripts
o Calculate Cart script: cart\CalculateCart.ds
Add following code after end of import packages from DW framework
importScript( "int_canadapost:lib/libCPUtils.ds" );
Add following code
var cpShippingSrv = new CPShippingServices();
© 2015 OSF Global Services. All Rights Reserved. Page 336655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
cpShippingSrv.SetCPShippingPrice(basket);
After CALCULATE SHIPPING COSTS code block
ShippingMgr.applyShippingCost(basket);
o Get applicable shipping methods script:
checkout\GetApplicableShippingMethods.ds
o Add following code after end of import packages from DW framework
importScript( "int_canadapost:lib/libCPUtils.ds" );
o Add following code
var cpShippingSrv = new CPShippingServices();
cpShippingSrv.CheckCPApplicable(countryCode, ret, basket);
after block code
// Retrieve the list of applicabnle shipping methods for the given
shipment and address.
var shippingModel : ShipmentShippingModel =
ShippingMgr.getShipmentShippingModel(shipment);
var ret : Collection = new ArrayList();
© 2015 OSF Global Services. All Rights Reserved. Page 346655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
ret = shippingModel.getApplicableShippingMethods(addressObj);
For testing the Tracking Summary feature you need to change API keys. To do this,
change productionEnvironment flag to false in libCPWSUtils.ds line 13. Please ensure
you change productionEnvironment flag to True, once you are done with testing.
Templates
o Header template : components/header/htmlhead.isml
Add the following code
[DW#CanadaPostShipping#HtmlHead]
[Demo@CanadaPostDemo@HtmlHead]
after element
THIRD PARTY STYLESHEETS STYLING
o Footer template : components/footer/footer.isml
Add the following lines at the end :
[DW#CanadaPostShipping#Footer] Include Canada
Post Footer
o Single shipping template: checkout\shipping\singleshipping.isml
Add the following code
© 2015 OSF Global Services. All Rights Reserved. Page 356655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
[#CanadaPostShipping#] Add Canada Post Shipping Methods
Content
after element
Also add the following code
$("#dwfrm_singleshipping_shippingAddress
input[name$='_addressFields_zip']").trigger('cpcustomchange');
after the code around line 370 :
// activate the tooltips in the newly loaded AJAX section
app.tooltipDefault();
o Order details template: components\order\orderdetails.isml
Insert the following code
[DW#CanadaPostShipping#OrderDetails] Display Canada
Post shipment details
after looping thru shipment.productLineItems code
© 2015 OSF Global Services. All Rights Reserved. Page 366655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Minisummary template : checkout/minisummary.isml
Remove the lines :
and
around the code at line 51 :
o Minibillinginfo template : checkout/billing/minibillinginfo.isml
Add the following code
[DW#CanadaPostShipping#Checkout] Display Post
Office Address on right sidebar of checkout
pages
before
around line 10
3.3.2 SiteGenesis 2 Custom code
3.3.2.1 Custom code added to storefront core
Forms
o Single shipping form: singleshipping.xml. Add the following code:
© 2015 OSF Global Services. All Rights Reserved. Page 376655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
after
o Order tracking form: ordertrack.xml.
For non-registered users to see order details they need to enter order
number and zip code (default Demandware functionality). To make it
© 2015 OSF Global Services. All Rights Reserved. Page 386655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
work for Canadian postal code you need to change regexp attribute of
“postalCode” formfield of ordertrack.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVW
XYZabceghjklmnprstvxy](
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
o Shipping address form : shippingaddress.xml.
To make it work for Canadian postal code you need to change regexp
attribute of “zip” formfield of shippingaddress.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVWXYZ
abceghjklmnprstvxy](
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
o Billing address form : billingaddress.xml.
To make it work for Canadian postal code you need to change regexp
attribute of “zip” formfield of billingaddress.xml form to :
(^[ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy]\d[ABCEGHJKLMNPRSTVW
XYZabceghjklmnprstvxy](
)?\d[ABCEGHJKLMNPRSTVWXYZabceghjklmnprstvxy]\d$)|(^\d{5}(-
\d{4})?$)
Pipelines
o Pipeline OnSession.xml.
Add the following (non-transactional) script node
Script File: int_canadapost:canadapost/callCPShippingServices.ds.
© 2015 OSF Global Services. All Rights Reserved. Page 396655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Pipeline Order-History in Order.xml
For registered users, include call node right before orderdetails.isml
template in History pipeline
© 2015 OSF Global Services. All Rights Reserved. Page 406655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Pipeline Order-Find in Order.xml
For non-registered users, include call node right before “ok” end node
Scripts
o Calculate Cart script: cart\CalculateCart.ds
Add following code after end of import packages from DW framework
importScript( "int_canadapost:lib/libCPUtils.ds" );
Add following code
var cpShippingSrv = new CPShippingServices();
© 2015 OSF Global Services. All Rights Reserved. Page 416655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
cpShippingSrv.SetCPShippingPrice(basket);
After CALCULATE SHIPPING COSTS code block
ShippingMgr.applyShippingCost(basket);
o Get applicable shipping methods script:
checkout\GetApplicableShippingMethods.ds
o Add following code after end of import packages from DW framework
importScript( "int_canadapost:lib/libCPUtils.ds" );
o Add following code
var cpShippingSrv = new CPShippingServices();
cpShippingSrv.CheckCPApplicable(countryCode, ret, basket);
after block code
// Retrieve the list of applicabnle shipping methods for the given
shipment and address.
var shippingModel : ShipmentShippingModel =
ShippingMgr.getShipmentShippingModel(shipment);
var ret : Collection = new ArrayList();
© 2015 OSF Global Services. All Rights Reserved. Page 426655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
ret = shippingModel.getApplicableShippingMethods(addressObj);
o For testing the Tracking Summary feature you need to change API keys.
To do that change productionEnvironment flag to false in libCPWSUtils.ds
line 13. Please ensure you change productionEnvironment flag to true,
once you are done with testing. Skip this step when first installing this
cartridge.
Templates
o Header template : components/header/htmlhead.isml
Add the following code
[DW#CanadaPostShipping#HtmlHead]
[Demo@CanadaPostDemo@HtmlHead]
after element
STYLE SHEETS ARE PLACED HERE SO THAT jQuery,
Power Review and other RichUI styles do not overwrite the
definitions below.
o Single shipping template: checkout\shipping\singleshipping.isml
Add the following code
[#CanadaPostShipping#] Add Canada Post Shipping Methods
Content
after block
© 2015 OSF Global Services. All Rights Reserved. Page 436655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
o Order details template: components\order\orderdetails.isml
Insert the following code
[DW#CanadaPostShipping#OrderDetails] Display Canada
Post shipment details
after looping through shipment.productLineItems code
o Order detail sent mail template :
components\order\orderdetailsemail.isml
© 2015 OSF Global Services. All Rights Reserved. Page 446655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
Insert following code
[DW#CanadaPostShipping#OrderDetails] Display Canada
Post shipment details
after looping through shipment.productLineItems code
o Minibillinginfo template : checkout/billing/minibillinginfo.isml
Add the following code
[DW#CanadaPostShipping#Checkout] Display Post
Office Address on right sidebar of checkout
pages
before
around line 10
3.3.2.2 Custom code added to storefront_richUI
Templates
o Footer UI template : \components\footer\footer_UI.isml
Insert at the end of file the following code:
© 2015 OSF Global Services. All Rights Reserved. Page 456655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
[DW#CanadaPostShipping#Footer] Include Canada Post
Footer
3.4 Testing
Tracking orders:
1. Go to your Demandware Storefront;
2. As a registered or guest customer click Check order;
o As a registered customer, open one of the orders and enter the Tracking
Number;
o As a guest customer enter the Order Number and Billing Zip Code and click
Check Status; Enter the Tracking Number;
3. The shipping status is displayed.
Checkout testing
1. Go to your Demandware Storefront;
2. As registered or guest customer you need to add products to your shopping cart
then proceed to checkout;
3. In the shipping section you can select an existing address from the list of saved
addresses (in case of a registered customer) or you can add a new address as
registered or guest customer;
4. From “Select Shipping Method” section select Canada Post option;
5. The available shipping services appear in a dropdown list;
6. After selecting the desired service all available options for that service will
appear. Select the desired options;
7. If the Delivery to Post Office service was selected the “Enter the Postal Code:”
field should appear already completed with the same ZIP code added in the
shipping address;
© 2015 OSF Global Services. All Rights Reserved. Page 466655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
8. Click Show the Map button and the nearest postal offices from that area will be
listed;
9. Pick one postal office for delivery - Expected delivery date and Shipping Price
should be available;
10. The Delivery Info section appears and all the shipping details are listed;
11. Continue the checkout process and submit the order.
12. Email containing order details, as well as Canada Post shipping information is
received.
Pricing rules testing
1. Go to Administrative Panel, section Pricing;
2. Add a new rule (flat rate or free shipping) and activate it;
3. Save changes in the panel;
4. Go to storefront;
5. Add products to cart;
6. Select Canada Post shipping method;
7. Check if the service to which special pricing was applied is listed in the Canada
Post services list.
4. Operations, Maintenance
4.1 Availability
If, for any reason, the service becomes inactive, an appropriate warning message will
appear informing that the service is unavailable and prompting the customer to choose a
different shipping method.
4.2 Support
1. Supporting documentation and data will be provided
Archived cartridge;
Configuration / installation files;
Integration guide
5. User guide
© 2015 OSF Global Services. All Rights Reserved. Page 476655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
5.1 Roles, Responsibilities
The merchant will have administrative role.
5.2 Business Manager
In Business Manager, the merchant can easily find all the information about the
shipping saved by customer for each order. There two places where the info is
saved:
1. In Business Manager->Ordering->Orders->Order-> Shipment->Shipping Address
"Postal Office Address" is saved next to Standard Address / Customer Address
Both Customer and Postal Office addresses will be available for the printing of the
shipping manifest / label;
2. In Business Manager -> Ordering->Orders->Shipment-> Attributes all the shipping
details are saved and displayed, including shipping method options, shipping
method, shipping price and all of the options selected by the customer.
© 2015 OSF Global Services. All Rights Reserved. Page 486655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
5.3 Storefront Functionality
1. Checkout:
1. On the Shipping page the customer selects an existing address or provides a new
address (as registered or as guest);
2. The customer selects Canada Post as the delivery option and browse within the
available shipping methods;
© 2015 OSF Global Services. All Rights Reserved. Page 496655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
3. The customer choses a shipping service and all of the available options are
displayed for the customer to choose from.
Note: the conflicting options are disabled.
© 2015 OSF Global Services. All Rights Reserved. Page 506655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
4. If a customer checks the “Deliver to Post Office” option, the “Enter the Postal
Code” field shows up; based on a provided postal code the user can view all the
available postal offices within his area;
Note: the postal code field is automatically populated based on the ZIP code
provided by customer in the Shipping Address form.
5. The customer selects the Show the Map button; the map is generated, and also
displays a list of the nearest Post Offices on the left of the map;
© 2015 OSF Global Services. All Rights Reserved. Page 516655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
6. Customer selects the desired postal office
Customer can click on a marker representing a postal office and more info will be
displayed (postal office address and working hours). Also on the left side of the map
there are details about distance to the postal office and directions to reach.
Note: Please see that if one postal office is selected to see its details that postal
office will be automatically picked and used as desired delivery point. This postal
office is also added as first item in the left additional list with postal offices.
© 2015 OSF Global Services. All Rights Reserved. Page 526655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
7. The customer clicks Calculate the Shipping Price; a list with the available
shipping information will be displayed:
© 2015 OSF Global Services. All Rights Reserved. Page 536655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
If the customer does not click on Calculate the Shipping Price button the price
will be calculated once the customer clicks Continue;
The shipping price will be visible in the “mini cart” (right) section when getting to
Billing page.
8. The customer clicks Continue button and goes to Billing page;
9. The customer follows standard checkout process required to submit the order.
2. Order Tracking:
Once a customer has completed an order he can go back on the merchant’s website
and track it.
b. Registered customer
1. The user logs in with his username and password;
2. Opens his account and then his orders;
3. Clicks Order Details on the order he wants to track;
4. Enters the “Tracking number” provided by the merchant and clicks Track;
© 2015 OSF Global Services. All Rights Reserved. Page 546655 Blvd. Pierre Bertrand, Office 240
Québec City, QC, G2K 1M1, Canada
Phone: +1-888-548-4344
www.osf-global.com
5. Details regarding the order status are displayed.
c. Guest Customer
1. User clicks Check Order , enters their order ID and Billing Zip code;
© 2015 OSF Global Services. All Rights Reserved. Page 55You can also read
