acrolinx quality improvement

Author: gourdsay

articles/data-manager-for-agri/how-to-write-weather-extension.md

@@ -11,7 +11,7 @@ ms.custom: template-how-to
 
 # How to write a weather extension
 
-In this section you'll see a step-by-step guide to write your own weather extension. 
+In this section, you see a step-by-step guide to write your own weather extension. 
 
 ## What is a weather extension
 
@@ -26,7 +26,7 @@ At a high-level the extension file is a JSON consisting of two things:
 
 ### Provider metadata
 
-It's a json object providing the details on the below fields that are necessary to uniquely identify an extension and its versioning information. The details provided in this section of the extension will be shown to external customers in Data Manager for Agriculture marketplace. Therefore `extensionId` & `extensionName` (for easy identification) and `description` (for value-proposition) needs to be customer focused.
+It's a json object providing the details on the below fields that are necessary to uniquely identify an extension and its versioning information. The details provided in this section of the extension are shown to external customers in Data Manager for Agriculture marketplace. Therefore `extensionId` & `extensionName` (for easy identification) and `description` (for value-proposition) needs to be customer focused.
 
 #### Sample provider metadata
 
@@ -47,18 +47,18 @@ It's a json object providing the details on the below fields that are necessary
 
 |Name | Type | Description|
 |:-----:|:----:|----|
-| extensionId | string | The ID provided in the fashion of organization name (ABC) and service (weather) Ex: `org.service`. extensionId is the unique identifier of the extension and the one which users will be using on the Data Manager for Agriculture platform to interact with the extension APIs|
+| extensionId | string | The ID provided in the fashion of organization name (Contoso) and service (weather) Ex: `org.service`. extensionId is the unique identifier of the extension and the one which users are using on the Data Manager for Agriculture platform to interact with the extension APIs|
 | extensionName |  string | Name of the extension as to be used in Data Manager for Agriculture extension marketplace.|
 | description | string | Description stating the capabilities and services offered by the extension.|
-| dataCategory | string | For weather extensions use `weather`.|
-| farmBeatsSchemaVersion | string | The version of the manifest file on the Data Manager for Agriculture side. Any updates to the existing manifest file will lead to a new version update to this field.|
-| extensionVersion | string | The version of extension file. Starting with `1.0`. As there are updates to your extension file increment this version number according to the convention of major & minor updates.|
+| dataCategory | string | For weather extensions, use `weather`.|
+| farmBeatsSchemaVersion | string | The version of the manifest file on the Data Manager for Agriculture side. Any updates to the existing manifest file lead to a new version update to this field.|
+| extensionVersion | string | The version of extension file. Starting with `1.0`. Updates to your extension file increment this version number according to the convention of major & minor updates.|
 | supportUrl | string | Website link to raise support queries & FAQs|
 | supportEmail | string | Email to send in the support queries.|
 
 ### API information
 
-The API Information JSON array (`apiInfos`) can be further broken into the following structural elements
+The API Information JSON array (`apiInfos`) can be further broken into the following structural elements.
 
 * API metadata
 * Authentication parameters
@@ -71,7 +71,7 @@ The API Information JSON array (`apiInfos`) can be further broken into the follo
 
 #### API metadata
 
-This section consists of basic information regarding the API. It's used by Data Manager for Agriculture to identify the `apiName` (called by users explicitly) and redirect the api request to the right `endpoint` based on the appropriate `requestType`.
+This section consists of basic information regarding the API used by Data Manager for Agriculture to identify the `apiName` (called by users explicitly) and redirect the API request to the right `endpoint` based on the appropriate `requestType`.
 
 ##### Sample API metadata
 
@@ -95,20 +95,20 @@ This section consists of basic information regarding the API. It's used by Data
 |Name | Type | Description|
 |:-----:|:----:|----|
 | apiInfos |  array | The JSON array of objects, where each API is an object within `apiInfos` array.|
-| apiName | string | The API Name as supported by the extension, this is the exact name using which the users would be calling into the extension APIs. Kindly follow the same naming convention as mentioned in your API documentation.|
+| apiName | string | The API Name as supported by the extension, it's the exact name using which the users would be calling into the extension APIs. Kindly follow the same naming convention as mentioned in your API documentation.|
 | description |  string | API description|
 | endpoint | string | API endpoint for Data Manager for Agriculture to call into the `apiName`.|
 | requestType | string | `GET` or `POST` or `PUT` request type as supported by the `apiName`.|
-| isLoadAPI | boolean | If the `apiName` is a pass-through API like current weather data, make this key as `false`. For all the load APIs (historical & forecast) keep this field as `true`. When the `isLoadAPI` key is `false`, the API response would be directly sent to the user and wouldn't be stored in the Data Manager for Agriculture storage service.|
+| isLoadAPI | boolean | If the `apiName` is a pass-through API like current weather data, make this key as `false`. For all the load APIs (historical & forecast), keep this field as `true`. When the `isLoadAPI` key is `false`, the API response would be directly sent to the user and wouldn't be stored in the Data Manager for Agriculture storage service.|
 | typeOfData | string | Currently supported values are `Historical` and `Forecast`.|
 | granularity | string | Currently supported values are `Daily` and `Hourly`.|
 | defaultUnitSystem | string | Provide the name of the default units system supported by the `apiName`.|
 
 #### Authentication parameters
 
-This section takes in the authentication related parameters as supported by the `apiName`. As Data Manager for Agriculture supports two types of auth-related keys (`x-ms-farmBeats-data-provider-id` & `x-ms-farmBeats-data-provider-key`) in the api header section, the extension file needs to explicitly provide the key name of its respective authentication keys as required by the `apiName`.
+This section takes in the authentication related parameters as supported by the `apiName`. As Data Manager for Agriculture supports two types of auth-related keys (`x-ms-farmBeats-data-provider-id` & `x-ms-farmBeats-data-provider-key`) in the API header section, the extension file needs to explicitly provide the key name of its respective authentication keys as required by the `apiName`.
 
-As Data Manager for Agriculture collects the authentication information via the api header (in the [Create Weather Job API](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/weather/create-data-delete-job)). Authentication parameter mapping is done to ensure that Data Manager for Agriculture can pass the key accordingly to the extension as required.
+As Data Manager for Agriculture collects the authentication information via the API header (in the [Create Weather Job API](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/weather/create-data-delete-job)). Authentication parameter mapping is done to ensure that Data Manager for Agriculture can pass the key accordingly to the extension as required.
 
 ##### Sample authentication parameters
 
@@ -142,7 +142,7 @@ As Data Manager for Agriculture collects the authentication information via the
 | authInputParameters | array | JSON array of authentication parameters, where each object signifies a type of authentication supported. Use the key based on the authentication type supported by your extension.|
 | farmBeatsAuthMapping |  string | Currently two types of authentication related keys are supported. For API Key based authentication, use only `x-ms-farmBeats-data-provider-key` object, whereas for APP ID and APP Key based authentication use both `x-ms-farmBeats-data-provider-id` &`x-ms-farmBeats-data-provider-key` objects.|
 | name | string | Name of the authentication key as supported by the `apiName`.|
-| isRequired | boolean | Is this name a required parameter to the apiName. Provide true or false values.|
+| isRequired | boolean | Is this name a required parameter to the apiName? Provide true or false values.|
 | providerDataType | string | Provide the datatype of the `name` parameter.|
 | description | string | Data Manager for Agriculture description of what each of the `farmBeatsAuthMapping` means within each object.|
 | location | string | Where in the API should the `name` parameter be sent. Currently supported values are `apiQuery` & `apiHeader`.|
@@ -194,14 +194,14 @@ This section provides the details about the API signature (input parameters) to
 |:-----:|:----:|----|
 | apiInputParameters | array | JSON array of API input parameters, where each object signifies an input parameter supported by the `apiName`.|
 | name |  string | Name of the input parameter as supported by the `apiName`.|
-| isRequired | boolean | Is this name a required parameter to the apiName. Provide true or false values.|
+| isRequired | boolean | Is this name a required parameter to the apiName? Provide true or false values.|
 | providerDataType | string | Provide the datatype of the `name` parameter.|
 | description | string |  Provide a description of what `name` parameter means.|
 | location | string | Where in the API should the `name` parameter be sent. Currently supported values are `apiQuery` & `apiHeader`.|
 
 #### Extracted API input parameters
 
-This section is for dedicated for Data Manager for Agriculture to extract certain set of input parameters passed during the API request for computation and storage purpose. In this example Data Manager for Agriculture would be extracting the location information (latitude and longitude) from the API Input request and store them as part of each weather output in Data Manager for Agriculture.
+This section is for Data Manager to extract input parameters passed in the API request for computation and storage. In this example Data Manager for Agriculture would be extracting the location information (latitude and longitude) from the API Input request and store them as part of each weather output in Data Manager for Agriculture.
 
 Hence the extension needs to provide a [**HandleBars template**](https://handlebarsjs.com/examples/simple-expressions.html) on how to extract location information. The below example suggests that the extension API collects location information as `"lat"` for `"latitude"` and `"lon"` for `"longitude"`.
 
@@ -220,15 +220,15 @@ Hence the extension needs to provide a [**HandleBars template**](https://handleb
 
 |Name | Type | Description|
 |:-----:|:----:|----|
-| extractedApiInputParameters | array | JSON array of extraction functionalities, where each object signifies what information needs to be extracted by Data Manager for Agriculture. Currently `location` is one such extraction.|
-| name |  string | Name of the extraction, currently the supported value will be `location` .|
+| extractedApiInputParameters | array | JSON array of extraction functionalities, where each object signifies what information needs to be extracted. Currently `location` is one such extraction.|
+| name |  string | Name of the extraction, currently the supported value is `location` .|
 | template | string |  HandleBars template depicting how is latitude and longitude information collected in the API input parameters.|
 
 #### Functional parameters
 
-This section is dedicated for the functionalities/capabilities built by Data Manager for Agriculture. In the case of weather extension, centroid calculation is one such functionality.
+This section is dedicated for the functionalities/capabilities built by Data Manager for Agriculture. For weather extension, centroid calculation is one such functionality.
 
-When users don't provide the latitude/longitude coordinates, Data Manager for Agriculture will be using the primary geometry of the field (ID passed by user) to compute the centroid. The computed centroid coordinates will be passed as the latitude and longitude to the extension (data provider). Hence for Data Manager for Agriculture to be able to understand the usage of location coordinates the functional parameters section is used.
+When users don't provide the latitude/longitude coordinates, Data Manager for Agriculture uses the primary geometry of the field (ID passed by user) to compute the centroid. The computed centroid coordinates are passed as the latitude and longitude to the extension (data provider). Hence for Data Manager for Agriculture to be able to understand the usage of location coordinates the functional parameters section is used.
 
 For Data Manager for Agriculture to understand the usage of latitude and longitude in the `apiName` input parameters, the extension is expected to provide the `name` of key used for collecting location information followed by a **handlebar template** to imply how the latitude and longitude values need to be passed.
 
@@ -260,7 +260,7 @@ For Data Manager for Agriculture to understand the usage of latitude and longitu
 |Name | Type | Description|
 |:-----:|:----:|----|
 | functionalParameters | array | JSON array of functionalities, where each object signifies a functionality supported by Data Manager for Agriculture. Currently `CentroidCalculation` is one such functionality.|
-| name |  string | Name of the functionality, currently the supported value will be `CentroidCalculation` .|
+| name |  string | Name of the functionality, currently the supported value is `CentroidCalculation` .|
 | description | string |  Data Manager for Agriculture description of functionality.|
 | functionalParameterEntities | array | JSON array of objects, where each object is specific to the latitude & longitude.|
 
@@ -293,7 +293,7 @@ This section is used by Data Manager for Agriculture to understand the various t
 
 #### Platform & custom parameters
 
-In each weather API response, the weather measures which are sent as part of the output (ex: temperature, dewpoint etc.) are called as parameters.
+In each weather API response, the weather measures, which are sent as part of the output (ex: temperature, dewpoint etc.) are called as parameters.
 
 Hence, when it comes to parameters, Data Manager for Agriculture internally supports the following set of parameters and treats them as `Platform parameters`.
 
@@ -314,9 +314,9 @@ Hence, when it comes to parameters, Data Manager for Agriculture internally supp
 * windGust
 * windSpeed
 
-Therefore, any extension sending weather parameters which do not fall under the platform parameters, will be sending them as part of `Custom parameters`. The key difference between platform & customer parameters is that, the users using Data Manager for Agriculture weather APIs will be able to query and filter on the platform parameters (Ex: temperature > 30) and not on custom parameters. However, custom parameters will be sent as part of the weather query output.
+Therefore, any extension sending weather parameters, which don't fall under the platform parameters, is sending them as part of `Custom parameters`. The key difference between platform & customer parameters is that, the users using Data Manager for Agriculture weather APIs are able to query and filter on the platform parameters (Ex: temperature > 30) and not on custom parameters. However, custom parameters are sent as part of the weather query output.
 
-In this section, the extension provides the units information for each of the parameters for every units system that is supported. This is done to ensure that Data Manager for Agriculture will know what is the underlying measurement unit for each weather parameter based on the information provided in this section of the extension.
+In this section, the extension provides the units information for each of the parameters for every units system that is supported. Using this  Data Manager for Agriculture knows what is the underlying measurement unit for each weather parameter based on the information provided in this section of the extension.
 
 > [!NOTE]
 >
@@ -432,14 +432,14 @@ In this section, the extension provides the units information for each of the pa
 
 #### Platform & custom template
 
-Template is the mapping information provided by the extension to convert the extension API output (JSON response) to the format which Data Manager for Agriculture expects. This is done to ensure that various weather data providers having different API output formats can now be uniformly mapped/converted to one single format.
+Template is the mapping information provided by the extension to convert the extension API output (JSON response) to the format which Data Manager for Agriculture expects. Using this different API output formats can now be uniformly mapped/converted to one single format.
 
 Template solution is found to be one of the most effective ways to parse the JSON output provided by the extension. In the case of weather extension, **Data Manager for Agriculture expects the extension to be written using [HandleBars](https://handlebarsjs.com/guide/#what-is-handlebars) template**. HandleBars is an open source templating language with simple to use expressions.
 
 > [!NOTE]
 > It is highly recommended to try-out the [HandleBars template](https://handlebarsjs.com/examples/simple-expressions.html) with the examples provided and learn how to make use of the helper functions to build your own parsing logic if it is not already provided by Data Manager for Agriculture.
 
-On a high-level this is how templates will work, by taking the API response as the input and generating the output in the format expected by Data Manager for Agriculture.
+On a high-level this is how templates work, by taking the API response as the input and generating the output in the format expected by Data Manager for Agriculture.
 
 >:::image type="content" source="./media/template-flow.png" alt-text="Screen Shot of template flow.":::
 
@@ -606,7 +606,7 @@ As shown in the above figure, validate your template against the respective API
 
 #### Helper functions
 
-Helper functions are used by the templates to perform specific transformation on the data which isn't supported natively. Below are few helper functions that are supported by Data Manager for Agriculture.
+Helper functions are used by the templates to perform specific transformation on the data, which isn't supported natively. Here are helper functions supported by Data Manager for Agriculture.
 
 ##### Sample helper functions
 
@@ -629,7 +629,7 @@ What action these helper functions do?
 * **ConvertDateInFormatToDateTime(object dateObject, string format)** - This function is used to parse a date in given format (Ex: 2016-12-15) to DateTime string.
 * **ConvertUnixTimeToDateTime(object unixTimeStamp)** - This function is used to convert unix timestamp (Ex: 1392267600) to datetime string.
 * **GetObjectFromListWithKeyValuePair(Array listOfObjects, string key, string value)** - Given a list of objects it fetches the object based on key (`type`) value (`RAIN`) pair.
-In the below example, to pick the precipitation of `"type": "RAIN"` this function will be used.
+In the below example, to pick the precipitation of `"type": "RAIN"` this function is used.
 
 ```json
 {