Getting started
This page is part of the Developer Documentation and is aimed at quickly getting a taste of JoinData’s platform capabilities. If you want to get more details, please see the other parts of the Developer Documentation as listed in Developer Documentation.
We’ll focus on getting a farmer’s consent for retrieving his data, and then actually retrieve that data. We will go through the entire process manually but you should note that all these steps can be fully automated as well and that there are multiple ways of integrating you software with our platform. This is simply to give you an overview of JoinData. Also note that we’ll be working on the integration environment. On production, most of the steps are similar, but you may not have access to all roles (e.g. the role of the farmer). You’ll find pointers to other parts of the documentation if you want to know more on a specific topic or are interested in automating that part.
Checklist
To get started, you should have received a couple of accounts from your JoinData representative:
account type | description |
---|---|
personal account | To be able to log in as an employee of your company. Note that it is connected to your company’s chamber of commerce number. |
farmer account | To be able to log in as one of your customers. By default, this farmer’s account uses the same chamber of commerce number as your own company. |
client account | To be used by your software to call our api’s. Note that it is connected to your company’s chamber of commerce number. |
If you have all of these, you are good to go!
Introducing ‘FarmFluent’
In this example we assume that you are building an awesome app called ‘FarmFluent’.This app will help the farmer to run his farm’s operations, saving him time. But, to do that, you’ll need data from the farm to be able to advice the farmer. And to get his data, you will need his consent. Our guided tour starts with creating a purpose, a description of what data you need for your project and what you are going to do with it. This is the contract the farmer needs to agree to before you can access his data.
Creating a Purpose
So the first step is to define a purpose. This can be thought of as a description of your project. In our example that is the ‘FarmFluent’ app.
- Log in to: https://integration.join-data.net/my-join-data-partners
This is our partner portal where data sources and application providers can interact with JoinData. Use your personal account to login, as you are creating a purpose on behalf of your company. You should be presented with a screen similar to this: - Click on ‘Purposes‘ or navigate to https://integration.join-data.net/my-join-data-partners/purposesIf this is a brand new account, there are no purposes yet. In this case, a single ’test’ purpose has already been created.
We are going to create one for our app ‘FarmFluent’. You can of course give this application your own brilliant (made-up) name. - Click on the button ‘new purpose‘. You will be presented with a form that you need to fill out.
You need to put in the title of your project and a description. Describe to the farmer what your app is going to do. Note that this has a legal meaning: this is the purpose binding that you have to comply with. Make sure that your description is accurate and clear to the farmer.
Select a few data sets that your app requires to function. In this case, we selected the data sets Housing and Identifiers, and from the Yield data set we specifically requested the Dairy data only. Also pick a category for this purpose, broadly indicating what your purpose is about. In this case, advising the farmer.
You can also set all kinds of restrictions and other fields, but we’ll leave them empty for now. See Using the Purpose Registry for more information on those. - Press ‘save‘ to store your purpose.
It now appears in the list. As you can see, it is ‘pending approval’ by JoinData.We will check if your description is clear and sometimes give feedback on how to improve it. On the integration environment, you can approve your purpose yourself.When it is approved, it will look like this: - The next step is to invite the farmer to approve this project. Press the ‘new participation‘ button to add a participant. You will be presented with the following form:
Fill out the chamber of commerce number for the farmer you want to invite. In most countries the farmer is identified with a chamber of commerce number, but a different scheme could be in use in your country. With your test credentials you have received a farmer test account. By default it is linked to the same chamber of commerce number as your company. So, you can simply enter your own chamber of commerce number here and invite yourself.
Optionally, you can specify specific sources that you want access to but right now we are interested in any data source that is available. Press the ‘create participation‘ button to complete it. - Now, navigate to ‘Participations‘ in the main menu (or click on https://integration.join-data.net/my-join-data-partners/participations):
You can see your project ‘FarmFluent’ here and which companies (farmers) have been invited. Note that the farmer has not yet accepted it since the participation is still on ‘pending’ state.
Accepting the participation
The next step is for the farmer to approve your project. There are a couple of ways to get his consent, but for now we will use the simplest way: have the farmer navigate to the JoinData website.
For the next steps, we are going to assume the role of the farmer. You should have received a farmer account for this. By default, the farmer’s account is linked to the same company as your application so it will feel a bit like inviting yourself to your own party. Just keep in mind that we are now playing the role of the farmer which in a normal situation would be a different company.
In the previous step we have created a participation for the farmer. You can now inform the farmer (e.g. via e-mail) that there is a pending participation and that he should go to the JoinData website.
- Go to https://integration.join-data.net/my-join-data/ and log in with the farmer credentials.
The farmer will be presented with a home screen where his latest messages are visible. Right now, there are no messages for this farmer, but as you can see in the menu bar, there are a few participations that require attention. - Click on ‘Participations‘ and navigate to the ‘unapproved participations‘ tab.
The purpose for FarmFluent is visible here since this farmer was invited to use this app in the previous step. - Click on ‘details‘ to see what this app is requesting.
The details should look familiar; this is the purpose that you filled out in the role of application developer. Since you are now in the role of a farmer, you can choose to share the farm’s data with this app, by clicking on ‘grant participation’. Of course, the participation can be refused as well, but for this tour we’ll accept the participation. - The FarmFluent app is now able to access the farm’s data (within the limitations of the defined purpose). The farmer can find it back under ‘approved participations’:
Retrieve data
We should now be able to retrieve data from the farm, since the farmer has approved our purpose. This is the most technical part that we will be looking at in our tour. Typically, a developer will integrate this in your application using API calls. For this tour, we’ll do it manually, just to see that everything works. So, we’re going to play the role of the application and thus use the client account.
- Navigate to our API documentation for the integration environment: https://integration.join-data.net/api/docs#broker-api
This contains most of the documentation for experienced API developers, but it also contains a convenient way to try out the JoinData broker API’s. And those are the API’s that can deliver data to our application. - First we have to authenticate ourselves as being an application of your company. We do that using the client accountas has been provided. Press the ‘Authorize’ button on the top right.
You will then be presented with this dialog:
We will authenticate ourselves using the ‘Client Credentials’ flow in this tour, so fill out your ‘client_id’ and the ‘client_secret’ as you have received them. Then, press ‘Authorize’. - If you filled out the client details correctly, you will get the following screen:
This means that the website has successfully retrieved a token. It will temporarily store it for you so you can use it in the next step. You can press ‘Close’ to close the dialog. - Now, we should be able to try and retrieve a herd list for this farm since that is part of the Housing data set that we have requested. Scroll down to the blue ‘GET /locations/{location-scheme}/{location-id}/herd-list’ resource and click on it:
Fill out the farm details. In this case, we’ll query a location called UBN 1234561 but if you have a farm location for your company you should use that. Set the ‘location-scheme’ to ‘nl-ubn’ and the ‘location-id’ to e.g. ‘1234561’. Then, press ‘execute’. - If you scroll down a bit, you should see the result of your query. If you used a location that belongs to the farm that you used, you should be able to get some data.
In this case, we get a 400 message back, indicating that the location is unknown:
If you waited too long, you may get a 403 message that states that your token has expired. You should then ‘Authorize’ again by logging out and logging in again: - You can also try out the Company Mapping service. This should always have data available to try out. Click on ‘Company Mapping’ in the menu, press ‘Authorize’ and fill out the credentials again. Then navigate to ‘GET /company-mapping’:
Fill out your test farm’s identification (’target-scheme’ = ‘nl-v1’ and ’target-value’ = ‘your chamber of commerce number‘)and press ‘execute’. - If everything went ok, you should be able to scroll down and see a ‘200’ response body (the ‘200’ means that everything went fine). The black box contains the data for your query, in this case the company mappings that we know for this farm.
- Now, feel free to try out other resources. Other resources may or may not be available, depending on what data sets you have requested in your purpose. Currently, not all data sources have data available on the integration environment, so even if you have access to a data source, you may get an empty response or a message that that location or farm doesn’t exist. On the integration environment, at least the following resources always give you (fake, synthesized) data:
- herdlist
- herdlist-core-data
- herdlist-movements
- weights
- milk intakes
- water intakes
A better way of asking consent
So now you have seen the most basic way of how JoinData works. But we can do better!
For example, in this flow we had to send the farmer an e-mail or inform him in some other way that there is a new participation waiting for him. It would be much nicer to have the farmer give consent when he is actually showing interest in your application. E.g., when he is installing his app or when he is subscribing on your website for your service. We have a special library for that as well, called the onboarding client.
So let’s see how that would look like.
Assume that we have a new version of FarmFluent. An improved version, but it requires a bit more data to be even more awesome. Of course, the farmer has to give consent for that new data to be used, so we have to create a new purpose for version 2.
- Log in with your personal account again on https://integration.join-data.net/my-join-data-partners
- Find your purpose under ‘purposes’ and click on it to open the details:
Note that there is a line with the ‘purpose identifier’. This is a unique id representing your purpose. When you are integrating with JoinData, your developers may require that id to be able to identify the purpose they are working with. We will be using it here as well for a couple of things so copy that number. - Close the dialog and create a ‘new purpose’:
Again, we write out a title and a description and now we also add the new ‘Feed’ data set as well since that is what our new version requires.
We are going to fill out two new fields as well: ‘Your reference’ is where we can store our own application version. This way we can track which purpose belongs to which application version, and use that to see which farmers have upgraded to the new conditions. We also fill out ‘Replaces purpose id’ and put there the purpose identifier we talked about in the previous step. This tells the JoinData system that the purpose we are creating now is a newer version of the existing purpose. When a farmer agrees with this new version, the old version is automatically revoked so that the administration is kept clean. - Press ‘save’, find your new purpose and click on it to see the details. Again, copy the purpose identifier since we will need it. Notify your JoinData representative to get your purpose approved.
- Now, go to our example onboarding app, located on: https://integration.join-data.net/onboarding-example/.This is not the prettiest app around, but it gets the job done. This app represents your app or website, and you can test the onboarding flow with it in an easy way. So imagine that this is your application. You see a couple of fields and buttons that would not be visible in your app, but for now are conveniently exposed so that we can play around with them.
Note that if you are still logged in, you should first press the ‘logout’ button to get a better representation of what would happen. - Remember that you copied the purpose id? Put that in the Purpose field. As mentioned, this would normally be hidden from the end user (and hopefully your layout is a bit prettier than this example app). If you are on a desktop, check the ‘desktop mode’, or if you want a mobile friendly version, leave it unchecked.
- So remember that this is representing an app the farmer has just installed. He or she should now be able to press ‘login’:
The farmer is now presented with a login screen (if he/she wasn’t logged in yet) and can immediately give consent for your application. After giving (or refusing) consent, the farmer is redirected back to your application. - When the farmer returns, a few things have happened. First of all, the farmer was identified and authenticated, and you now know exactly who that farmer is. Secondly, the onboarding client has created a participation for that farmer and (hopefully) the farmer has given consent for that participation. And finally, the onboarding client has given a token back to your app that can be immediately used to retrieve data.
Next steps
This concluded our short tour of the JoinData platform. Hopefully it has given you a good idea on what the platform is capable of. There are many levels on which you can integrate; as you have seen you can do most things by hand, or you can fully integrate everything in your own website. There is even a middle ground allowing you to simply embed specific pages of My JoinData in your own website, something which we haven’t touched upon in this tour. You can read more on https://www.join-data.nl/developers/.