Merge pull request #3361 from MicrosoftDocs/master-jdaly-tag-documentation

content about tags

Author: JimDaly

powerapps-docs/developer/common-data-service/org-service/use-messages.md

@@ -2,13 +2,13 @@
 title: "Use messages with the Organization service (Common Data Service) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Understand how messages are used to invoke operations using the organization service." # 115-145 characters including spaces. This abstract displays in the search result.
 ms.custom: ""
-ms.date: 10/31/2018
+ms.date: 09/08/2020
 ms.reviewer: "pehecke"
 ms.service: powerapps
 ms.topic: "article"
 author: "JimDaly" # GitHub ID
-ms.author: "jdaly" # MSFT alias of Microsoft employees only
-manager: "ryjones" # MSFT alias of manager or PM counterpart
+ms.author: "pehecke" # MSFT alias of Microsoft employees only
+manager: "sunilg" # MSFT alias of manager or PM counterpart
 search.audienceType: 
   - developer
 search.app: 
@@ -100,6 +100,32 @@ req["SuppressDuplicateDetection"] = true;
 CreateResponse response = (CreateResponse)svc.Execute(req);  
 ```  
 
+### Add a Shared Variable from the Organization Service
+
+You can set a string value that will be available to plug-ins within the ExecutionContext in the `SharedVariables` collection. More information: [Shared variables](../understand-the-data-context.md#shared-variables)
+
+```csharp
+var account = new Entity("account");
+account["name"] = "Contoso";
+
+var request = new CreateRequest() { Target = account };
+request["tag"] = "This is a value passed.";
+
+var response = (CreateResponse)svc.Execute(request);
+```
+
+
+Will result in the following value within the `SharedVariables` collection when sent using a webhook.
+
+```json
+{
+"key": "tag",
+"value": "This is a value passed."
+}
+```
+
+This can also be done using the Web API: [Add a Shared Variable from the Web API](../webapi/compose-http-requests-handle-errors.md#add-a-shared-variable-from-the-web-api)
+
 ### See also
 
 [Entity Operations using the Organization service](entity-operations.md)<br />

powerapps-docs/developer/common-data-service/understand-the-data-context.md

@@ -2,13 +2,13 @@
 title: "Understand the execution context (Common Data Service) | Microsoft Docs" 
 description: "Learn about the data that is passed to your plug-ins when it is executed." 
 ms.custom: ""
-ms.date: 06/20/2019
+ms.date: 09/08/2020
 ms.reviewer: pehecke
 ms.service: powerapps
 ms.topic: "article"
 author: JimDaly
-ms.author: jdaly
-manager: ryjones
+ms.author: pehecke
+manager: sunilg
 search.audienceType: 
   - developer
 search.app: 
@@ -127,7 +127,7 @@ The `OutputParameters` are not populated until after the database transaction, s
 
 ## Shared variables
 
-The <xref:Microsoft.Xrm.Sdk.IExecutionContext.SharedVariables> property allows for including data that can be passed from a plug-in to a step that occurs later in the execution pipeline. Because this is a <xref:Microsoft.Xrm.Sdk.ParameterCollection> value, plug-ins can add, read, or modify properties to share data with subsequent steps.
+The <xref:Microsoft.Xrm.Sdk.IExecutionContext.SharedVariables> property allows for including data that can be passed from the API or a plug-in to a step that occurs later in the execution pipeline. Because this is a <xref:Microsoft.Xrm.Sdk.ParameterCollection> value, plug-ins can add, read, or modify properties to share data with subsequent steps.
 
 The following example shows how a `PrimaryContact` value can be passed from a plug-in registered for a **PreOperation** step to a **PostOperation** step.
 
@@ -178,6 +178,19 @@ public class PostOperation : IPlugin
 > [!NOTE]
 > For a plug-in registered for the **PreOperation** or **PostOperation** stages to access the shared variables from a plug-in registered for the  **PreValidation** stage that executes on **Create**, **Update**, **Delete**, or by a <xref:Microsoft.Crm.Sdk.Messages.RetrieveExchangeRateRequest>, you must access the <xref:Microsoft.Xrm.Sdk.IPluginExecutionContext.ParentContext>.**SharedVariables** collection. For all other cases, <xref:Microsoft.Xrm.Sdk.IPluginExecutionContext>.**SharedVariables** contains the collection.
 
+### Passing a Shared Variable from the API
+
+If you need to introduce a shared variable when you call an API, use the keyword `tag` from either the Web API or the Organization service to pass a string value.
+
+This value will be accessible in the Shared Variable collection using the `tag` key. Once set, this value cannot be changed, it is immutable.
+
+For information about how to set this see the following topics:
+
+- [Add a Shared Variable from the Web API](webapi/compose-http-requests-handle-errors.md#add-a-shared-variable-from-the-web-api)
+- [Add a Shared Variable from the Organization Service](org-service/use-messages.md#add-a-shared-variable-from-the-organization-service)
+
+
+
 ## Entity Images
 
 When you register a step for a plug-in that includes an entity as one of the parameters, you have the option to specify that a copy of the entity data be included as *snapshot* or image using the <xref:Microsoft.Xrm.Sdk.IExecutionContext.PreEntityImages> and/or <xref:Microsoft.Xrm.Sdk.IExecutionContext.PostEntityImages> properties.

powerapps-docs/developer/common-data-service/webapi/compose-http-requests-handle-errors.md

@@ -2,7 +2,7 @@
 title: "Compose HTTP requests and handle errors (Common Data Service)| Microsoft Docs"
 description: "Read about the HTTP methods and headers that form a part of HTTP requests that interact with the Web API and how to identify and handle errors returned in the response"
 ms.custom: ""
-ms.date: 08/09/2020
+ms.date: 09/08/2020
 ms.service: powerapps
 ms.suite: ""
 ms.tgt_pltfrm: ""
@@ -12,9 +12,9 @@ applies_to:
 ms.assetid: 64a39182-25de-4d31-951c-852025a75811
 caps.latest.revision: 13
 author: "JimDaly" # GitHub ID
-ms.author: "jdaly"
+ms.author: "pehecke"
 ms.reviewer: "pehecke"
-manager: "annbe"
+manager: "sunilg"
 search.audienceType: 
   - developer
 search.app: 
@@ -261,6 +261,24 @@ This response includes the following annotations:
 If you do not want to receive all annotations in the response, you can specify which specific annotations you want to have returned. Rather than using `Prefer: odata.include-annotations="*"`, you can use the following to receive only formatted values for operations that retrieve data and the helplink if an error occurs:
 `Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink"`.
 
+## Add a Shared Variable from the Web API
+
+You can set a string value that will be available to plug-ins within the ExecutionContext in the `SharedVariables` collection. More information: [Shared variables](../understand-the-data-context.md#shared-variables)
+
+To pass this value using the Web API, simply use the `tag` query option.
+
+For example: `?tag=This is a value passed.`
+
+Will result in the following value within the `SharedVariables` collection when sent using a webhook.
+
+```json
+{
+"key": "tag",
+"value": "This is a value passed."
+}
+```
+This can also be done using the Organization Service: [Add a Shared Variable from the Organization Service](../org-service/use-messages.md#add-a-shared-variable-from-the-organization-service)
+
 ### See also  
 
 [Perform operations using the Web API](perform-operations-web-api.md)<br />