Import - User Guide v0.

Introduction

The import is a feature that allows users to upload packages into the system by using a .csv file. This is
especially useful for ventures that want to deliver packages either:

1. From different ventures (e.g. Zalora delivers packages for Lazada);

2. From different companies (e.g. Zalora delivers packages for TennisShoesIndonesia);
3. To accommodate replacements and other parcels delivered outside the normal flow (e.g. replacement,
marketing campaigns).

Packages imported this way have their status set to “On the way to Hub” which is the entry point status
for all packages. Although not all features are available for packages imported by csv, these can be processed as
any other packages imported automatically by the Pull. The following figure shows the import feature screen
which can be accessed by using the application main navigation: Administration -> Import.

Import Fields

The following table lists the fields supported by the import feature. Note that there are fields, not
available for importing, that are automatically generated when the import is completed, namely:
1. Order Number
a. Client + Tracking Number. This order is also marked as a dummy order.
 2. Order Date
a. Current Datetime.
3. Package Status
a. Always On the way to hub.

Header field validations description

Tracking Number* tracking_number Not Empty Package tracking number.
Unique

Shipment Provider fk_shipment_provider Not Empty Package shipment provider. Shipment

Must exist providers must exist in the system before
being imported. A shipment provider
cannot be created; it is pulled along with
the package information from the respective
order management system, e.g., OMS..

Customer Name name Not Empty Customer full name. If the customer does not
exist in the system, one will be created.

Email email Not Empty Customer email.

Phone Number phone_number Not Empty Customer phone number.

Address address Not Empty Full address where the package should be
delivered / picked. If the address does not
exist in the system, one will be created.

Region region Not Empty Address region.

City city Not Empty Customer city.

Amount To Collect amount Not Empty Package amount that should be collected
from the customer.

Payment Method fk_payment_method Not Empty The sales order payment method. The
Must exist payment method must exist in the system
before being imported. A payment method
can be created in Administration ->
Management -> Payment Methods

Package Type* fk_package_type Not Empty The package type. Delivery or Pickup.
Must exist

Client* fk_client Not Empty The package client. Different from customer.
Must exist E.g., Zalora, Lazada,
TennisShoesIndonesia. The client must
exist in the system before being imported. A
client can be created in Administration ->
Management -> Clients

* These 3 fields unambiguously identify a package.

Importing Packages

To import packages into the delivery application, one can firstly download the import .csv template by
clicking “Download” in the File Sample label. The template includes all mandatory headers; one can fill it with
values, and import it. After the template is filled it can be uploaded by clicking “Choose file”. A navigator screen
will pop up and the user can select the .csv file and click “Upload”. The file is, from here on, ready to be imported
and should become visible in the Datatable as shown by the following figure.

Each row from the table represents an Import. An Import has an id, a total number of rows, a start end
generation and a status. It also has an “Open” action which allows the user to see the import details, e.g.,
number of imported rows, number of failed import rows and import errors.
The execution of each import is controlled by a background service that runs each five minutes. Thus,
the import is not executed immediately after the user clicks the “Upload” button. This mechanism (Mass Import)
scales well with large amounts of data and doesn’t block the user actions. The import will remain “In Progress”
until the service kicks off it’s execution.
When an Import is completed it’s status changes to “Done” and the start and end generation times are
filled accordingly. The user can then see the import details by clicking “Open” (See the following figure).
In this case, both import rows (2) failed. To see the failure reason per row, the user can click in “View Errors”
and a pop up as shown in the following figure should appear. This pop up shows data for each row that wasn’t
imported. By hovering the “view reason” link the user can see the concrete error for each row. In this case, the
client “Open Box” does not exist in the system, and thus, it cannot be imported.

A successful version of the previous import (after the client creation) is shown in the following figure. If
an Import is successful, the imported packages will appear on the “In transit to Hub” screen which can be
accessed in Inbound -> In transit to hub.
Features not available
As stated before, packages imported by csv do not take advantage of all available features in the
application. Most notably, since these packages are “isolated” in the system, that is, they are not directly tied to
any external software, their data cannot be pulled / synced back to the latter. Basically, they do not support
external events, only internal. For example, a package can change it’s status internally, but it cannot warn an
outer system that it’s status as changed. The following table lists all external events available in the application.

Event Description

pullPackages Pulls all packages and related data from an external software into the delivery
application.

pullShipmentProviders Pulls all shipment providers from an external software into the delivery
application. A package belongs to a shipment provider (hub).

pullFailureReasons Pulls all failure reasons from an external software into the delivery application.
A package can have one or more failure reason according with the failed
delivery attempts.

pullPickups Pulls all pickups and related data from an external software into the delivery
application.

deliverPackage Syncback event. Attempts to mark the packages as delivered in the

corresponding external software.

getOrderLink Event that transforms all Datatable order number fields into links that redirect
the user to the order detail page in the external software.

updateDeliveryInfo Syncback event. Syncs the delivery info field with the external software.

changeShipmentProvider Syncback event. Changes the package shipment provider internally and syncs
back to the external software.