Merge pull request #248414 from lbpudi/main

FarmOps CDMV2 changes

Author: v-ccolin

articles/data-manager-for-agri/concepts-farm-operations-data.md

@@ -0,0 +1,27 @@
+---
+title: Working with Farm Activities data in Azure Data Manager for Agriculture
+description: Learn how to integrate with Farm Activities data providers and ingest data into ADMA 
+author: lbpudi
+ms.author: lbethapudi
+ms.service: data-manager-for-agri
+ms.topic: conceptual
+ms.date: 08/14/2023
+ms.custom: template-concept
+---
+# Working with Farm Activities data in Azure Data Manager for Agriculture
+Farm Activities data is one of the most important ground truth datasets in precision agriculture. It's these machine-generated reports that preserve the record of what exactly happened where and when that is used to both improve in-field practice and the downstream values chain analytics cases
+
+The Data Manager for Agriculture supports both
+* summary data - entered as properties in the operation data item directly
+* precision data - (for example, a .shp, .dat, .isoxml) uploaded as an attachment file and reference linked to the operation data item. 
+
+New operation data can be pushed into the service via the APIs for operation and attachment creation. Or, if the desired source is in the supported list of OEM connectors, data can be synced automatically from providers like Climate FieldView with a farm operation ingestion job.
+[!INCLUDE [public-preview-notice.md](includes/public-preview-notice.md)]
+* Azure Data Manager for Agriculture supports a range of Farm Activities data that can be found [here](/rest/api/data-manager-for-agri/#farm-activities)
+
+## Integration with farm equipment manufacturers
+Azure Data Manager for Agriculture fetches the associated Farm Activities data (planting, application, tillage & harvest) from the data provider (Ex: Climate FieldView) by creating a Farm Activities data ingestion job. Look [here](./how-to-ingest-and-egress-farm-operations-data.md) for more details.
+
+## Next steps
+
+* Test our APIs [here](/rest/api/data-manager-for-agri).

articles/data-manager-for-agri/concepts-hierarchy-model.md

@@ -15,7 +15,8 @@ ms.custom: template-concept
 
 To generate actionable insights data related to growers, farms, and fields should be organized in a well defined manner. Firms operating in the agriculture industry often perform longitudinal studies and need high quality data to generate insights. Data Manager for Agriculture  organizes agronomic data in the below manner.
 
-:::image type="content" source="./media/data-model.png" alt-text="Screenshot showing farm hierarchy model.":::
+:::image type="content" source="./media/data-model-v-2.png" alt-text="Screenshot showing farm hierarchy model.":::
+:::image type="content" source="./media/management-zones.png" alt-text="Screenshot showing management zones.":::
 
 ## Understanding farm hierarchy
 
@@ -28,25 +29,19 @@ To generate actionable insights data related to growers, farms, and fields shoul
 * Farms don't have any geometry associated with them. Farm entity helps you organize your growing operations. For example Contoso Inc is the Party that has farms in Oregon and Idaho.
 
 ### Field
-* Fields denote a stable boundary that is in general agnostic to seasons and other temporal constructs. For example, field could be the boundary denoted in government records.
+* Fields denote a stable geometry that is in general agnostic to seasons and other temporal constructs. For example, field could be the geometry denoted in government records.
 * Fields are multi-polygon. For example, a road might divide the farm in two or more parts.
-* Fields are multi-boundary.
 
 ### Seasonal field
 * This is the most important construct in the farming world. A seasonal fields definition includes the following things
-     * Boundary
+     * geometry
      * Season 
      * Crop
 * A seasonal field is associated with a field or a farm
 * In Data Manager for Agriculture, seasonal fields are mono crop entities. In cases where farmers are cultivating different crops simultaneously, they have to create one seasonal field per crop.
 * A seasonal field is associated with one season. If a farmer cultivates across multiple seasons, they have to create one seasonal field per season.
 * It's multi-polygon. Same crop can be planted in different areas within the farm.
 
-
-### Boundary
-* Boundary represents the geometry of a field or a seasonal field.
-* It's represented as a multi-polygon GeoJSON consisting of vertices (lat/long).
-
 ### Season
 * Season represents the temporal aspect of farming. It is a function of local agronomic practices, procedures and weather.
 

articles/data-manager-for-agri/concepts-ingest-satellite-imagery.md

@@ -17,7 +17,7 @@ Satellite imagery makes up a foundational pillar of agriculture data. To support
 *	Read the Sinergise Sentinel Hub terms of service and privacy policy: https://www.sentinel-hub.com/tos/
 *	Have your providerClientId and providerClientSecret ready
 
-## Ingesting boundary-clipped imagery
+## Ingesting geometry-clipped imagery
 Using satellite data in Data Manager for Agriculture involves following steps: 
 
 :::image type="content" source="./media/satellite-flow.png" alt-text="Diagram showing satellite data ingestion flow.":::

articles/data-manager-for-agri/concepts-ingest-sensor-data.md

@@ -38,7 +38,7 @@ In addition to the above approach, IOT devices (sensors/nodes/gateway) can direc
 
 ## Sensor topology
 
-The following diagram depicts the topology of a sensor in Azure Data Manager for Agriculture. Each boundary under a party has a set of devices placed within it. A device can be either be a node or a gateway and each device has a set of sensors associated with it. Sensors send the recordings via gateway to the cloud. Sensors are tagged with GPS coordinates helping in creating a geospatial time series for all measured data.
+The following diagram depicts the topology of a sensor in Azure Data Manager for Agriculture. Each geometry under a party has a set of devices placed within it. A device can be either be a node or a gateway and each device has a set of sensors associated with it. Sensors send the recordings via gateway to the cloud. Sensors are tagged with GPS coordinates helping in creating a geospatial time series for all measured data.
 
 :::image type="content" source="./media/sensor-topology-new.png" alt-text="Screenshot showing sensor topology.":::
 

articles/data-manager-for-agri/concepts-isv-solutions.md

@@ -33,7 +33,7 @@ The solution framework is built on top of Data Manager for Agriculture that prov
 
  Following are some of the examples of use cases on how an ISV partner could use the solution framework to build an industry specific solution.
 
-* Yield Prediction Model: An ISV partner can build a yield model using historical data for a specific boundary and track periodic progress. The ISV can then enable forecast of estimated yield for the upcoming season.
+* Yield Prediction Model: An ISV partner can build a yield model using historical data for a specific geometry and track periodic progress. The ISV can then enable forecast of estimated yield for the upcoming season.
 * Carbon Emission Model: An ISV partner can estimate the amount of carbon emitted from the field based upon the imagery, sensors data for a particular farm.
 * Crop Identification: Use imagery data to identify crop growing in an area of interest.
 

articles/data-manager-for-agri/how-to-ingest-and-egress-farm-operations-data.md

@@ -0,0 +1,82 @@
+---
+title: Working with Farm Activities and in-field activity data in Azure Data Manager for Agriculture
+description: Learn how to manage Farm Activities data with manual and auto sync data ingestion jobs
+author: lbpudi
+ms.author: lbethapudi
+ms.service: data-manager-for-agri
+ms.topic: how-to
+ms.date: 08/14/2023
+ms.custom: template-how-to
+---
+# Working with Farm Activities and activity data in Azure Data Manager for Agriculture
+
+Users can create a farm operation data ingestion job to **pull associated Farm Activities activity data** from a specified data provider into your Azure Data Manager for Agriculture instance, associated with a specific party. The job handles any required auth refresh, and by default detects and syncs any changes daily. In some cases, the job will also **pull farm and field** information associated with the given account into the party. 
+
+> [!NOTE]
+>
+>Before creating Farm Activities job, it is mandatory to successfully [**integrate with Farm Activities data provider oAuth flow**](./how-to-integrate-with-farm-ops-data-provider.md)
+>
+
+## Create FarmOperations Job
+
+Create a farm-operations job to ingest Farm Activity data with an ID of your choice. This job ID is used to monitor the status of the job using GET Farm Operations job.
+
+API documentation:[FarmOperations_CreateDataIngestionJob](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/farm-operations/create-data-ingestion-job)
+
+> [!NOTE] 
+>`shapeType` and `shapeResolution` are provider specific attributes. If they aren't applicable to your provider, set the value to "None". 
+
+Based on the `startYear` and `operations` list provided, Azure Data Manager for Agriculture fetches the data from the start year to the current date.
+
+Along with specific data (geometry), Farm Activities data provider also gives us the DAT file for the activity performed on your farm or field. The DAT file, Shape File etc. contain a geometry that reflects where the activity was performed.
+
+Job status and details can be retrieved with: [FarmOperations_GetDataIngestionJobDetails](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/farm-operations/get-data-ingestion-job-details)
+
+
+## Finding and retrieving Farm Activities data
+
+Now that the data is ingested into Azure Data Manager for Agriculture, it can be queried or listed with the following methods:
+
+### Method 1: List data by type
+
+Retrieved data is sorted by type under the party. These can be listed, with standard filters applied
+
+[PlantingData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/planting-data/search)
+
+[HarvestData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/harvest-data/search)
+
+[ApplicationData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/application-data/search)
+
+Individual data items may be retrieved to view the properties and metadata, including the `sourceActivityId`, `providerFieldId` and `Geometry`.
+
+
+[PlantingData_Get](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/planting-data/get)
+
+[HarvestData_Get](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/harvest-data/get)
+
+[ApplicationData_Get](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/application-data/get)
+  
+
+### Method 2: search Farm Activities data using geometry intersect
+To account for the high degree of change found in field definitions, Azure Data Manager for Agriculture supports a search by intersect feature that allows you to organize data by space and time, without needing to first know the farm/field hierarchy or association.
+
+
+
+[PlantingData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/planting-data/search)
+
+
+[HarvestData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/harvest-data/search)
+
+[ApplicationData_Search](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/application-data/search)
+
+You can also use the ID like `plantingId` to fetch the above data in the same API. if you remove the ID, you're able to see any other data that intersects with the same geometry across party. So it shows data for the same geometry across different parties.
+
+## List and Download Attachments
+
+The message attribute in the response of `FarmOperations_GetDataIngestionJobDetails` API shows how much data was processed and how many attachments were created. To check the attachments associated to the partyId, go to attachment API. The response gives you all the attachments created under the partyId.
+
+API documentation: [Attachments](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/attachments)
+
+## Next steps
+
+* Understand our APIs [here](/rest/api/data-manager-for-agri).

articles/data-manager-for-agri/how-to-integrate-with-farm-ops-data-provider.md

@@ -0,0 +1,63 @@
+---
+title: How to integrate with Farm Activities data provider
+description: Learn how to integrate with Farm Activities data provider
+author: lbpudi
+ms.author: lbethapudi
+ms.service: data-manager-for-agri
+ms.topic: how-to
+ms.date: 08/14/2023
+ms.custom: template-how-to
+---
+
+# Integrate with Farm Activities Data Provider
+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](https://dev.fieldview.com/join-us/) 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](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/o-auth-providers/create-or-update)
+
+
+**Optional Step:** Once the operation is done, you can run the [oAuthProviders_Get](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/o-auth-providers/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](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/o-auth-tokens/get-o-auth-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](/rest/api/data-manager-for-agri/dataplane-version2023-07-01-preview/o-auth-tokens/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](./how-to-ingest-and-egress-farm-operations-data.md) to start pulling the Farm Activities data from Climate FieldView.