Introduction
Most errors can be identified by performing basic troubleshooting. Basic troubleshooting involves checking the endpoint status and the message feed for errors or warnings.
if you need further help to troubleshoot errors with your integration, please send an e-mail to support@oneio.cloud.
Overview
In this article, we will show you how to perform basic troubleshooting by identifying the main issue through the following steps:
- Check your endpoint status
- Check the message feed
- Inbound messages
- Routing messages
- Outbound messages
- More troubleshooting options
Check your endpoint status
The home view provides a list of your endpoints and their status. If the endpoint related to the current issue is active and has a status different from Operational, it should be investigated. It's also a quick way to determine when your endpoint has an inbound or outbound queue.
Inbound queues are mostly caused in cases where we receive a large number of messages at once. It can happen in the following scenarios:
- In test environments when a large number of messages are created by mistake when the instance returns from a maintenance window and starts to send a lot of messages at once
- When your endpoint is suspended but the instance still sends messages to this endpoint.
- It can also happen when a poller endpoint type returns many messages at once.
If you have an inbound queue caused by a large number of messages received at once, in most cases the queue will subside with time.
Note
Suspended endpoints keep receiving inbound messages. Suspending an endpoint only stops sending outbound messages. If the suspended endpoint is a poller endpoint type, it will keep polling results unless the endpoint status and the entity status are set to 'suspended'.
Outbound queues are mostly caused by a message 'stuck' in a recoverable error retry state (see more about recoverable errors here), or when we encounter problems/slowness sending messages to the destination instance. We send the messages to the destination instance as fast as we can, and as soon as we receive a response, we start to send the following message. If your instance is processing the messages slowly, it could lead to an outbound queue.
See more about ONEiO's UI Home view here
Check the message feed
Most errors can be identified by checking the message feed. In the message feed you have access to all successfully received incoming messages - pushed to us or pulled from ONEiO, matched rules, and all outbound messages (successfully sent or not). The message feed is the main tool for troubleshooting messages handled by ONEiO.
When troubleshooting, there are three basic situations you should check by looking at the message feed:
- Was the message received by ONEiO (Inbound messages)?
- Was the message processed (Routing messages)?
- Was the message sent to the integrated instance (Outbound messages)?
Inbound messages
Was the message received by ONEiO?
If we successfully received the message and the message is not dropped by an inbound message filter (whitelist), you should see the message in the message feed.
Info
You can view the inbound message payload, and inbound lookups - message enrichment, non-inline attachments - by clicking on the message and clicking on 'see details' in the inbound column.
Message feed containing the inbound message attributes
The inbound message details show:
- Access to inbound data and all inbound additional calls (additional requests such as downloaded attachments, lookups, etc)
- Date / Time of which ONEiO received the inbound message
- Click to show in box 4: the inbound message payload, the raw inbound message payload,, the received headers, and the response provided by ONEiO
Message details containing the message's unprocessed payload and additional requests
The response provided by ONEiO to your instance containing the transaction ID.
If you send a message to ONEiO and the message is not present in the message feed, the first action is to check if the message was successfully sent to ONEiO.
REST / SOAP endpoints:
We always send a synchronous message back: If the message is successfully received and has no errors, we respond back with a transaction id. If the message is invalid, or the authentication is not successful, we respond back with an error message.
If your message doesn't reach ONEiO, we always advise checking your instance for errors sent by ONEiO as a synchronous response: in most cases, it will contain the error reason.
There are several common reasons why a message may not reach ONEiO:
| Issue | Troubleshoot |
|---|---|
| Authentication/connection issues |
|
| Message issues |
|
| Endpoint issues |
|
Poller endpoint type
Polling endpoints work differently from REST endpoints, as in this case, we will make a request to your instance instead of receiving a request from your instance. Pollers are currently not available as self-service endpoints. Our integration engineers work together with you to ensure the polling endpoint is working. Once the poller is set, it is rare to find problems, but they can occur.
Here are some reasons for your poller to stop receiving messages:
| Issue | Troubleshoot |
|---|---|
| Authentication issues |
|
| Query /message issues |
|
| Endpoint issues |
|
It is also important to verify the status of your poller. Note that polling should be enabled or suspended by entity, and enabling both system and entity pollers can result in an error. To avoid issues, it is recommended to keep the main poller status as suspended, and only enable or disable pollers on the entity level, as shown in the example below:
General Info - Polling status must be suspended
Entity types (entity) - Enable or disable your entity poller here.
Routing messages
Was the message processed?
If the inbound message matches a routing rule, it will be routed. If the message does not match a routing rule, the message will not be routed further.
1 - message matches a rule and is routed to the integrated instance. 2 - The message does not match a rule and is not routed to the integrated instance
Below you can find reasons for a message not being routed further or common message route errors:
| Issue | Troubleshoot |
|---|---|
| The message doesn't match a configured entity |
The message entity could be blank or it contains an entity different from the one mapped on existing routing rules. |
| The message does not match the routing rule attribute conditions |
|
| The message does not match the routing rule operation |
|
| The message should have an attachment |
|
If the message is routed by a routing rule but doesn't reach the outbound column:
| Issue | Troubleshoot |
|---|---|
| The message is routed, it doesn't reach the outbound column but there are no errors |
Check if the rule's action is not 'process only' or 'drop the message' |
| The message is routed and seems to be delayed |
|
Outbound messages
Was the message sent to the integrated instance?
If the message was routed successfully, you should see the message in the outbound column.
A green tooltip means that the message was successfully sent to your instance. If the message was successfully sent by ONEiO and it didn't reach your endpoint, verify your security layers and check if anything is blocking the message.
A message not sent successfully by ONEiO will show a tooltip other than green. The tooltip will show you the reason the message wasn't sent. Check the table below for a basic tooltip meaning:
| Issue | Troubleshoot |
|---|---|
| Blue tooltip (message delayed) |
This means the message sending is delayed and this message is in the outbound queue. Usually, this happens when there is a slowness in sending messages to your instance, meaning your instance is processing the messages slowly.
|
| Yellow tooltip (recoverable error) |
A recoverable error means we are retrying to send a message due to an error. As this error is not in the unrecoverable error list, we will retry it indefinitely until receiving a successful response.
|
| Red tooltip (failed) |
This means we failed to send the message to your instance, due to a failure before or after sending the message. All failed messages status contains the status added to your endpoint's unrecoverable error list, meaning we will not retry sending the message. Failing before sending usually are related to an invalid outbound JSON. Check the outbound values, in special if you are using JSON_FRAGMENT attributes.
Failing after sending means we received an error from your instance when we delivered the message.
|
| Black tooltip (manually canceled) | The message was manually canceled. You still can check the message details and access the outbound message payload, and if that is the case - outbound message retries. |
When the message sending fails (failed after sending), you can check the tooltip and the message response for errors.
In most cases, your instance will return details about what is happening and you will be able to fix the error. Basic errors are related to:
| Issue | Troubleshoot |
|---|---|
| Mandatory fields |
Check if the outbound payload contains all mandatory fields your instance requires for the method used. A create method would require at least a title and description, and an update method requires the id. Your instance's documentation should provide you with more detail about each method and required fields. |
| Authentication |
Review your instance's ONEiO user and password.
Does your instance require any specific value to be sent in the message header? Check the message headers tabs and verify if the value is correct. |
| Correct methods/id |
Check the message details for the used method (create, update, put, patch) and what it requires. If an update fails, does the method URI contain the entity ID? |
| Check if the CREATE message was successful |
Check the message conversation for errors. Usually, when a create message fails, all subsequent messages related to the source id also fail, as there is no message id (target id) for the following updates. |
| Permissions |
|
Info
You can view the outbound message payload by clicking on the message and clicking on 'see details' in the outbound column.
Message feed containing the outbound message attributes
The outbound message details show:
- All additional outbound requests, including lookups, attachment uploads, and recoverable error retries. If there is an error, you can see all retries. For example, if you encounter an HTTP error 401, it may not be configured as an unrecoverable error, and you can view all the retries. By clicking on each retry, you can view the retry date/time, payload, and error.
- Date / Time of which ONEiO sent the outbound message or the requested retry was performed
- URI the request was sent, method, and received HTTP status
- Click to show in box 5: the formatted message payload, the raw message, sent headers, or the Response received from the instance after sending the message.
- box containing the option selected above.
Example: After attempting to send a message, you should receive a response from the instance. In this case, the response indicates that the credentials are invalid.
Note
Some systems reply with a successful HTTP status even if there are errors. In most cases, the response tab will bring you the error detail.
Test basic methods with an external tool
Testing the requests externally is a good option, especially if it is a new integration and if you are performing tests in QA environment. Most of the providers have request/response examples by using CURL or Postman, and they are good tools for checking the basics:
- Authentication
- Get
- Post
- Put/Patch.
Testing with an external tool is also useful to troubleshoot polling issues. Check if the poller query configured in your ONEiO endpoint returns the same data as the external request, and if it returns all required fields (i.e. last modified date, id)
Comments
Please sign in to leave a comment.