Scrittura di espressioni per il mapping degli attributi in Azure Active DirectoryWriting Expressions for Attribute Mappings in Azure Active Directory

Quando si configura il provisioning in un'applicazione SaaS, come mapping degli attributi è possibile specificare il mapping di espressioni.When you configure provisioning to a SaaS application, one of the types of attribute mappings that you can specify is an expression mapping. Per questo tipo di mapping è necessario scrivere un'espressione analoga a uno script, che permette di trasformare i dati utente in formati più idonei all'applicazione SaaS.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.

Panoramica della sintassiSyntax Overview

La sintassi per le espressioni per i mapping degli attributi è simile a quella delle funzioni di Visual Basic for Applications (VBA).The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic for Applications (VBA) functions.

  • L'intera espressione deve essere definita in termini di funzioni, che sono costituite da un nome seguito da argomenti racchiusi tra parentesi: The entire expression must be defined in terms of functions, which consist of a name followed by arguments in parentheses:
    FunctionName(<<argument 1>>,<>)FunctionName(<<argument 1>>,<>)
  • È possibile annidare le funzioni in altre funzioni.You may nest functions within each other. Ad esempio: For example:
    FunzioneUno(FunzioneDue(<>))FunctionOne(FunctionTwo(<>))
  • È possibile passare tre tipi diversi di argomenti nelle funzioni:You can pass three different types of arguments into functions:

    1. Attributi, che devono essere racchiusi tra parentesi quadre.Attributes, which must be enclosed in square square brackets. Ad esempio: [NomeAttributo]For example: [attributeName]
    2. Costanti di stringa, che devono essere racchiuse tra virgolette doppie.String constants, which must be enclosed in double quotes. Ad esempio: "Stati Uniti"For example: "United States"
    3. Altre funzioni.Other Functions. Ad esempio: FunzioneUno(<>, FunzioneDue(<>))For example: FunctionOne(<>, FunctionTwo(<>))
  • Eventuali barre rovesciate ( \ ) o virgolette ( " ) da inserire nella costante di stringa dovranno essere precedute dal simbolo di barra rovesciata ( \ ) come carattere di escape.For string constants, if you need a backslash ( \ ) or quotation mark ( " ) in the string, it must be escaped with the backslash ( \ ) symbol. Ad esempio: "Nome società: "Contoso""For example: "Company name: "Contoso""

Elenco di funzioniList of Functions

Append      FormatDateTime      Join      Mid           NormalizeDiacritics Not      Replace      SingleAppRoleAssignment     StripSpaces      SwitchAppend      FormatDateTime      Join      Mid           NormalizeDiacritics Not      Replace      SingleAppRoleAssignment     StripSpaces      Switch


AppendAppend

Funzione:Function:
Append(source, suffix)Append(source, suffix)

Descrizione:Description:
Accetta un valore di stringa di origine e aggiunge un suffisso alla fine del valore.Takes a source string value and appends the suffix to the end of it.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString In genere è il nome dell'attributo dell'oggetto di origine.Usually name of the attribute from the source object
suffixsuffix ObbligatoriaRequired stringString Stringa da aggiungere alla fine del valore di origine.The string that you want to append to the end of the source value.

FormatDateTimeFormatDateTime

Funzione:Function:
FormatDateTime(source, inputFormat, outputFormat)FormatDateTime(source, inputFormat, outputFormat)

Descrizione:Description:
Accetta una stringa data in un formato e la converte in un formato diverso.Takes a date string from one format and converts it into a different format.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString In genere è il nome dell'attributo dell'oggetto di origine.Usually name of the attribute from the source object.
inputFormatinputFormat ObbligatoriaRequired stringString Formato previsto del valore source.Expected format of the source value. Per informazioni sui formati supportati, vedere http://msdn.microsoft.com/library/8kb3ddd4%28v=vs.110%29.aspx.For supported formats, see http://msdn.microsoft.com/library/8kb3ddd4%28v=vs.110%29.aspx.
outputFormatoutputFormat ObbligatoriaRequired stringString Formato della data di output.Format of the output date.

JoinJoin

Funzione:Function:
Join(separator, source1, source2, …)Join(separator, source1, source2, …)

Descrizione:Description:
Join() è simile ad Append(), ma può combinare più valori di stringa source in un singola stringa e ogni valore sarà separato da una stringa separator.Join() is similar to Append(), except that it can combine multiple source string values into a single string, and each value will be separated by a separator string.

Se uno dei valori di origine è un attributo con più valori, verranno aggiunti tutti i valori dell'attributo, separati dal valore separatore.If one of the source values is a multi-value attribute, then every value in that attribute will be joined together, separated the separator value.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
separatorseparator ObbligatoriaRequired stringString Stringa usata per separare i valori di origine quando sono concatenati in una stringa.String used to separate source values when they are concatenated into one string. Può essere "" se non sono necessari separatori.Can be "" if no separator is required.
source1 …source1 … sourceN**sourceN ** Obbligatorio per un numero variabile di volteRequired, variable-number of times stringString Valori stringa da unire.String values to be joined together.

MidMid

Funzione:Function:
Mid(source, start, length)Mid(source, start, length)

Descrizione:Description:
Restituisce una sottostringa del valore source.Returns a substring of the source value. Una sottostringa è una stringa che contiene solo alcuni caratteri della stringa di origine.A substring is a string that contains only some of the characters from the source string.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString Corrisponde in genere al nome dell'attributo.Usually name of the attribute.
startstart ObbligatoriaRequired numero interointeger Indice nella stringa source che indica il punto di inizio della sottostringa.Index in the source string where substring should start. L'indice del primo carattere della stringa sarà pari a 1, quello del secondo carattere a 2 e così via.First character in the string will have index of 1, second character will have index 2, and so on.
lengthlength ObbligatoriaRequired numero interointeger Lunghezza della sottostringa.Length of the substring. Se la lunghezza eccede la stringa source, la funzione restituirà una sottostringa dall'indice start fino alla fine della stringa source.If length ends outside the source string, function will return substring from start index till end of source string.

NormalizeDiacriticsNormalizeDiacritics

Funzione:Function:
NormalizeDiacritics(source)NormalizeDiacritics(source)

Descrizione:Description:
Richiede un argomento stringa.Requires one string argument. Restituisce la stringa, ma con i caratteri diacritici sostituiti dagli equivalenti caratteri non diacritici.Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. Viene in genere usata per convertire i nomi e i cognomi contenenti caratteri diacritici (accenti) in valori validi che possono essere usati in vari ID utente, ad esempio nomi dell'entità utente, nomi di account SAM e indirizzi di posta elettronica.Typically used to convert first names and last names containing diacritical characters (accent marks) into legal values that can be used in various user identifiers such as user principal names, SAM account names, and email addresses.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString In genere un attributo nome o cognomeUsually a first name or last name attribute

notNot

Funzione:Function:
Not(source)Not(source)

Descrizione:Description:
Inverte il valore booleano di source.Flips the boolean value of the source. Se il valore di source è "True", restituisce "False".If source value is "True", returns "False". In caso contrario, restituisce "True".Otherwise, returns "True".

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired Stringa booleanaBoolean String I valori previsti per source sono "True" o "False".Expected source values are "True" or "False"..

ReplaceReplace

Funzione:Function:
Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

Descrizione:Description:
Sostituisce i valori all'interno di una stringa.Replaces values within a string. Funziona in modo diverso a seconda dei parametri forniti:It works differently depending on the parameters provided:

  • Se vengono forniti oldValue e replacementValue:When oldValue and replacementValue are provided:

    • Sostituisce tutte le occorrenze di oldValue in source con replacementValueReplaces all occurrences of oldValue in the source with replacementValue
  • Se vengono forniti oldValue e template:When oldValue and template are provided:

    • Sostituisce tutte le occorrenze di oldValue in template con il valore sourceReplaces all occurrences of the oldValue in the template with the source value
  • Se vengono forniti regexPattern, regexGroupName e replacementValue:When regexPattern, regexGroupName, replacementValue are provided:

    • Sostituisce tutti i valori corrispondenti a oldValueRegexPattern nella stringa source con replacementValue.Replaces all values matching oldValueRegexPattern in the source string with replacementValue
  • Se vengono forniti regexPattern, regexGroupName e replacementPropertyName:When regexPattern, regexGroupName, replacementPropertyName are provided:

    • Se source non ha alcun valore, viene restituito sourceIf source has no value, source is returned
    • Se source ha un valore, usa regexPattern e regexGroupName per estrarre il valore di sostituzione dalla proprietà con replacementPropertyName.If source has a value, uses regexPattern and regexGroupName to extract replacement value from the property with replacementPropertyName. Il valore di sostituzione viene restituito come risultato.Replacement value is returned as the result

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString In genere è il nome dell'attributo dell'oggetto di origine.Usually name of the attribute from the source object.
oldValueoldValue FacoltativoOptional stringString Valore da sostituire in source o template.Value to be replaced in source or template.
regexPatternregexPattern FacoltativoOptional stringString Criterio di espressione regolare per il valore da sostituire in source.Regex pattern for the value to be replaced in source. Se invece si usa replacementPropertyName, corrisponde al modello usato per estrarre il valore dalla proprietà di sostituzione.Or, when replacementPropertyName is used, pattern to extract value from replacement property.
regexGroupNameregexGroupName FacoltativoOptional stringString Nome del gruppo in regexPattern.Name of the group inside regexPattern. Solo se si usa replacementPropertyName, il valore di questo gruppo verrà estratto come replacementValue dalla proprietà di sostituzione.Only when replacementPropertyName is used, we will extract value of this group as replacementValue from replacement property.
replacementValuereplacementValue FacoltativoOptional stringString Nuovo valore con cui sostituire il precedente.New value to replace old one with.
replacementAttributeNamereplacementAttributeName FacoltativoOptional stringString Nome dell'attributo da usare per il valore di sostituzione, se non sono presenti valori per source.Name of the attribute to be used for replacement value, when source has no value.
templatetemplate FacoltativoOptional stringString Se viene fornito il valore template, il valore oldValue verrà cercato in template e sostituito con il valore source.When template value is provided, we will look for oldValue inside the template and replace it with source value.

SingleAppRoleAssignmentSingleAppRoleAssignment

Funzione:Function:
SingleAppRoleAssignment([appRoleAssignments])SingleAppRoleAssignment([appRoleAssignments])

Descrizione:Description:
Richiede un argomento stringa.Requires one string argument. Restituisce la stringa, ma con i caratteri diacritici sostituiti dagli equivalenti caratteri non diacritici.Returns the string, but with any diacritical characters repalced with equivalent non-diacritical characters.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
[appRoleAssignments][appRoleAssignments] ObbligatoriaRequired stringString Oggetto [appRoleAssignments].[appRoleAssignments] object.

StripSpacesStripSpaces

Funzione:Function:
StripSpaces(source)StripSpaces(source)

Descrizione:Description:
Rimuove tutti i caratteri di spazio (" ") dalla stringa di origine.Removes all space (" ") characters from the source string.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString source da aggiornare.source value to update.

SwitchSwitch

Funzione:Function:
Switch(source, defaultValue, key1, value1, key2, value2, …)Switch(source, defaultValue, key1, value1, key2, value2, …)

Descrizione:Description:
Quando il valore source corrisponde a key, verrà restituito un parametro value per tale oggetto key.When source value matches a key, returns value for that key. Se il valore del parametro source non corrisponde ad alcuna chiave, verrà restituito defaultValue.If source value doesn't match any keys, returns defaultValue. I parametri key e value devono essere sempre accoppiati.Key and value parameters must always come in pairs. Le funzioni prevedono sempre un numero pari di parametri.The function always expects an even number of parameters.

Parametri:Parameters:

NOMEName Obbligatorio/RipetutoRequired/ Repeating typeType NoteNotes
sourcesource ObbligatoriaRequired stringString Source da aggiornare.Source value to update.
defaultValuedefaultValue FacoltativoOptional stringString Valore predefinito da usare se l'origine non corrisponde ad alcuna chiave.Default value to be used when source doesn't match any keys. Può essere una stringa vuota ("").Can be empty string ("").
keykey ObbligatoriaRequired stringString Parametro key con cui confrontare il valore di source.Key to compare source value with.
valuevalue ObbligatoriaRequired stringString Valore di sostituzione per il valore source corrispondente al parametro key.Replacement value for the source matching the key.

EsempiExamples

Rimuovere un nome di dominio notoStrip known domain name

Occorre rimuovere un nome di dominio noto dall'indirizzo di posta elettronica di un utente per ottenere il nome utente.You need to strip a known domain name from a user’s email to obtain a user name.
Ad esempio, se il dominio è "contoso.com", è possibile usare l'espressione seguente:For example, if the domain is "contoso.com", then you could use the following expression:

Espressione:Expression:
Replace([mail], "@contoso.com", , ,"", ,)

Input/output di esempio:Sample input / output:

  • INPUT (mail): "john.doe@contoso.com"INPUT (mail): "john.doe@contoso.com"
  • OUTPUT: "john.doe"OUTPUT: "john.doe"

Aggiungere un suffisso costante al nome utenteAppend constant suffix to user name

Se si usa un ambiente sandbox Salesforce, potrebbe essere necessario aggiungere un suffisso a tutti i nomi utente prima di sincronizzarli.If you are using a Salesforce Sandbox, you might need to append an additional suffix to all your user names before synchronizing them.

Espressione:Expression:
Append([userPrincipalName], ".test"))

Input/output di esempio:Sample input/output:

  • INPUT (userPrincipalName): "John.Doe@contoso.com"INPUT: (userPrincipalName): "John.Doe@contoso.com"
  • OUTPUT: "John.Doe@contoso.com.test"OUTPUT: "John.Doe@contoso.com.test"

Generare un alias utente concatenando parti del nome e del cognomeGenerate user alias by concatenating parts of first and last name

Occorre generare un alias utente contenente le prime tre lettere del nome e le prime cinque lettere del cognome dell'utente.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.

Espressione:Expression:
Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))

Input/output di esempio:Sample input/output:

  • INPUT (givenName): "John"INPUT (givenName): "John"
  • INPUT (surname): "Doe"INPUT (surname): "Doe"
  • OUTPUT: "JohDoe"OUTPUT: "JohDoe"

Rimuovere i segni diacritici da una stringaRemove diacritics from a string

È necessario sostituire i caratteri contenenti accenti con gli equivalenti caratteri non contenenti accenti.You need to replace characters containing accent marks with equivalent characters that don't contain accent marks.

Espressione:Expression:
NormalizeDiacritics([givenName])NormalizeDiacritics([givenName])

Input/output di esempio:Sample input/output:

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

Eseguire l'output della data come stringa in un formato specificoOutput date as a string in a certain format

Occorre inviare date a un'applicazione SaaS in un formato specifico,You want to send dates to a SaaS application in a certain format.
Ad esempio, formattare le date per ServiceNow.For example, you want to format dates for ServiceNow.

Espressione:Expression:

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

Input/output di esempio:Sample input/output:

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

Sostituire un valore in base a un set di opzioni predefinitoReplace a value based on predefined set of options

È necessario definire il fuso orario dell'utente in base al codice di stato archiviato in Azure AD.You need to define the time zone of the user based on the state code stored in Azure AD.
Se il codice di stato non corrisponde ad alcuna opzione predefinita, usare il valore predefinito "Australia/Sydney".If the state code doesn't match any of the predefined options, use default value of "Australia/Sydney".

Espressione:Expression:

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

Input/output di esempio:Sample input/output:

  • INPUT (state): "QLD"INPUT (state): "QLD"
  • OUTPUT: "Australia/Brisbane"OUTPUT: "Australia/Brisbane"