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

Deployment

Prerequisites

Jiwa REST API Plugin

The Machship plugin has a dependency on the Jiwa REST API plugin, so this plugin must first be enabled.

Open the Plugin Maintenance form in Jiwa, and locate the REST API plugin and ensure it is enabled.

If not intending to send consignments via the Jiwa REST API, then it is not necessary for the Jiwa REST API service to be running, but the Machship plugin will still require the Jiwa REST API plugin to be present and enabled.

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.

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.

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 either the user pressing the Send to Freight System button on a sales order, Freight tab - or by invoking a REST API route

/SalesOrders/{InvoiceID}/SendToFreightSystem

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 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.

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.

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.

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.

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 easier debugging, 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.