User synchronization

User field synchronization can be configured in the dashboard for a database in "Settings" → "User Auth & Sync Settings".

Example configuration:

<UserSyncConfig batchSize="1" syncIntervalInSeconds="86400">

    <!-- List of various sync sources available, e.g. LdapSyncSource -->
    <LdapSyncSource name="OneOffixx AD" queryKey="OneOffixxIdentifier" isOptional="false">
        <QueryKeyRegex group="0" match="0">([a-z0-9])*</QueryKeyRegex>
        [...]

        <!-- Any sync source has claims -->
        <Claims>	
            <Claim type="http://schema.oneoffixx.com/ws/2011/01/identity/claims/uid" property="uid" />
            <Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenName" property="givenName" />
            <Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sn" property="sn" /> 
        </Claims>

  </LdapSyncSource>
</UserSyncConfig>

Attributes

batchSize The UserSyncJob synchronizes users in batches. This attribute can be used to adjust the number of users in a batch. The value must be between 1 and 100. – Default: 10
syncIntervalInSeconds Sets the interval in seconds for synchronization. The value must be greater than 60. Default: 86400 (= 1 day)
syncTimeoutInSeconds When synchronization is started, a time stamp is stored with the user. If an error occurs during synchronization or the action is aborted, the user remains in this state. This attribute can be used to set a "timeout" in seconds so that the user is again captured by the synchronization process. The value must be between 10 and 3600. Default: 60
skipLockedFields In the default case, all fields are synchronized – depending on the configuration. If locked user fields should be excluded from synchronization, this value can be set to true. Default: false

SyncSources

The following sources are currently available for synchronization:

All SyncSources have the following attributes and elements in common:

name
queryKey Field name to be used as a parameter for the query. Available are:
- OneOffixxIdentifier
- User.SID
- User.Title
isOptional
QueryKeyRegex (optional) If only part of the value of the QueryKey is to be used, it can be specified here.
Claims see next section

Note when using "User.Title":

The User.Title is the name of the user in the OneOffixx database. The source of the name can be determined via the properties of the "Active Directory Connector" or the "Office 365 Connector". An adjustment is possible at any time and is applied during user synchronization.

Claims

<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" property="wWWHomePage" />

type describes the claim path. It must have a valid URI format, but does not have to exist – as long as it is only used in OneOffixx. If it is not used only in OneOffixx, it is beneficial to follow Microsoft's claims.
property is the counterpart to the property defined in the SyncSource. The values of the two must be identical.

In addition to direct assignments, claims can also store certain rules:

useValueIfEmpty If set to true: if the property in the SyncSource is empty, the default value inside the Claim element is taken. If there is no value, the field remains empty.

<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function" property="description" useValueIfEmpty="true">Fallback-Value</Claim>

If you define a claim for the user synchronization and map it to a field at the end, the corresponding value is applied. However, if you want to avoid, for example, that empty properties are applied from the SyncSource, you can also "ignore" the claim via the following property:

Note

The LdapSyncSource maps only "existing" attributes by itself, other sources handle this differently.

ignoreClaimIfEmpty If set to true, empty fields in the SyncSource will be ignored. Otherwise, depending on the SyncSources, empty fields are also synchronized to the user and user-defined values are overwritten.

<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function" ignoreClaimIfEmpty="true" property="description" useValueIfEmpty="true" />

Claims also support regex so that, for example, parts of values can be accessed.

<!-- Value for property 'uid' is 'bernhard.diener@oneoffixx.com' -->
<Claim type="http://schema.oneoffixx.com/ws/2011/01/identity/claims/uid" property="uid">
    <Regex match="0" group="2">([a-z\\.]*)@([a-z\\.]*)</Regex> <!-- liefert 'oneoffixx.com' -->
</Claim>

match Index of the match, mostly 0
group Index of the group
- Attention! The group number can be increased by 1, because in group 0 may be the fullmatch.
value Valid regex expression

Multilingualism

By default, user synchronization only synchronizes fields in the default document language. If you want to set certain field contents also in other languages, for example, this is possible by setting the lcid attribute:

<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function" property="description" />
<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function" lcid="1036" property="descriptionFR" />
<Claim type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function" lcid="1040" property="descriptionIT" />

In this example, the claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/function is filled in the default document language via the description property. In the example, the same claim is assigned to the respective property from the source for the document language Italian and French (LCID 1040 and 1036). The rules of the normal claims also apply to these "translated" claims.