How to create a Workflow Task to map and import an XML file – Machship

The workflow task in MachShip allows you to define field mappings between MachShip fields and data fields from a selected file type such as CSV or XML.

How to navigate to create a Workflow Task

To navigate to Workflow Results select Admin and Other Options.

Then select Workflow Task.

From this page, you can create a new workflow task by clicking on the Create Workflow Task button at the top of the screen.

Create a Workflow Task - XML file

In order to generate a workflow task, you will need to enter the following fields:

Name
Abbreviation
Company
Workflow Task Type

The workflow task type can be Consignment Importer or Invoice Importer.

Mapping Type

Since you are going to import an XML file, please select XML File Mapper.

Note: Once you choose a Task Type and a Mapping Type, you will not be able to change them. If the selected type is incorrect, the only way to change it is to start the process over.

Once you have chosen the Delimited File Mapper as the Mapping Type, you will see a new section called Workflow Task Options as shown below.

For XML file type, you only need to define property mappings.

Define Mapping:

Please click on Add Property Map Options button to add a new property/field mapping.

For each property mapping, you will need to fill in the following info.

Location

Specify which part of the file to take the information from.

Body: Take the information from within the file contents. It is the most common location.
File Name: Take the information from the file name.
Extension: Take the information from the file extension.
File Name and Extension: Take the information from the combination of the file name and the file extension.
Constant Value: Specify that the information is a constant value, the value is defined in the Map From column.
Company: Take the company from the name of your current company.
Base Company: Take the information from the name of your base company.
User: Take the information from your user display name.
Constant Location: If the data is to come from the file from a location that does not change.

Mapping Target

Depending on your import type, there will be a list of properties in MachShip that you can map a location property to.

Mapping From

You need to define how to read the value and map into the target. Typically for the delimited file import, it will be the header name when the file contains headers. When there are no headers, the best input is the index position of the property.

Ignore Row if Empty

If you file will likely contain some lines or tag collection which do not relate to data you wish to import set this flag as being "Yes". MachShip will then ignore all the data related to this collection of tags or row in the file, allowing you to import the other data.

Pattern and Replacement

Only use this option when you want to use Regular Expression to determine whether to replace the original field value with a different value. The regular expression functionality will also allow you to undertake direct replacement. For example - set the field you wish to replace in the box on the left and what you wish to replace it with, in the box on the right.

For example - the input below will replace every term of Startrack with the expected abbreviation in MachShip of STRACK for the carrier Startrack.

Mapping Targets

To successfully set up and import an XML file as a consignment, you need to make sure the file has all the required fields. To create a consignment, we will need the following info:

Despatch date
Despatch time
Carrier: It needs to be the carrier abbreviation
Account: It needs to be the account abbreviation
Service: It needs to be the service abbreviation
From location name
From Abbreviation
From contact
From phone
From address line one (Required if you are not mapping a company location name)
From address line two
From suburb (Required if you are not mapping a company location name)
From postcode (Required if you are not mapping a company location name)
To location name
To Abbreviation
To contact
To phone
To address line one (Required if you are not mapping a company location name)
To address line two
To suburb (Required if you are not mapping a company location name)
To postcode (Required if you are not mapping a company location name)
Special instructions
Reference one
Reference two
Item quantity (Required if you are not mapping a company Item)
Item SKU
Item description
Item type (Required if you are not mapping a company Item)
Item length (Required if you are not mapping a company Item)
Item width (Required if you are not mapping a company Item)
Item height (Required if you are not mapping a company Item)
Item Reference - This will be the item Identifier / Barcode on the label
Carrier Consignment Id - Set this if you are telling MachShip the Consignment Number.
Company - If you need to set the company for the consignment that is imported
Questions - If you wish to set a Routing Question through import
Printer Token
Staff Member Name
Is Receiver Account - If the consignment is receiver pays - will need to work in conjunction with the Receiver Account Code
Receiver Account Code
Is Existing Consignment - If the consignment being created is a benign or existing consignment
Serialised Settings - Allows the setting of consignment specific options

The fields in bold are all required if you are importing as a consignment. Note the fields in italics are only required if MachShip cannot obtain this data from the saved company locations or items.

If you are intending to import to a pending consignment there are no required fields but the more information provided the easier it will be to finalise the consignment.

An example of how to import an XML file as Consignments

See an example XML file below.

<?xml version="1.0" encoding="utf-8"?>
<Consignment>
 <Sender>
   <Company>MACBRO</Company>
   <AddresLine>Main office</AddresLine>
   <AddresLine>123 Happy Lane</AddresLine>
   <Suburb>Cremone</Suburb>
   <Postcode>3121</Postcode>
   <Contact>Scott Tiger</Contact>
   <Phone>04 1234 5678</Phone>
   <Email>scott@tiger.com</Email>
 </Sender>
 <DespatchDate>30/12/2018</DespatchDate>
 <Reference>123456789</Reference>
 <Receiver>
   <AddresLine>Despatch Center</AddresLine>
   <AddresLine>345 Wonder Way</AddresLine>
   <Suburb>Adelaide</Suburb>
   <Postcode>5000</Postcode>
   <Contact>John Doe</Contact>
   <Phone>04 8765 4321</Phone>
   <Email>john@doe.com</Email>
 </Receiver>
 <Package>
   <Reference>SKU 1234</Reference>
   <Length>100</Length>
   <Width>60</Width>
   <Height>10</Height>
   <Weight>10</Weight>
   <Quantity>1</Quantity>
 </Package>
 <Package>
   <Reference>SKU 45678</Reference>
   <Length>200</Length>
   <Width>30</Width>
   <Height>20</Height>
   <Weight>8.5</Weight>
   <Quantity>2</Quantity>
 </Package>
</Consignment>

The XML file contains the following fields:

Consignment tag, it means an XML file can have more than one consignment
Sender info
Receiver info
Despatch Date
Reference
Package/Item data: each consignment can have more than one package nodes, each node represent one item

A valid setup would look like this:

There are a few notes with this mapping option:

XML node referencing

When referring to a field from the XML, you need to make sure to follow the node trace, for example, in order to get the value of the Company, the correct reference is Consignment.Sender.Company.

When there is more than one node with the same name, you need to provide the index of the file. For instance, in this example, we have address line one and address line two both come from AddressLine node. Since we know there will be 2 AddressLine node, the best way to reference it is set it as Consignment.Sender.AddressLine[0] and Consignment.Sender.AddressLine[1].
Date Format

When mapping a date field, you need to let MachShip know the date format. In this example, since the date is in Australian format, the correct value is dd/MM/yyyy, if it is an American date, then the value would be MM/dd/yyyy.

Note that this field can be left blank if the date format will vary.
Using constant value

My XML file doesn't have any value that specifies the carrier account and the carrier service that will be used, but since I already know they come from StarTrack and the service will always be Express, I can set up 2 Constant mappings as below:
Item dimension

For some properties, you will need to instruct MachShip on how to get the value correctly.

Once all of the options have been populated, please click on the Create Workflow Task button and the workflow task will be created.

Related articles