Edit

Integrate with Farm Activities Data Provider

  • Article

Azure Data Manager for Agriculture supports connectors to conveniently sync your end-users' data from a range of farm machinery data sources. The setup involves Configuring oAuth flow as a pre-requisite for integrating with any Farm Activities data provider, along with a per-account, transparent consent step that handles initial and incremental data sync to keep the ADMA data estate up to date.

Note

Steps 1 to 3 are part of the one-time-per-provider initial configuration. Once integrated, you will be able to enable all your end users to use the existing oAuth workflow and call the config API (Step 4) per user (PartyID) to retrieve the access token.

Provider setup

The example flow here uses Climate FieldView

Step 1: App Creation

If your application isn't already registered with Climate Fieldview, go to FieldView portal and submit the form. Once FieldView processes your request, they send your client_id and client_secret which you'll use once per ADMA instance for FieldView.

Step 2: Provider Configuration

Use the oAuthProvider API to create or update the oAuth provider (Ex: FIELDVIEW) with appropriate credentials of the newly created App.

API documentation: oAuthProviders - Create Or Update

Optional Step: Once the operation is done, you can run the oAuthProviders_Get to verify whether the application is registered. Now, all the parties created in your Azure Data Manager for Agriculture instance can use FieldView as a provider to fetch Farm Activities data.

Step 3: Endpoint Configuration

User redirect endpoint: This endpoint is where you want your users to be redirected to once the oAuth flow is completed. This endpoint will be generated by you and provided to ADMA as userRedirectLink in the oauth/tokens/:connect API. Register the oAuth callback endpoint with your App on Climate FieldView portal.

End-user account setup

Step 4: Party (End-user) Integration

When a party (end-user) lands on your webpage where the user action is expected (Ex: Connect to FieldView button), make a call to oauth/tokens/:connect API in the below fashion to get the oAuth provider's (Ex: Climate FieldView) sign-in uri back to start the end-user oAuth flow.

API documentation: oAuthTokens - Get OAuth Connection Link

Once the oauth/tokens/:connect API successfully returns the oauthAuthorizationLink, end-user clicks on this link to complete the oAuth flow (Ex: For Climate FieldView, the user is served a FieldView access consent and sign-in page). Once the sign-in is completed, ADMA will redirect the user to the endpoint provided by customer (userRedirectLink) with the following query parameters in the url

  1. status (success/failure)
  2. state (optional string to uniquely identify the user at customer end)
  3. message (optional string)
  4. errorCode (optional string sent for Failure/error) in the parameters.

Note

If the API returns 404, then it implies the oAuth flow failed and ADMA could not acquire the access token.

Step 5: Check Access Token Info (Optional)

This step is optional, only to confirm if for a given user or list of users, the required valid access token has been acquired or not. This can be done via making a call to the oauth/tokens API to check for the entry isValid: true in the response body.

API documentation: oAuthTokens - List

This step marks the successful completion of the oAuth flow for a user. Now, the user is all-set to trigger a new FarmOperationsDataJob to start pulling the Farm Activities data from Climate FieldView.