Merge pull request #174762 from ArvindHarinder1/patch-214

v-ccolin · web-flow · commit bcc62258cf1a · 2021-11-02T16:42:47.000Z
Add randomString function
diff --git a/articles/active-directory/app-provisioning/functions-for-customizing-application-data.md b/articles/active-directory/app-provisioning/functions-for-customizing-application-data.md
@@ -15,7 +15,7 @@ ms.reviewer: arvinh
 
 # Reference for writing expressions for attribute mappings in Azure Active Directory
 
-When you configure provisioning to a SaaS application, one of the types of attribute mappings that you can specify is an expression mapping. For these, you must write a script-like expression that allows you to transform your users' data into formats that are more acceptable for the SaaS application.
+When you configure provisioning to a SaaS application, one of the types of attribute mappings that you can specify is an expression mapping. For these mappings, you must write a script-like expression that allows you to transform your users' data into formats that are more acceptable for the SaaS application.
 
 ## Syntax overview
 
@@ -34,7 +34,7 @@ The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic
 
 ## List of Functions
 
-[Append](#append) &nbsp;&nbsp;&nbsp;&nbsp; [AppRoleAssignmentsComplex](#approleassignmentscomplex) &nbsp;&nbsp;&nbsp;&nbsp; [BitAnd](#bitand) &nbsp;&nbsp;&nbsp;&nbsp; [CBool](#cbool) &nbsp;&nbsp;&nbsp;&nbsp; [CDate](#cdate) &nbsp;&nbsp;&nbsp;&nbsp; [Coalesce](#coalesce) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToBase64](#converttobase64) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToUTF8Hex](#converttoutf8hex) &nbsp;&nbsp;&nbsp;&nbsp; [Count](#count) &nbsp;&nbsp;&nbsp;&nbsp; [CStr](#cstr) &nbsp;&nbsp;&nbsp;&nbsp; [DateAdd](#dateadd) &nbsp;&nbsp;&nbsp;&nbsp; [DateDiff](#datediff) &nbsp;&nbsp;&nbsp;&nbsp; [DateFromNum](#datefromnum) &nbsp;[FormatDateTime](#formatdatetime) &nbsp;&nbsp;&nbsp;&nbsp; [Guid](#guid) &nbsp;&nbsp;&nbsp;&nbsp; [IgnoreFlowIfNullOrEmpty](#ignoreflowifnullorempty) &nbsp;&nbsp;&nbsp;&nbsp;[IIF](#iif) &nbsp;&nbsp;&nbsp;&nbsp;[InStr](#instr) &nbsp;&nbsp;&nbsp;&nbsp; [IsNull](#isnull) &nbsp;&nbsp;&nbsp;&nbsp; [IsNullOrEmpty](#isnullorempty) &nbsp;&nbsp;&nbsp;&nbsp; [IsPresent](#ispresent) &nbsp;&nbsp;&nbsp;&nbsp; [IsString](#isstring) &nbsp;&nbsp;&nbsp;&nbsp; [Item](#item) &nbsp;&nbsp;&nbsp;&nbsp; [Join](#join) &nbsp;&nbsp;&nbsp;&nbsp; [Left](#left) &nbsp;&nbsp;&nbsp;&nbsp; [Mid](#mid) &nbsp;&nbsp;&nbsp;&nbsp; [NormalizeDiacritics](#normalizediacritics) &nbsp;&nbsp; &nbsp;&nbsp; [Not](#not) &nbsp;&nbsp;&nbsp;&nbsp; [Now](#now) &nbsp;&nbsp;&nbsp;&nbsp; [NumFromDate](#numfromdate) &nbsp;&nbsp;&nbsp;&nbsp; [PCase](#pcase) &nbsp;&nbsp;&nbsp;&nbsp; [RemoveDuplicates](#removeduplicates) &nbsp;&nbsp;&nbsp;&nbsp; [Replace](#replace) &nbsp;&nbsp;&nbsp;&nbsp; [SelectUniqueValue](#selectuniquevalue)&nbsp;&nbsp;&nbsp;&nbsp; [SingleAppRoleAssignment](#singleapproleassignment)&nbsp;&nbsp;&nbsp;&nbsp; [Split](#split)&nbsp;&nbsp;&nbsp;&nbsp;[StripSpaces](#stripspaces) &nbsp;&nbsp;&nbsp;&nbsp; [Switch](#switch)&nbsp;&nbsp;&nbsp;&nbsp; [ToLower](#tolower)&nbsp;&nbsp;&nbsp;&nbsp; [ToUpper](#toupper)&nbsp;&nbsp;&nbsp;&nbsp; [Word](#word)
+[Append](#append) &nbsp;&nbsp;&nbsp;&nbsp; [AppRoleAssignmentsComplex](#approleassignmentscomplex) &nbsp;&nbsp;&nbsp;&nbsp; [BitAnd](#bitand) &nbsp;&nbsp;&nbsp;&nbsp; [CBool](#cbool) &nbsp;&nbsp;&nbsp;&nbsp; [CDate](#cdate) &nbsp;&nbsp;&nbsp;&nbsp; [Coalesce](#coalesce) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToBase64](#converttobase64) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToUTF8Hex](#converttoutf8hex) &nbsp;&nbsp;&nbsp;&nbsp; [Count](#count) &nbsp;&nbsp;&nbsp;&nbsp; [CStr](#cstr) &nbsp;&nbsp;&nbsp;&nbsp; [DateAdd](#dateadd) &nbsp;&nbsp;&nbsp;&nbsp; [DateDiff](#datediff) &nbsp;&nbsp;&nbsp;&nbsp; [DateFromNum](#datefromnum) &nbsp;[FormatDateTime](#formatdatetime) &nbsp;&nbsp;&nbsp;&nbsp; [Guid](#guid) &nbsp;&nbsp;&nbsp;&nbsp; [IgnoreFlowIfNullOrEmpty](#ignoreflowifnullorempty) &nbsp;&nbsp;&nbsp;&nbsp;[IIF](#iif) &nbsp;&nbsp;&nbsp;&nbsp;[InStr](#instr) &nbsp;&nbsp;&nbsp;&nbsp; [IsNull](#isnull) &nbsp;&nbsp;&nbsp;&nbsp; [IsNullOrEmpty](#isnullorempty) &nbsp;&nbsp;&nbsp;&nbsp; [IsPresent](#ispresent) &nbsp;&nbsp;&nbsp;&nbsp; [IsString](#isstring) &nbsp;&nbsp;&nbsp;&nbsp; [Item](#item) &nbsp;&nbsp;&nbsp;&nbsp; [Join](#join) &nbsp;&nbsp;&nbsp;&nbsp; [Left](#left) &nbsp;&nbsp;&nbsp;&nbsp; [Mid](#mid) &nbsp;&nbsp;&nbsp;&nbsp; [NormalizeDiacritics](#normalizediacritics) &nbsp;&nbsp; &nbsp;&nbsp; [Not](#not) &nbsp;&nbsp;&nbsp;&nbsp; [Now](#now) &nbsp;&nbsp;&nbsp;&nbsp; [NumFromDate](#numfromdate) &nbsp;&nbsp;&nbsp;&nbsp; [PCase](#pcase) &nbsp;&nbsp;&nbsp;&nbsp; [RandomString](#randomstring) &nbsp;&nbsp;&nbsp;&nbsp; [RemoveDuplicates](#removeduplicates) &nbsp;&nbsp;&nbsp;&nbsp; [Replace](#replace) &nbsp;&nbsp;&nbsp;&nbsp; [SelectUniqueValue](#selectuniquevalue)&nbsp;&nbsp;&nbsp;&nbsp; [SingleAppRoleAssignment](#singleapproleassignment)&nbsp;&nbsp;&nbsp;&nbsp; [Split](#split)&nbsp;&nbsp;&nbsp;&nbsp;[StripSpaces](#stripspaces) &nbsp;&nbsp;&nbsp;&nbsp; [Switch](#switch)&nbsp;&nbsp;&nbsp;&nbsp; [ToLower](#tolower)&nbsp;&nbsp;&nbsp;&nbsp; [ToUpper](#toupper)&nbsp;&nbsp;&nbsp;&nbsp; [Word](#word)
 
 ---
 ### Append
@@ -54,7 +54,7 @@ Takes a source string value and appends the suffix to the end of it.
 
 
 #### Append constant suffix to user name
-Example: If you are using a Salesforce Sandbox, you might need to append an additional suffix to all your user names before synchronizing them.
+Example: If you are using a Salesforce Sandbox, you might need to append another suffix to all your user names before synchronizing them.
 
 **Expression:** 
 `Append([userPrincipalName], ".test")`
@@ -96,8 +96,8 @@ In other words, it returns 0 in all cases except when the corresponding bits of
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **value1** |Required |num |Numeric value that should be AND'ed with value2|
-| **value2** |Required |num |Numeric value that should be AND'ed with value1|
+| **value1** |Required |Num |Numeric value that should be AND'ed with value2|
+| **value2** |Required |Num |Numeric value that should be AND'ed with value1|
 
 **Example:**
 `BitAnd(&HF, &HF7)`
@@ -116,7 +116,7 @@ In other words, it returns 0 in all cases except when the corresponding bits of
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required | expression | Any valid expression |
+| **Expression** |Required | expression | Any valid expression |
 
 **Example:**
 `CBool([attribute1] = [attribute2])`                                                                    
@@ -134,7 +134,7 @@ The CDate function returns a UTC DateTime from a string. DateTime is not a nativ
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required | expression | Any valid string that represents a date/time. For supported formats, refer to [.NET custom date and time format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |
+| **Expression** |Required | Expression | Any valid string that represents a date/time. For supported formats, refer to [.NET custom date and time format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |
 
 **Remarks:**  
 The returned string is always in UTC and follows the format **M/d/yyyy h:mm:ss tt**.
@@ -289,22 +289,22 @@ The **interval** string must have one of the following values:
 * **INPUT** (StatusHireDate): 2012-03-16-07:00
 * **OUTPUT**: 3/23/2012 7:00:00 AM
 
-**Example 2: Get a date 10 days prior to hire date**  
+**Example 2: Get a date ten days prior to hire date**  
 `DateAdd("d", -10, CDate([StatusHireDate]))`
 * **INPUT** (StatusHireDate): 2012-03-16-07:00
 * **OUTPUT**: 3/6/2012 7:00:00 AM
 
-**Example 3: Add 2 weeks to hire date**  
+**Example 3: Add two weeks to hire date**  
 `DateAdd("ww", 2, CDate([StatusHireDate]))`
 * **INPUT** (StatusHireDate): 2012-03-16-07:00
 * **OUTPUT**: 3/30/2012 7:00:00 AM
 
-**Example 4: Add 10 months to hire date**  
+**Example 4: Add ten months to hire date**  
 `DateAdd("m", 10, CDate([StatusHireDate]))`
 * **INPUT** (StatusHireDate): 2012-03-16-07:00
 * **OUTPUT**: 1/16/2013 7:00:00 AM
 
-**Example 5: Add 2 years to hire date**  
+**Example 5: Add two years to hire date**  
 `DateAdd("yyyy", 2, CDate([StatusHireDate]))`
 * **INPUT** (StatusHireDate): 2012-03-16-07:00
 * **OUTPUT**: 3/16/2014 7:00:00 AM
@@ -352,7 +352,7 @@ The **interval** string must have one of the following values:
 | Difference in seconds between two dates | s | 2021-08-24 | 2021-08-25 | 86400 | 
 
 **Example 2: Combine DateDiff with IIF function to set attribute value** <br>
-If an account is Active in Workday, set the *accountEnabled* attribute of the user to True only if hire date is within the next 5 days. 
+If an account is Active in Workday, set the *accountEnabled* attribute of the user to True only if hire date is within the next five days. 
 
 ```
 Switch([Active], , 
@@ -438,7 +438,7 @@ The IgnoreFlowIfNullOrEmpty function instructs the provisioning service to ignor
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** | Required | expression | Expression to be evaluated |
+| **Expression** | Required | Expression | Expression to be evaluated |
 
 **Example 1: Don't flow an attribute if it is null** <br>
 `IgnoreFlowIfNullOrEmpty([department])` <br>
@@ -506,7 +506,7 @@ If the expression evaluates to Null, then the IsNull function returns true. For
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required |expression |Expression to be evaluated |
+| **Expression** |Required |Expression |Expression to be evaluated |
 
 **Example:**
 `IsNull([displayName])`
@@ -526,7 +526,7 @@ The inverse of this function is named IsPresent.
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required |expression |Expression to be evaluated |
+| **Expression** |Required |Expression |Expression to be evaluated |
 
 **Example:**
 `IsNullOrEmpty([displayName])`
@@ -545,7 +545,7 @@ If the expression evaluates to a string that is not Null and is not empty, then
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required |expression |Expression to be evaluated |
+| **Expression** |Required |Expression |Expression to be evaluated |
 
 **Example:**
 `Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])`
@@ -562,7 +562,7 @@ If the expression can be evaluated to a string type, then the IsString function
 
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
-| **expression** |Required |expression |Expression to be evaluated |
+| **Expression** |Required |Expression |Expression to be evaluated |
 
 ---
 ### Item
@@ -602,7 +602,7 @@ If one of the source values is a multi-value attribute, then every value in that
 ---
 ### Left
 **Function:** 
-Left(String,NumChars)
+Left(String, NumChars)
 
 **Description:** 
 The Left function returns a specified number of characters from the left of a string. 
@@ -636,8 +636,8 @@ Returns a substring of the source value. A substring is a string that contains o
 | Name | Required/ Repeating | Type | Notes |
 | --- | --- | --- | --- |
 | **source** |Required |String |Usually name of the attribute. |
-| **start** |Required |integer |Index in the **source** string where substring should start. First character in the string will have index of 1, second character will have index 2, and so on. |
-| **length** |Required |integer |Length of the substring. If length ends outside the **source** string, function will return substring from **start** index till end of **source** string. |
+| **start** |Required |Integer |Index in the **source** string where substring should start. First character in the string will have index of 1, second character will have index 2, and so on. |
+| **length** |Required |Integer |Length of the substring. If length ends outside the **source** string, function will return substring from **start** index untill end of **source** string. |
 
 ---
 ### NormalizeDiacritics
@@ -677,7 +677,7 @@ Requires one string argument. Returns the string, but with any diacritical chara
 
 
 #### Remove diacritics from a string
-Example: You need to replace characters containing accent marks with equivalent characters that don't contain accent marks.
+Example: Replace characters containing accent marks with equivalent characters that don't contain accent marks.
 
 **Expression:** 
 NormalizeDiacritics([givenName])
@@ -730,11 +730,11 @@ The NumFromDate function converts a DateTime value to Active Directory format th
 
 **Example:**
 * Workday example 
-  Assuming you want to map the attribute *ContractEndDate* from Workday which is in the format *2020-12-31-08:00* to *accountExpires* field in AD, here is how you can use this function and change the timezone offset to match your locale. 
+  Assuming you want to map the attribute *ContractEndDate* from Workday, which is in the format *2020-12-31-08:00* to *accountExpires* field in AD, here is how you can use this function and change the timezone offset to match your locale. 
   `NumFromDate(Join("", FormatDateTime([ContractEndDate], ,"yyyy-MM-ddzzz", "yyyy-MM-dd"), " 23:59:59-08:00"))`
 
 * SuccessFactors example 
-  Assuming you want to map the attribute *endDate* from SuccessFactors which is in the format *M/d/yyyy hh:mm:ss tt* to *accountExpires* field in AD, here is how you can use this function and change the time zone offset to match your locale.
+  Assuming you want to map the attribute *endDate* from SuccessFactors, which is in the format *M/d/yyyy hh:mm:ss tt* to *accountExpires* field in AD, here is how you can use this function and change the time zone offset to match your locale.
   `NumFromDate(Join("",FormatDateTime([endDate], ,"M/d/yyyy hh:mm:ss tt","yyyy-MM-dd")," 23:59:59-08:00"))`
 
 
@@ -782,6 +782,35 @@ Let's say you are sourcing the attributes *firstName* and *lastName* from SAP Su
 | `PCase(Join(" ",[firstName],[lastName]))` | *firstName* = GREGORY, *lastName* = "JAMES" | "Gregory James" | You can nest the Join function within PCase. As the *wordSeparators* parameter is not specified, the *PCase* function uses the default word separators character set.  |
 
 
+---
+
+### RandomString
+**Function:** 
+RandomString(Length, MinimumNumbers, MinimumSpecialCharacters , MinimumCapital, MinimumLowerCase, CharactersToAvoid)
+
+**Description:** 
+The RandomString function generates a random string based on the conditions specified. Characters allowed can be identified [here](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/password-must-meet-complexity-requirements#reference).
+
+**Parameters:** 
+
+| Name | Required/ Repeating | Type | Notes |
+| --- | --- | --- | --- |
+| **Length** |Required |Number |Total length of the random string. This should be greater than or equal to the sum of MinimumNumbers, MinimumSpecialCharacters, and MinimumCapital. 256 characters max.|
+| **MinimumNumbers** |Required |Number |Minimum numbers in the random string.|
+| **MinimumSpecialCharacters** |Required |Number |Minimum number of special characters.|
+| **MinimumCapital** |Required |Number |Minimum number of capital letters in the random string.|
+| **MinimumLowerCase** |Required |Number |Minimum number of lower case letters in the random string.|
+| **CharactersToAvoid** |Optional |String |Characters to be excluded when generating the random string.|
+
+
+**Example 1:** - Generate a random string without special character restrictions:
+`RandomString(6,3,0,0,3)`
+Generates a random string with 6 characters. The string contains 3 numbers and 3 lower case characters (1a73qt).
+
+**Example 2:** - Generate a random string with special character restrictions:
+`RandomString(10,2,2,2,1,"?,")`
+Generates a random string with 10 characters. The string contains at least 2 numbers, 2 special characters, 2 capital letters, 1 lower case letter and excludes the characters "?" and "," (1@!2BaRg53).
+
 ---
 
 ### RemoveDuplicates
@@ -860,7 +889,7 @@ SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)
 Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. The first unique value found will be the one returned. If all of the values already exist in the target, the entry will get escrowed and the reason gets logged in the audit logs. There is no upper bound to the number of arguments that can be provided.
 
 
- - This is a top-level function, it cannot be nested.
+ - This function must be at the top-level and cannot be nested.
  - This function cannot be applied to attributes that have a matching precedence.     
  - This function is only meant to be used for entry creations. When using it with an attribute, set the **Apply Mapping** property to **Only during object creation**.
  - This function is currently only supported for "Workday to Active Directory User Provisioning" and "SuccessFactors to Active Directory User Provisioning". It cannot be used with other provisioning applications. 
@@ -902,7 +931,7 @@ Example: Based on the user's first name, middle name and last name, you need to
 SingleAppRoleAssignment([appRoleAssignments])
 
 **Description:** 
-Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. Note that the best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable. 
+Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. The best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable. 
 
 **Parameters:** 
 
@@ -969,7 +998,7 @@ When **source** value matches a **key**, returns **value** for that **key**. If
 | **value** |Required |String |Replacement value for the **source** matching the key. |
 
 #### Replace a value based on predefined set of options
-Example: You need to define the time zone of the user based on the state code stored in Azure AD. 
+Example: Define the time zone of the user based on the state code stored in Azure AD. 
 If the state code doesn't match any of the predefined options, use default value of "Australia/Sydney".
 
 **Expression:** 
@@ -1018,7 +1047,7 @@ ToUpper(source, culture)
 **Description:** 
 Takes a *source* string value and converts it to upper case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture.
 
-If you would like to set existing values in the target system to upper case, please [update the schema for your target application](./customize-application-attributes.md#editing-the-list-of-supported-attributes) and set the property caseExact to 'true' for the attribute that you are interested in. 
+If you would like to set existing values in the target system to upper case, [update the schema for your target application](./customize-application-attributes.md#editing-the-list-of-supported-attributes) and set the property caseExact to 'true' for the attribute that you are interested in. 
 
 **Parameters:** 
 
@@ -1062,7 +1091,7 @@ Returns "has".
 This section provides more expression function usage examples. 
 
 ### Strip known domain name
-You need to strip a known domain name from a user's email to obtain a user name. 
+Strip a known domain name from a user's email to obtain a user name. 
 For example, if the domain is "contoso.com", then you could use the following expression:
 
 **Expression:** 
@@ -1075,7 +1104,7 @@ For example, if the domain is "contoso.com", then you could use the following ex
 
 
 ### Generate user alias by concatenating parts of first and last name
-You need to generate a user alias by taking first 3 letters of user's first name and first 5 letters of user's last name.
+Generate a user alias by taking first three letters of user's first name and first five letters of user's last name.
 
 **Expression:** 
 `Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))`
