Active Directory Provider::Translate Name
Converts names between different Microsoft Win32 naming conventions. Used by Microsoft Provisioning Framework (MPF).
Wrapper for the Win32 API function Translate Name.
Arguments
The following table describes the XML schema elements and attributes. Unless otherwise indicated, the data type is string.
Element | Description, relationships, and attributes |
---|---|
executeData |
Description: Children: |
inputFormat |
Description: Table of EXTENDED_NAME_FORMAT strings and values:
NameUnknown0Unknown name type.
NameFullyQualifiedDN1Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible2Microsoft Windows NT 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay3A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId6Globally unique identifier (GUID) string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical7Complete canonical name (for example, sales.tailspintoys.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal8User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx9Same as NameCanonical except that the rightmost forward slash (/) is replaced with a newline character (\n), even in a domain-only case (for example, engineering.microsoft.com/software\nsomeone).
NameServicePrincipal10Generalized service principal name (for example, www/www.microsoft.com@microsoft.com).
Parent: |
inputName |
Description: Parent: |
outputFormat |
Description: Table of EXTENDED_NAME_FORMAT strings and values:
NameUnknown0Unknown name type.
NameFullyQualifiedDN1Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible2Windows NT 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay3A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId6GUID string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical7Complete canonical name (for example, engineering.microsoft.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal8User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx9Same as NameCanonical except that the rightmost forward slash (/) is replaced with a newline character (\n), even in a domain-only case (for example, engineering.microsoft.com/software\nsomeone).
NameServicePrincipal10Generalized service principal name (for example, www/www.microsoft.com@microsoft.com).
Parent: |
outputName |
Description: Parent: |
Remarks
For example, to obtain the "otherHomePhone" property of "user@domain.com", you would use Translate Name to convert the name from NameUserPrincipal to NameFullyQualifiedDN, then Path From DN to convert the DN to a lightweight directory access protocol (LDAP) path, and finally Get Properties to get the value of "otherHomePhone".
Sample request:
<request>
<data>
<inputName>user@domain.com</inputName>
<referencePath>LDAP://domain.com/dc=domain,dc=com</referencePath>
</data>
<procedure>
<!-- Convert from "user@domain.com" to "cn=user,cn=users,dc=domain,dc=com" -->
<execute namespace='Active Directory Provider' procedure='Translate Name'>
<executeData>
<inputFormat>NameUserPrincipal</inputFormat>
<outputFormat>NameFullyQualifiedDN</outputFormat>
</executeData>
<before source='data' sourcePath='inputName' destination='executeData'/>
<after source='executeData' sourcePath='outputName' destination='data'/>
</execute>
<!-- Convert the DN from above to an LDAP path -->
<execute namespace='Active Directory Provider' procedure='Path From DN'>
<executeData>
<distinguishedName/>
</executeData>
<before source='data' sourcePath='outputName' destination='executeData' destinationPath='distinguishedName' mode='merge'/>
<before source='data' sourcePath='referencePath' destination='executeData'/>
<after source='executeData' sourcePath='path' destination='data'/>
</execute>
<!-- Get the user's "otherHomePhone" property from Active Directory -->
<execute namespace='Active Directory Provider' procedure='Get Properties'>
<executeData>
<propertyList>
<otherHomePhone>
</propertyList>
</executeData>
<before source='data' sourcePath='path' destination='executeData'/>
<after source='executeData' sourcePath='properties' destination='data'/>
</execute>
</procedure>
</request>
Sample response:
<response>
<data>
<inputName>user@domain.com</inputName>
<referencePath>LDAP://domain.com/dc=domain,dc=com</referencePath>
<outputName>cn=user,cn=users,dc=domain,dc=com</outputName>
<path>LDAP://domain.com/cn=user,cn=users,dc=domain,dc=com</path>
<properties>
<property name='otherHomePhone'><value>555-1212</value></property>
</properties>
</data>
</response>
Schema Definition
Input
<executeData>1..1
<outputFormat>1..1</outputFormat>
<inputName>0..1</inputName>
<inputFormat>0..1</inputFormat>
</executeData>
Output
<executeData>1..1
<outputName></outputName>1..1
</executeData>
Sample Code
Example XML Request
The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.
Example XML Response
The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.
Applies To
Active Directory Provider for:
Hosted Messaging and Collaboration version 4.5
Hosted Messaging and Collaboration version 4.0
Hosted Messaging and Collaboration version 3.5
Hosted Messaging and Collaboration version 3.0
Windows-based Hosting version 4.5
Windows-based Hosting version 4.0
Windows-based Hosting version 3.5
Windows-based Hosting for Applications version 1.0