Custom/Bespoke Courier Integration

The Custom/Bespoke Courier Configuration can be found by navigating to:‘Settings’ > ‘Shipping Management’, find the row for ‘Custom/Bespoke Courier’, and select the ‘Configure’ option. 

This integration method allows you to connect to a courier’s desktop software where Linnworks does not have a direct integration method available. It allows you to configure multiple import/export routine configurations to produce export files for the software to import, or to be sent to the courier’s website. The resulting files from the courier can then be imported back into Linnworks with the shipping details for the orders that can be passed onto the channel.

 

 

Click on ‘Configure’ to display the configuration screen.

 

 

At the top right are the ‘Save’ and ‘Exit’ buttons, and below that are 3 buttons. ‘Switch to v3’, ‘Add New’ and ‘Delete’.

 

Add New

 

Click ‘Add New’

Specify a name for the set of services you will be setting a configuration for.

Click OK

 

 

This produces a new entry on the list.

Select ‘Edit’ to make changes to this.

 

Flat file

 

 

Add

Allows you to select the postal services affected by this configuration

 

Batch size

Batch size denotes the number of orders you want output to each file.

eg.

Batch Size 1, with 3 orders exported, produces 3 files

.Batch Size 10, with 3 orders exported, produces 1 file.

Tick the entries to include, then use the ‘Select’ button to add them.

Once you have selected services for one configuration, they will no longer be shown in as options for other configurations.

 

Delete

Allows you to adjust the list of services included.

The ‘X’ next to a Postal Service allows you to remove it from the list.

Save the selection to make sure it is retained.

You can reopen it if you need to make any adjustments.

 

Options

 

This section allows you to specify fields and values for inclusion in the export file in addition to the values supplied by Linnworks. For example, you may create a field named ‘Insurance Code’, and give it a value of ‘3’.

Save ensures the changes are retained by LinnWorks.

 

 

Export File

The Export file section has 3 buttons, and 3 columns:

Options

 

File Path

The path and file name for the export file. See Tags

 

 

Delimeter

The character used to separate fields in each row of the file. Can be comma(,), tab, pipe (|), semicolon(;) or colon (:)

Column Headers

If Active, the column titles you have specified for the file will be shown in the first row.

UTF8

Produce the text using this character set instead of standard ASCII.

Text Separator”

Use “ as a separator around character string fields in case of spaces.

Backup Exported File

Make a backup copy within the folder (“Copy of”) of the old export file, before overwriting it with the most recent file.

Add Column

 

Add new column in the list, see below for the headings.

Remove

Remove the highlighted entry from the list of export file columns.

Index

Index value for the column, affects where the field is within the file.

eg:

Index	Column Name
1	Test
3	Possible
2	Impossible

 

Would be in the file as:

Test,Impossible,Possible

Column Name

A descriptive name for the value to be entered in that column by the export. Will be shown in the file if ‘Column Headers’ has been enabled for export.

Output Column

Specify which value will be output in this column from the database record for that order. Produces a dropdown list, including all the fields available from the order. Will also include any fields specified in ‘Service Name’, ‘Options’ for selection.

Also includes special fields:

{Nothing} – An Empty Field

{Default} – Instead of drawing a value from a record, you can specify a default value that will be written in this column for every record. To edit after creation, click on the button containing the three full stops (…)

 

Delivery Instructions

There is no specific field in Linnworks to hold delivery instructions. Generally the channels will provide this information in the form of Order Notes. The delivery instruction column looks at the order notes that begin with the word “Delivery”.  If this format is not provided by the channel the order note can be altered by right clicking on the Order in Open Orders and selecting Actions > Edit Order Notes.

 

{Expression} Allows you to allocate the result of a formula manipulating other field values to this field.

Expressions

Import/Export Evaluation Expressions

 

Predefined Column Names

OutputColumn	Description
{Nothing}	Field will be left blank
{Default}	The defined value will always be output
{Expression}	The result of the evaluated expression will output
OrderID	The Linnworks Order Number
Source	The Channel as defined in the Linnworks Order, eg EBAY
SubSource	The Sub Channel as in the Linnworks Order, eg EBAY1
ReferenceNumber	The order number as defined by the sales channel
FullName	The contents of the Name field as defined in the Linnworks Order
ChannelBuyerName	Typically only avaialble with orders from Ebay
CompanyName	The contents of the Company field as defined in the Linnworks Order
Address1	The contents of the Address 1 field as defined in the Linnworks Order
Address2	The contents of the Address 2 field as defined in the Linnworks Order
Address3	The contents of the Address 3 field as defined in the Linnworks Order
Town	The contents of the Town field as defined in the Linnworks Order
Region	The contents of the Region/State field as defined in the Linnworks Order
Postalcode	The contents of the Postal Code field as defined in the Linnworks Order
Country	The contents of the Country field as defined in the Linnworks Order
CountryCode	As defined in Application Settings > Managae Countries from the contents of the Country field as defined in the Linnworks Order
EmailAdress	The contents of the E-mail field as defined in the Linnworks Order
PhoneNumber	The contents of the Telephone field as defined in the Linnworks Order
OrderNotes	The contents of the all Order Notes as defined in the Linnworks Order seperated by commas
TotalWeight	The calculated overall weight of the order items and packaging as defined in My Inventory and mapped to the Linnworks Order Items
PostalServiceCode	The contents of the Code field from Settings > PostalServiceMethods from the mapped Shipping service as defined in the Linnworks Order
PostalServiceName	The contents of the Shipping service field as defined in the Linnworks Order
DeliveryInstructions	The contents of all Order Notes that begin with the word Delivery as defined in the Linnworks Order
SKUList	The Linnworks SKU and ordered quantity from the mapped Order Item, if not mapped the Channel SKU will be used
ItemList	The Linnworks Item Title from the mapped Order Item, if not mapped the Channel SKU will be used
SKUListExcChildSKU	The same output as SKUList, but with composite child items excluded
ItemListExcChildItems/td>	The same output as ItemList, but with composite child items excluded
SKUListExcCompSKU	The same output as SKUList, but with composite parent items excluded
ItemListExcCompItems	The same output as ItemList, but with composite parent items excluded
NumberOdItems	Number of order items including both parent and child composite items
NumberofItemsExcChildSku	Number of order items excluding child composite items
PackagingGroup	The packaging group as defined in the Linnworks Order
TotalCharge	The total charged for the order including shipping and tax
PaymentMethod	The Linnworks payment method as defined in the Linnworks Order
PackageWidth	Overall Package Width from the automatically assigned Packaging Type
PackageHeight	Overall Package Height from the automatically assigned Packaging Type
PackageDepth	Overall Package Depth from the automatically assigned Packaging Type
NumberOfItemsNocompParent	Number of order items excluding the composite parent items

 

Import File

The Import File section allows you to map the columns in the file exported by your courier software to the required import fields for LinnWorks. You MUST have the Order ID in the Import file. The Import File section contains 2 buttons:

Load Sample

The recommended method of setting up the mappings is to have a sample file which you can load using this button. LinnWorks will then load the Column Name headers from the file into the drop downs against the Column Names. This way you ensure the column names are accurate, including any misspellings.

 

Options

 

File Path

The path and file name for the import file. See Tags

Delimeter

The character used to separate fields in each row of the file. Can be comma(,), tab, pipe (|), semicolon(;) or colon (:)

Column Headers

If Active, the system will expect the column titles will be present in the first row.

UTF8

The text uses this character set instead of standard ASCII.

Text Separator”

Uses “ as a separator around character string fields in case of spaces.

Wait for Export file to be deleted

System will monitor the export file location, and attempt import once the export file has been deleted or renamed by the Courier program.

Delete after import

Delete Import file when processing completed.

Backup before delete

Make a backup copy of the Import file before deleting it.

Timeout

Time to wait for Import file to be created by Courier program.

 

Tags

Tags can be used in file names. Different tags are useable for Import and Export, and are enclosed in square brackets []

 

Import

DATE

Will be substituted by LinnWorks for the current Date at time of file creation

DATETIME

Will be substituted by LinnWorks for the current Date and Time at time of file creation

TIME

Will be substituted by LinnWorks for the current Time at time of file creation

RAND

Will be substituted by LinnWorks for a Random Number

COUNT

Will be substituted by LinnWorks for a number, incremented each time you generate another file

Any Column Name

Will be substituted by LinnWorks for the contents of the first row in that Column.

 

Export

EXPORTNAME

Will be substituted by LinnWorks for the name of the Export File previously created.
eg.

Export:

C:\Import\Velocity\CourierProgram\output_[RAND]_[DATETIME].csv

Would be created as:C:\Import\Velocity\CourierProgram\output_300125_2012-07-13_12_35_54.csv

eg.

Import:

C:\Export\Velocity\CourierProgram\[EXPORTNAME].out

Would look for:C:\Export\Velocity\CourierProgram\output_300125_2012-07-13_12_35_54.out

You can also use the wildcard (*) symbol:C:\Export\Velocity\CourierProgram\*.out

Macro scripting

This option allows you to inject your own automation behaviour in Linnworks by creating a macro that runs every time you print a label.

Add Postal Service

As in the Flat File option you can select the postal service affected by this configuration. 

Sample code

In this script we check if a Postal Tracking number exists, if not create a random one. Then print a label with the Ship From, Ship To, Order Value, Order Weight and Tracking Number. 

namespace linnworks.finaware.CommonData.Objects                // leave untouched                            
{                                                                                               // leave untouched                            
    public class ShippingLabelMacro : linnworks.scripting.core.IShippingMacro                       // leave untouched                            
        {                                                                                       // leave untouched                            
            public List<linnworks.scripting.core.ReturnClass.ShippingLabel> Initialize(linnworks.scripting.core.Debugger debug, SqlConnection ActiveConnection, linnworks.finaware.CommonData.Objects.Order order,linnworks.scripting.core.Classes.OptionCollection ServiceOptions)           // leave untouched                            
            {                                                                                   // leave untouched                            
                        
               // **** DO NOT COPY OR EDIT CODE ABOVE THIS LINE **** 
                
                List<linnworks.scripting.core.ReturnClass.ShippingLabel> labels = new List<linnworks.scripting.core.ReturnClass.ShippingLabel>();
                
                // *********************** 
                // Initialise label content
                
                // From Address
                String shipFrom = "Linn Systems Ltd" + Environment.NewLine + "City Gates House" + Environment.NewLine + "2-4 Southgate" + Environment.NewLine + "Chichester" + Environment.NewLine + "PO19 8DJ";
                
                // Deliver to address
                String label = order.ShippingAddress;
                
                // tracking number must not exceed 64 chars. If it is it will only use first 64 chars.
                String tracking = order.PostalTrackingNumber.Length>64 ? order.PostalTrackingNumber.Substring(0,64) : order.PostalTrackingNumber;
                if (String.IsNullOrEmpty(tracking))
                {
                    //if a Postal Tracking number does not exist create one
                    tracking = GenerateTrackingNumber("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ");
                }
                    
                // *********************** 
                // create label
                System.Drawing.Image bmp = GenerateGraphics(label, shipFrom, tracking, order);
                linnworks.scripting.core.ReturnClass.ShippingLabel lbl = new linnworks.scripting.core.ReturnClass.ShippingLabel(tracking, "", bmp);
                labels.Add(lbl);
                
                return labels;
            }
            
            // ============================= 
            // dummy routine for creating a Tracking Number
            string GenerateTrackingNumber(string CharList)
            {
                DateTime t = DateTime.UtcNow;
                char[] charArray = CharList.ToCharArray();
                Stack<char> result = new Stack<char>();
                int length = charArray.Length;
                long dgit = 1000000000000L +
                            t.Millisecond * 1000000000L +
                            t.DayOfYear * 1000000L +
                            t.Hour * 10000L +
                            t.Minute * 100L +
                            t.Second;
                while (dgit != 0)
                {
                    result.Push(charArray[dgit % length]);
                    dgit /= length;
                }
                return new string(result.ToArray());
            }

            // =============================
            // The following method will generate label graphics
            public static System.Drawing.Bitmap GenerateGraphics(string shipTo,string shipFrom,string tracking, linnworks.finaware.CommonData.Objects.Order order)
            {
                // set up environment
                System.Drawing.Bitmap b = new System.Drawing.Bitmap(1000, 1000);
                b.SetResolution(1000, 1000); 
                System.Drawing.Graphics g = System.Drawing.Graphics.FromImage(b);
                g.CompositingQuality = System.Drawing.Drawing2D.CompositingQuality.HighQuality;
                g.CompositingMode = System.Drawing.Drawing2D.CompositingMode.SourceOver;
                g.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.NearestNeighbor;
                g.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAliasGridFit;
                g.SmoothingMode = System.Drawing.Drawing2D.SmoothingMode.None;
                g.PageUnit = GraphicsUnit.Millimeter;
                System.Drawing.Pen blackPen = new System.Drawing.Pen(System.Drawing.Brushes.Black);
                blackPen.Width = 0.1f;
                
                // set up fonts
                System.Drawing.Font fontHeading = new System.Drawing.Font("Microsoft Sans Serif", 1.2f, System.Drawing.FontStyle.Bold, System.Drawing.GraphicsUnit.Millimeter);
                System.Drawing.Font fontAddress = new System.Drawing.Font("Microsoft Sans Serif", 1.0f, System.Drawing.FontStyle.Regular, System.Drawing.GraphicsUnit.Millimeter);
                System.Drawing.Font fontBarcode = new System.Drawing.Font("3 of 9 Barcode", 2.0f, System.Drawing.FontStyle.Regular, System.Drawing.GraphicsUnit.Millimeter);
                System.Drawing.StringFormat centreAlign = new System.Drawing.StringFormat();
                centreAlign.Alignment = System.Drawing.StringAlignment.Center;  
                System.Drawing.StringFormat leftAlign = new System.Drawing.StringFormat();
                leftAlign.Alignment = System.Drawing.StringAlignment.Near;  

                // Ship From
                System.Drawing.RectangleF rect1 = new System.Drawing.RectangleF(0.0f, 0.0f, 20.0f, 10.0f);
                g.DrawRectangle(blackPen, rect1.X, rect1.Y, rect1.Width, rect1.Height);
                g.DrawString("SHIP FROM:" , fontHeading, System.Drawing.Brushes.Blue, 0.5f, 0.5f);
                g.DrawString(shipFrom, fontAddress, System.Drawing.Brushes.Black, 1.0f, 1.8f);
                // Ship to
                System.Drawing.RectangleF rect2 = new System.Drawing.RectangleF(0.0f, 10.0f, 20.0f, 10.0f);
                g.DrawRectangle(blackPen, rect2.X, rect2.Y, rect2.Width, rect2.Height);
                g.DrawString("SHIP TO:" , fontHeading, System.Drawing.Brushes.Blue, 0.5f, 10.5f);
                g.DrawString(shipTo, fontAddress, System.Drawing.Brushes.Black, 1.0f, 11.8f);
                // Customs
                System.Drawing.RectangleF rect3 = new System.Drawing.RectangleF(0.0f, 20.0f, 10.0f, 5.0f);
                g.DrawRectangle(blackPen, rect3.X, rect3.Y, rect3.Width, rect3.Height);
                g.DrawString("CUSTOMS" , fontHeading, System.Drawing.Brushes.Blue, 0.5f, 20.5f, leftAlign);
                g.DrawString("Value : " + order.Currency + order.TotalCharge + System.Environment.NewLine + "Weight : " + order.Pack_TotalWeight + "g",fontAddress, System.Drawing.Brushes.Black, 1.0f, 21.8f, leftAlign);
                // Tracking
                System.Drawing.RectangleF rect4 = new System.Drawing.RectangleF(10.0f, 20.0f, 10.0f, 5.0f);
                g.DrawRectangle(blackPen, rect4.X, rect4.Y, rect4.Width, rect4.Height);
                g.DrawString("TRACKING" , fontHeading, System.Drawing.Brushes.Blue, 15.0f, 20.5f, centreAlign);
                g.DrawString(tracking, fontBarcode, System.Drawing.Brushes.Black, 15.0f, 21.8f, centreAlign);
                g.DrawString(tracking, fontAddress, System.Drawing.Brushes.Black, 15.0f, 23.5f, centreAlign);
                
                return b;
                
                // **** DO NOT COPY OR EDIT CODE BELOW THIS LINE ****

            }                                                                                   // leave untouched                            
    }                                                                                           // leave untouched                            
}                                                                                               // leave untouched