About

The Machship plugin provides an interface between Jiwa and the Machship freight platform via the Machship API.

Consignments in Machship can be created from a sales order in Jiwa, and the consignment information and freight items on a Jiwa sales order updated from Machship.

Machship will select a carrier and service, based on the pickup and delivery addresses, item dimensions and weight and if the user selects “Least Cost” or “fastest”. The freight charges, consignment note number and freight items within the consignment are updated on the Jiwa sales order.

Deployment

Import plugin

Open the Plugin Maintenance form in Jiwa and locate any other freight integration plugins (such as IFS) and disable and save those.

Import the Machship plugin and ensure it is enabled and save.

SQL Script

A SQL Script attached to the documents tab of the Machship plugin, Machship.sql, should be run against your database. This script will create the required Machship freight descriptions against each carrier.

Configuration

Exit Jiwa and log back in after the deployment steps before proceeding to the following configuration steps.

System Configuration

Open the System Configuration Form, and on the Machship tab, enter the Machship API Token provided to you by Machship.

Open

Also on the same tab of the System Configuration Form, you can also optionally set a Placeholder Freight Item. Machship requires at least one freight item when creating a consignment, and setting this value allows a sales order to have a consignment created in Jiwa with no freight items.

Warehouse Maintenance

Open the Warehouse Maintenance form in Jiwa, and for each Physical Warehouse which will be creating consignments in Machship, enter the Machship Company Id.

Open

The Machship Company Id is obtained from the companies view of the Admin sections of the Machship portal. Whilst the Company Id is not visible on the page, it is revealed in the URL when a company is selected.

Also on the Custom Fields tab, select a Jiwa Staff member as the Freight Contact

Ensure also the Address and Phone fields are correct. The Address fields are used by Machship to determine the pick up location of the consignment and is a factor in selecting carriers, services and thus freight charges.

Carrier Maintenance

Carriers and their services in Jiwa are matched to Carriers in Machship by name.

So, Carriers in Jiwa need to be enabled and have the same name as carriers in Machship, and the same applies to the Services.

Freight Descriptions (Freight Items in Machship) are fixed and the same for all carriers in Machship, and the SQL Script run previously in this guide would have created these Freight Descriptions for all carriers.

Freight descriptions which were already attached to the carrier when the script was run that did not match the Machship Freight Items will have been disabled by the script.

Creating Consignments in Machship from Jiwa

Consignments are created in Machship by the user pressing the Send to Freight System button on a sales order, Freight tab.

Setting a Carrier or Service selection before creating the consignment is optional.

Machship will select the carrier and service based on its own rules, and Jiwa will be updated with the carrier, service, consignment and freight items from Machship.

The Contact Name and address details on the Delivery Address tab of the sales order is what is sent to Machship as the delivery address in order for it to determine which carrier and which cost(s) apply - so ensure these are set.

The Contact Email Address and Contact Phone are custom fields introduced by the Machship plugin. These fields are automatically set when a contact name is selected, but the values can be overridden.

When a sales order is first created, or a debtor changed on a sales order the Contact Name is selected as the first contact name from the debtor maintenance form, and the Email Address and mobile phone number are populated into the respective delivery address fields.

Contact names on the debtor maintenance form can be ordered as desired, so if the first contact of a debtor is not the desired contact for deliveries, then move the desired contact to be the first contact on the debtor maintenance form.

On the Freight tab of a sales order, change the Status to Ready To Send and press the Send To Freight System button to create a consignment. The Use Least Cost checkbox can be used to instruct Machship to use the lowest cost option for carrier and service selection - leaving unchecked and Machship will use the fastest option.

Jiwa will be updated with the Carrier, Service, Consignments and Freight items from Machship.

The Consignment Note No. field is how Jiwa links the Jiwa consignment to the Machship consignment, and is used for subsequent updates.

If no freight items were on the sales order when initially sent, then a freight item “Item 01” of dimensions 1x1x1 and weight 1Kg is automatically added.

Updating Consignments In Jiwa From Machship

A button on the Freight tab of the sales order form, Update From Machship, will update the consignments and freight items on a sales order with the Machship consignment details.

The changes can be saved by the user by saving the sales order. Cancelling the changes will leave the order unchanged.

Jiwa will attempt to match each Consignment Note No. from the Consignment Notes tab to a Machship consignment, and if a match is found the freight items for that consignment are removed and replaced with all the Freight Items from Machship for that consignment, as well as update the Ex GST Amount and GST Amount for the consignment.

Automatic Scheduled Updates

Updates to consignment information on Jiwa sales orders can also be performed automatically, leveraging the Jiwa Plugin Scheduler.

A schedule is attached to the Machship plugin, which will automatically update Jiwa with any consignment information that has changed in Machship in the last 24 hours.

This schedule is configured to run hourly, from 7am to 7pm, Monday to Saturday, but can be changed to suit as required.

The event log will log the activity of the updates - including any errors.

To aid in toubleshooting, a button has been added to the sales order form, Utilites tab - Update Sales Orders From Machship Consignments - which can manually trigger the update of all consignments without having to wait for the next schedule execution.

Note that this will trigger the update for all consignments which have changed in Machship in the last 24 hours, not just the consignments for the currently viewed order.