Adaptor-Generic-(version-1) Routine: SQUIZZ.com Reconcile And Send Customer Invoices

The SQUIZZ.com Reconcile And Send Customer Invoices routine looks at sales orders previously imported into the Connector against a Generic adaptor, and matches up the original orders to the invoices generated in the business system that the Connector can read invoices from. If a match is found then the routine will generate customer invoice(s) that can be automatically sent to the customer's system via the SQUIZZ.com platform. The routine automates a number of business processes and can reduce the amount of labour required through the use of Electronic Data Interchange (EDI) workflows. This routines helps to reduce errors, as well as reduce the time, money and effort required for invoicing is handled effectively.

Topics

Prerequisites

Please make sure you have read through the Get Started/Overview and the Connector Adaptor Generic (version 1) documents before reading further on.

How It Works

Below are each of the steps that the routine will do when being run.

Locate sales orders within the Connector that are assigned to the same Generic adaptor that is running the routine.
For each sales order check that the order's Invoice field doesn't contain the text "FULLY INVOICED"
Call the adaptor's Customer Account Invoice Record's data export and find any invoices from the connected business system. If the Generic adaptor routes the Customer Account Invoice Record data export then call the routed adaptor to obtain the invoice records from it's configured system/data source. Match invoices on the same Key Customer Account ID and Purchase Order Number field set in the sales order.
For each found invoice check if any delivered quantities have been set in each line.
For each found invoice check that it hasn't already been sent previously. This is done by checking in the sales order's Invoice Number field doesn;t contain the keyInvoiceID with its comma delimited list.
For invoices containing delivered quantities generate a Customer Invoice Ecommerce Standards Document record.
Send each generated customer invoice for the sales order to SQUIZZ.com against the customer organisation specified by the Customer Organisation ID routine setting.
If the customer invoice successfully sent to SQUIZZ.com then within the Connector's sales order place the value of the key Invoice ID within the Invoice Number field. If a value exists then comma delimit multiple invoice IDs.
After all order files have been processed and if configured Email out a notification to specified Email addresses a report of the orders that have had invoices sent, and those orders that could not have invoices sent.

Reasons Why An Order Fails To Have Its Invoices Sent

Below are the reasons why the routine may not be able to send out invoice(s) for a sales order.

The Connector cannot connect to any business system to search for the invoices. This could be because the Connector's adaptor has not been configured correctly, or the data source its connecting to is not running, or not able to return successful responses.
No invoices in the configured connected data source match the customer account based on the Key Customer Account ID set within the sales order.
No invoices in the connected data source match the Purchsae Order Number based on the order number set within the sales order.
Invoices matched to a sales order in the connected data source do not contain lines that match on the order's Purchase Order Line Number. This is because either the purchase order line number has not been set against an invoice line, or that the connector's adaptor has not been configured to look at the correct invoice line field. If personel within the connected data source are changing the lines in an invoice that is matched to an sales order the following actions could cause the purchase order line number to not exist.
- A person has deleted an invoice line that causes purchase order line number to disappear.
- A person has added an invoice line that never had the purchase order line number assigned to it,
Invoices matched to a sales order in the connected data source don't have delivered quantities that match the original quantities from the sales order.
The Connector's routine could not send out a customer invoice to SQUIZZ.com because the network/internet connection between the Connector and SQUIZZ.com is unavailable, or has become broken.
The Connector's routine could not send out an customer invoice to SQUIZZ.com because SQUIZZ.com API's in unavailable, or incorrect credentials to SQUIZZ.com have been set against the adaptor, or the routine, or is not returning a successful response.
The customer organisation has not registered within SQUIZZ.com, or is not allowing trade to occur on the platform, or a connection has not been made within the organisation running the adaptor routine, and the organisation that the invoices are specified to be sent to.
The Connector's routine could not update the status of the sales order. This could be due to the computer that the Connector is running on has ran out of resources, such as free disk space, memory, or restrictive permissions on the Connector's own database file.

Routine Setup: Creating a new SQUIZZ.com Reconcile And Send Customer Invoices routine

Open up the Connector application.
In the Adaptors and Messages tab, Under the Adaptors section, click on the Settings button against a listed Generic (version 1) adaptor.
Click on the Data Routines tab.
In the Routine Type drop down, select the SQUIZZ.com Reconcile And Send Customer Invoices 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.

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.

Notes:

In the Routine Settings section below describes what each of the settings do. Use this to configure the routine.
If a red icon appears in the 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
Invoice Sending Timeout (seconds)	Positive numbers	Set the amount of seconds before giving up on a response when trying to send an invoice to the SQUIZZ.com API. It's recommended to put a number of 60 or higher. For slow internet connections or invoices with large amounts of lines set a number such as 120.
Key Customer Account ID	All Characters	If set only allows invoices to be sent out for sales orders that are assigned with the customer account containing the the specified Key Customer Account ID.
Order Instructions Prefix Matcher	All Characters	If set only allows invoices to be sent out for sales orders that have the instructions field start with the text set. If left empty then all sales orders that have not been fully invoiced will attempted to find invoices for.
Report Notification Email Subject	All Characters	Set the subject set in the routine's report notification email. This only needs to be set if the Send Report Notification Email setting is set to true.
Report Notification From Email Address	All Valid Email Characters	Set the email address that will be set in the From email address if the Report Email Notification is sent out. This only needs to be set if the Send Report Notification Email setting is set to true.
Report Notification To Email Address	All Valid Email Characters	Set a comma delimited list of addresses that the report notification email will be sent to. This only needs to be set if the Send Report Notification Email setting is set to true.
SQUIZZ API Session Creation Timeout (seconds)	Positive 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	Values: true or 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 invoices that could be sent. If set to true then ensure that the email settings for the adaptor running the routine have been configured and the Connector is able to send out emails. Read Configure Adaptor Settings for more details.
Squizz Customer Org ID	All Characters	Set the organisation ID of the customer assigned to them within SQUIZZ.com. Invoices are sent to this organisation. If the customer's organisation is not registered on the SQUIZZ.com platform, then a person from the organisation will need to do the following: Personally sign up, Register their organisation, Connect to the organisation assigned against the adaptor Set their organisation's Trading Status to Fully Trading, or Buying Only.
Supplier Account Code	All Characters	Optionally set the code of the supplier account that the customer organisation has assigned the supplier organisation to. Only required if customer organisation has multiple accounts assigned to the supplier organisation.

Routine Data Fields

The routine has no configurable data fields.

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	Cannot find the key customer account ID in the sales order. Adaptor Sales Order ID: adaptorOrderSaleID	This error occurs when the routine tries to find the details of sales order in the connector, but the KeyCustomerAccountID field contains no value. This means the routine has no way of knowing which customer account in the business system it should try to look for associated invoices. The sales order needs to have a Key Customer Account ID set.
Error	Unable to obtain Micronet invoices that correspond with the order.	This error occurs when the routine connects to the Micronet Distribution system but cannot find any invoices that have an order number that matches the order. This issue could occur because either a picking slip has not been converted into an invoice, the invoice has has the order number removed, or the order was never imported or invoiced.
Error	No invoices exist with the sales order code. Adaptor Sales Order ID: adaptorOrderSaleID Sales Order Code: salesOrderCode	This error occurs when the routine tries to call the the adaptor's Customer Account Invoice Records data export, or the adaptor routed for the export, and the request to obtain the invoices from the connected system/data source returned no invoices. This may indicate that either no invoices yet exist that match the sales order's Purchase Order Number field, or that any invoices do exist either are not ready to be invoiced, or that the data export is not correctly configured to look for invoices, or the invoices are not assigned to the same customer account that is set in the sales order. Check that the connected business system/data source contains any invoices and that the invoice data is correct. Lastly check that the Connector has been correctly configured. This error may actually just be a warning or information indicator if it takes time for sales orders to be converted into invoices.
Error	Unable to obtain adaptorName invoices that correspond with the sales order. This could be caused by a connection issue or a retrieval issue. Error: errorDescription	This error occurs when the routine tries to call the the adaptor's Customer Account Invoice Records data export, or the adaptor routed for the export, and the request to obtain the invoices from the connected system/data returned back a failure response. This could indicate that either the connected system or data source was not able to correctly handle returning data, the system/data source is not running, a processing error occurred, or another type of error. Look at the error description in the message to determine what caused the failure. Optionally turn on the ALL filter message logs in the Connector messages table to see what is occurring when the request is made to retrieve the invoice data for a sales order.
Error	Unable to obtain details of the invoice in adaptorName associated to the sales order since the invoice does not exist, cannot be found, or a connection issue occurred. Invoice ID: invoiceID	This error occurs when the routine tries to call the the adaptor's Customer Account Invoice Records data export, or the adaptor routed for the export, and the request to obtain the details of an invoice from the connected system/data returned back a failure response. This could indicate that either the connected system or data source was not able to correctly handle returning data, the system/data source is not running, a processing error occurred, or another type of error. Look at the error description in the message to determine what caused the failure. Optionally turn on the ALL filter message logs in the Connector messages table to see what is occurring when the request is made to retrieve the invoice data for a sales order. This error indicates that either the details of the invoice could not be obtained or the lines within the invoice could not be obtained.
Error	An ordered quantity could not be matched to an invoiced and delivered quantity for product line number: lineNumbers in the matched adaptorName invoices.	This error occurs after the routine has found invoices for a matching sales order however one of the lines in the order cannot be matched to one or more invoice lines, or the sum of the invoice lines delivered quantity does not match the ordered quantity. This error could occur if no stock was available in the order and is awaiting to be back ordered. It could also occur if the purchase order line number was no longer set against an invoice line. The invoices associated with the order should be checked to see if outstanding quantities are yet to be delivered, or if purchase order number data is missing. If the later then manual sending of the invoice may be required and the sales order needs to be marked as FULLY INVOICED: in the Connector sales order's Invoice Number field.
Error	The order quantity does not match the invoiced and delivered quantity for product line number: productLineID in the matched adaptorName invoices. Sales Order Code: salesOrderCode Adaptor Sales Order ID: adaptorOrderSaleID	See message directly above.
Error	Unable to obtain details of the customer account in adaptorName because it cannot be found, or connection issue occurred. Key Customer Account ID: keyCustomerAccountID Error: message	This error occurs when the routine could not connect to the system/or data source to obtain the details of the customer account associated to find invoices for a sales order, via the Customer Account Status data export. Or if the Customer Account Status data export successfully connected the details from the customer account could not be obtained. The Customer Account Status data export settings should be checked, as well as check that the system/data source of the Customer Account Status is configured to communicate with is running and able to return data. Alternatively this could happen if the customer account associated to the order was deleted from the connecting system/data source. Look at the error message to obtain more information about this issue.
Error	Unable to send invoices to SQUIZZ.com API since a session could not be created. Error: resultMessage Error Code: resultCode	This error occurs when the routine was trying to talk to the SQUIZZ.com platform's API to try and establish a session. The may fail if incorrect SQUIZZ.com organisation credentials are set up in the adaptor settings, or if SQUIZZ.com is currently unable to handle requests. Check the result message and error code for more details why the failure occurred.
Error	Unable to generate a customer invoice ESD record for the sales order. adaptorName Invoice ID: invoiceID Error: message	This error occurs when the routine was trying to generate a customer invoice document containing the invoice details obtained previously from the connected system/data source. The mostly reason why this error message may occur if incorrect data is trying to be set up in the invoice. Look at the message to determine the reason or raise the issue with SQUIZZ.com if it repeatedly occurs.
Error	An invoice has been successfully sent to the customer organisation in SQUIZZ.com, however its sales order in the Connector could not be updated with send invoice ID. Please set the Invoice ID: invoiceID in the sales order Invoice Number field to to avoid the invoice being sent again.	This error occurs if the routine was able to successfully send a customer invoice to the SQUIZZ.com platform, however the routine was unable to update the sales order within the Connector to denote that the invoice was sent. You need to do this manually through the Connector application by finding the sales order, then within its Invoice Number field place the ID of the invoice into this field. If this is not done then the next time the routine runs it may send the same invoice to SQUIZZ.com again, which may cause duplicate invoices to be sent to the customer. This issue may be due to the Connector's database being locked by another process, or the hard disk being full/corrupt on the computer.
Error	The Customer Invoice invoice for a sales order failed to send to SQUIZZ.com. Reason: resultMessage Error Code: resultCode Invoice ID: invoiceID Sales Order: salesOrderCode	This error occurs when the routine tries to send a customer invoice to the SQUIZZ.com platform, however an failure response was returned from the platform. Check the message in the error to see what went wrong. It could be due to several reasons, such as the organisation sending the invoice data not having enough trading tokens, or having no relationship set up with the customer organisation, or a data issue.
Error	The Customer Invoice for the sales order failed to send. This could be due to the receiving system being uncontactable, or the internet connection is down at either end, or because of a networking issue, or because of a system processing issue. Invoice ID: invoiceID Error: message	This error occurs when the routine tries to send a customer invoice to the SQUIZZ.com platform, however error occurred when trying to send the invoice data. Mostly likely due to an internet connection issue, networking issue, or a data sending issue. View the message in the error for more details.
Error	An invoice has been successfully sent to the customer organisation in SQUIZZ.com, however its order in the Connector not be marked as being fully invoiced. Please update the sales order to to avoid the invoice being sent again. Adaptor Sales Order ID: adaptorOrderSaleID	This error occurs if the routine was able to successfully send a customer invoice to the SQUIZZ.com platform, however the routine was unable to update the sales order within the Connector to denote that all invoices for the sales orders have now been successfully sent. You need to do this manually through the Connector application by finding the sales order, then within its Invoice Number field place the text FULLY INVOICED into this field. If this is not done then the next time the routine runs it will try to find invoices for the sales order that do not have IDs listed in the Invoice Number field. This issue may be due to the Connector's database being locked by another process, or the hard disk being full/corrupt on the computer.
Error	Cannot read the original sales order stored in the Connector. This could be due to another application locking or moving the Connector's database, or else another related error. Error: message	This error occurs when the routine tried to find the sales order in the Connector but was not able to. This issue may be due to the Connector's database being locked by another process, or the hard disk being full/corrupt on the computer.
Info	Customer Invoice has been successfully sent to customer organisation through SQUIZZ.com. Invoice No: invoiceID Sales Order: salesOrderCode Adaptor: adaptorName	This message occurs when the routine was able to successfully send a customer invoice to the SQUIZZ.com platform and had been saved against the customer organisation within the platform. The invoice may or may not have yet been imported into the customer's system, depending if the customer has allowed SQUIZZ.com to do so.
Debug	Attempting to export out customer invoices to SQUIZZ.com	This message appears when the routine begins to run.
Debug	Attempting to obtain details of the sales order. Adaptor Sales Order ID: adaptorOrderSaleID Adaptor: adaptorName	This message appears when the routine starts to try and find invoices for the next sales order in the Connector.
Debug	AdaptorName invoice has been found for the sales order. Attempting to obtain its details.	This message appears when the routine was able to find an invoice for a sales order when calling the Customer Account Invoice Records data export from a connected business system/data source. The routine will then try to get the details of the invoice by calling the Customer Account Invoice Records and Customer Account Invoice Line Records data exports.
Debug	AdaptorName invoice details have been found for the sales order. Attempting to match up invoice(s) to the original sales order. Sales Order Code: salesOrderCode Adaptor Sales Order ID: adaptorOrderSaleID Adaptor: adaptorName	This message appears when the routine was able to find the details of an invoice for a sales order when calling the Customer Account Invoice Records data export from a connected business system/data source. The routine will then try to look through each of the found invoice lines and match them up to the sales order lines.
Debug	AdaptorName invoice(s) have been matched up. Attempting to obtain customer account details. Account ID: customerAccountCode Adaptor: adaptorName	This message appears when the routine was able to find and match up invoice lines to the original sales order. The routine is then calling the adaptor's Customer Account Status data export or the export of a routed adaptor to obtain the details of the customer account to place into the invoice being sent out.
Debug	API Session successfully created with SQUIZZ.com. Adaptor: adaptorName	This message appears when the routine is about to try and send an invoice to a customer in SQUIZZ.com and it first needed to authenticate and set up a session with the SQUIZZ.com API, using the organisation credentials set against the adaptor.
Debug	Attempting to create the customer invoice record. Invoice ID: invoiceID Adaptor: adaptorName	This message appears when the routine is trying to convert a Customer Account Enquiry Invoice record into a Customer Account Invoice record, ready to be sent to the SQUIZZ.com platform in a standardised form.

Document last modified on the 24th October 2019