Troubleshooting checklist

Use this checklist to systematically review the most common root causes of synchronization issues. Work through these steps to resolve the problem before you contact the Tinx Support Team. If you’re an advanced Tinx user, continue with the Advanced troubleshooting guide for more complex methods. If you have a specific error message, start with Error messages to find the cause and solution.

Follow the checklist in order, starting with the most common root causes.

Step 1: Check the job queue status

The job queues control all communication between Business Central and your webshop. Synchronization is impossible if the job queues aren’t running. Check the job queues first.

To check the outbound and inbound job queue status

1. Select Search (Alt+Q) in the upper-right corner, enter Job Queue Entries, and select the related link.

2. On the Job Queue Entries page, find Tinx NAS Outbound Mgt. and Tinx NAS Inbound Mgt., and check their Status fields. Each job should show a status of Ready or In Process.

   • If the status is On Hold, choose the Set Status to Ready action for both Tinx NAS Outbound Mgt. and Tinx NAS Inbound Mgt. Wait for one minute to see whether the synchronization works.
   • If the status is Error, choose the Restart action and wait for one minute to see whether the synchronization works. If the error was temporary, restarting the job queue resolves the issue. If the error returns, review the job queue log entries to identify the underlying problem and resolve it before restarting again. For more information, see Step 4: Check the job queue log entries.

Step 2: Check the webshop order fault reasons

The most common issue Tinx Connector users encounter is webshop orders failing to convert into sales orders. If that’s your case, check the error message on the Webshop Orders page. If you have issues with data other than webshop orders, proceed to Step 3: Check the synchronisation ledger entries.

To identify the fault reason

Each webshop order that fails to convert into a sales order in Business Central contains a fault reason. Follow these steps to check the error message.

1. Select Search (Alt+Q) in the upper-right corner, enter Webshop Orders, and then choose the related link.

2. On the Webshop Orders page, check the Process Message part of the FactBox to see the error message.

   

3. Resolve the fault reason. Here are the most common ones. Select the error message to see the details about the cause and solution.

   After resolving the issue, return to the Webshop Orders page, select the order that failed to process, and clear the Failed to Import checkbox. Tinx Connector automatically retries processing the failed webshop order during the next job queue run, typically within one minute.

   Error message	Solution
   Blocked must be equal to ‘No’ in Item: No.={item_number}. Current value is ‘Yes’.	Unblock the item.
   You cannot create this type of document when Customer ({customer_number}) is blocked	Unblock the customer.
   The field Sell-to Customer No. of table Sales Header contains a value ({customer_number}) that cannot be found in the related table (Customer)	Update customer matching or modify the mapping in the message definition.
   The field Shipping Agent Service Code of table Sales Header contains a value ({value})	Add the shipping agent service code in Business Central and map it to the corresponding code in the webshop.
   The supplied field number ‘{field_number}’ cannot be found in the ‘{table_name}’ table.	Delete the field from the message definition mapping or restore the field in Business Central.

Step 3: Check the synchronisation ledger entries

On the Synchronisation Ledger Entries page, you can see whether each synchronization was successful and, if not, any data issues that led to an error. For more information, see Synchronisation ledger entries.

To review the synchronisation ledger entries

1. Select Search (Alt+Q) in the upper-right corner, enter Synchronisation Ledger Entries, and then choose the related link.

2. On the Synchronisation Ledger Entries page, check the entries with a status other than Processed.

   • Rejected: The request sent by Tinx Connector was rejected by the webshop.
   • Failed: The request sent by Tinx Connector was accepted by the webshop, but there was an issue with saving the data in Business Central. For example, you might publish a product to the webshop and the request is accepted. However, if the webshop’s product ID is not written back to Business Central, the entry is marked as Failed.
   • New: The mapping conflicts with the response. Tinx Connector tried to locate a specific element in the web response but could not find it. This typically occurs when the message definition mapping has been modified or when there is a mismatch between the expected data format and the actual response from the webshop.

3. To check the details of an entry, use one of the following:

   • Review the message in the Additional Information FactBox.
   • Select the View action, and then choose Web Request or Web Response.

   For more information, see View & Download Functions.

To find the entries related to a specific failed webshop order

1. Select Search (Alt+Q) in the upper-right corner, enter Webshop Orders, and then choose the related link.

2. On the Webshop Orders page, find the order that failed to import, and copy the value in the Entity ID field.

3. Select Search (Alt+Q) in the upper-right corner, enter Synchronisation Ledger Entries, and then choose the related link.

4. Select Filter (Shift+F3) at the top of the list, to open the filter pane.

5. In the filter pane, select Filter, then Webservice, and then enter orders/ followed by the Entity ID value you copied before, such as orders/12345.

   With the filters applied, the Synchronisation Ledger Entries page shows only the entries related to your failed webshop orders. The Document No. field shows the message definition specific to each entry.

6. Select the failed or rejected entry, choose the Entry action, and choose the Message Definition action to see its details. If the error was caused by mapping, you can fix it on the Message Definition page.

   

7. On the Message Definition page, select the appropriate line on the Lines FastTab.

8. Select Fields to open the Message Line Field page.

9. Review and update the mappings as needed.

Step 4: Check the job queue log entries

Job queue log entries can help you identify two types of problems:

• Communication issues between Business Central and your webshop.
• Business rules that prevented processing.

For example, if a customer is blocked in Business Central and you try to create an order for that customer, an error is logged in the job queue log entries. For more information, see Job queues.

To review the job queue log entries

1. Select Search (Alt+Q) in the upper-right corner, enter Job Queue Log Entries, and then choose the related link.

2. On the Job Queue Log Entries page, check the entries with the status Error.

3. To see the details of the error message on the Error Message page, select the Show Error Message action. For some errors, Tinx Connector provides the recommended actions on the Error Messages page.

   

4. Resolve the error. Here are the most common ones. Select the error message to see the details about the cause and solution.

   Error message	Solution
   The data does not represent a valid JSON token.	Review the web response to identify the cause.
   The value “{value}” cannot be evaluated into type Integer	Review the web response and correct the field mapping in the message definition.
   The activity was deadlocked with another user who was modifying…	Reschedule conflicting processes in Business Central.

Step 5: Check the Record Queue

The Record Queue page displays changes that are waiting to be processed. If a large number of changes are synchronized at once, they might still be in the queue. In this case, there is no error. Wait for the queue to finish processing. For more information, see Record queue.

Records can also remain in the Record Queue due to temporary connectivity issues between Business Central and your webshop. If the connection is interrupted during a synchronization run, the records stay in the queue and are processed when the connection is restored.

To check the record queue

1. Select Search (Alt+Q) in the upper-right corner, enter Record Queue, and then choose the related link.
2. On the Record Queue page, check for records waiting to be processed. If many records are waiting, let the queue finish processing. Then check whether synchronization works.

You can change the priority of your message definition to ensure it is processed first. For more information, see Synchronisation Dashboards.

Step 6: Check the filters

Filters on a message definition can prevent specific data from being synchronized. For example, orders with a status of canceled might be excluded if the filter requires the status to be processing or pending. Verify the filters to understand which messages are being excluded.

To check the filters on the message definition

This example shows filters applied to the message definition related to creating sales orders in Business Central. Similar steps can be applied to all other message definitions.

1. Select Search (Alt+Q) in the upper-right corner, enter Synchronisation Dashboard List, and then choose the related link.
2. On the Synchronisation Dashboard List page, select and open the dashboard related to the task you need to verify, such as WOO-IN-ORDERS for importing orders from the WooCommerce webshop.
3. On the selected synchronisation dashboard page, choose the appropriate message definition, and then choose the Filters action.
4. On the Inbound Line Filter page, review the filters applied to the message.

The following image shows an example of filters applied to the message definition used to process incoming WooCommerce orders. By reviewing the filters, you can see that only orders with statuses processing or pending are accepted. When you try to import webshop orders with a different status, the filter blocks them. This can look like a synchronization problem, but your synchronization is working fine.

Checking the filters helps you understand whether the Tinx Connector setup is intentionally excluding certain data. If the filters are configured as expected, they are not the cause of the issue. The data is excluded intentionally.

In some cases, you can use the Ignore Filter option as a temporary workaround to bypass the filter that blocks synchronization. Use this option carefully, because it might cause unintended data synchronization.

For more information, see Filter criteria and operators.

Next steps

If your problem is still not resolved after completing this checklist:

• Review the Error messages to find the cause and solution for your error.
• Go to Advanced troubleshooting, if you don’t have the specific error message, and you are an experienced Tinx Connector user who is comfortable with more complex methods.
• Contact the Tinx Support Team for further assistance.

Related information

Job queues
Synchronization ledger entries
Record queue
Error messages
Advanced troubleshooting
Key concepts in Tinx Connector