10.12 Shipping


10.12.4 Delivery cost Editor  <<  10.12.5  >>  10.12.5.1 Itella SmartPOST and Prinetti 

10.12.5 Pick-up point services

With pick-up point services the customer can order to any pick-up point office he likes (for example: to a specific office of Posti or Matkahuolto). When the delivery has arrived to the selected pick-up point office the office sends arrival notice to the mobile phone number which was given in the order process.

The pick-up point office will be selected from a list created after search. When the pick-up point office is selected its address will be put into the delivery address fields which have to be passed on to for example Prinetti (if Posti pick-up point service is selected).



Installation

Introduction of pick-up point services requires several actions. The instructions below are for the older Workspace visual (shop URLs contain 'PublishedService'), but the instructions that aren't about visual side apply also with the new visual (webshop). In case of Itella (Posti), information about the order must be sent to Itella in electronic form (e.g. using Prinetti), the delivery service (method) must be 'Itella Economy 16' and the additional service 'alternative pick-up point' must be selected. In addition to these, Itella requires that their routing service code, an extension added onto the pick-up point number of the chosen pick-up point, must be sent back to them in the order information. For this you must create an order question, where the shop pick-up point search javascript must save the routing service code. Itella will also automatically use additional service 'electrical notice of arrival', so that the customer will get notified about the delivery with an SMS when it has been delivered to the pick-up point.

In the case of Matkahuolto, a login number for Toimipistehaku from Matkahuolto must be requested and set in its own page. Workspace has to be version 15 or newer and Ajax interface has to be enabled (by default it is). Instructions about how to install pick-up point service(s) to Workspace are below. Some of the details concern only installation of a certain pick-up point service (for example Posti). These vendor specific details are marked separately. All the other installation details are vendor neutral.


  • Download a javascript file for customer specific modifications and settings from following URL "http://host:port/workspace.admin/sse.html/ajax/pickup_point_services_customer_specific-clean.js" (where host and port are of course the same as for the admin interface in general). The file name should be changed so that the "-clean" part in the end is removed, or alternately that part can be added to references to the file. Make sure that the file encoding will become UTF-8. (Browser may save the file in a wrong encoding, and in that case it have to be changed. See encoding help.) The file can also be copied to the file manager (of Workspace) directly and edited in-place. In the file manager the default place for this file (and other user specific Javascript files) is a sub folder called "js" (the folder may have to be created manually). If the file is put to another place, or it has a different name, the head block of the main HTML code has to be edited accordingly (see the next section below).

  • From "Visual -> Themes -> Structure -> FrameFree" edit the HTML to be similar to this:
    ...
    <head>
    	...
    	<script>
    		var WSContext = { "token":"$token$" };
    	</script>
    	<script type="text/javascript" src="/workspace.admin/sse.html/lib/jQuery/jquery-1.3.2.min.js"></script>
    	<script type="text/javascript" src="/workspace.admin/sse.html/lib/json/json2.js"></script>
    	<script type="text/javascript" src="/workspace.admin/sse.html/ajax/wsajaxlib-min.js"></script>
    	
    	<script type="text/javascript" src="js/pickup_point_services_customer_specific.js"></script>
    	<script type="text/javascript" src="/workspace.admin/sse.html/ajax/wsajaxlib_pickup_point_services-min.js"></script>
    	...
    </head>
    ...
    Note that some of the file names can differ a bit if the version of the file is different (...-min.js or ...-clean.js).

    In addition some of the files or blocks of inline scripts can already be in use if other Ajax features are in use (for example Ajax shopping carts). If a pick-up point service feature is the only Ajax feature in use then all of the Javascript above can be moved to the order page. (Not necessarily including the jQuery because it may be needed by other Javascript features as well.)

    Note that wsajaxlib is not compatible with jQuery 1.4.



  • Add a new delivery method from the Workspace Administration interface (Payment -> Shipping -> Add/Remove):


    • Posti:
      Nouto valitsemastasi postista


    • Posti SmartPOST:
      Nouto Postin pakettiautomaatista


    • Matkahuolto:
      Matkahuollon noutopiste


    Also remember to make the delivery method active and editable (both in and out).

  • If you want that the delivery method is used in the shop with a different name, change the name in both places: the Workspace Admin and the javascript. Then the editable part of the script looks like this:


    • Posti:
      ...
      var userSettingsForPostiNoutopiste = {
          // Shipping method name for this pick-up point service; choose either style,
          // depending if you need either one or multiple shipping methods to have search.
          //shippingMethodName: ['Nouto valitsemastasi postista', 'Nouto Postin pakettiautomaatista'],
          //shippingMethodName: 'Nouto valitsemastasti postista',
      
          // The subset of shipping method names that use SmartPOST
          //smartPostMethodNames: ['Nouto Postin pakettiautomaatista'],
      ...


    • Matkahuolto:
      ...
      var userSettingsForMatkahuoltoToimipistehaku = {
      	// Shipping method name for this pick-up point service
      	//shippingMethodName: 'Matkahuollon noutopiste',
      ...


    Remember to remove comments before every edited line. Note that there shouldn't be any commas after last uncommented configuration line. Notice that there are default values on the commented lines.

  • Posti: Make sure that "Phone" question is in use and mandatory (Customers -> Settings -> Questions -> Questions). It is good to tell the customer that, when using pick-up point service, SMS message is sent to given phone number. Therefore the phone number needs to be mobile phone number.

  • Edit the Id of the delivery method field: Check the "HTML id" of the delivery method question from the admin side question list page. Then edit the configuration file accordingly:
    ...
    var userSettingsForAllPickupPointServices = {
    
    	// Shipping method select field ID
    	//shippingSelectID: 'ws11',
    ...
    				


  • Select the location where the search box of the pick-up point service will appear: Choose the question below which the search box should appear (typically the same delivery method question that was chosen above) and check its "HTML id" from the admin side question list page. Edit the Id to the Javascript, on the following place:


    • Posti:
      ...
      var userSettingsForPostiNoutopiste = {
      ...
      	// ID of the previous element, after which the search form is to be
      	// placed. If empty, the form will be placed as the first element in
      	// the order form.
      	//insertAfterID: 'ws11',
      ...
      						


    • Matkahuolto:
      ...
      var userSettingsForMatkahuoltoToimipistehaku = {
      ...
      	// ID of the previous element, after which the search form is to be
      	// placed. If empty, the form will be placed as the first element in
      	// the order form.
      	//insertAfterID: 'ws11',
      ...
      						


    Remember to remove comments before every edited line. Note that there shouldn't be any commas after the last uncommented configuration line. Notice that there are default values on the commented lines.

  • Activate all the wanted pick-up point services from the configuration file:
    ...
    // Select which pick-up point services will be enabled for use
    var enabledPickUpPointsConf = {
    	itellaEnabled: false,
    	matkahuoltoEnabled: false
    };
          			
    Change the value "false" to "true" from every line matching to the pick-up service you want to activate.

  • Matkahuolto: Order a customer login number with which the service can be used from the customer service of Matkahuolto. After this the customer login number should be added in the Workspace Administration Interface (Payment -> Shipping -> Matkahuolto).

  • Add the following questions for delivery address information from the Workspace Administration interface (Customers -> Settings -> Questions -> Questions). The type of the questions has to be "Custom question (text)" type, labels can be anything. Most of the customers want the question fields to be visible on the order form. In that case make the questions "modifiable". "Hidden" questions are also allowed but "visible" questions are not. Make sure they are enabled for orders. Example with data:
    Name of the questionExample value
    Pick-up point office namec/o Posti/R-kioski
    Delivery addressNP 1075, Soukantie 16
    Delivery postal code02360
    Delivery cityEspoo
    Itella: Routing service code3200
    Table 10.1 :



  • Check the "HTML ids" of the added questions.

  • Change (if default values doesn't match) the Id constants in the user specific configuration file to match those Ids on the admin page, at the following location:
    ...
    var userSettingsForAllPickupPointServices = {
    ...
    	// IDs of the customer question fields for the delivery address
    	// to be filled when search and select is performed.
    	//fieldIDPickUpPointName: 'ws14',
    	//fieldIDAddress: 'ws15',
    	//fieldIDPostalCode: 'ws16',
    	//fieldIDCity: 'ws17',
    	//fieldIdServiceCode: 'ws18'
    ...
    Remember to remove comments before every edited line. Note that there shouldn't be any commas after the last uncommented configuration line. Notice that there are default values on the commented lines.

  • If pickup_point_services_customer_specific.js file is not loaded to the filemanager yet, do it now.

  • Test pick-up point services: In the shop, add some product to shopping cart, move to order page and choose one of the activated new pickup point service from the delivery method drop down menu, search for pick-up point offices (for example, search with a city "Espoo"), select one pick-up point office from the search results. Finalize and make the order. After that check from order management that all of the delivery address field values came through correctly. Finishing the order is not utterly necessary because the delivery address values shown (unless those fields are set hidden) on the order confirmation page are the same as those in the finalized order. If there is an error somewhere it can be seen already on the order confirmation page.

  • Posti: Delivery address has to be passed on so that Posti gets an EDI message of the transaction (this can be achieved with using for example Posti's Prinetti service, which is supported by the Workspace). The message must contain a mobile phone number of the receiver. Using of additional services 'alternative pick-up point' and 'electrical notice of arrival' is also required, but the latter is used automatically if other settings are correct. There will be four fields in the receivers address; those four Custom Questions you added earlier. Example of the address data:

    c/o Posti/Tarmo Lähikauppias
    NP 1092, Rinnekodintie 9
    02980
    ESPOO
    Do note that if the customer chose "SmartPOST" delivery and Prinetti is to be used, the selected Prinetti template must also have SmartPOST delivery method selected or the method must be modified to be SmartPOST before requesting printing of the Prinetti form.



Making customer specific changes/customizations

Making customer specific changes or customizations can be done by editing configurations from the configuration file pickup_point_services_customer_specific.js. By editing the configurations in the file you can modify the messages shown to the customer and change the HTML code of the search form. Note that configurations of all of the pick-up point services are in the same file. Posti's customizations should be done after the line
var userSettingsForPostiNoutopiste = {
and Matkahuolto's customizations after the line
var userSettingsForMatkahuoltoToimipistehaku = {
After the line
var userSettingsForAllPickupPointServices = {
shared configurations for all of the pick-up point services are found. With those you can change the Id's of the delivery address fields (described some above) or set (all or some of the) delivery address fields to hide when there is no pick-up point services selected from the delivery method drop down menu. Remember to remove comments before every edited line. Note that there shouldn't be any commas after the last uncommented configuration line. Notice that there are default values on the commented lines.



Temporarily disable pick-up point services

This can be done in two ways, by editing the configuration file (pickup_point_services_customer_specific.js), or by commenting off all the lines affecting pick-up point services from the following place: Visual -> Themes -> Structure -> FrameFree (This method works only in the situation when all pick-up point services are removed from use, see the top part of the page). In both situations it is also necessary to remove deprecated pick-up point service(s) from use; script will not have any effect on the order page and the customer cannot use the service or select a pick-up point service as a delivery method. There will not be any error messages because of this, even if the Custom Questions are left working on the background. If you decided to edit the configuration file it should be done in the following section:
...
// Select which pick-up point services will be enabled for use
var enabledPickUpPointsConf = {
	itellaEnabled: true,
	matkahuoltoEnabled: true
};
      	
Change the value "true" to "false" from every line matching to the pick-up service you want to inactivate.

10.12.5.1 Itella SmartPOST and Prinetti