Merge pull request #207555 from yoelhor/patch-298

[Azure AD B2C] Generate JSON collections

Author: PRMerger16

articles/active-directory-b2c/json-transformations.md

@@ -9,7 +9,7 @@ manager: CelesteDG
 ms.service: active-directory
 ms.workload: identity
 ms.topic: reference
-ms.date: 02/16/2022
+ms.date: 08/10/2022
 ms.author: kengaderdus
 ms.subservice: B2C
 ---
@@ -59,6 +59,90 @@ Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/c
 | InputParameter | Any string following dot notation | string | The JsonPath of the JSON where the constant string value will be inserted into. |
 | OutputClaim | outputClaim | string | The generated JSON string. |
 
+### JSON Arrays
+
+To add JSON objects to a JSON array, use the format of **array name** and the **index** in the array. The array is zero based. Start with zero to N, without skipping any number. The items in the array can contain any object. For example, the first item contains two objects, *app* and *appId*. The second item contains a single object, *program*. The third item contains four objects, *color*, *language*, *logo* and *background*.
+
+The following example demonstrates how to configure JSON arrays. The **emails** array uses the `InputClaims` with dynamic values. The **values** array uses the `InputParameters` with static values. 
+
+```xml
+<ClaimsTransformation Id="GenerateJsonPayload" TransformationMethod="GenerateJson">
+  <InputClaims>
+    <InputClaim ClaimTypeReferenceId="mailToName1" TransformationClaimType="emails.0.name" />
+    <InputClaim ClaimTypeReferenceId="mailToAddress1" TransformationClaimType="emails.0.address" />
+    <InputClaim ClaimTypeReferenceId="mailToName2" TransformationClaimType="emails.1.name" />
+    <InputClaim ClaimTypeReferenceId="mailToAddress2" TransformationClaimType="emails.1.address" />
+  </InputClaims>
+  <InputParameters>
+    <InputParameter Id="values.0.app" DataType="string" Value="Mobile app" />
+    <InputParameter Id="values.0.appId" DataType="string" Value="123" />
+    <InputParameter Id="values.1.program" DataType="string" Value="Holidays" />
+    <InputParameter Id="values.2.color" DataType="string" Value="Yellow" />
+    <InputParameter Id="values.2.language" DataType="string" Value="Spanish" />
+    <InputParameter Id="values.2.logo" DataType="string" Value="contoso.png" />
+    <InputParameter Id="values.2.background" DataType="string" Value="White" />
+  </InputParameters>
+  <OutputClaims>
+    <OutputClaim ClaimTypeReferenceId="result" TransformationClaimType="outputClaim" />
+  </OutputClaims>
+</ClaimsTransformation>
+```
+
+The result of this claims transformation:
+
+```json
+{
+  "values": [
+    {
+      "app": "Mobile app",
+      "appId": "123"
+    },
+    {
+      "program": "Holidays"
+    },
+    {
+      "color": "Yellow",
+      "language": "Spanish",
+      "logo": "contoso.png",
+      "background": "White"
+    }
+  ],
+  "emails": [
+    {
+      "name": "Joni",
+      "address": "[email protected]"
+    },
+    {
+      "name": "Emily",
+      "address": "[email protected]"
+    }
+  ]
+}
+```
+
+To specify a JSON array in both the input claims and the input parameters, you must start the array in the `InputClaims` element, zero to N. Then, in the `InputParameters` element continue the index from the last index. 
+
+The following example demonstrates an array that is defined in both the input claims and the input parameters. The first item of the *values* array `values.0` is defined in the input claims. The input parameters continue from index one `values.1` through two index  `values.2`. 
+
+```xml
+<ClaimsTransformation Id="GenerateJsonPayload" TransformationMethod="GenerateJson">
+  <InputClaims>
+    <InputClaim ClaimTypeReferenceId="app" TransformationClaimType="values.0.app" />
+    <InputClaim ClaimTypeReferenceId="appId" TransformationClaimType="values.0.appId"  />
+  </InputClaims>
+  <InputParameters>
+    <InputParameter Id="values.1.program" DataType="string" Value="Holidays" />
+    <InputParameter Id="values.2.color" DataType="string" Value="Yellow" />
+    <InputParameter Id="values.2.language" DataType="string" Value="Spanish" />
+    <InputParameter Id="values.2.logo" DataType="string" Value="contoso.png" />
+    <InputParameter Id="values.2.background" DataType="string" Value="White" />
+  </InputParameters>
+  <OutputClaims>
+    <OutputClaim ClaimTypeReferenceId="result" TransformationClaimType="outputClaim" />
+  </OutputClaims>
+</ClaimsTransformation>
+```
+
 ### Example of GenerateJson
 
 The following example generates a JSON string based on the claim value of "email" and "OTP" and constant strings.