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

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.

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.

1. Body: Take the information from within the file contents. It is the most common location.
   
   
2. File Name: Take the information from the file name.
   
   
3. Extension: Take the information from the file extension.
   
   
4. File Name and Extension: Take the information from the combination of the file name and the file extension.
   
   
5. Constant Value: Specify that the information is a constant value, the value is defined in the Map From column.
   
   
6. Company: Take the company from the name of your current company.
   
   
7. Base Company: Take the information from the name of your base company.
   
   
8. User: Take the information from your user display name.
   
   
9. 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
• Item content reference one
• Item content reference two
• Item content reference three
• Item content quantity (Required if you are mapping an Item Content)
• Item SKU
• Item content description
• Item content dollar value
• 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.