magento module documentation - dpdgroup. dpd portal.created by dpd magento module documentation 5/27...

Magento module

Documentation

Created by DPD Magento module documentation 2/27

DPD 06/08/2014

Magento module Documentation

Table of contents 1 General............................................................................................................................................ 4

1.1 Languages ................................................................................................................................ 4

2 Installation ....................................................................................................................................... 4

2.1 Search module.......................................................................................................................... 4

2.2 Installation in Magento .............................................................................................................. 6

2.3 Installation as a local package .................................................................................................. 7

2.4 Uninstalling the module ............................................................................................................. 8

2.5 Upgrading the module ............................................................................................................... 8

3 Configuration ................................................................................................................................. 10

3.1 Log level ................................................................................................................................. 10

3.2 General ................................................................................................................................... 10

3.3 Shipping methods ................................................................................................................... 11

3.3.1 DPD Home Delivery ......................................................................................................... 11

3.3.2 DPD ParcelShops ............................................................................................................ 12

4 Frontend implementation ............................................................................................................... 15

4.1 DPD Home Delivery ................................................................................................................ 15

4.2 DPD ParcelShops ................................................................................................................... 15

4.2.1 Choosing a ParcelShop ................................................................................................... 16

4.2.2 Custom ParcelShops ....................................................................................................... 17

5 Backend order processing ............................................................................................................. 20

5.1 Weight .................................................................................................................................... 20

5.2 Generating labels .................................................................................................................... 20

5.2.1 Processing order with multiple shipments ........................................................................ 21

5.3 Downloading labels ................................................................................................................. 22

5.3.1 Download a single label ................................................................................................... 22

6 Return labels ................................................................................................................................. 24

6.1 Instructions PDF ..................................................................................................................... 24

6.2 Generate return label and instruction file................................................................................. 24

6.3 Download label and instructions ............................................................................................. 25

6.4 Email label and instructions to client ....................................................................................... 25

7 Track & Trace ................................................................................................................................ 26

8 OneStepCheckout ......................................................................................................................... 26

8.1 Backend configuration ............................................................................................................ 26


DPD 06/08/2014


8.2 Frontend implementation ........................................................................................................ 27


DPD 06/08/2014


1 General

De DPD Shipping module for Magento installs as 2 shipping methods in Magento:

- DPD ParcelShops - DPD Home Delivery

As Magento administrator, you can choose to have one or both shipping methods available after installation. For more information about these DPD ParcelShops en DPD Home Delivery you can contact DPD at: [email protected].

Important: before you can use the module, you need to contact DPD to acquire the necessary test and production credentials and configuration settings. For more information, contact: [email protected].

The module impacts your Magento installation in the following areas:

- Frontend: o During checkout one or two extra shipping methods will be available.

- Backend: o Extra menu item “Sales > DPD Orders” to manage your orders and generate labels. o Extra tab in “System > Configuration > Sales > Shipping Settings”: “DPD Shipping” to

set general account configurations. o Two extra shipping methods in “System > Configuration > Sales > Shipping Methods” to

set specific configurations.

1.1 Languages

The following language packs are included in the module:

- English - Dutch - French - German

2 Installation

In most cases a new module will be installed via Magento Connect, Magento’s official module marketplace. This chapter provides a quick overview of how to install a new module in your Magento Installation.

It is important to backup your Magento online store before installing any module.

2.1 Search module

You will need to find the module to install. Open Magento Connect at http://www.magentocommerce.com/magento-connect and search for the module:

mailto:[email protected]

mailto:[email protected]

http://www.magentocommerce.com/magento-connect


DPD 06/08/2014


After clicking the search icon, you will see an overview of the search results. Select the official DPD Shipping module. This will open up the detail page.

At the detailed view of the module you can see extra info about the module such as the number of downloads (Popularity Score), the number of reviews, a description, etc.

The URL needed for installation is found by selecting your platform (your edition of Magento – Community or Enterprise) and clicking “Install Now”:

Note: You need to be logged in to be able to request the URL.

After clicking “Install Now” you will see a small form where you need to choose your version of Magento Connect. As the DPD Shipping module only support Magento versions that run on Magento Connect 2.0, you should select the same.

After selecting Magento Connect 2.0, agree to the license agreement and click “Get Extension Key”. The URL will appear:


DPD 06/08/2014


2.2 Installation in Magento

Now that you have acquired the URL, you can install the module in your Magento installation. Log in to the administration of Magento and navigate to “System > Magento Connect > Magento Connect Manager”:

You will be asked to log in once again, after which you will see the Magento Connect Manager:


DPD 06/08/2014


Paste the URL of the module in the field and click “Install”. Magento will check for dependencies and show them to you, prompting for confirmation.

Upon clicking “Proceed” you will be directed to the lower side of the page where you are able to follow the progress of the installation (output may vary according to Magento version).

After these steps the module is installed, and you may start using it.

2.3 Installation as a local package

There are cases in which you might have a package locally and want to install it into Magento directly. For this you will use the Magento Connect Manager in a similar manner. Navigate to the Magento Connect Manager like in the previous example.

You will see the Magento Connect Manager where you will choose “Direct package file upload”:

Click “Choose file”, navigate to your local package and click “Open”. Click “Upload“ and you will be directed to the lower side of the page where you are able to follow the progress of the installation (output may vary according to Magento version).

After these steps the module is installed, and you may start using it.


DPD 06/08/2014


2.4 Uninstalling the module

Whenever you wish to uninstall a plugin in Magento, go to the Magento Connect Manager by logging in to the administration and navigating to “System > Magento Connect > Magento Connect Manager”. Login once again if prompted.

Once you are at the Magento Connect Manager, scroll down the page until you see a list of installed extensions (displayed extensions varies by Magento version):

From the actions dropdown, select “Uninstall” for each plugin you wish to uninstall:

Press the “Commit changes” button. You will be directed to the bottom of the page where you are able to follow the process of the uninstallation.

2.5 Upgrading the module

In order to check for upgrades for the Magento extensions you can follow the instructions below.

Log in to the Magento administration panel and navigate to ”System > Magento Connect > Magento Connect Manager”. On the “Extensions” tab, click on “Check for Upgrades”:


DPD 06/08/2014


The Magento Connect manager will automatically connect to the Magento Connect server and check for available upgrades. If you have an extension that has a published upgrade they will be colored in yellow and you will be able to apply the upgrade to your Magento module.

Note that it is extremely important to backup your Magento online store before applying the upgrade.

From the “Actions” drop-down menu you will be able to select the desired upgrade version. Click “Commit Changes” to proceed with the upgrade.

The chosen upgrade will be automatically downloaded and applied.

Once the extension is upgraded you can refresh the page via the “Refresh” button. Then check the current status of your extension. You will find the yellow color has been removed for your “Upgraded Extension” and the “Installed” column has changed to the version number you just installed.

You can now click “Return to Admin” and check if any new “Configuration Settings” for your Extension are available. Also make sure that your online store is properly functioning and there are no errors.


DPD 06/08/2014


3 Configuration

Important: it is important you aware of the default behavior within Magento. You can find the default behavior in an online example demo store: http://demo.magentocommerce.com/.

The DPD Shipping module is configured in the default Magento system configuration.

3.1 Log level

The module comes with three log levels:

- Debug - Info - Error

The module uses the Magento log level “debug” by default. It is advised, certainly on production environment to set this level to “error”.

To change the DPD log level, change the following file: app/code/community/DPD/Shipping/etc/config.xml (tag <log_level>).

The default is 7 (debug), this is an overview of all available values:

- 3 = Error - 6 = Info - 7 = Debug - 0 = No logging

Note: if logging is disabled in Magento backend in the Log Settings, nothing will be logged.

All log entries can be found in the file dpd.log in the default Magento log folder.

3.2 General

If the module installed correctly, the general settings for your DPD Shipping module can be set in “System > Configuration > Sales > Shipping Settings” in the tab “DPD Shipping”:

The following table provides you an overview of all available options:

http://demo.magentocommerce.com/


DPD 06/08/2014


Setting Description Default

Paperformat Select in which format the labels should be generated for printing.

“A6”

Weight unit Select in which unit you are setting the weight on your products.

“kg”

User Id Mandatory, contact DPD for this information.

Password Mandatory, contact DPD for this information.

Webservice URL Do not change unless instructed by DPD! https://public-ws-stage.dpd.com/services/

Sender name, street, …

Mandatory, contact DPD for this information.

This information is used by the webservice and needs to be filled in exactly as provided by DPD or the webservice will not work!

Note: These settings are configured at the “Global” (default) Magento scope by default, but can be set on website level/scope if needed.

3.3 Shipping methods

If the module installed correctly, two new DPD Shipping methods can be found in “System > Configuration > Sales > Shipping Methods”:

Expand the tab of the shipping method you want to configure.

3.3.1 DPD Home Delivery

All settings are mandatory unless specifically mentioned otherwise.


DPD 06/08/2014




Enabled Enables or disables the shipping method. Yes

Shipping method name

The name of the shipping method during checkout. “DPD Home Delivery”

Sort order The order in the list of shipping methods during checkout. 0

Default selected Selects the shipping by default during checkout. No

Rate type Select “flat rate” if you require a fixed rate for this shipping method. Select “table rates” if you want the rates to be based on a table rates configuration.

Flat Rate

Flat rate price Only applicable if “Rate type” is set to “flat rate”.

Fixed amount as shipment cost e.g.: 4.95.

0

Table rates condition

Only applicable if “Rate type” is set to “table rates”.

The module uses table rates configuration in the same way the default Magento table rates work.

For choosing your condition and configuring the table rates CSV, please visit: http://www.magentocommerce.com/knowledge-base/entry/how-do-i-set-up-table-rate-shipping

Export table rates file


You can download the current CSV by clicking the “Export CSV” button.

Import table rates file


You can upload your CSV here.

Note: The table rates configuration file is only available in the Magento

[Website] scope; it will not be visible in another configuration scope!

Tip: you can use online tools to generate a CSV file like

this: http://elgentos.nl/tablerates/

Ship to countries Select whether you want to allow this shipping method to ship to all available countries or to specific countries.

Specific Countries

Allowed countries Specify the countries for which this shipping method should be available to ship to.

Only available if “Ship to countries” is set to “specific countries”.

BE,FR,DE,LU,NL

3.3.2 DPD ParcelShops

All settings are mandatory unless specifically mentioned otherwise.



http://www.magentocommerce.com/knowledge-base/entry/how-do-i-set-up-table-rate-shipping


http://elgentos.nl/tablerates/


DPD 06/08/2014


Enabled Enables or disables the shipping method. Yes

Shipping method name

The name of the shipping method during checkout. DPD Home Delivery

Sort order The order in the list of shipping methods during checkout. 0

Default selected Selects the shipping by default during checkout. No

Rate type Select “flat rate” if you require a fixed rate for this shipping method. Select “table rates” if you want the rates to be based on a table rates configuration.

Flat Rate

Flat rate price Only applicable if “Rate type” is set to “flat rate”.

Fixed amount as shipment cost e.g.: 4.95.

0

Table rates condition

On applicable if “Rate type” is set to “table rates”.

The module uses table rates configuration in the same way the default Magento table rates work.

For choosing your condition and configuring the table rates CSV, please visit: http://www.magentocommerce.com/knowledge-base/entry/how-do-i-set-up-table-rate-shipping

Export table rates file


You can download the current CSV by clicking the “Export CSV” button.

Import table rates file


You can upload your CSV here.

Note: The table rates configuration file is only available in the Magento

[Website] scope; it will not be visible in another configuration scope!

Tip: You can use online tools to generate a CSV file like

this: http://elgentos.nl/tablerates/

Ship to countries Select whether you want to allow this shipping method to ship to all available countries or to specific countries.

Specific Countries

Allowed countries Specify the countries for which this shipping method should be available to ship to.

Only available if “Ship to countries” is set to “specific countries”.

BE,FR,DE,LU,NL

Google Maps API The shipping method uses Google Maps to display the map in the frontend. Fill in the API key here.

Note: This is optional if you will not meet the usage limits. Visit this URL

for more information: https://developers.google.com/maps/documentation/javascript/tutorial?hl=nl#api_key

Map width The width of the map in pixels. Note that this includes the list on the right side of the map if activated.

600

Map height The height of the map in pixels. 430



http://elgentos.nl/tablerates/


DPD 06/08/2014


Map – max num of shops

The maximum number of shops to show on the map and in the list.

Note: This number doe not apply to custom ParcelShops, all custom

ParcelShops are always added to the number of regular ParcelShops. The maximum only applies the the number of regular ParcelShops.

Map presentation “Inline” will show the map within the page within the shipping method. “Overlay” will show the maps as an overlay on the checkout page.

Inline

Map list Enabling the map list will show the returned ParcelShops also as a list on the right side of the map.

Note: Custom ParcelShops are also added to this list, at the bottom.

No

Custom ParcelShops - CSV

DPD allows you to show “custom” ParcelShops on the map. These are you own pick-up points like your outlets.

The CSV needs to be provided by DPD, you cannot upload your own CSV!

Note: This setting is only available in the Magento [Website] scope; it

will not be visible in another configuration scope!

Custom ParcelShops – logo

You can use your own logo to display your custom ParcelShops, upload it here. It should be 100x100 px.

The default DPD logo

Custom ParcelShops – map logo

This is the map pointer image that is used, it is usually your logo in a text balloon-like pointer image.

It should be 57x57 px.

The default DPD logo

Custom ParcelShops - free shipping

If this option is enabled, the shipping price will be €0.00 for custom ParcelShops.

No


DPD 06/08/2014


4 Frontend implementation

This chapter describes how DPD Shipping works in the frontend of your Magento installation.

4.1 DPD Home Delivery

The DPD Home Delivery shipping method is displayed in the same way as a default shipping method like “Flat rate”.

This means no extra visual features are added. DPD Home Delivery displays in the checkout as follows:

1. This text can be configured with the option “Shipping method name” in the shipping method configuration

2. The cost is based on your configuration, be it “flat rate” or “table rates”.

4.2 DPD ParcelShops

The DPD ParcelShops shipping methods basically displays the same as other shipping method but with some extra features:


DPD 06/08/2014


1. This text can be configured with the option “Shipping method name” in the shipping method configuration

2. The cost is based on your configuration, be it “flat rate” or “table rates”. 3. This link opens the map based on the shipping address. In the map the visitor can select the

ParcelShop. The map is shown inline or as an overlay, based on the configuration setting “Map presentation” in the shipping method configuration.

4.2.1 Choosing a ParcelShop

Customers can choose a ParcelShop by clicking on the link “Click here to select your ParcelShop”:

This opens the Google Map and shows the ParcelShops that where found based on the shipping address:

The presentation of the map can be configured in the configuration of the shipping method:

- you can choose to display the map inline in stead of as an overlay - you can choose to hide the list on the right - you can choose the width and height of the map - you can choose the number of ParcelShops to find an show

The map is automatically zoomed based on the ParcelShops that need to be shown.


DPD 06/08/2014


Note: if you are using custom ParcelShops, the zoom will not take them into account, because custom ParcelShops are always shown on the map, not taking the shipping address into account.

To select a ParcelShop, the customer can select a ParcelShop on the map and click “Ship to this ParcelShop”, or use the list on the right:

After choosing the ParcelShop, the selected ParcelShop is presented on the checkout page:

By clicking the [i]-icon, details about the ParcelShop will be shown.

By clicking the link “Click here to change your ParcelShop” the map appears again and a new ParcelShop can be chosen.

4.2.2 Custom ParcelShops

DPD allows certain customers to use their outlets as ParcelShops and present them to the customer in custom way; this is called “Custom ParcelShops”.

If your contract with DPD allows you to use this feature, DPD will provide you with a CSV file to upload in the Magento backend. This CSV file contains the information about your outlets, also known as custom ParcelShops.


DPD 06/08/2014


If a custom ParcelShops CSV has been uploaded in the backend, these custom ParcelShops will be added to the list of regular ParcelShops that are retrieved from DPD based on the shipping address.

They will also be added to the list on the right of the map (if active) and use there own logo and pointer on the map (if uploaded in the backend):

User can select the customer ParcelShops as any other ParcelShop. The frontend and backend process is the same for a regular or a custom ParcelShop.


DPD 06/08/2014


If “Custom Parcelshops - free shipping” is enabled, the shipping cost will be €0.00 when selecting a custom ParcelShop.

Note for developers: When the shipping cost changes after selecting a ParcelShop, the price element in the DPD ParcelShops label will get the class “price-changes” for 2 seconds.


DPD 06/08/2014


5 Backend order processing

Orders that have been created with the DPD Home Delivery or DPD ParcelShops shipping method appear in the overview:

Orders should be processed from within this view. Processing is the same for DPD Home Delivery orders and DPD ParcelShops orders.

5.1 Weight

The module calculates the total weight of the shipment based on the weight of the products in the shipment. All items without a parent item are taken into account to counter problems with configurable and bundled products.

A label is generated for each shipment and the total weight of the shipment is sent to DPD when generating a label. Please be aware that you are expected to fill in the weight of your product and that this weight will impact you monthly invoice from DPD.

Note: The setting “Unit weight” under “Shipping Settings” is used to calculate the weight and translate it to the unit DPD is expecting, make sure it is set correctly.

5.2 Generating labels

In the “DPD Orders” overview, you can filter the orders you would like to process using the standard Magento column filters that are available in the overview:

Filter the overview and select all the orders you would like to process.

Then, perform the action “Generate Label and Complete” that is available in the “Actions” dropdown top right of the overview by selecting it and clicking the “Submit” button next to it. Generating a label can take up to 1 second per label, please be patient during this process. It can take up to maximum 2 minutes. Also, there is a maximum of 100 orders that can be processed in one action.

This action results in the following:


DPD 06/08/2014


1. Magento shipment will be created.

Performing then “Generate Label and Complete” action will contact DPD through a webservice, which will provide a tracking code and a DPD Label as PDF.

If the order does not yet have a shipment, a Magento shipment will be created and the tracking number will be added to that shipment:

You can also verify if a label is present by checking the “DPD Label” column in the overview:

If an order already has a shipment, a new shipment will not be created, a label and tracking number will be generated for each existing DPD shipment. See “Processing order with multiple shipments” for more information.

2. The status of the order changes.

If your order had the status “Processing” before performing the “Generate Label and Complete”, it will automatically be set to “Complete”.

The status of the order is changed based on the standard Magento status workflow.

As a result, if no invoice has been created before the action “Generate Label and Complete” the status would go from “Pending” to “Processing”.

3. An email will *not* be sent to the client

If you want a shipment email to be sent, you will have to go to the shipment and click the “Send Email” button.

5.2.1 Processing order with multiple shipments

When an order requires multiple shipments, you have to create as many shipment as needed manually in Magento before performing the “Generate Label and Complete” action.

You can create the shipment like any other Magento shipment, but if a DPD label needs to be generated for that shipment, you need to select DPD as carrier and fill in a dummy tracking number:


DPD 06/08/2014


Note: The dummy tracking number will be replaced with the DPD tracking number as soon as the action “Generate Label and Complete” has been performed.

When the “Generate Label and Complete” processes the order, it will generate a label and tracking number for each DPD shipment in the order. You can also add other (non-DPD) shipment in the order if needed; they will be ignored by the “Generate Label and Complete” action.

After the “Generate Label and Complete” has been performed on an order, the value in the “DPD Label” column will change to “Yes” and you will not be able to re-process the order.

5.3 Downloading labels

The module assumes you will only download the label once, and you do not want to download a label you already downloaded and therefore is flag “Label Downloaded” is set on an order when a label has been downloaded.

To download the labels that have been generated with the action “Generate Label and Complete”, select the order for which you want to download the labels and perform the “Download all undownloaded” action:

This action will process all the orders you have selected - that do not have the flag “Label Downloaded” - and generate a ZIP-file containing the labels of all the orders (that where not downloaded before) as PDF’s.

5.3.1 Download a single label

You can also download a single label without setting or reading the “downloaded” flag.

To download a single label, navigate to the shipment of an order, and click the “Download DPD Label” button:


DPD 06/08/2014


A PDF will be downloaded.

This button does not set the “downloaded” flag, and you can also always download the DPD label with this button, regardless of the fact you downloaded it before (= “DPD Downloaded” flag is set to “Yes”).


DPD 06/08/2014


6 Return labels

The module allows Magento webshop administrators to generate return labels for an order. Where regular labels are generated and maintained at a shipment level, the return labels are not linked to a certain shipment in Magento, and can be managed from with the order:

A return label also comes with an instruction file, this file can be sent to the customer and explains how to use the return label.

You can generate a DPD return on any order, it does not need to be an order with DPD as shipping method.

6.1 Instructions PDF

The instructions PDF is a fixed (hard-coded) PDF, but will include the logo of the webshop.

The logo is retrieved from the logo that is configured to be used in the Transaction Emails in Magento in “System > Configuration > General > Design > Transactional Emails”. For versions prior to Magento CE 1.7, the header logo is used, as there is no configuration option available.

Notes:

1. GIF images and interlaced PNG images are not supported. 2. The fixed base PDF is located at “magento_root_dir/media/dpd/returnlabel/” – do not remove it !

6.2 Generate return label and instruction file

To generate a return label for an order, click on the “DPD Retour Label” button top right of an order:

After clicking on this button, a DPD return label will be generated and is available in under “DPD Return Labels”:


DPD 06/08/2014


6.3 Download label and instructions

To download the return label or the instructions PDF, you can click on the links in the “Download” column:

6.4 Email label and instructions to client

You do not have to download the label and instructions to send it to the client, you can email the return label and instructions PDF with the action “Email to client” in the “Email” column:

An email will be sent to the email address of the customer that is available in the order.

A default template included (and used) in the module for this and is called “DPD Returnlabel Email”:


DPD 06/08/2014


7 Track & Trace

When a label is generated, DPD will return a tracking code for the order, and a tracking code per shipment in the order.

Both links will be added to the “Track your order” window:

8 OneStepCheckout

The DPD extension is compatible with the OneStepCheckout available at http://www.onestepcheckout.com/. Version 4.1.2 is supported, little to no problems are reported or expected on other stable versions.

8.1 Backend configuration

The DPD Shipping Method configuration “Map presentation” has to be set to “overlay” in “System > Configuration > Shipping Methods > DPD Parcelshops”

http://www.onestepcheckout.com/


DPD 06/08/2014


For DPD to be compatible a few settings are also required in the OneStepCheckout configuration:

- The “default country” has to be set under “System > Configuration > OneStepCheckout > General”.

- “Country” and “postcode” have to be enabled for AJAX update. You can find this setting in “System > Configuration > OneStepCheckout > AJAX update shipping/payment methods”.

When using OneStepCheckout, if you want to DPD shipping method selected by default, choose the “empty” option in the Default shipping method dropdown in “System > Configuration > OneStepCheckout > General”, this way you can handle default selection from the DPD shipping method configuration.

8.2 Frontend implementation

When all settings are correct your checkout will contain the DPD shipping methods:

magento module documentation - dpdgroup. dpd portal.created by dpd magento module documentation 5/27...

Documents