Generic Adaptor (1.0) Adaptor Routine: SQUIZZ.com - Smartfreight Customer Freight Delivery Notice Export

The routine looks at sales orders imported into the Connector against its adaptor, and tries to find freight delivery/tracking data associated to the order within SmartFreight's system against a consignment note. If found then a delivery notice is created at sent back to the customer via SQUIZZ.com. This allows the customer to be aware of the progress of the ordered goods being delivered, as well as automating freight data being retrieved and sent out from SmartFreight's system, possibly saving many hours of manual key entry and associated costs for both suppliers and customers. This routine may be used to send Advanced Shipping Notices (ASN).

Note that this routine requires an organisation to both have an account set up within SmartFreight's system, as well as the organisation be set up on the SQUIZZ.com platform.

Topics

Prerequisites

Please make sure you understand and have the following setup, and have read the following linked documents before proceeding on.

An account set up with Smartfreight
An organisation registered on SQUIZZ.com platform, see more details here.
Customer accounts have been imported into SQUIZZ.com against the organisation that delivery notices are coming from.

How It Works

The SQUIZZ.com - Smartfreight Customer Freight Delivery Notice Export routine will look at each of the sales orders assigned to the same adaptor as the routine is created for, and will for orders that have a "Delivered" status set to No. For these orders it will then attempt to make a request to find an associated consignment note within Smartfreight, based on either the order's "Freight System Ref, Code" having the same ID of a smartfreight consignment note, or if not set then it will try to search Smartfreight orders that have a reference matching either the order's "Sales Order Code" or "Purchase Order Number" (a routine controls which order field to match on). If one or more consignment notes is found in Smartfreight then the routine will look at the first consignment, and only if it contains both a connote number and a tracking number of the freight carrier, will the routine then create a delivery notice.

An attempt will be made to then send the delivery notice for the sales order to SQUIZZ.com, with the delivery notice containing the key details, including the freight carrier tracking number, carrier name, carrier service, sales order code, purchase order number, customer account key, delivery status, and delivery message. The routine will use adaptor's SQUIZZ.com settings to control which organisation it will connect to SQUIZZ.com API with and send the delivery notice on behalf of. SQUIZZ.com may then save the delivery notice against the corresponding customer account and optionally against the sales orders it originated from. It may also then raise a notification to advise the individual person of the delivery notice if the order was raised by an individual person. If the sales order was raised by an organisation then the delivery notice may be passed to the organisation to import into their own system. Alternatively the routine can advise to use the supplying organisation's own Customer Delivery Notice data export in SQUIZZ.com to send to another business system if configured in a data adaptor in SQUIZZ.com. If the delivery notice has successfully been sent to SQUIZZ.com then the routine will update the "Delivered" status to Yes to avoid the order being looked at the next time the routine is run.

A number of settings can be configured for the routine. This includes settings that control the delivery status and message that appears in the delivery notice, as well as settings to control if the routine should only look at specific undelivered sales orders that belong to specific customer accounts, or optionally have instructions that start with matching text. The routine also includes settings that control if the routine should email out a report, containing details of each of the sales orders the routine looked at, and results of trying to find consignment notes and send delivery notices to SQUIZZ.com.

When the routine is run, if the DEBUG logging is set to show within the Connector's message logs, then it will show details of attempts made to call SmartFreight, send delivery notices to SQUIZZ.com, as too will the email notification if it is set to be sent out.

Routine steps:

Get the list of the sales orders assigned to the adaptor that have the Delivered status set to No, is not an export order, and conditionally match the following:
- Key Customer Account ID order field matches a value in the Key Customer Account IDs routine setting if not empty
- Instructions order field starts with the value in the Order Instructions Prefix Matcher routine setting if not empty.
For each found sales order perform the following steps:
1. If the sales order does not have a Freight System Ref. Code then call Smartfreight's FindCon web service endpoint to find one or more consignment notes that contain have a reference that matches the order's Sales Order Code field if the routine's Smartfreight Search Order Field setting is set to "salesOrderCode", or or match the consignment note reference to the order's Purchase Order Number field if the routine's Smartfreight Search Order Field setting is set to "purchaseOrderNumber". If one or more consignment notes was found then obtain the ID of the first consignment note. If no consignment note was found then abort processing the sales order and move onto the next order.
2. Using the ID of the consignment note either found in the previous step or that is stored in the Freight System Ref. Code of the sales order, call Smartfreight's Enquiry web service endpoint to obtain details of the consignment.
3. If the Smartfreight consignment was found check that it has values for the connote number and the tracking number label. If it does not then abort processing the sales order and move onto the next order. If it does then create a Delivery Notice, setting values for the following notce fields:
  - keyCustomerAccountID
  - freightCarrierConsignCode
  - freightCarrierName
  - freightCarrierServiceCode
  - freightCarrierCode
  - freightCarrierName
  - freightCarrierTrackingCode
  - freightCarrierConsignCode
  - deliveryStatus
  - deliveryStatusMessage
  - freightSystemRefCode
  - keySalesOrderID
  - salesOrderCode
  - purchaseOrderNumber
  - purchaseOrderCode
4. For each product line in the sales order add to the delivery notice.
5. Call the SQUIZZ.com API to create a new session if not previously been created, using the SQUIZz.com credentials set against the adaptor that the routine belongs to in the Connector.
6. Call the SQUIZZ.com API endpoint Send Delivery Notice To Customer to send the created delivery notice.
7. If the delivery notice was successfully sent then update the sales order's Delivered status to Yes.
8. Repeat step 2 for the next sales order found.
If the routine's Send Report Notification Email setting is set to "true" then create a email that lists the sales orders found, and the attempts to send out delivery notices for each sales order. Use the routine's "Report Notification To Email Addresses" setting to determine the emails addresses to send the report to, and use the adaptor's email settings to determine which outgoing SMTP email server to send the report's email through.
Log the outcome of sending the email notification within the Connector's message logs, and the final results of running the routine.

Routine Setup: SQUIZZ.com - Smartfreight Customer Freight Delivery Notice Export

Open up the Connector application.
In the Adaptors and Messages tab, Under the Adaptors section, click on the Settings button against a listed Generic adaptor.
Click on the Data Routines tab.
In the Routine Type drop down, select the SQUIZZ.com - Smartfreight Customer Freight Delivery Notice Export option, then click the Create Routine button.
In the Routine Code text box enter a name for the routine, then press the Save Routine button.

A new routine will be created for the adaptor and appear in the Routines drop down.

Routine Setup: Configure Settings

Click on the Settings tab of the routines.
For each row in the settings table, click on the Setting Value field.
Enter a setting value, then click to the next row. The setting will automatically save once the cursor exits the field.
Click on the Data Fields tab.
Click on the Add Field button to add a data field to the routine for each product field that needs to be checked for missing data.
1. Within Source Field column set the value of the argument. If the value contain spaces then wrap the value with double quote characters.

Notes:

In the Routine Settings section below describes what each of the settings does. Use this to configure the routine or read the settings documentation below.
If a red icon appears in the routine table's Setting Value cell, then the cell does not accept the given input. You will need to change the value in the cell to be valid.

Routine Settings

Below are the settings that can be configured for the routine.

Setting label	Allowed Values	Description
Delivery Notice Sending Timeout (seconds)	Any Numbers	Set the amount of seconds before giving up on a response when trying to send an delivery notice to the SQUIZZ.com API.
Delivery Notice Status	Any Characters	Sets the status of the delivery notice that is sent, indicating where the goods being delivered are currently at. Must be set to a value defined in the Ecommerce Standsrds Documents.
Delivery Status Message	Any Characters	Set the message to display in the delivery notice to inform the receiver of the status of the delivery.
Include Sales Order Product Lines	true,false	If set to true then include sales order lines in the delivery notice to denote the products that are being delivered.
Key Customer Account IDs	Any Characters	If set only allows delivery notices to be sent out for sales orders that are assigned with the customer account containing the the specified Key Customer Account ID, for multiple accounts set a comma delimited list.
Order Instructions Prefix Matcher	Any Characters	If set only allows delivery notices to be sent out for sales orders that have the instructions field start with the text set.
Report Notification Email Subject	Any Characters	Set the subject set in the report notification email.
Report Notification From Email Address	Allowed Email Characters	Set the email address that will be set in the From email address if the Report Email Notification is sent out.
Report Notification To Email Addresses	Allowed Email Characters and Commas	Set a comma delimited list of email addresses that the report notification email will be sent to.
SQUIZZ API Session Creation Timeout (seconds)	Any Numbers	Set the amount of seconds before giving up on a response when trying to create a new organisation session within SQUIZZ.com API.
Send Report Notification Email	true,false	If set to true then a report of the routine will be sent out after it finishes running, with details of the sales orders and delivery notices that could be sent.
SmartFreight API ID	Any Characters	The ID credential used to authenticate and access the Smartfreight API web service.
SmartFreight API Password	Any Characters	The Password credential used to authenticate and access the Smartfreight API web service.
SmartFreight API URL	Allowed URL Characters	Set the absolute URL of the Smartfreight SOAP based API webservice that is called to obtain freight details for a sales order
SmartFreight Enquiry Timeout (seconds)	Any Numbers	Set the amount of seconds to wait before giving up on recieving a response from the Smartfreight API endpoint to retrieve freight details for an order.
Smartfreight Search Order Field	salesOrderCode or purchaseOrderNumber	If a sales order contains no freight system reference ID, then set the order field used to search for a matching consignment within Smartfreight that contains a matching reference value. Set either salesOrderCode or purchaseOrderNumber
Squizz Customer Org ID	Any Characters	Optionally set the organisation ID of the customer organisation within SQUIZZ.com that delivery notices are sent to. Leave empty to allow SQUIZZ.com to determine this based on a linked sales order or customer account.
Supplier Account Code	Any Characters	Optionally set the code of the supplier account that the customer organisation has assigned the supplier organisation to. Only required if a customer organisation is receiving the notification and has multiple accounts assigned to the supplier organisation and the Use Customer Delivery Notice Export setting is set to false.
Use Customer Delivery Notice Export	true,false	If set to true then the delivery notice is imported into SQUIZZ.com. have the notice exported from SQUIZZ.com using Customer Delivery Notice data adaptor export. Only set to true if the export is set up and needed.

Routine Message Meanings

Listed below are a majority of the messages that are generated by the routine, either through the connector logs, or in the sent email notification.

Type	Message	Meaning
Error	Unable to search through the sales orders in the Connector to create delivery notices for. Error: errorMessage	This error may occur if the Connector's database file is locked by another application, is corrupted has been deleted, or the hard disk it sits on has a problem.
	Cannot find the Freight System Ref Code in the sales order when calling Smartfreight's FindCon web service endpoint. Error: errorMessage	This error can occur for several reasons, from the list of errors below. It means that the routine was not able to find a consignment in Smartfreight that contains a reference that matches an order's sales order code or purchase order number.
Error	No Smartfreight consignment was found containing the reference value	This error occurs if after calling Smartfreight's web service, for the consignment data returned it did not contain any ID to a references connote. This typically occurs if no matching consignment could be found in Smartfreight. Check that a connote matches the sales order data in its reference field.
Error	Unable to parse XML data returned. Error:errorMessage	This error may indicate that either Smartfreight have changed the way their system returns data in the response, or incorrectly is returning data in the XML data format.
Error	HTTP Response Code: responseCode doesn't match expected code: 200	This error may indicate that Smartfreight's web service did not return a successful response. The responseCode will correlate with the type of issue. Typically it will be caused by incorrect Smartfreight credentials being set up within the routine's settings.
	Request to enquire and search for matching consigment took too long to return a response. Timed out after: numberOfMilliseconds milliseconds.	This error occurs if Smartfreight's sytem takes too longer to return a response. It may indicate that their system is unable or the computer network is blocking traffic from reaching Smartfreight's system. Check that Smartfreight's system is running, and that you don't have firewall or networking issues on your side.
Error	Error occurred when trying to make HTTP request. Error: responseMessage URL: smartfreightURL Response Body: responseBody	This error typically occurs when a timeout is exceeded or a connection issue has occurred when trying request data from Smartfreight's web service. Check that your internet connection is running and correct URL has been set up for Smartfreight.
Error	Unable to obtain delivery notice that corresponds with the sales order from Smartfreight's Enquiry web service endpoint. Error: errorMessage	This error occurs for any of the resons above when a request is attempted to obtain details of a consignment note from SmartFreight's system. Because of this the freight carrier cannot be obtained for the sales order and no delivery notice can be sent out.
Error	A delivery notice has been successfully sent to the customer organisation in SQUIZZ.com, however its sales order in the Connector could not be updated with send deliveryNotice ID. Please update the Delivered status of the sales order to avoid the delivery notice being sent again.	This error occurs if the routine was able to successfully sent out a delivery notice for a sales order, but was unable to then update the delivered status of the order. This typically occurs only if another application has locked the Connector's database, or hard disk it sits on has run out of space.
	Unable to send delivery notices to SQUIZZ.com API since a session could not be created. Error: errorMessage Error Code: errorCode	This error typically occurs if incorrect SQUIZZ.com organisation API credentials have been set up against the adaptor, or else the SQUIZZ API was unable to return a success response. Check the API credentials are correct.
Error	An error occurred while trying to send out an email notification for the routineLabel routine.	This error occurs when the routine tries to send out an email notification of the report and fails. This could be because the adaptor's Email server setting have not been configured correctly, if if the From and To recipient email settings have been incorrectly configured.
Info	No adaptorName sales orders were found to be processed into delivery notices.	This occurs if there's no sales orders that are not delivered, or matching the customer account or instructions prefix settings.
Info	An email notification has been sent out for the routineLabel routine.	This message occurs when the routine has successfully sent out an email notification containing details of the attempt the routine to send out the delivery notices, and if successful the details of the report.
Debug	Attempting to export out customer delivery notices to SQUIZZ.com	This message appears before the routine attempts to first start running.
Debug	Attempting to obtain sales orders for the adaptor with undelivered product
Debug	Beginning processing of the next sales order.
Debug	Attempting to obtain details of the sales order.
Debug	Sales order has been obtained from the Connector database. Freight System Reference not found, attempting to search Smartfreight for matching consignment.

Document last modified on the 12th May 2021