add documatation for new query_response_input_key_map enhancement

Author: sullivtr

docs/resources/mutation.md

@@ -28,7 +28,7 @@ resource "graphql_mutation" "basic_mutation" {
 ```
 
 ## Argument Reference
-* `mutation_variables` - (Required) A map of any variables that will be used in your create & update mutation. Each variable's value is interpreted as JSON when possible.
+* `mutation_variables` - (Required) A map of any variables that will be used in your create & update mutation. Each variable's value is interpreted as JSON when possible. In order for the provider to keep track of state with respect to inputs provided in `mutation_variables`, you should ensure that your `read_query` includes the property that holds the value for your mutation variable. The keys do not need to be the same, as the provider with automatically map the keys based on value. See `query_response_input_key_map` description for details on how this works. 
   >NOTE: If a mutation variable is a number that must be interpreted as a string, it should be wrapped in quotations. For example `"marVar" = "\"123\""`.
 
 * `read_query_variables` - (Optional) A map of any variables that will be used in the read query for the resource's lifecycle. Each variable's value is interpreted as JSON when possible.
@@ -55,6 +55,24 @@ resource "graphql_mutation" "basic_mutation" {
 * `query_response` - A computed json encoded http response object received from the query.
     - To use properties from this response, leverage Terraform's built in [jsondecode](https://www.terraform.io/docs/configuration/functions/jsondecode.html) function.
 
+* `query_response_input_key_map` - A computed map between the values represented by mutation_variable inputs and query response object keys. The purpose of this comnputed map is for the provider to keep track of drift between a resource's server-state and its state representation in terraform. Its value is calculated by creating a map of key-value pairs such that the key is the key for a particular input of the `mutation_variables`, and the value is the key that represents the corresponding value in the `query_response`. For example, consider we have a query response with the following structure: 
+  ```javascript
+  "data": {
+    "id": "123456"
+    "user": {
+      "id": "654321"
+    } 
+  }
+  ```
+
+  Consider there is a mutation variable input of `userID = "654321"`. The computed `query_response_input_key_map` would be: 
+  ```javascript
+  {
+    "userID": "data.user.id"
+  }
+  ```
+  Internally, the provider uses this map to check the state of given input properties against their value returned from server state via `query_response` during a read lifecycle. 
+
 * `computed_update_operation_variables` - A computed map that combines any computed variables with the `mutation_variables` input based on what is provided in the `compute_mutation_keys` input. This is also useful for outputing properties of the response object and using it on other resources.
 
 * `computed_delete_operation_variables` - A computed map that combines any computed variables with the `delete_mutation_variables` input based on what is provided in the `compute_mutation_keys` input.

docsite/docs/resource_graphql_mutation.md

@@ -38,7 +38,7 @@ resource "graphql_mutation" "basic_mutation" {
 ### mutation_variables
   - **Required**: true
   - **Type**: map(string)
-  - **Description**: A map of any variables that will be used in your create & update mutation. Each variable's value is interpreted as JSON when possible.
+  - **Description**: A map of any variables that will be used in your create & update mutation. Each variable's value is interpreted as JSON when possible. In order for the provider to keep track of state with respect to inputs provided in `mutation_variables`, you should ensure that your `read_query` includes the property that holds the value for your mutation variable. The keys do not need to be the same, as the provider with automatically map the keys based on value. See `query_response_input_key_map` description for details on how this works. 
   >NOTE: If a mutation variable is a number that must be interpreted as a string, it should be wrapped in quotations. For example `"marVar" = "\"123\""`. Any variables that are not actually used in mutations will be ignored. 
 
 ### read_query_variables
@@ -96,6 +96,26 @@ resource "graphql_mutation" "basic_mutation" {
   - **Type**: string (json encoded http response)
   - **Desciption**: A computed json encoded http response object received from the query.
     - To use properties from this response, leverage Terraform's built in [jsondecode](https://www.terraform.io/docs/configuration/functions/jsondecode.html) function.
+    - 
+### query_response_input_key_map
+  - **Type**: map(string)
+  - **Desciption**: A computed map between the values represented by mutation_variable inputs and query response object keys. The purpose of this comnputed map is for the provider to keep track of drift between a resource's server-state and its state representation in terraform. Its value is calculated by creating a map of key-value pairs such that the key is the key for a particular input of the `mutation_variables`, and the value is the key that represents the corresponding value in the `query_response`. For example, consider we have a query response with the following structure: 
+  ```javascript
+  "data": {
+    "id": "123456"
+    "user": {
+      "id": "654321"
+    } 
+  }
+  ```
+
+  Consider there is a mutation variable input of `userID = "654321"`. The computed `query_response_input_key_map` would be: 
+  ```javascript
+  {
+    "userID": "data.user.id"
+  }
+  ```
+  Internally, the provider uses this map to check the state of given input properties against their value returned from server state via `query_response` during a read lifecycle. 
 
 ### computed_update_operation_variables
   - **Type**: map(string)