Escritura de expresiones para asignaciones de atributos en el identificador de Microsoft Entra

Al configurar la sincronización en la nube, uno de los tipos de asignaciones de atributos que puede especificar es una asignación de expresiones.

La asignación de expresiones permite personalizar atributos mediante una expresión similar a un script. Esto le permite transformar los datos locales en un valor nuevo o diferente. Por ejemplo, puede que desee combinar dos atributos en un solo atributo porque una de las aplicaciones en la nube usa este atributo único.

En el siguiente documento se tratarán las expresiones de tipo script que se usan para transformar los datos. Esto solo forma parte del proceso. A continuación, deberá usar esta expresión y colocarla en una solicitud web al inquilino. Para obtener más información sobre eso, consulte Transformaciones.

Introducción a la sintaxis

La sintaxis de Expresiones para asignaciones de atributos recuerda a las funciones de Visual Basic para Aplicaciones (VBA).

• Toda la expresión debe definirse en términos de funciones, que constan de un nombre seguido de argumentos entre paréntesis:
  FunctionName(<<argument 1>>,<<argument N>>)

• Puede anidar funciones entre sí. Por ejemplo:
  FunctionOne(FunctionTwo(<<argument1>>))

• Puede pasar tres tipos diferentes de argumentos a funciones:

  1. Atributos, que se deben incluir entre corchetes. Por ejemplo: [attributeName]
  2. Constantes de cadena, que deben incluirse entre comillas dobles. Por ejemplo: "Estados Unidos"
  3. Otras funciones. Por ejemplo: FunctionOne(<<argument1>>, FunctionTwo(<<argument2>>))

• En el caso de las constantes de cadena, si necesita una barra diagonal inversa ( \ ) o comillas ( " ) en la cadena, debe tener un escape con el símbolo de barra diagonal inversa ( \ ). Por ejemplo: "Nombre de la compañía: \"Contoso\""

Lista de funciones

Anexar

Función:
Append(source, suffix)

Descripción:
Toma un valor de cadena de origen y anexa el sufijo al final.

Parámetros:

BitAnd

Descripción:
: la función BitAnd establece los bits especificados en un valor.

Sintaxis:
num BitAnd(num value1, num value2)

• value1, value2: valores numéricos que deberían estar unidos por el operador AND

Observaciones:
: esta función convierte ambos parámetros en la representación binaria y establece un bit en los siguientes valores:

• 0: si uno o ambos de los bits correspondientes en value1 y value2 son 0.
• 1: si ambos de los bits correspondientes son 1.

En otras palabras, devuelve 0 en todos los casos excepto cuando los bits correspondientes de los dos parámetros son 1.

Ejemplo:

BitAnd(&HF, &HF7)
Devuelve 7 porque "F" Y "F7" hexadecimal se evalúan como este valor.

CBool

Descripción:
: la función CBool devuelve un valor booleano basado en la expresión evaluada.

Sintaxis:
bool CBool(exp Expression)

Observaciones:
Si la expresión se evalúa en un valor distinto de cero, CBool devuelve True. En caso contrario, devuelve False.

Ejemplo:
CBool([attrib1] = [attrib2])

Devuelve True si ambos atributos tienen el mismo valor.

ConvertFromBase64

Descripción:
: la función ConvertFromBase64 convierte el valor codificado en base64 especificado en una cadena normal.

Sintaxis:
str ConvertFromBase64(str source) da por hecho que se usará Unicode para la codificación.
str ConvertFromBase64(str source, enum Encoding)

• source: cadena codificada en Base64
• Codificación: Unicode, ASCII, UTF8

Ejemplo
ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")
ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)

Ambos ejemplos devuelven "Hola a todos"

ConvertToBase64

Descripción:
La función ConvertToBase64 convierte una cadena en una en base64 de Unicode.
Convierte el valor de una matriz de enteros en su representación de cadena equivalente que se codifica con dígitos de base 64.

Sintaxis:
str ConvertToBase64(str source)

Ejemplo:
ConvertToBase64("Hello world!")
devuelve "SABlAGwAbABvACAAdwBvAHIAbABkACEA".

ConvertToUTF8Hex

Descripción:
: la función ConvertToUTF8Hex convierte una cadena en un valor codificado hexadecimal UTF8.

Sintaxis:
str ConvertToUTF8Hex(str source)

Observaciones:
El formato de salida de esta función es usado por Microsoft Entra ID como formato de atributo DN.

Ejemplo:
ConvertToUTF8Hex("Hello world!")
devuelve 48656C6C6F20776F726C6421.

Contar

Descripción:
: la función Count devuelve el número de elementos en un atributo multivalor.

Sintaxis:
num Count(mvstr attribute)

CStr

Descripción:
: la función CStr se convierte en un tipo de datos de cadena.

Sintaxis:
str CStr(num value)
str CStr(ref value)
str CStr(bool value)

• value: puede ser un valor numérico, un atributo de referencia o un valor booleano.

Ejemplo:
CStr([dn])
podría devolver "cn=Joe,dc=contoso,dc=com"

DateFromNum

Descripción:
: la función DateFromNum convierte un valor con formato de fecha de AD en un tipo DateTime.

Sintaxis:
dt DateFromNum(num value)

Ejemplo:
DateFromNum([lastLogonTimestamp])
DateFromNum(129699324000000000)
devuelve un valor DateTime que representa 2012-01-01 23:00:00.

DNComponent

Descripción:
: la función DNComponent devuelve el valor de un componente DN especificado empezando por la izquierda.

Sintaxis:
str DNComponent(ref dn, num ComponentNumber)

• dn: el atributo de referencia que interpretar
• ComponentNumber: el componente en DN para devolver

Ejemplo:
DNComponent(CRef([dn]),1)
si dn es "cn=Joe,ou=…", devuelve Joe.

Error

Descripción:
: la función Error se usa para devolver un error personalizado.

Sintaxis:
void Error(str ErrorMessage)

Ejemplo:
IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))
si el atributo accountName no está presente, se produce un error en el objeto.

FormatDateTime

Función:
FormatDateTime(source, inputFormat, outputFormat)

Descripción:
Toma una cadena de fecha de un formato y la convierte en un formato diferente.

Parámetros:

GUID

Descripción:
La función GUID genera un nuevo GUID aleatorio.

Sintaxis:
str Guid()

IIF

Descripción:
: la función IIF devuelve uno de un conjunto de valores posibles según una condición especificada.

Sintaxis:
var IIF(exp condition, var valueIfTrue, var valueIfFalse)

• condition: cualquier valor o expresión que pueda evaluarse en True o False.
• valueIfTrue: si la condición se evalúa como true, el valor devuelto.
• valueIfFalse: si la condición se evalúa como false, el valor devuelto.

Ejemplo:
IIF([employeeType]="Intern","t-" & [alias],[alias])
Si el usuario está en prácticas, devuelve el alias de un usuario al que agrega "t-" al principio. De lo contrario, el alias del usuario se queda como está.

Instr

Descripción:
: la función InStr busca la primera repetición de una subcadena en una cadena.

Sintaxis:

num InStr(str stringcheck, str stringmatch)
num InStr(str stringcheck, str stringmatch, num start)
num InStr(str stringcheck, str stringmatch, num start, enum compare)

• stringcheck: cadena que se va a buscar
• stringmatch: cadena que se tiene que encontrar
• start: posición de inicio para encontrar la subcadena
• compare: vbTextCompare o vbBinaryCompare

Observaciones:
: devuelve la posición en la que se encontró la subcadena o 0 si no se encuentra.

Ejemplo:
InStr("The quick brown fox","quick")
Se evalúa en 5

InStr("repEated","e",3,vbBinaryCompare)
Se evalúa en 7.

IsNull

Descripción:
si la expresión se evalúa como Null, la función IsNull devuelve True.

Sintaxis:
bool IsNull(var Expression)

Observaciones:
para un atributo, un valor Null se expresa mediante la ausencia del atributo.

Ejemplo:
IsNull([displayName])
devuelve True si el atributo no está presente en CS o MV.

IsNullOrEmpty

Descripción:
si la expresión es Null o una cadena vacía, la función IsNullOrEmpty devuelve True.

Sintaxis:
bool IsNullOrEmpty(var Expression)

Observaciones:
para un atributo, esto se evaluaría como True si el atributo no está presente o está presente, pero es una cadena vacía.
La función contraria a esta es IsPresent.

Ejemplo:
IsNullOrEmpty([displayName])
devuelve True si el atributo no está presente o si es una cadena vacía en CS o MV.

IsPresent

Descripción:
si la expresión se evalúa como una cadena que no es Null y no está vacía, la función IsPresent devuelve True.

Sintaxis:
bool IsPresent(var expression)

Observaciones:
la función contraria a esta es IsNullOrEmpty.

Ejemplo:
Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])

Elemento

Descripción:
la función Item devuelve un elemento de un atributo o una cadena de varios valores.

Sintaxis:
var Item(mvstr attribute, num index)

• attribute: atributo de varios valores
• index: índice para un elemento en la cadena de varios valores.

Observaciones:
la función Item es útil con la función Contains puesto que esta última función devuelve el índice a un elemento en el atributo de varios valores.

Se produce un error si el índice está fuera de los límites.

Ejemplo:
Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)
devuelve la dirección de correo electrónico principal.

IsString

Descripción:
si la expresión se puede evaluar en un tipo de cadena, la función IsString se evalúa en True.

Sintaxis:
bool IsString(var expression)

Observaciones:
se usa para determinar si CStr() puede analizar correctamente la expresión.

Unirse

Función:
Join(separator, source1, source2, ...)

Descripción:
Join() es similar a Append(), salvo que puede combinar varios valores de cadena de origen en una sola cadena, y cada valor se separará mediante una cadena separadora .

Si uno de los valores de origen es un atributo de varios valores, todos los valores de ese atributo se combinarán, separados por el valor separador.

Parámetros:

Izquierda

Descripción:
la función Left devuelve un número especificado de caracteres desde la izquierda de una cadena.

Sintaxis:
str Left(str string, num NumChars)

• string: la cadena desde la que devolver los caracteres
• NumChars: un número que identifica el número de caracteres que devolver desde el principio (izquierdo) de la cadena

Observaciones:
una cadena que contiene los primeros caracteres numChars de la cadena:

• Con numChars = 0, se devuelve una cadena vacía.
• Si numChars < 0, se devuelve la cadena de entrada.
• Si la cadena es null, se devuelve una cadena vacía.

Si la cadena contiene menos caracteres que el número especificado en numChars, se devuelve una cadena idéntica a la cadena (es decir, que contiene todos los caracteres en el parámetro 1).

Ejemplo:
Left("John Doe", 3)
Devuelve Joh.

Medio

Función:
Mid(source, start, length)

Descripción:
Devuelve una subcadena del valor de origen. Una subcadena es una cadena que contiene solo algunos de los caracteres de la cadena de origen.

Parámetros:

NormalizarDiacritics

Función:
NormalizeDiacritics(source)

Descripción:
Requiere un argumento de cadena. Devuelve la cadena, pero con los caracteres diacríticos reemplazados por caracteres no diacríticos equivalentes. Normalmente se usa para convertir nombres y apellidos que contienen caracteres diacríticos (marcas de énfasis) en valores legales que se pueden usar en varios identificadores de usuario, como nombres principales de usuario, nombres de cuenta SAM y direcciones de correo electrónico.

Parámetros:

not

Función:
Not(source)

Descripción:
Voltea el valor booleano del origen. Si el valor de origen es "True", devuelve "False". De lo contrario, devuelve "True".

Parámetros:

RemoveDuplicates

Descripción:
la función RemoveDuplicates toma una cadena multivalor y garantiza que cada valor es único.

Sintaxis:
mvstr RemoveDuplicates(mvstr attribute)

Ejemplo:
RemoveDuplicates([proxyAddresses])
devuelve un atributo proxyAddress saneado donde se han quitado todos los valores duplicados.

Reemplazar

Función:
Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

Descripción:
Reemplaza los valores de una cadena. Funciona de forma diferente en función de los parámetros proporcionados:

• Cuando se proporcionan oldValue y replacementValue :

  • Reemplaza todas las apariciones de oldValue en el origen por replacementValue

• Cuando se proporcionan oldValue y template :

  • Reemplaza todas las apariciones de oldValue en la plantilla por el valor de origen .

• Cuando se proporcionan regexPattern y replacementValue :

  • La función aplica regexPatterna la cadena de origen y puede usar los nombres de grupo regex para construir la cadena para replacementValue.

• Cuando regexPattern, regexGroupName, replacementValue se proporcionan:

  • La función aplica regexPatterna la cadena de origen y reemplaza todos los valores que coinciden con regexGroupName por replacementValue.

• Cuando regexPattern, regexGroupName, replacementAttributeName se proporcionan:

  • Si el origen no tiene ningún valor, se devuelve el origen .
  • Si source tiene un valor, la función aplica regexPattern a la cadena de origen y reemplaza todos los valores que coinciden con regexGroupName por el valor asociado a replacementAttributeName.

Parámetros:

SelectUniqueValue

Función:
SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, ...)

Descripción:
Requiere un mínimo de dos argumentos, que son reglas de generación de valores únicas definidas mediante expresiones. La función evalúa cada regla y, a continuación, comprueba el valor generado para la unicidad en el directorio o la aplicación de destino. El primer valor único encontrado será el devuelto. Si todos los valores ya existen en el destino, la entrada obtendrá escrowed y el motivo se registrará en los registros de auditoría. No hay ningún límite superior para el número de argumentos que se pueden proporcionar.

Parámetros:

SingleAppRoleAssignment

Función:
SingleAppRoleAssignment([appRoleAssignments])

Descripción:
Devuelve un único appRoleAssignment de la lista de todos los appRoleAssignments asignados a un usuario para una aplicación determinada. Esta función es necesaria para convertir el objeto appRoleAssignments en una sola cadena de nombre de rol. Tenga en cuenta que el procedimiento recomendado es asegurarse de que solo se asigna un appRoleAssignment a un usuario a la vez y, si se asignan varios roles, es posible que la cadena de rol devuelta no sea predecible.

Parámetros:

Partir

Función:
Split(source, delimiter)

Descripción:
Divide una cadena en una matriz de varios valores mediante el carácter delimitador especificado.

Parámetros:

StringFromSid

Descripción:
la función StringFromSid convierte una matriz de bytes o una matriz de bytes multivalor que contiene un identificador de seguridad en una cadena o en una cadena multivalor.

Sintaxis:
str StringFromSid(bin ObjectSID)

StripSpaces

Función:
StripSpaces(source)

Descripción:
Quita todos los caracteres de espacio (" ") de la cadena de origen.

Parámetros:

Interruptor

Función:
Switch(source, defaultValue, key1, value1, key2, value2, ...)

Descripción:
Cuando el valor de origen coincide con una clave, devuelve el valor de esa clave. Si el valor de origen no coincide con ninguna clave, devuelve defaultValue. Los parámetros de clave y valor siempre deben aparecer en pares. La función siempre espera un número par de parámetros.

Parámetros:

ToLower

Función:
ToLower(source, culture)

Descripción:
Toma un valor de cadena de origen y lo convierte en minúsculas mediante las reglas de referencia cultural especificadas. Si no se especifica información de referencia cultural , usará la referencia cultural invariable.

Parámetros:

ToUpper

Función:
ToUpper(source, culture)

Descripción:
Toma un valor de cadena de origen y lo convierte en mayúsculas mediante las reglas de referencia cultural especificadas. Si no se especifica información de referencia cultural , usará la referencia cultural invariable.

Parámetros:

Recortar

Descripción:
la función Trim quita los espacios en blanco del principio y del final de una cadena.

Sintaxis:
str Trim(str value)

Ejemplo:
Trim(" Test ")
devuelve "test".

Trim([proxyAddresses])
Quita los espacios del principio y del final de cada valor en el atributo proxyAddress.

Palabra

Descripción:
: la función Word devuelve una palabra incluida en una cadena, según los parámetros que describen los delimitadores que se usarán y el número de palabras que se devolverán.

Sintaxis:
str Word(str string, num WordNumber, str delimiters)

• string: la cadena desde la que devolver una palabra.
• WordNumber: un número que identifica qué número de palabras debe devolver.
• delimiters: una cadena que representa los delimitadores que deben usarse para identificar palabras

Observaciones:
: cada cadena de caracteres en la cadena separada por uno de los caracteres en los delimitadores se identifica como palabras:

• Si el número es < 1, se devuelve una cadena vacía.
• Si la cadena es Null, se devuelve una cadena vacía.

Si la cadena contiene menos palabras o si la cadena no contiene palabras identificadas por los delimitadores, se devuelve una cadena vacía.

Ejemplo:
Word("The quick brown fox",3," ")
devuelve "brown".

Word("This,string!has&many separators",3,",!&#")
devolvería "has".

Ejemplos

Quitar el nombre de dominio conocido

Debe quitar un nombre de dominio conocido del correo electrónico de un usuario para obtener un nombre de usuario.
Por ejemplo, si el dominio es "contoso.com", puede usar la siguiente expresión:

expresión :
Replace([mail], "@contoso.com", , ,"", ,)

Entrada y salida de ejemplo:

• ENTRADA (mail): "john.doe@contoso.com"
• SALIDA: "john.doe"

Anexar sufijo constante al nombre de usuario

Si usa un espacio aislado de Salesforce, es posible que tenga que anexar un sufijo adicional a todos los nombres de usuario antes de sincronizarlos.

expresión :
Append([userPrincipalName], ".test")

Entrada y salida de ejemplo:

• ENTRADA: (userPrincipalName): "John.Doe@contoso.com"
• SALIDA: "John.Doe@contoso.com.test"

Generación de alias de usuario mediante la concatenación de partes de nombre y apellidos

Debe generar un alias de usuario tomando las primeras 3 letras del nombre del usuario y las primeras 5 letras del apellido del usuario.

expresión :
Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))

Entrada y salida de ejemplo:

• INPUT (givenName): "John"
• INPUT (apellido): "Doe"
• SALIDA: "JohDoe"

Quitar diacríticos de una cadena

Debe reemplazar caracteres que contengan marcas de énfasis por caracteres equivalentes que no contengan marcas de énfasis.

expresión :
NormalizeDiacritics([givenName])

Entrada y salida de ejemplo:

• INPUT (givenName): "Zoë"
• SALIDA: "Zoe"

Dividir una cadena en una matriz de varios valores

Debe tomar una lista delimitada por comas de cadenas y dividirlas en una matriz que se pueda conectar a un atributo de varios valores, como el atributo PermissionSets de Salesforce. En este ejemplo, se ha rellenado una lista de conjuntos de permisos en extensionAttribute5 en microsoft Entra ID.

expresión :
Split([extensionAttribute5], ",")

Entrada y salida de ejemplo:

• INPUT (extensionAttribute5):
• OUTPUT: ["PermissionSetOne", "PermissionSetTwo"]

Fecha de salida como una cadena en un formato determinado

Quiere enviar fechas a una aplicación SaaS en un formato determinado.
Por ejemplo, quiere dar formato a las fechas de ServiceNow.

expresión :

FormatDateTime([extensionAttribute1], "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")

Entrada y salida de ejemplo:

• INPUT (extensionAttribute1): "20150123105347.1Z"
• SALIDA: "2015-01-23"

Reemplazar un valor basado en un conjunto predefinido de opciones

Debe definir la zona horaria del usuario en función del código de estado almacenado en microsoft Entra ID.
Si el código de estado no coincide con ninguna de las opciones predefinidas, use el valor predeterminado de "Australia/Sydney".

expresión :
Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")

Entrada y salida de ejemplo:

• INPUT (estado): "QLD"
• SALIDA: "Australia/Brisbane"

Reemplazar caracteres mediante una expresión regular

Debe buscar caracteres que coincidan con un valor de expresión regular y quitarlos.

expresión :

Replace([mailNickname], , "[a-zA-Z_]*", , "", , , )

Entrada y salida de ejemplo:

• INPUT (mailNickname: "john_doe72"
• SALIDA: "72"

Convertir el valor userPrincipalName (UPN) generado en minúsculas

En el ejemplo siguiente, el valor UPN se genera mediante la concatenación de los campos de origen PreferredFirstName y PreferredLastName y la función ToLower funciona en la cadena generada para convertir todos los caracteres en minúsculas.

ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))

Entrada y salida de ejemplo:

• INPUT (PreferredFirstName): "John"
• INPUT (PreferredLastName): "Smith"
• SALIDA: "john.smith@contoso.com"

Generación de un valor único para el atributo userPrincipalName (UPN)

En función del nombre del usuario, el nombre intermedio y el apellido, debe generar un valor para el atributo UPN y comprobar su exclusividad en el directorio de AD de destino antes de asignar el valor al atributo UPN.

expresión :

    SelectUniqueValue( 
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  [PreferredFirstName], [PreferredLastName]))), "contoso.com"), 
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")
    )

Entrada y salida de ejemplo:

• INPUT (PreferredFirstName): "John"
• INPUT (PreferredLastName): "Smith"
• OUTPUT: "John.Smith@contoso.com" si el valor UPN de John.Smith@contoso.com aún no existe en el directorio
• OUTPUT: "J.Smith@contoso.com" si el valor UPN de John.Smith@contoso.com ya existe en el directorio
• OUTPUT: "Jo.Smith@contoso.com" si los dos valores de UPN anteriores ya existen en el directorio

Pasos siguientes

• ¿Qué es el aprovisionamiento?
• ¿Qué es Microsoft Entra Cloud Sync?