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:
- 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.
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.
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.
- 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.
- 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.
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 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 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)
- From location abbreviation
- To location abbreviation
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"?>
<AddresLine>123 Happy Lane</AddresLine>
<Phone>04 1234 5678</Phone>
<AddresLine>345 Wonder Way</AddresLine>
<Phone>04 8765 4321</Phone>
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
- 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 and Consignment.Sender.AddressLine.
- 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.