Handling Errors

What Happens to the File if an Error Occurs?

If Zyllem finds an error in a file, it rejects the file, converts it into CSV or TXT, and moves it to the errors folder. It is important to note that once a file is rejected, all orders within that file will be rejected. You can read more about this process in How it Works.

🚧

Keep in mind...

When an error is found in a file, Zyllem will reject the entire file. This means that all orders within that file will be rejected.

Email notification for errors

To proactively manage errors, we recommend that you set up an email to automatically notify you of errors in your booking—that is every time an error file is dumped into the errors folder. You can attach the error file into the email. This way, you can fix errors in real time.

📘

Email notification setup

The email notification is optional and must be configured by your enterprise. Contact your administrator for assistance.

Fixing the Error

The easiest way to find out which part of your data caused the error is by manually uploading your booking file via the Bulk Order wizard. The wizard takes you through an interactive UI that highlights the error and allows you to fix it on the spot.

What you need:
(1) The booking file
(2) Access to your enterprise web portal

1. Download the booking file

To download the booking file, log in to your enterprise web portal and go to /Settings/SFTP then click on your client name. Look for RECENT ACTIVITY and click on the relevant filename (rejected files will have a "Completed with Errors" status).

:bulb: Click Show Logs to know the cause of the error (sample screenshot here).

Downloading the original fileDownloading the original file

Downloading the original file

*Alternatively, you may download the CSV converted error file. To do so, go to the errors folder of your SFTP account. If you have set up an email notification for errors, you can also download it from the email attachment. After which, edit the file before proceeding with Step 2. *

:bulb: Which file should I use -- the original or CSV error file?

2. Upload the file via Bulk Order

Log in to your enterprise web portal and click Bulk Order on the left menu panel. The wizard takes you through for steps:

4 steps in Bulk Order wizard4 steps in Bulk Order wizard

4 steps in Bulk Order wizard

Step 1. Upload File

Browse to your file and click Upload. NOTE: If you choose to upload the original file, make sure to select the right translator.

Select your translator and upload your fileSelect your translator and upload your file

Select your translator and upload your file

Step 2. Validate Entries

In this step, Zyllem validates the contact details.

Errors pertaining to addresses and phone numbers are displayed in this stage. All errors will be moved to the top row. Click Fix to update the contact details (click X to delete the row).

Once you have cleared all errors, click Next on the upper right side of the screen.

Click Fix to update the contact detailsClick Fix to update the contact details

Click Fix to update the contact details

Step 3. Validate Routes

During this stage, Zyllem validates the routes based on your process (Bridge) configuration.

An error in this stage is often caused by a configuration issue. If clicking Fix results in another warning (see example below), contact your enterprise administrator. In most cases, a change in configuration is required. Click Discard and re-upload the file once the configuration is fixed.

If there are no errors, click Next.

Click Fix to select the route or contact your enterprise administratorClick Fix to select the route or contact your enterprise administrator

Click Fix to select the route or contact your enterprise administrator

Step 4. Confirm Order

If you have reached this stage, your file is good to go! Review the order summary and click Confirm Order.

Review the order summary and confirm the orderReview the order summary and confirm the order

Review the order summary and confirm the order

👍

Order Confirmed

Once the order is confirmed, the system will direct you to the Items page where you will see your newly booked orders.

Common Errors

Below are common errors that you may encounter when booking. Also see: Examples of error files

Error Message

Fix

Message: Invalid content, the content must follow the 'translator' format.
Error File: TXT file

Cause of Error: Wrong file type or format
Fix: Upload the right file type or format

Message: '###ERROR###' marker on the relevant cell
Error File: CSV file
SFTP Log: Completed with errors: Some records could not be validated (invalid contact details)

Cause of Error: Missing name or phone number
Fix: Update and reupload file or use Bulk Order.

Message: '###ERROR###' marker on the relevant cell
Error File: CSV file
SFTP Log: Completed with errors: Some records could not be validated (invalid contact details)

Cause of Error: Missing or invalid address
Fix: Update and reupload file or use Bulk Order.

Message: none
Error File: CSV file

Cause of Error: No route found
Fix: This is usually a configuration issue. Contact your enterprise administrator.

Message: No records in file.
Error File: TXT file

Cause of Error: The booking file is empty or the file format is invalid
Fix: Upload a file that contains records with the right format.

Message: '###ERROR###' marker on the relevant cell' marker on the relevant cell
Error File: CSV file
SFTP Log: Duplicate External ID

Cause of Error: One or more external IDs already exists.
Fix: Ensure that all external IDs are unique across your enterprise (including past bookings). Update and reupload file or use Bulk Order.

📘

Contact Policy

Errors that are related to contact details (e.g., missing or invalid phone or address) are dependent on your Contact Policy settings, which allows you to define the level of validation you want Zyllem to perform. For example, you can allow the name and phone number to be optional. To configure this setting, go to /Settings/Enterprise/Contact Policy or contact your administrator.

Tips

1. When editing the CSV error file

🚧

Use a CSV editor to avoid discrepancies

Certain applications such as Microsoft Excel may cause changes or discrepancies in your file (for this reason, we recommend using the original booking file). To avoid this, edit your file using a CSV editor (or similar/text editors) that preserves the data formats in your file.

To fix the errors, look for the error marker and update the value of that field. The default error marker is '###ERROR###' and can be changed through the SFTP Settings

Here's an example of this file. Once you have updated this file, you can upload it via Bulk Order.

Example of a CSV error file with error markersExample of a CSV error file with error markers

Example of a CSV error file with error markers

2. When handling errors, which file should I use? (Original vs CSV error file)

In most cases, the original file works best for two reasons. Firstly, since you don't need to edit the file before uploading it, you will not have any file format issues (as opposed to the CSV error file), except if the whole file itself is corrupted or incompatible. Another advantage of this method is that it allows you to fix errors on the spot through an interactive UI. For example, if you need to fix an address, the UI includes a Google Maps interface integrated into the wizard (here's a sample snapshot). However, since the wizard allows you to fix errors individually, this method is ideal if the errors are minimal.

The CSV error file, on the other hand, may be a better option if your file contains numerous errors that can be fixed more quickly by editing the file before uploading it. Fixing an address in this file may also require additional steps outside of your CSV editor. (See Editing the CSV error file).

Here's a comparison table to help you decide:

Original File

CSV Error File

Available for

All types of errors

Selected errors

Best for

Minimal errors

Numerous errors
(e.g., more than 10)

Steps

1.Download file
2.Upload via Bulk Order
3.Fix errors individually

1.Download file
2.Edit and fix all errors
3.Upload via Bulk Order

Download from

Web portal

errors folder or email attachment

3. Fixing addresses in the CSV file

When fixing an address in the CSV file, it's good practice to validate the address via Google Maps first. This lessens (if not eliminates) any chances of address errors in your updated file.

Google Maps: example of a valid addressGoogle Maps: example of a valid address

Google Maps: example of a valid address

Google Maps: Example of an invalid addressGoogle Maps: Example of an invalid address

Google Maps: Example of an invalid address

📘

Why Google?

Zyllem uses Google Places API to validate all addresses in your order. This is applies to all types of integration with Zyllem.

4. Fixing addresses via Bulk Order wizard

When fixing an address via Bulk Order, observe the Google Map section just below the 'Save' button.

If you enter a valid address, the map will be auto-populated (and in most cases, the Postal Code too). If the map stays blank or grey, check the address and try again.

Bulk Order wizard: Example of a valid addressBulk Order wizard: Example of a valid address

Bulk Order wizard: Example of a valid address

Bulk Order wizard: Example of an invalid addressBulk Order wizard: Example of an invalid address

Bulk Order wizard: Example of an invalid address

5. Is Bulk Order wizard the only way to fix errors?

If you are using an application such as an order management system that is integrated to your SFTP account, you can also fix the errors by updating the relevant fields in your system and then 're-pushing' the files to the designated SFTP folder.

6. Examples of error files

All rejected files are converted into 'error files' in CSV or TXT format, with the original filename. For example, MyBookingFile.xml will be converted to MyBookingFile.csv or .txt.

CSV error files contain the error marker on the relevant cells (except for errors that are caused by 'no route found'). You can change the error marker through the SFTP Settings.

Snapshot of a CSV error file with the error markerSnapshot of a CSV error file with the error marker

Snapshot of a CSV error file with the error marker

TXT error files contain the cause of error and the details about the original file.

Snapshot of a TXT error fileSnapshot of a TXT error file

Snapshot of a TXT error file