Specify property for object display names

When you make a request to get a directory object, the object in the response body will always contain the displayName attribute:

{
    ...
    "guid": "7a4267ce-d354-44e7-8bd6-c681f1284a41",
    "dn": "CN=John Smith,CN=Users,DC=example,DC=com",
    "displayName": "John Smith",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1
    ...
}

By default, the value of the attribute is obtained from the object's relative distinguished name (RDN). In the example above:

Distinguished name (DN) is CN=John Smith,CN=Users,DC=example,DC=com
Relative distinguished name is CN=John Smith
Display name is John Smith

You can configure REST API to obtain object display names from a specific object property, for example, displayName or userPrincipalName.

Out of the box, only Adaxes service administrators have the rights to configure REST API. Other users can be granted such rights using a security role with the Write all properties permission assigned over Configuration objects.

Change settings

To specify the properties to get display names from, execute the following script and restart IIS on the computer where REST API component is installed.

In the script:

$serviceHost – the host name of the computer where the Adaxes service is installed.
$propertyNames – an array of property names that will be used to obtain object display names. To reset settings to default, specify $null.

If you include multiple properties in the $propertyNames array, they will be used in the order of priority i.e. if the first property is not specified for an object, its display name is obtained from the second property, and so on. If neither is specified, display name will be obtained from the RDN.

Adaxes 2023 and newer

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$propertyNames = @(
    "lastname",
    "userPrincipalName",
    "employeeID"
)

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Change settings.
$newConfig =  ConvertTo-Json -Depth 4 @{
    "advancedParameters"= @(
        @{
            "name" = "Common.DisplayNameProperties";
            "values" = $propertyNames
        }
    )
}

# Save settings.
$restApi.FromJson("{elements: ['AdvancedParameters']}", $newConfig)

Adaxes 2021.1

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 
$propertyNames = @(
    "displayName",
    "userPrincipalName",
    "employeeID"
) 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Set properties for object display names.
$parameters = $restApi.AdvancedParameters
$displayNameProperties = $parameters.GetParameter("Common.DisplayNameProperties")
$displayNameProperties.Values = $propertyNames
$parameters.SetParameter($displayNameProperties)

# Save settings.
$restApi.AdvancedParameters = $parameters
$restApi.SetInfo()

After executing the script, restart IIS on the computer where REST API component is installed.

View current settings

Execute the following script. In the script:

$serviceHost – the host name of the computer where the Adaxes service is installed.

Adaxes 2023 and newer

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Properties for display names.
$advancedParameters = $restApi.ToJson("{elements: ['AdvancedParameters']}") | ConvertFrom-Json
$displayNameProperties = $advancedParameters.advancedParameters | `
    Where name -eq Common.DisplayNameProperties

if ($null -eq $displayNameProperties.values) 
{
    Write-Host "Display names obtained from: <Default>"
}
else
{
    Write-Host "Display names obtained from: $($displayNameProperties.values)"
}

Adaxes 2021.1

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Properties for display names.
$parameters = $restApi.AdvancedParameters
$displayNameProperties = $parameters.GetParameter("Common.DisplayNameProperties")

if ($null -eq $displayNameProperties.Values) 
{
    Write-Host "Display names obtained from: <Default>"
}
else
{
    Write-Host "Display names obtained from: $($displayNameProperties.Values)"
}

Send feedback