Micronet Adaptor (2.0-2.9) Adaptor-Routine: xCBL3.0 Reconcilliation Invoice Export

The xCBL3.0 Reconcilliation Invoice Export routine looks at sales orders previously imported the Micronet Distribution system through the Connector, and matches up the original orders to the invoices generated in the Micronet Distribution system. If a match is found then the routine will generate invoice files that can be automatically uploaded to a specified web service where the order originated from. 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.

The routine specifically looks at purchase orders that were delivered to the Connector in the xCBL3.0 data file format. Subseqently the routine sends back invoice file data in the xCBL3.0 data file format. This data format is simply an XML file data that formatted to agreed xCBL specification. Any compatible business systems that use the xCBL data standard to push and receive order/invoice data can effectively work with this routine in the Connector's Micronet Distribution adaptor.

Topics

Prerequisites

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

How It Works

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

Locate xCBL orders in the specified directory where the order files were saved when imported into the Connector.
For each xCBL order file check that the file's name is configured in the following format to allow required data to be extracted.
PO-[debtor_account_id]-[order_ID]-[date]-[time]-GEN.xml
Parse the xCBL order file and extract out details of the order.
Connect to the Micronet Distribution system's database and find any invoices that match the debtor account ID and order ID obtained from step 2.
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.
For invoices containing delivered quantities generate xCBL3.0 invoice files.
Send each generated xCBL3.0 invoice file for the order to the designated web service.
Save the generated and sent xCBL3.0 invoice files to the configured directory for referencing purposes.
Move the original xCBL3.0 order file into the "orders_sent" subdirectory once all of its line quantities have been delivered. This ensures that the order is not processed again when the routine next runs.
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 an order file.

The directory where the xCBL3.0 order files are saved to does not exist or cannot be accessed by the Connector.
The xCBL3.0 file's name does not conform to the required file format.
The Connector cannot connect to the Micronet Distribution system's database using ODBC. This could be because the database is not available, or the ODBC data source name has not been configured correctly, or the Connector's adaptor has not been configured correctly.
No invoices in the Micronet Distribution system match the debtor account based on the account ID set within the order's file name.
No invoices in the Micronet Distribution system match the order number based on the order number set within the order's file name.
Invoices matched to an order in the Micronet Distribution system 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 Micronet Distribution system are changing the lines in an invoice that is matched to an 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 an order in the Micronet Distribution system don't have delivered quantities that match the original quantities from the order.
The Connector's routine could not send out an invoice file to the configured webservice because the network/internet connection between the Connector and the webservice is unavailable, or has become broken.
The Connector's routine could not send out an invoice file to the configured webservice because the webservice is not running, or is being sent incorrect access credentials, or is not returning a successful response.
The Connector's routine could not move the original xCBL3.0 order file to the sent directory. This would typically occur if the Connector did not have permission to write to the directory.

Routine Setup: Creating a new Order Product Deliveries Text File Export routine

Open up the Connector application.
In the Adaptors and Messages tab, Under the Adaptors section, click on the Settings button against a listed Micronet version 2.0-2.9 adaptors.
Click on the Data Routines tab.
In the Routine Type drop down, select the xCBL3.0 Reconcilliation Invoices 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.

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
Company Business Number	All Characters	Number of the company or business that the invoices are being sent from.
Company Name	All Characters	Name of the company or business that the invoices are being sent from.
Email Subject	All Characters	Text that is set in the subject field of the Email notification that gets sent out for the routine.
Notification From Email Address	All Valid Email Characters	Email address to send notifications to once the routine has been completed. Emails will only be sent to the address if the "Send Email Notification" is set to true.
Notification To Email Address	Allowed Filename Characters	Email address that the routine's report will be Emailed to. Emails can be sent to multiple addresses if each address is comma delimited. Eg. address1@example.com,address2@example.com
Send Email Notification	Values: true or false	Sends out an email notification containing the report of the routine running. If true, ensure that the "Notification To Email Address" setting contains an email address. Also ensure that the connector's SMTP property has been configured for the adaptor.
xCBL3.0 Invoice Folder Location	Allowed Filename Characters	Folder path that specifies where generated xCBL3.0 invoice files are to be saved to.
xCBL3.0 Invoice Tax Category Code	All Characters	Tax category code embedded within the generated xCBL3.0 invoice file.
xCBL3.0 Tax Code	All Characters	Tax code that is embedded within the generated xCBL3.0 invioce file that indicates the tax applied to the invoiced lines.
xCBL3.0 Invoice Tax Rate	All Characters	Tax rate that is embedded within the generated xCBL3.0 invoice file that indicates the percentage of tax applied to each invoiced line.
xCBL3.0 Purchase Order Folder Location	Allowed Filename Characters	Folder path that specifies where the xCBL3.0 order files are to be read from.
xCBL3.0 Upload Password	All Characters	Password of the webservice where the xCBL3.0 invoice files will be uploaded to. The password forms part of the HTTP basic authentication header embedded in the upload HTTP request.
xCBL3.0 Upload URL	All Characters	URL of the webservice where the xCBL3.0 invoice files will be uploaded to.
xCBL3.0 Upload User	All Characters	User of the webservice where the xCBL3.0 invoice files will be uploaded to. The user forms part of the HTTP basic authentication header embedded in the upload HTTP request.

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	No Micronet invoices exist with the order number	This error occurs when the routine connects to the Micronet Distribution system's database 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	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	Unable to obtain Micronet invoices that correspond with the order. This could be caused by a connection issue or a retrieval issue.	This error occurs when the routine could not connect to the Micronet Distribution system's database to search for invoices, or if it successfully connected an error occurred to not allow the invoice data to be obtained. The database connection settings should be checked as well as the the Connector's logs to provide more details.
Error	Unable to obtain details of the invoice in Micronet	This error occurs when the routine connects to the Micronet Distribution system's database but cannot find any details of an invoice that matches an order's number. This is most likely due a connectivity issue or an issue with Micronet's database.
Error	Unable to obtain details of the invoice in Micronet associated to the order since the invoice does not exist, cannot be found, or a connection issue occurred.	This error occurs when the routine connects to the Micronet Distribution system's database but cannot find any details of an invoice that matches an order's number. This is most likely due a connectivity issue or an issue with Micronet's database.
Error	The order quantity does not match the invoiced and delivered quantity for product line number: [XYZ] in the matched Micronet invoices.	This error occurs after the routine has found invoices within the Micronet Distribution system matching the 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 no stock was available in the order and is awaiting back order. 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 removal of the order file from the Connector directory should occur.
Error	Unable to obtain details of the organisation in Micronet most likely due to a connection or configuration issue	This error occurs when the routine could not connect to the Micronet Distribution system's database, or if it successfully connected the details from the configured company file could not be obtained. The database connection settings should be checked as well as the the Connector's routine settings.
Error	Unable to obtain details of the debtor account in Micronet because it cannot be found, or connection issue occurred	This error occurs when the routine could not connect to the Micronet Distribution system's database, or if it successfully connected the details from the debtor account could not be obtained. The database connection settings should be checked as well as the the Connector's routine settings. This could happen if the debtor account associated to the order was deleted.
Error	Unable to obtain details of the organisation in the Micronet invoice.	This error occurs when the routine could not connect to the Micronet Distribution system's database, or if it successfully connected the details from the configured company file could not be obtained. The database connection settings should be checked as well as the the Connector's routine settings.
Error	Unable to generate an xCBL3.0 invoice file for the order	This error occurs if the xCBL3.0 invoice file could not be generated based on data from the invoice data obtain from the Micronet Distribution system. This error should be raised to the Connector's support team.
Error	The invoice XML file could not be saved to the filesystem	This error occurs if the routine could not save the generated xCBL3.0 invoice file to the directory specified in the routine's settings. This issue is mostly caused by an incorrectly configured directory, or that the Connector software does not have permission to write to the directory. It may also be caused if another file named the same already exists within the directory and contains locks on it.
Error	The xCBL3.0 invoice file for the order was successfully sent however the file could not be saved to the file system	This error occurs if the routine could not save the generated xCBL3.0 invoice file to the directory after the xCBL3.0 file was successfully uploaded to the specified web service. This issue is mostly caused by an incorrectly configured directory, or that the Connector software does not have permission to write to the directory. It may also be caused if another file named the same already exists within the directory and contains locks on it.
Error	Invoice file failed to be received or received correctly	This error occurs if the routine could not upload the generated xCBL3.0 invoice file to the specified web service. 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. To solve this problem check that the computer that the Connector software is installed on has access to the internet or relevent internal network URL. Check that the web service is running at the other end. Check that the credentials given in the routine are correct.
Error	The xCBL3.0 invoice file for the 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	This error occurs if the routine could not upload the generated xCBL3.0 invoice file to the specified web service. 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. To solve this problem check that the computer that the Connector software is installed on has access to the internet or relevent internal network URL. Check that the web service is running at the other end. Check that the credentials given in the routine are correct.
Error	The failed invoice XML file could not be saved to the filesystem	This error occurs if the routine could not save the generated xCBL3.0 invoice file to the directory specified in the routine's settings. This issue is mostly caused by an incorrectly configured directory, or that the Connector software does not have permission to write to the directory. It may also be caused if another file named the same already exists within the directory and contains locks on it.
Error	Invoice file failed to be sent out.	This error occurs if the routine could not upload the generated xCBL3.0 invoice file to the specified web service. 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. To solve this problem check that the computer that the Connector software is installed on has access to the internet or relevent internal network URL. Check that the web service is running at the other end. Check that the credentials given in the routine are correct.
Error	The xCBL3.0 invoice file for the 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	This error occurs if the routine could not upload the generated xCBL3.0 invoice file to the specified web service. 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. To solve this problem check that the computer that the Connector software is installed on has access to the internet or relevent internal network URL. Check that the web service is running at the other end. Check that the credentials given in the routine are correct.
Error	The failed invoice XML file could not be saved to the filesystem	This error occurs if the routine could not save the generated xCBL3.0 invoice file to the directory specified in the routine's settings. This issue is mostly caused by an incorrectly configured directory, or that the Connector software does not have permission to write to the directory. It may also be caused if another file named the same already exists within the directory and contains locks on it.
Error	An invoice has been successfully sent in the xCBL data format however its order file could not be moved into the orders_sent directory. Please move the file manually to avoid the invoice being sent again.	The error occurs when the routine tries to move the original xCBL3.0 order file to the orders_sent subdirectory. This issue could be due to folder permission issues, or existing locks on the file named the same. The order file should be manually moved by a person for the routine is run again, otherwise duplicate invoices make get sent again.
Error	The xCBL3.0 invoice file for the order successfully was sent however the original order file could not be moved. This must be manually done or else duplicate invoices for the order may be sent again the next time the routine runs	The error occurs when the routine tries to move the original xCBL3.0 order file to the orders_sent subdirectory. This issue could be due to folder permission issues, or existing locks on the file named the same. The order file should be manually moved by a person for the routine is run again, otherwise duplicate invoices make get sent again.
Error	Cannot find the ordering account ID in the order file name.	The error occurs when xCBL3.0 order file's name is not formatted correctly and the debtor's account ID cannot be obtained from the file name.
Error	Cannot find the ordering debtor account ID in the order file name. The file name should multiple dashes with the account ID after the first dash.	The error occurs when xCBL3.0 order file's name is not formatted correctly and the debtor's account ID cannot be obtained from the file name.
Error	Invoice file could not be read in correctly.	The error occurs when the routine's xCBL3.0 order file could not be read. This could occur if its contents does not conform to the xCBL3.0 standards. The file most likely has become malformed or corrupt. Manual checking of the file needs to occur.
Error	Cannot read the original xCBL3.0 order file. This is mostly likely due to the contents of it being altered or badly formed	The error occurs when the routine's xCBL3.0 order file could not be read. This could occur if its contents does not conform to the xCBL3.0 standards. The file most likely has become malformed or corrupt. Manual checking of the file needs to occur.
Error	Invoice file could not be opened	The error occurs when the routine's xCBL3.0 order file could not be opened. This could occur if the file is locked by another application, or has been moved from the directory, or contains permissions issues.
Error	Cannot read the original xCBL3.0 order file. This could be due to another application locking or moving the file.	The error occurs when the routine's xCBL3.0 order file could not be opened. This could occur if the file is locked by another application, or has been moved from the directory, or contains permissions issues.
Error	The directory to send out invoices could not be found. Please modify the "xCBL3.0 Invoice Folder Location" setting for the adaptor.	This issue occurs if the routine could not find the directory where the xCBL3.0 order files reside. This is mostly likely due to a configuration issue with the routine's settings, or a directory permission issue.
Error	An error occurred while trying to send out an email notification for the xCBL3.0 Reconcilliation Invoice Export routine.	This issue occurs if the routine could not Email out the report of the routine running. This issue could be due to incorrect Email addresses specified in the routine's settings, or the adaptor's outgoing SMTP server has not been configured correctly, or else the connection to the internet is down, or unavailable.
Info	Invoice(s) have been successfully sent out and received for the purchase order	This message appears If the routine has successfully sent out all invoices associated for an associated order and the order's file was successfully moved.

Document last modified on the 21st October 2019