Frequently Asked Questions
How often does the API data transfer between the cloud and farm take place?
The API runs on Nedap cloud servers. You can connect with the API from your own software. Our API is hosted on what we call the Nedap Business Insight software. The data on our cloud servers is filled by a synchronization process between Nedap Business Insight and the farm software. The synchronization is initiated by the farm software.
The synchronization process runs at user-defined time intervals. See Get farmer’s permission for more information. Typically, the time interval is set to 10 minutes.
It can be important for your software to know when the last synchronization between Nedap Business Insight and the farm has occurred. There is an API call that can be used to obtain this information. Refer to API call GET /v1/installations for details. The response contains information about the last synchronization.
Keep in mind that the data read out from the API is not always current. It will only represent the information from the last synchronization with the software at the farm.
If you use the API to write information, it will be stored instantly in our cloud servers, but it will only arrive at the farm after the next synchronization. Be aware of this and use API call GET /v1/installations to learn the synchronisation status between our cloud and the farm.
Can synchronization conflicts occur?
This question is only relevant for software writing to the Nedap APIs.
Problems may arise when objects are created in multiple places at the same time. For instance, when an animal is created in the API and also at the farm software at the same time before synchronization. When synchronization starts, the objects will collide. In this example, Nedap Business Insight can usually solve the problem by merging the two objects. However, problems that can’t be solved automatically may occur.
Make sure that the users do understand that one particular bit of data must only be entered in one software system at a time (either in the Nedap farm software, or in your software which then writes it to the API, but NOT in the two software systems at the same time). Entering the same data in the two software systems at the same time can result in conflicts that the Nedap Business Insight software cannot solve. In general, the synchronisation process will have a lower risk of a conflict if data is only entered in one system, instead of two.
It is not a problem if some data is entered in the two systems as long as it is not the same data. In that case, it can never result in a conflict. An example is to create some animals in one system, and some different animals in the other system. As long as they are not being created with the same animal number, tag number, or life number in both systems, this is not a problem.
It is advisable to communicate proactively with end-users about this. When your software starts using the Nedap API in production, this is the moment when farmers must start taking this into account.
How does conflict management during the synchronization process work?
If, during the synchronization proces, Nedap Business Insight discovers that there is a synchronization conflict, it will first try to resolve it. This can be done when the two objects contain equal values.
If the two objects do not contain the same value, however, for example when two animal calendar events were created with different values, the Nedap Business Insight software cannot determine which of the two values is correct.
If this happens, the synchronization process stops and an error is generated.
How do I know when a synchronization conflict occurred?
The synchronization conflict is visible for Nedap Support, Nedap Business Partners, and for you as a party connecting to our API as well. You may detect the synchronization error through the API call GET /v1/installations : the response attribute sync_status will contain a value of 2.
What should I do whether a synchronization error occurred?
When a synchronization conflict occurs, the error can be solved by letting one of the two objects overrule the other one. This action can only be performed by Nedap Support. To contact Nedap Support, use the contact details that are shared with you when you initially contacted Nedap to connect to the API.
For the farmer, in general, their first point of contact when anything is wrong with a Nedap product is the Nedap Business Partner. They are always involved or in the lead of installing Nedap products and provide support. In a case of a synchronization conflict in the API however, there will not be much that they can do other than observe that the problem occurred, and manually inform the farmer, Nedap, or you as a Nedap API partner.
Do synchronization conflicts occur often?
No. We know from experience that conflicts can only occur in a rare situation: when the same data is entered in two software systems (Nedap’s farm software and our API) at the same time before synchronization has completed. The next paragraph contains guidelines to reduce the chance of running into synchronization conflicts.
Our experience is that by following these guidelines, synchronization conflicts will be fully eliminated.
How can I reduce the chances of a synchronization conflict?
- The farmer enters their data in your organization’s software and in Nedap’s farm software.
As explained in the previous two paragraph, this is the main cause of synchronization conflict. You can help reduce this problem by providing the farmer with a work instruction to enter their data into only one system. If the farmer implements this work instruction, the chances of a synchronization conflict are zero. We typically see that when software starts using Nedap’s API in production for the first time, this point is quite critical. The moment that the API is being used is when the farmer should stop inserting data in two systems. Once the farmer is used to this new way of working and if they only enter data in one system, synchronisation conflicts don’t occur anymore.
- The farm you write information to has a frequently unstable internet connection.
If the internet connection is unstable, this increases the time between two synchronizations, which increases the time window for a user to enter conflicting data into two systems. You can help reduce this problem by communicating the importance of a stable farm internet connection to the farmer.
- The software created by your organization communicates its information to the Nedap API in batches.
While this scenario is supported, it increases the time window for a synchronization conflict to occur. The chances for a synchronization conflict are made smaller by your organization’s software not sending the data in batches. Instead, your software should send the data to the API as soon as it becomes possible to do so.
Do all API calls always show the latest data?
As explained before, if the data synchronization is delayed, for instance due to an instable internet connection at the farm, the GET API calls will not show the latest data. In case of an unstable internet connection, keep in mind that the data collected since the synchronization process may be not up-to-date.
The data that you send to the farm, is stored in our cloud servers instantly. However, it only arrives at the farm once the next synchronization completes.
You can use API call API call GET /v1/installations to find out when the last synchronization between Nedap Business Insight and the Nedap farm software took place.
In addition, there are some GET API calls that aggregate over multiple other data. For example, some API calls will return a day total. The information below will help you understand how to interpret these API calls.
- The totals are created shortly after midnight in the farms’ local timezone. You can see the timezone in which a farm is located through API call GET /v1/installations . There is no exact moment when this is completed as farms generate different amounts of data. You can be quite certain that this proces has completed at 3 am in the morning of the farm’s local timezone.
- It is possible that there has not yet been a synchronization after the end of a day. For example, the last synchronization of a farm could be at 1 pm on the previous day.
If this is the case, the totals for the previous day are still calculated and are presented in the API. If additional data for that day comes in later, the results are updated. From then on, the API will also present the new data. Use API call GET /v1/installations to find out when the last synchronization took place between Nedap Business Insight and the Nedap farm software.
- If you discover that the last synchronization was a while ago, it is your choice whether you want to still present results from the API call in your software. Alternatively, you may also decide to not yet present the results of the API call in your software. You could for example show a guiding text to users that explains that once their farm restores their internet connection, the results will become available in your software. In both cases, be sure to perform the API call again at a later point in time once the latest data has become avaialble.
Can I connect to multiple farms with the API?
Yes. The authorization process guide explains how to obtain access to one farm.
You can perform this authorization process multiple times for different farms. Always use your software’s application credentials every time you walk through the process (i.e. always use the same application credentials). At the end of step 4, you receive a token which refers to the specific farm that was authorized in step 2.
So: if you wish to support your software connecting to multiple farms, you must initiate the authorization process for each farm. Each authorization process results in one token. Your software must store every token. Every token refers to one farm: if you pass it as an argument in an API call, it will return data for that farm.
The Authentication & Refresh tokens guide explains how refresh tokens work. Please note that the token and refresh token form one pair of tokens that are both specific to one farm.
Does Nedap have a test environment for the APIs?
We have a test environment that can be used to test the authorization process. We also have a test environment that can be used to test API calls. The most realistic data however, will only be obtained from production data.
More information about the test environment is be provided when you request access to our APIs.
Does the API return information that has previously been deleted?
Some API calls do, and some API calls don’t. Please refer to the API documentation . If an API call supports returning deleted information, it is displayed in the API call description.